Merge remote-tracking branch 'mvo/feature/srcrec-enum2' into debian/sid

[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 ae01fbc35c46b24eaff484716ea8ee1350c6a203..790f2f1ee80a511f708a86f01589f5de687a92b4 100644 (file)
--- a/doc/external-dependency-solver-protocol.txt
+++ b/doc/external-dependency-solver-protocol.txt
@@ -1,4 +1,4 @@
-# APT External Dependency Solver Protocol (EDSP) - version 0.4
+# 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
@@ -47,7 +47,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.
 
-- **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
@@ -110,16 +110,24 @@ 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
-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
-be `EDSP 0.4`.
+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:
 
@@ -201,6 +209,15 @@ 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).
 
+- **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).
+
 ### Answer
 
 An answer from the external solver to APT is either a *solution* or an