doc/external-dependency-solver-protocol.txt

   1 # APT External Dependency Solver Protocol (EDSP) - version 0.5
   2
   3 This document describes the communication protocol between APT and
   4 external dependency solvers. The protocol is called APT EDSP, for "APT
   5 External Dependency Solver Protocol".
   6
   7
   8 ## Components
   9
  10 - **APT**: we know this one.
  11 - APT is equipped with its own **internal solver** for dependencies,
  12   which is identified by the string `internal`.
  13 - **External solver**: an *external* software component able to resolve
  14   dependencies on behalf of APT.
  15
  16 At each interaction with APT, a single solver is in use.  When there is
  17 a total of 2 or more solvers, internals or externals, the user can
  18 choose which one to use.
  19
  20 Each solver is identified by an unique string, the **solver
  21 name**. Solver names must be formed using only alphanumeric ASCII
  22 characters, dashes, and underscores; solver names must start with a
  23 lowercase ASCII letter. The special name `internal` denotes APT's
  24 internal solver, is reserved, and cannot be used by external solvers.
  25
  26
  27 ## Installation
  28
  29 Each external solver is installed as a file under Dir::Bin::Solvers (see
  30 below), which defaults to `/usr/lib/apt/solvers`. We will assume in the
  31 remainder of this section that such a default value is in effect.
  32
  33 The naming scheme is `/usr/lib/apt/solvers/NAME`, where `NAME` is the
  34 name of the external solver.
  35
  36 Each file under `/usr/lib/apt/solvers` corresponding to an external
  37 solver must be executable.
  38
  39 No non-solver files must be installed under `/usr/lib/apt/solvers`, so
  40 that an index of available external solvers can be obtained by listing
  41 the content of that directory.
  42
  43
  44 ## Configuration
  45
  46 Several APT options can be used to affect dependency solving in APT. An
  47 overview of them is given below. Please refer to proper APT
  48 configuration documentation for more, and more up to date, information.
  49
  50 - **APT::Solver**: the name of the solver to be used for
  51   dependency solving. Defaults to `internal`
  52
  53 - **APT::Solver::Strict-Pinning**: whether pinning must be strictly
  54   respected (as the internal solver does) or can be slightly deviated
  55   from. Defaults to `yes`.
  56
  57 - **APT::Solver::NAME::Preferences** (where NAME is a solver name):
  58   solver-specific user preference string used during dependency solving,
  59   when the solver NAME is in use. Check solver-specific documentation
  60   for what is supported here. Defaults to the empty string.
  61
  62 - **Dir::Bin::Solvers**: absolute path of the directory where to look for
  63   external solvers. Defaults to `/usr/lib/apt/solvers`.
  64
  65 ## Protocol
  66
  67 When configured to use an external solver, APT will resort to it to
  68 decide which packages should be installed or removed.
  69
  70 The interaction happens **in batch**: APT will invoke the external
  71 solver passing the current status of installed and available packages,
  72 as well as the user request to alter the set of installed packages. The
  73 external solver will compute a new complete set of installed packages
  74 and gives APT a "diff" listing of which *additional* packages should be
  75 installed and of which currently installed packages should be
  76 *removed*. (Note: the order in which those actions have to be performed
  77 will be up to APT to decide.)
  78
  79 External solvers are invoked by executing them. Communications happens
  80 via the file descriptors: **stdin** (standard input) and **stdout**
  81 (standard output). stderr is not used by the EDSP protocol. Solvers can
  82 therefore use stderr to dump debugging information that could be
  83 inspected separately.
  84
  85 After invocation, the protocol passes through a sequence of phases:
  86
  87 1. APT invokes the external solver
  88 2. APT send to the solver a dependency solving **scenario**
  89 3. The solver solves dependencies. During this phase the solver may
  90    send, repeatedly, **progress** information to APT.
  91 4. The solver sends back to APT an **answer**, i.e. either a *solution*
  92    or an *error* report.
  93 5. The external solver exits
  94
  95
  96 ### Scenario
  97
  98 A scenario is a text file encoded in a format very similar to the "Deb
  99 822" format (AKA "the format used by Debian `Packages` files"). A
 100 scenario consists of two distinct parts: a **request** and a **package
 101 universe**, occurring in that order. The request consists of a single
 102 Deb 822 stanza, while the package universe consists of several such
 103 stanzas. All stanzas occurring in a scenario are separated by an empty
 104 line.
 105
 106
 107 #### Request
 108
 109 Within a dependency solving scenario, a request represents the action on
 110 installed packages requested by the user.
 111
 112 A request is a single Deb 822 stanza opened by a mandatory Request field
 113 and followed by a mixture of action, preference, and global
 114 configuration fields.
 115
 116 The value of the **Request:** field is a string describing the EDSP
 117 protocol which will be used to communicate. At present, the string must
 118 be `EDSP 0.5`. Request fields are mainly used to identify the beginning
 119 of a request stanza; their actual values are otherwise not used by the
 120 EDSP protocol.
 121
 122 The following **configuration fields** are supported in request stanzas:
 123
 124 - **Architecture:** (mandatory) The name of the *native* architecture on
 125   the user machine (see also: `dpkg --print-architecture`)
 126
 127 - **Architectures:** (optional, defaults to the native architecture) A
 128   space separated list of *all* architectures known to APT (this is
 129   roughly equivalent to the union of `dpkg --print-architecture` and
 130   `dpkg --print-foreign-architectures`)
 131
 132 The following **action fields** are supported in request stanzas:
 133
 134 - **Install:** (optional, defaults to the empty string) A space
 135   separated list of package names, with *no version attached*, to
 136   install. This field denotes a list of packages that the user wants to
 137   install, usually via an APT `install` request.
 138
 139 - **Remove:** (optional, defaults to the empty string) Same syntax of
 140   Install. This field denotes a list of packages that the user wants to
 141   remove, usually via APT `remove` or `purge` requests.
 142
 143 - **Upgrade:** (optional, defaults to `no`). Allowed values: `yes`,
 144   `no`. When set to `yes`, an upgrade of all installed packages has been
 145   requested, usually via an APT `upgrade` request.
 146
 147 - **Dist-Upgrade:** (optional, defaults to `no`). Allowed values: `yes`,
 148   `no`. Same as Upgrade, but for APT `dist-upgrade` requests.
 149
 150 - **Autoremove:** (optional, defaults to `no`). Allowed values: `yes`,
 151   `no`. When set to `yes`, a clean up of unused automatically installed
 152   packages has been requested, usually via an APT `autoremove` request.
 153
 154 The following **preference fields** are supported in request stanzas:
 155
 156 - **Strict-Pinning:** (optional, defaults to `yes`). Allowed values:
 157   `yes`, `no`. When set to `yes`, APT pinning is strict, in the sense
 158   that the solver must not propose to install packages which are not APT
 159   candidates (see the `APT-Pin` and `APT-Candidate` fields in the
 160   package universe). When set to `no`, the solver does only a best
 161   effort attempt to install APT candidates. Usually, the value of this
 162   field comes from the `APT::Solver::Strict-Pinning` configuration
 163   option.
 164
 165 - **Preferences:** a solver-specific optimization string, usually coming
 166   from the `APT::Solver::Preferences` configuration option.
 167
 168
 169 #### Package universe
 170
 171 A package universe is a list of Deb 822 stanzas, one per package, called
 172 **package stanzas**. Each package stanzas starts with a Package
 173 field. The following fields are supported in package stanzas:
 174
 175 - All fields contained in the dpkg database, with the exception of
 176   fields marked as "internal" (see the manpage `dpkg-query (1)`). Among
 177   those fields, the following are mandatory for all package stanzas:
 178   Package, Version, Architecture.
 179
 180   It is recommended not to pass the Description field to external
 181   solvers or, alternatively, to trim it to the short description only.
 182
 183 - **Installed:** (optional, defaults to `no`). Allowed values: `yes`,
 184   `no`. When set to `yes`, the corresponding package is currently
 185   installed.
 186
 187   Note: the Status field present in the dpkg database must not be passed
 188   to the external solver, as it's an internal dpkg field. Installed and
 189   other fields permit to encode the most relevant aspects of Status in
 190   communications with solvers.
 191
 192 - **Hold:** (optional, defaults to `no`). Allowed values: `yes`,
 193   `no`. When set to `yes`, the corresponding package is marked as "on
 194   hold" by dpkg.
 195
 196 - **APT-ID:** (mandatory). Unique package identifier, according to APT.
 197
 198 - **APT-Pin:** (mandatory). Must be an integer. Package pin value,
 199   according to APT policy.
 200
 201 - **APT-Candidate:** (optional, defaults to `no`). Allowed values:
 202   `yes`, `no`. When set to `yes`, the corresponding package is the APT
 203   candidate for installation among all available packages with the same
 204   name.
 205
 206 - **APT-Automatic:** (optional, defaults to `no`). Allowed values:
 207   `yes`, `no`. When set to `yes`, the corresponding package is marked by
 208   APT as automatic installed. Note that automatic installed packages
 209   should be removed by the solver only when the Autoremove action is
 210   requested (see Request section).
 211
 212 - **APT-Release:** (optional) The releases the package belongs to, according to
 213   APT. The format of this field is multiline with one value per line and the
 214   first line (the one containing the field name) empty. Each subsequent line
 215   corresponds to one of the releases the package belongs to and looks like
 216   this: `o=Debian,a=unstable,n=sid,l=Debian,c=main`. That is, each release line
 217   is a comma-separated list of "key=value" pairs, each of which denotes a
 218   Release file entry (Origin, Label, Codename, etc.) in the format of
 219   APT_PREFERENCES(5).
 220
 221 ### Answer
 222
 223 An answer from the external solver to APT is either a *solution* or an
 224 *error*.
 225
 226 The following invariant on **exit codes** must hold true. When the
 227 external solver is *able to find a solution*, it will write the solution
 228 to standard output and then exit with an exit code of 0. When the
 229 external solver is *unable to find a solution* (and s aware of that), it
 230 will write an error to standard output and then exit with an exit code
 231 of 0. An exit code other than 0 will be interpreted as a solver crash
 232 with no meaningful error about dependency resolution to convey to the
 233 user.
 234
 235
 236 #### Solution
 237
 238 A solution is a list of Deb 822 stanzas. Each of them could be an
 239 install stanza (telling APT to install a specific package), a remove
 240 stanza (telling APT to remove one), or an autoremove stanza (telling APT
 241 about the *future* possibility of removing a package using the
 242 Autoremove action).
 243
 244 An **install stanza** starts with an Install field and supports the
 245 following fields:
 246
 247 - **Install:** (mandatory). The value is a package identifier,
 248   referencing one of the package stanzas of the package universe via its
 249   APT-ID field.
 250
 251 - All fields supported by package stanzas.
 252
 253 **Remove stanzas** are similar to install stanzas, but have **Remove**
 254 fields instead of Install fields.
 255
 256 **Autoremove stanzas** are similar to install stanzas, but have
 257 **Autoremove** fields instead of Install fields. Autoremove stanzas
 258 should be output so that APT can inform the user of which packages they
 259 can now autoremove, as a consequence of the executed action. However,
 260 this protocol makes no assumption on the fact that a subsequent
 261 invocation of an Autoremove action will actually remove the very same
 262 packages indicated by Autoremove stanzas in the former solution.
 263
 264 In terms of expressivity, install and remove stanzas can carry one
 265 single field each, as APT-IDs are enough to pinpoint packages to be
 266 installed/removed. Nonetheless, for protocol readability, it is
 267 recommended that solvers either add unconditionally the fields Package,
 268 Version, and Architecture to all install/remove stanzas or,
 269 alternatively, that they support a `--verbose` command line flag that
 270 explicitly enables the output of those fields in solutions.
 271
 272
 273 #### Error
 274
 275 An error is a single Deb 822 stanza, starting the field Error. The
 276 following fields are supported in error stanzas:
 277
 278 - **Error:** (mandatory). The value of this field is ignored, although
 279   it should be a unique error identifier, such as a UUID.
 280
 281 - **Message:** (mandatory). The value of this field is a text string,
 282   meant to be read by humans, that explains the cause of the solver
 283   error. Message fields might be multi-line, like the Description field
 284   in the dpkg database. The first line conveys a short message, which
 285   can be explained in more details using subsequent lines.
 286
 287
 288 ### Progress
 289
 290 During dependency solving, an external solver may send progress
 291 information to APT using **progress stanzas**. A progress stanza starts
 292 with the Progress field and might contain the following fields:
 293
 294 - **Progress:** (mandatory). The value of this field is a date and time
 295   timestamp, in RFC 2822 format. The timestamp provides a time
 296   annotation for the progress report.
 297
 298 - **Percentage:** (optional). An integer from 0 to 100, representing the
 299   completion of the dependency solving process, as declared by the
 300   solver.
 301
 302 - **Message:** (optional). A textual message, meant to be read by the
 303   APT user, telling what is going on within the dependency solving
 304   (e.g. the current phase of dependency solving, as declared by the
 305   solver).
 306
 307
 308 # Future extensions
 309
 310 Potential future extensions to this protocol, listed in no specific
 311 order, include:
 312
 313 - fixed error types to identify common failures across solvers and
 314   enable APT to translate error messages
 315 - structured error data to explain failures in terms of packages and
 316   dependencies