Release 1.1.4

[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 8c13b185cdf1e47c16641de6e34d02c4a2efb703..5757991a835af14e590cb83d10710a70a58d8d0f 100644 (file)
--- a/doc/external-dependency-solver-protocol.txt
+++ b/doc/external-dependency-solver-protocol.txt
@@ -1,10 +1,18 @@
-# APT External Dependency Solver Protocol (EDSP) - version 0.3
+# APT External Dependency Solver Protocol (EDSP) - version 0.5

 
 This document describes the communication protocol between APT and
 external dependency solvers. The protocol is called APT EDSP, for "APT
 External Dependency Solver Protocol".
 
 
 
 This document describes the communication protocol between APT and
 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.
 ## Components
 
 - **APT**: we know this one.


@@ -26,10 +34,12 @@ internal solver, is reserved, and cannot be used by external solvers.
 
 ## Installation
 
 
 ## Installation
 

-Each external solver is installed as a file under
-`/usr/lib/apt/solvers`. The naming scheme is
-`/usr/lib/apt/solvers/NAME`, where `NAME` is the name of the external
-solver.
+Each external solver is installed as a file under Dir::Bin::Solvers (see
+below), which defaults to `/usr/lib/apt/solvers`. We will assume in the
+remainder of this section that such a default value is in effect.
+
+The naming scheme is `/usr/lib/apt/solvers/NAME`, where `NAME` is the
+name of the external solver.

 
 Each file under `/usr/lib/apt/solvers` corresponding to an external
 solver must be executable.
 
 Each file under `/usr/lib/apt/solvers` corresponding to an external
 solver must be executable.


@@ -45,7 +55,7 @@ Several APT options can be used to affect dependency solving in APT. An
 overview of them is given below. Please refer to proper APT
 configuration documentation for more, and more up to date, information.
 
 overview of them is given below. Please refer to proper APT
 configuration documentation for more, and more up to date, information.
 

-- **APT::Solver::Name**: the name of the solver to be used for
+- **APT::Solver**: the name of the solver to be used for

   dependency solving. Defaults to `internal`
 
 - **APT::Solver::Strict-Pinning**: whether pinning must be strictly
   dependency solving. Defaults to `internal`
 
 - **APT::Solver::Strict-Pinning**: whether pinning must be strictly


@@ -57,6 +67,9 @@ configuration documentation for more, and more up to date, information.
   when the solver NAME is in use. Check solver-specific documentation
   for what is supported here. Defaults to the empty string.
 
   when the solver NAME is in use. Check solver-specific documentation
   for what is supported here. Defaults to the empty string.
 

+- **Dir::Bin::Solvers**: absolute path of the directory where to look for
+  external solvers. Defaults to `/usr/lib/apt/solvers`.
+

 
 ## Protocol
 
 
 ## Protocol
 


@@ -106,23 +119,31 @@ Within a dependency solving scenario, a request represents the action on
 installed packages requested by the user.
 
 A request is a single Deb 822 stanza opened by a mandatory Request field
 installed packages requested by the user.
 
 A request is a single Deb 822 stanza opened by a mandatory Request field

-and followed by a mixture of action and preference fields.
+and followed by a mixture of action, preference, and global
+configuration fields.

 
 The value of the **Request:** field is a string describing the EDSP
 protocol which will be used to communicate. At present, the string must
 
 The value of the **Request:** field is a string describing the EDSP
 protocol which will be used to communicate. At present, the string must

-be `EDSP 0.3`.
+be `EDSP 0.5`. Request fields are mainly used to identify the beginning
+of a request stanza; their actual values are otherwise not used by the
+EDSP protocol.

 
 

-a unique request identifier, such as an
-UUID. Request fields are mainly used to identify the beginning of a
-request stanza; their actual values are otherwise not used by the EDSP
-protocol.
+The following **configuration fields** are supported in request stanzas:
+
+- **Architecture:** (mandatory) The name of the *native* architecture on
+  the user machine (see also: `dpkg --print-architecture`)
+
+- **Architectures:** (optional, defaults to the native architecture) A
+  space separated list of *all* architectures known to APT (this is
+  roughly equivalent to the union of `dpkg --print-architecture` and
+  `dpkg --print-foreign-architectures`)

 
 The following **action fields** are supported in request stanzas:
 
 - **Install:** (optional, defaults to the empty string) A space
 
 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
 
 - **Remove:** (optional, defaults to the empty string) Same syntax of
   Install. This field denotes a list of packages that the user wants to


@@ -189,7 +210,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
 - **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
 
 - **APT-Automatic:** (optional, defaults to `no`). Allowed values:
   `yes`, `no`. When set to `yes`, the corresponding package is marked by


@@ -197,6 +218,22 @@ field. The following fields are supported in package stanzas:
   should be removed by the solver only when the Autoremove action is
   requested (see Request section).
 
   should be removed by the solver only when the Autoremove action is
   requested (see Request section).
 

+- **APT-Release:** (optional) The releases the package belongs to, according to
+  APT. The format of this field is multiline with one value per line and the
+  first line (the one containing the field name) empty. Each subsequent line
+  corresponds to one of the releases the package belongs to and looks like
+  this: `o=Debian,a=unstable,n=sid,l=Debian,c=main`. That is, each release line
+  is a comma-separated list of "key=value" pairs, each of which denotes a
+  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
 ### Answer
 
 An answer from the external solver to APT is either a *solution* or an


@@ -205,11 +242,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
 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
 
 
 #### Solution