diff options
| -rw-r--r-- | doc/apt-solver-protocol.mdwn | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/doc/apt-solver-protocol.mdwn b/doc/apt-solver-protocol.mdwn new file mode 100644 index 000000000..b1435102e --- /dev/null +++ b/doc/apt-solver-protocol.mdwn @@ -0,0 +1,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 ** |