edsp: support generic and solver-specific configs

[apt.git] / doc / external-dependency-solver-protocol.txt

diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt
index 790f2f1ee80a511f708a86f01589f5de687a92b4..e2bd95866f303abea02de859fbdff9202a7d5672 100644 (file)
--- a/doc/external-dependency-solver-protocol.txt
+++ b/doc/external-dependency-solver-protocol.txt
@@ -5,6 +5,14 @@ external dependency solvers. The protocol is called APT EDSP, for "APT
 External Dependency Solver Protocol".
 
 
+## Terminology
+
+In the following we use the term **architecture qualified package name**
+(or *arch-qualified package names* for short) to refer to package
+identifiers of the form "package:arch" where "package" is a package name
+and "arch" a dpkg architecture.
+
+
 ## Components
 
 - **APT**: we know this one.
@@ -50,17 +58,25 @@ configuration documentation for more, and more up to date, information.
 - **APT::Solver**: the name of the solver to be used for
   dependency solving. Defaults to `internal`
 
+- **Dir::Bin::Solvers**: absolute path of the directory where to look for
+  external solvers. Defaults to `/usr/lib/apt/solvers`.
+
 - **APT::Solver::Strict-Pinning**: whether pinning must be strictly
   respected (as the internal solver does) or can be slightly deviated
   from. Defaults to `yes`.
 
-- **APT::Solver::NAME::Preferences** (where NAME is a solver name):
-  solver-specific user preference string used during dependency solving,
-  when the solver NAME is in use. Check solver-specific documentation
-  for what is supported here. Defaults to the empty string.
+- **APT::Solver::Preferences**: user preference string used during
+  dependency solving by the requested solver. Check the documentation
+  of the solver you are using if and what is supported as a value here.
+  Defaults to the empty string.
+
+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
+of the external solver this option should apply to. These options if set
+override the generic options; for simplicity the documentation will
+refer only to the generic options.
 
-- **Dir::Bin::Solvers**: absolute path of the directory where to look for
-  external solvers. Defaults to `/usr/lib/apt/solvers`.
 
 ## Protocol
 
@@ -132,9 +148,9 @@ The following **configuration fields** are supported in request stanzas:
 The following **action fields** are supported in request stanzas:
 
 - **Install:** (optional, defaults to the empty string) A space
-  separated list of package names, with *no version attached*, to
-  install. This field denotes a list of packages that the user wants to
-  install, usually via an APT `install` request.
+  separated list of arch-qualified package names, with *no version
+  attached*, to install. This field denotes a list of packages that the
+  user wants to install, usually via an APT `install` request.
 
 - **Remove:** (optional, defaults to the empty string) Same syntax of
   Install. This field denotes a list of packages that the user wants to
@@ -162,8 +178,13 @@ The following **preference fields** are supported in request stanzas:
   field comes from the `APT::Solver::Strict-Pinning` configuration
   option.
 
-- **Preferences:** a solver-specific optimization string, usually coming
-  from the `APT::Solver::Preferences` configuration option.
+- **Solver:** (optional, defaults to the empty string) a purely
+  informational string specifying to which solver this request was send
+  initially.
+
+- **Preferences:** (optional, defaults to the empty string)
+  a solver-specific optimization string, usually coming from the
+  `APT::Solver::Preferences` configuration option.
 
 
 #### Package universe
@@ -201,7 +222,7 @@ field. The following fields are supported in package stanzas:
 - **APT-Candidate:** (optional, defaults to `no`). Allowed values:
   `yes`, `no`. When set to `yes`, the corresponding package is the APT
   candidate for installation among all available packages with the same
-  name.
+  name and architecture.
 
 - **APT-Automatic:** (optional, defaults to `no`). Allowed values:
   `yes`, `no`. When set to `yes`, the corresponding package is marked by
@@ -218,6 +239,13 @@ field. The following fields are supported in package stanzas:
   Release file entry (Origin, Label, Codename, etc.) in the format of
   APT_PREFERENCES(5).
 
+- **Source:** (optional) The name of the source package the binary
+  package this record is for was built from.
+  This field does NOT include the version of the source package unlike
+  the Source field in the dpkg database. The version is optionally
+  available in the **Source-Version:** field.
+
+
 ### Answer
 
 An answer from the external solver to APT is either a *solution* or an
@@ -226,11 +254,11 @@ An answer from the external solver to APT is either a *solution* or an
 The following invariant on **exit codes** must hold true. When the
 external solver is *able to find a solution*, it will write the solution
 to standard output and then exit with an exit code of 0. When the
-external solver is *unable to find a solution* (and s aware of that), it
-will write an error to standard output and then exit with an exit code
-of 0. An exit code other than 0 will be interpreted as a solver crash
-with no meaningful error about dependency resolution to convey to the
-user.
+external solver is *unable to find a solution* (and is aware of that),
+it will write an error to standard output and then exit with an exit
+code of 0. An exit code other than 0 will be interpreted as a solver
+crash with no meaningful error about dependency resolution to convey to
+the user.
 
 
 #### Solution