X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/d67db03c2ab853eba7b67c8870af41796eea387c..28ee7f19b865c32ce1b03cc0afa26983a0208693:/doc/external-dependency-solver-protocol.txt

diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt
index d914db309..566890665 100644
--- a/doc/external-dependency-solver-protocol.txt
+++ b/doc/external-dependency-solver-protocol.txt
@@ -70,6 +70,11 @@ configuration documentation for more, and more up to date, information.
   of the solver you are using if and what is supported as a value here.
   Defaults to the empty string.
 
+- **APT::Solver::RunAsUser**: if APT itself is run as root it will
+  change to this user before executing the solver. Defaults to the value
+  of APT::Sandbox::User, which itself defaults to `_apt`. Can be
+  disabled by set this option to `root`.
+
 The options **Strict-Pinning** and **Preferences** can also be set for
 a specific solver only via **APT::Solver::NAME::Strict-Pinning** and
 **APT::Solver::NAME::Preferences** respectively where `NAME` is the name
@@ -156,17 +161,26 @@ The following **action fields** are supported in request stanzas:
   Install. This field denotes a list of packages that the user wants to
   remove, usually via APT `remove` or `purge` requests.
 
-- **Upgrade:** (optional, defaults to `no`). Allowed values: `yes`,
+- **Upgrade-All:** (optional, defaults to `no`). Allowed values `yes`,
   `no`. When set to `yes`, an upgrade of all installed packages has been
-  requested, usually via an APT `upgrade` request.
-
-- **Dist-Upgrade:** (optional, defaults to `no`). Allowed values: `yes`,
-  `no`. Same as Upgrade, but for APT `dist-upgrade` requests.
+  requested, usually via an upgrade command like 'apt full-upgrade'.
 
 - **Autoremove:** (optional, defaults to `no`). Allowed values: `yes`,
   `no`. When set to `yes`, a clean up of unused automatically installed
   packages has been requested, usually via an APT `autoremove` request.
 
+- **Upgrade:** (deprecated, optional, defaults to `no`). Allowed values:
+  `yes`, `no`. When set to `yes`, an upgrade of all installed packages
+  has been requested, usually via an APT `upgrade` request. A value of
+  `yes` is equivalent to the fields `Upgrade-All`,
+  `Forbid-New-Install`and `Forbid-Remove` all set to `yes`.
+
+- **Dist-Upgrade:** (deprecated, optional, defaults to `no`). Allowed
+  values: `yes`, `no`. Same as Upgrade, but for APT `dist-upgrade`
+  requests. A value of `yes` is equivalent to the field `Upgrade-All`
+  set to `yes` and the fields `Forbid-New-Install`and `Forbid-Remove`
+  set to `no`.
+
 The following **preference fields** are supported in request stanzas:
 
 - **Strict-Pinning:** (optional, defaults to `yes`). Allowed values:
@@ -178,6 +192,14 @@ The following **preference fields** are supported in request stanzas:
   field comes from the `APT::Solver::Strict-Pinning` configuration
   option.
 
+- **Forbid-New-Install:* (optional, defaults to `no`). Allowed values:
+  `yes`, `no`. When set to `yes` the resolver is forbidden to install
+  new packages in its returned solution.
+
+- **Forbid-Remove:* (optional, defaults to `no`). Allowed values: `yes`,
+  `no`.  When set to `yes` the resolver is forbidden to remove currently
+  installed packages in its returned solution.
+
 - **Solver:** (optional, defaults to the empty string) a purely
   informational string specifying to which solver this request was send
   initially.
@@ -289,10 +311,15 @@ this protocol makes no assumption on the fact that a subsequent
 invocation of an Autoremove action will actually remove the very same
 packages indicated by Autoremove stanzas in the former solution.
 
-The package identifiers of install, remove and autoremove stanzas from a single
-solution are unique. That is, a package identifier does not occur more than
-once in the solution. Every package identifier is only associated with a single
-action (either install, remove or autoremove).
+A package can't be installed in multiple versions at the same time, so
+for each package there can at most one version be selected either for
+installation or removal. This especially means that a solver is neither
+allowed to represent package upgrades as a remove of the installed
+version and the installation of another (the remove is implicit and must
+be omitted from the solution) nor is it supported to revert previous
+actions in the solution with later actions. APT is allowed to show
+warnings and might even misbehave in earlier versions if a solver is
+violating this assumption.
 
 In terms of expressivity, install and remove stanzas can carry one
 single field each, as APT-IDs are enough to pinpoint packages to be
@@ -325,8 +352,9 @@ information to APT using **progress stanzas**. A progress stanza starts
 with the Progress field and might contain the following fields:
 
 - **Progress:** (mandatory). The value of this field is a date and time
-  timestamp, in RFC 2822 format. The timestamp provides a time
-  annotation for the progress report.
+  timestamp from the UTC timezone, in RFC 2822 format (see 'date -uR' as
+  an example). The timestamp provides a time annotation for the
+  progress report.
 
 - **Percentage:** (optional). An integer from 0 to 100, representing the
   completion of the dependency solving process, as declared by the