"Fossies" - the Fresh Open Source Software Archive

Member "apt-2.2.4/doc/external-dependency-solver-protocol.md" (10 Jun 2021, 16393 Bytes) of package /linux/misc/apt-2.2.4.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

APT External Dependency Solver Protocol (EDSP) - version 0.5

This document describes the communication protocol between APT and 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

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.

Each solver is identified by an unique string, the solver name. Solver names must be formed using only alphanumeric ASCII characters, dashes, and underscores; solver names must start with a lowercase ASCII letter. The special name internal denotes APT's internal solver, is reserved, and cannot be used by external solvers.

Installation

Each external solver is installed as a file under Dir::Bin::Solvers (see below), which defaults to /usr/lib/apt/solvers. We will assume in the remainder of this section that such a default value is in effect.

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 listing 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.

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.

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 a sequence of phases:

  1. APT invokes the external solver
  2. APT send to the solver a dependency solving scenario
  3. The solver solves dependencies. During this phase the solver may send, repeatedly, progress information to APT.
  4. The solver sends back to APT an answer, i.e. either a solution or an error report.
  5. The external solver exits

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, preference, and global configuration 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.5. 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 configuration fields are supported in request stanzas:

The following action fields are supported in request stanzas:

The following preference fields are supported in request stanzas:

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:

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 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 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:

Remove stanzas are similar to install stanzas, but have Remove fields instead of Install fields.

Autoremove stanzas are similar to install stanzas, but have Autoremove fields instead of Install fields. Autoremove stanzas should be output so that APT can inform the user of which packages they can now autoremove, as a consequence of the executed action. However, this protocol makes no assumption on the fact that a subsequent invocation of an Autoremove action will actually remove the very same packages indicated by Autoremove stanzas in the former solution.

A package can't be installed in multiple versions at the same time, so for each package there can at most one version be selected either for installation or removal. This especially means that a solver is neither allowed to represent package upgrades as a remove of the installed version and the installation of another (the remove is implicit and must be omitted from the solution) nor is it supported to revert previous actions in the solution with later actions. APT is allowed to show warnings and might even misbehave in earlier versions if a solver is violating this assumption.

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 recommended that solvers either add unconditionally the fields Package, Version, and Architecture to all install/remove stanzas or, alternatively, that they support a --verbose command line flag that explicitly enables the output of those fields in solutions.

Error

An error is a single Deb 822 stanza, starting the field Error. The following fields are supported in error stanzas:

Progress

During dependency solving, an external solver may send progress information to APT using progress stanzas. A progress stanza starts with the Progress field and might contain the following fields:

Future extensions

Potential future extensions to this protocol, listed in no specific order, include: