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.
- **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
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
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
- **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
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
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
-A solution is a list of Deb 822 stanzas. Each of them could be an
-install stanza (telling APT to install a specific package), a remove
-stanza (telling APT to remove one), or an autoremove stanza (telling APT
-about the *future* possibility of removing a package using the
-Autoremove action).
+A solution is a list of Deb 822 stanzas. Each of them could be an install
+stanza (telling APT to install a specific new package or to upgrade or
+downgrade a package to a specific version), a remove stanza (telling APT to
+remove one), or an autoremove stanza (telling APT about the *future*
+possibility of removing a package using the Autoremove action).
An **install stanza** starts with an Install field and supports the
following fields:
invocation of an Autoremove action will actually remove the very same
packages indicated by Autoremove stanzas in the former solution.
+The package identifiers of install, remove and autoremove stanzas from a single
+solution are unique. That is, a package identifier does not occur more than
+once in the solution. Every package identifier is only associated with a single
+action (either install, remove or autoremove).
+
In terms of expressivity, install and remove stanzas can carry one
single field each, as APT-IDs are enough to pinpoint packages to be
installed/removed. Nonetheless, for protocol readability, it is
projects / apt.git / blobdiff