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