"Fossies" - the Fresh Open Source Software Archive

Member "apt-1.8.4/doc/external-installation-planner-protocol.md" (19 Sep 2019, 12926 Bytes) of package /linux/misc/apt-1.8.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 Installation Planner Protocol (EIPP) - version 0.1

This document describes the communication protocol between APT and external installation planner. The protocol is called APT EIPP, for “APT External Installation Planner 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 planner is in use. When there is a total of 2 or more planners, internals or externals, the user can choose which one to use.

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

Installation

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

The naming scheme is /usr/lib/apt/planners/NAME, where NAME is the name of the external planner.

Each file under /usr/lib/apt/planners corresponding to an external planner must be executable.

No non-planner files must be installed under /usr/lib/apt/planners, so that an index of available external planners can be obtained by listing the content of that directory.

Configuration

Several APT options can be used to affect installation planing in APT. An overview of them is given below. Please refer to proper APT configuration documentation for more, and more up to date, information.

Protocol

When configured to use an external planner, APT will resort to it to decide in which order packages should be installed, configured and removed.

The interaction happens in batch: APT will invoke the external planner passing the current status of (half-)installed packages and of packages which should be installed, as well as a request denoting the packages to install, reinstall, remove and purge. The external planner will compute a valid plan of when and how to call the low-level package manager (like dpkg) with each package to satisfy the request.

External planners are invoked by executing them. Communications happens via the file descriptors: stdin (standard input) and stdout (standard output). stderr is not used by the EIPP protocol. Planners 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 planner
  2. APT send to the planner an installation planner scenario
  3. The planner calculates the order. During this phase the planner may send, repeatedly, progress information to APT.
  4. The planner sends back to APT an answer, i.e. either a solution or an error report.
  5. The external planner 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 an installation planner scenario, a request represents the action on packages requested by the user explicitly as well as potentially additions calculated by a dependency resolver which the user has accepted.

An installation planner is not allowed to suggest the modification of package states (e.g. removing additional packages) even if it can’t calculate a solution otherwise – the planner must error out in such a case. An exception is made for scenarios which contain packages which aren’t completely installed (like half-installed or trigger-awaiting): Solvers are free to move these packages to a fully installed state (but are still forbidden to remove them).

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 EIPP protocol which will be used to communicate and especially which answers APT will understand. At present, the string must be EIPP 0.1. Request fields are mainly used to identify the beginning of a request stanza; their actual values are otherwise not used by the EIPP 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 planner to APT is either a solution or an error.

The following invariant on exit codes must hold true. When the external planner 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 planner 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 planner 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:

An unpack stanza starts with an Unpack field and supports the following fields:

Configure and Remove stanzas require and support the same fields with the exception of the Unpack field which is replaced in these instances with the Configure or Remove field respectively.

The order of the stanzas is significant (unlike in the EDSP protocol), with the first stanza being the first performed action. If multiple stanzas of the same type appear in direct succession the order in such a set isn’t significant through.

The solution needs to be valid (it is not allowed to configure a package before it was unpacked, dependency relations must be satisfied, …), but they don’t need to be complete: A planner can and should expect that any package which wasn’t explicitly configured will be configured at the end automatically. That also means through that a planner is not allowed to produce a solution in which a package remains unconfigured. Also, packages which are requested to be removed will be automatically removed at the end if not marked for removal explicitly earlier.

In terms of expressivity, all 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 planners 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 planner 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 are to be discussed on deity@lists.debian.org.