summaryrefslogtreecommitdiff
path: root/doc/external-dependency-solver-protocol.txt
diff options
context:
space:
mode:
authorMichael Vogt <mvo@debian.org>2015-08-18 11:54:05 +0200
committerMichael Vogt <mvo@debian.org>2015-08-18 11:54:05 +0200
commit21248c0f00ee71412dbadc6ebf84011cf974346d (patch)
tree7dc1f5904399482d2128765b5b86d57a4ac5b3e1 /doc/external-dependency-solver-protocol.txt
parente5f34ad3b043abf033c1626eb8449b75955d6760 (diff)
parent4fc6b7570c3e97b65c118b58cdf6729fa94c9b03 (diff)
Merge branch 'debian/experimental' into feature/srv-records
Conflicts: cmdline/apt-helper.cc cmdline/makefile
Diffstat (limited to 'doc/external-dependency-solver-protocol.txt')
-rw-r--r--doc/external-dependency-solver-protocol.txt59
1 files changed, 43 insertions, 16 deletions
diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt
index 7a124d8f9..14e9528c8 100644
--- 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.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
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.
@@ -62,6 +70,7 @@ configuration documentation for more, and more up to date, information.
- **Dir::Bin::Solvers**: absolute path of the directory where to look for
external solvers. Defaults to `/usr/lib/apt/solvers`.
+
## Protocol
When configured to use an external solver, APT will resort to it to
@@ -110,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
-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:
- **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
@@ -193,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
- name.
+ name and architecture.
- **APT-Automatic:** (optional, defaults to `no`). Allowed values:
`yes`, `no`. When set to `yes`, the corresponding package is marked by
@@ -201,6 +218,16 @@ 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
@@ -209,11 +236,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