1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
** TENTATIVE PROPOSAL, VERY VERY VERY DRAFT **
# APT External Dependency Solver Protocol (EDSP) - version 0.1
This document describes the communication protocol between APT and
external dependency solvers. The protocol is called APT EDSP, for "APT
External Dependency Solver Protocol".
## Components
- **APT**: we know this one.
- APT is equipped with its own **internal solver** for dependencies,
which is identified by the string `internal`.
- **External solver**: an *external* software component able to resolve
dependencies on behalf of APT. Each external solver is identified by
an unique string (other than `internal`) called the solver **name**.
At each interaction with APT, a single solver is in use. When there is
a total of 2 or more solvers, internals or externals, the user can
choose which one to use.
## 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 file under `/usr/lib/apt/solvers` corresponding to an external
solver must be executable.
No non-solver files must be installed under `/usr/lib/apt/solvers`, so
that an index of available external solvers can be obtained by simply
looking at the content of that directory.
## Configuration
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
dependency solving. Defaults to `internal`
- **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::Preferences**: solver-specific user preferences used
during dependency solving. Check your solver documentation for what is
supported here. Default to empty.
## Protocol
When configured to use an external solver, APT will resort to it to
decide which packages should be installed or removed.
The interaction happens **in batch**: APT will invoke the external
solver passing the current status of installed and available packages,
as well as the user request to alter the set of installed packages. The
external solver will compute a new complete set of installed packages
and gives APT a "diff" listing of which *additional* packages should be
installed and of which currently installed packages should be
*removed*. (Note: the order in which those actions have to be performed
will be up to APT to decide.)
External solvers are invoked by executing them. Communications happens
via the file descriptors: **stdin** (standard input) and **stdout**
(standard output). stderr is not used by the EDSP protocol. Solvers can
therefore use stderr to dump debugging information that could be
inspected separately.
After invocation, the protocol passes through 3 separate phases:
1. APT send to the solver a dependency solving **scenario**
2. The solver solves dependencies. No communication with APT happens
during this phase.
3. The solver sends back to APT an **answer**, i.e. either a *solution*
or an *error* report.
### Scenario
A scenario is a text file encoded in a format very similar to the "Deb
822" format (AKA "the format used by Debian `Packages` files"). A
scenario consists of two distinct parts: a **request** and a **package
universe**, occurring in that order. The request consists of a single
Deb 822 stanza, while the package universe consists of several such
stanzas. All stanzas occurring in a scenario are separated by an empty
line.
#### Request
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.
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.1`.
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 **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.
- **Remove:** (optional, defaults to the empty string) Same syntax of
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`,
`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.
- **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.
The following **preference fields** are supported in request stanzas:
- **Strict-Pinning:** (optional, defaults to `yes`). Allowed values:
`yes`, `no`. When set to `yes`, APT pinning is strict, in the sense
that the solver must not propose to install packages which are not APT
candidates (see the `APT-Pin` and `APT-Candidate` fields in the
package universe). When set to `no`, the solver does only a best
effort attempt to install APT candidates. Usually, the value of this
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.
#### Package universe
A package universe is a list of Deb 822 stanzas, one per package, called
**package stanzas**. Each package stanzas starts with a Package
field. The following fields are supported in package stanzas:
- All fields supported by Debian Packages file (see one of the
`/var/lib/apt/lists/*Packages` file for an example), *with the
exception of the Description field* that is not allowed.
Among those fields, the following are mandatory: Package, Version,
Architecture.
- **Installed:** (optional, default value `no`). Allowed values: `yes`,
`no`. When set to `yes`, the corresponding package is currently
installed.
##TODO## changed with respect to current prototype, which uses Status
- **APT-ID:** (mandatory). Unique package identifier, according to APT.
- **APT-Pin:** (mandatory). Must be a non-negative integer. Package pin
value, according to current APT policy.
- **APT-Candidate:** (optional, default value `no`). Allowed values:
`yes`, `no`. When set to `yes`, the corresponding package is granted
to have the highest pinning value among all the packages having the
same name.
##TODO## what about multi-arch? is the pin value granted to be the
higest also across different architectures?
### Answer
An answer from the external solver to APT is either a *solution* or an
*error*.
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 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
A solution is a single Deb 822 stanza, starting with the field
Solution. The following fields are supported in solution stanzas:
- **Solution:** (mandatory). The value of this field is ignored,
although it should be a unique solution identifier, such as a UUID.
- **Install:** (optional, defaults to the empty string). A space
separated list of strings of the form `PACKAGE=VERSION` where
`PACKAGE` is a package name and `VERSION` is an available version of
that package. The list denotes a set of packages that must be
installed to satisfy user request.
- **Remove:** (optional, defaults to the empty string). Same as Install,
but denoting a set of packages that must be removed to satisfy user
request.
#### Error
An error is a single Deb 822 stanza, starting the field Error. The
following fields are supported in error stanzas:
- **Error:** (mandatory). The value of this field is ignored, although
it should be a unique error identifier, such as a UUID.
- **Message:** (mandatory). The value of this field is a text string,
meant to be read by humans, that explains the cause of the solver
error.
##TODO## can we support line continuations throughout this format? If
yes, they might come handy both for error stanzas and for solution
stanzas (which might have very long install/remove lines)
** TENTATIVE PROPOSAL, VERY VERY VERY DRAFT **
|
