X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/caa3279367401965cbdd5e3a41c47945f3e263bd..eb1000f6e5fa7035c764d0e7aa9ca71c7aa8d52d:/doc/external-dependency-solver-protocol.txt?ds=sidebyside diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index 477bc23ed..e2bd95866 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -5,6 +5,14 @@ external dependency solvers. The protocol is called APT EDSP, for "APT External Dependency Solver Protocol". +## Terminology + +In the following we use the term **architecture qualified package name** +(or *arch-qualified package names* for short) to refer to package +identifiers of the form "package:arch" where "package" is a package name +and "arch" a dpkg architecture. + + ## Components - **APT**: we know this one. @@ -50,17 +58,25 @@ configuration documentation for more, and more up to date, information. - **APT::Solver**: the name of the solver to be used for dependency solving. Defaults to `internal` +- **Dir::Bin::Solvers**: absolute path of the directory where to look for + external solvers. Defaults to `/usr/lib/apt/solvers`. + - **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::NAME::Preferences** (where NAME is a solver name): - solver-specific user preference string used during dependency solving, - when the solver NAME is in use. Check solver-specific documentation - for what is supported here. Defaults to the empty string. +- **APT::Solver::Preferences**: user preference string used during + dependency solving by the requested solver. Check the documentation + of the solver you are using if and what is supported as a value here. + Defaults to the empty string. + +The options **Strict-Pinning** and **Preferences** can also be set for +a specific solver only via **APT::Solver::NAME::Strict-Pinning** and +**APT::Solver::NAME::Preferences** respectively where `NAME` is the name +of the external solver this option should apply to. These options if set +override the generic options; for simplicity the documentation will +refer only to the generic options. -- **Dir::Bin::Solvers**: absolute path of the directory where to look for - external solvers. Defaults to `/usr/lib/apt/solvers`. ## Protocol @@ -132,9 +148,9 @@ The following **configuration fields** are supported in request stanzas: 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. + separated list of arch-qualified 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 @@ -162,8 +178,13 @@ The following **preference fields** are supported in request stanzas: 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. +- **Solver:** (optional, defaults to the empty string) a purely + informational string specifying to which solver this request was send + initially. + +- **Preferences:** (optional, defaults to the empty string) + a solver-specific optimization string, usually coming from the + `APT::Solver::Preferences` configuration option. #### Package universe @@ -201,7 +222,7 @@ field. The following fields are supported in package stanzas: - **APT-Candidate:** (optional, defaults to `no`). Allowed values: `yes`, `no`. When set to `yes`, the corresponding package is the APT candidate for installation among all available packages with the same - name. + name and architecture. - **APT-Automatic:** (optional, defaults to `no`). Allowed values: `yes`, `no`. When set to `yes`, the corresponding package is marked by @@ -209,6 +230,22 @@ field. The following fields are supported in package stanzas: should be removed by the solver only when the Autoremove action is requested (see Request section). +- **APT-Release:** (optional) The releases the package belongs to, according to + APT. The format of this field is multiline with one value per line and the + first line (the one containing the field name) empty. Each subsequent line + corresponds to one of the releases the package belongs to and looks like + this: `o=Debian,a=unstable,n=sid,l=Debian,c=main`. That is, each release line + is a comma-separated list of "key=value" pairs, each of which denotes a + Release file entry (Origin, Label, Codename, etc.) in the format of + APT_PREFERENCES(5). + +- **Source:** (optional) The name of the source package the binary + package this record is for was built from. + This field does NOT include the version of the source package unlike + the Source field in the dpkg database. The version is optionally + available in the **Source-Version:** field. + + ### Answer An answer from the external solver to APT is either a *solution* or an @@ -217,11 +254,11 @@ An answer from the external solver to APT is either a *solution* or an 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 s 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. +external solver is *unable to find a solution* (and is 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