doc/apt-solver-protocol.mdwn

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