From 8e99b22c31eb47d0422e9a69e83dc99bb315ded8 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Wed, 29 Jun 2016 09:16:53 +0200 Subject: eipp: let apt make a plan, not make stuff plane Julian noticed on IRC that I fall victim to a lovely false friend by calling referring to a 'planer' all the time even through these are machines to e.g. remove splinters from woodwork ("make stuff plane"). The term I meant is written in german in this way (= with a single n) but in english there are two, aka: 'planner'. As that is unreleased code switching all instances without any transitional provisions. Also the reason why its skipped in changelog. Thanks: Julian Andres Klode Gbp-Dch: Ignore --- doc/external-installation-planer-protocol.txt | 298 -------------------------- 1 file changed, 298 deletions(-) delete mode 100644 doc/external-installation-planer-protocol.txt (limited to 'doc/external-installation-planer-protocol.txt') diff --git a/doc/external-installation-planer-protocol.txt b/doc/external-installation-planer-protocol.txt deleted file mode 100644 index 916982ca1..000000000 --- a/doc/external-installation-planer-protocol.txt +++ /dev/null @@ -1,298 +0,0 @@ -# APT External Installation Planer Protocol (EIPP) - version 0.1 - -This document describes the communication protocol between APT and -external installation planer. The protocol is called APT EIPP, for "APT -External Installation Planer 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 is equipped with its own **internal planer** for the order of - package installation (and removal) which is identified by the string - `internal`. -- **External planer**: an *external* software component able to plan an - installation on behalf of APT. - -At each interaction with APT, a single planer is in use. When there is -a total of 2 or more planers, internals or externals, the user can -choose which one to use. - -Each planer is identified by an unique string, the **planer name**. -Planer names must be formed using only alphanumeric ASCII characters, -dashes, and underscores; planer names must start with a lowercase ASCII -letter. The special name `internal` denotes APT's internal planer, is -reserved, and cannot be used by external planers. - - -## Installation - -Each external planer is installed as a file under Dir::Bin::Planers (see -below), which defaults to `/usr/lib/apt/planers`. We will assume in the -remainder of this section that such a default value is in effect. - -The naming scheme is `/usr/lib/apt/planers/NAME`, where `NAME` is the -name of the external planer. - -Each file under `/usr/lib/apt/planers` corresponding to an external -planer must be executable. - -No non-planer files must be installed under `/usr/lib/apt/planers`, so -that an index of available external planers 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. - -- **APT::Planer**: the name of the planer to be used for dependency - solving. Defaults to `internal` - -- **Dir::Bin::Planers**: absolute path of the directory where to look - for external solvers. Defaults to `/usr/lib/apt/planers`. - - -## Protocol - -When configured to use an external planer, 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 -planer 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 planer -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 planers 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. Planers 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 planer -2. APT send to the planer an installation planer **scenario** -3. The planer calculates the order. During this phase the planer may - send, repeatedly, **progress** information to APT. -4. The planer sends back to APT an **answer**, i.e. either a *solution* - or an *error* report. -5. The external planer 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 planer 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 planer 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 planer 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: - -- **Architecture:** (mandatory) The name of the *native* architecture on - the user machine (see also: `dpkg --print-architecture`) - -- **Architectures:** (optional, defaults to the native architecture) A - space separated list of *all* architectures known to APT (this is - roughly equivalent to the union of `dpkg --print-architecture` and - `dpkg --print-foreign-architectures`) - -The following **action fields** are supported in request stanzas: - -- **Install:** (optional, defaults to the empty string) A space - 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 - remove, usually via APT `remove` or `purge` requests. - -- **ReInstall:** (optional, defaults to the empty string) Same syntax of - Install. This field denotes a list of packages which are installed, - but should be reinstalled again e.g. because files shipped by that - package were removed or corrupted accidentally, usually requested via - an APT `install` request with the `--reinstall` flag. - -The following **preference fields** are supported in request stanzas: - -- **Planer:** (optional, defaults to the empty string) a purely - informational string specifying to which planer this request was send - initially. - -- **Immediate-Configuration:** (option, unset by default) A boolean - value defining if the planer should try to configure all packages as - quickly as possible (true) or shouldn't perform any kind of immediate - configuration at all (false). If not explicitly set with this field - the planer is free to pick either mode or implementing e.g. a mode - which configures only packages immediately if they are flagged as - `Essential` (or are dependencies of packages marked as `Essential`). - -- **Allow-Temporary-Remove-of-Essentials** (optional, defaults to `no`). - A boolean value allowing the planer (if set to yes) to temporarily - remove an essential package. Associated with the APT::Force-LoopBreak - configuration option its main use is highlighting that planers who do - temporary removes must take special care in terms of essentials. Legit - uses of this option by users is very uncommon, traditionally - a situation in which it is needed indicates a packaging error. - - -#### 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: - -- The fields Package, Version, Architecture (all mandatory) and - Multi-Arch, Pre-Depends, Depends, Conflicts, Breaks, Essential - (optional) as they are contained in the dpkg database (see the manpage - `dpkg-query (1)`). - -- **Status:** (optional, defaults to `uninstalled`). Allowed values are - the "package status" names as listed in `dpkg-query (1)` and visible - e.g. in the dpkg database as the second value in the space separated - list of values in the Status field there. In other words: Neither - desired action nor error flags are present in this field in EIPP! - -- **APT-ID:** (mandatory). Unique package identifier, according to APT. - - -### Answer - -An answer from the external planer to APT is either a *solution* or an -*error*. - -The following invariant on **exit codes** must hold true. When the -external planer 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 planer 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 planer -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: - -- unpack stanza to cause the extraction of a package to the disk - -- configure stanza to cause an unpacked package to be configured and - therefore the installation to be completed - -- remove stanza to cause the removal of a package from the system - -An **unpack stanza** starts with an Unpack field and supports the -following fields: - -- **Unpack:** (mandatory). The value is a package identifier, - referencing one of the package stanzas of the package universe via its - APT-ID field. - -- All fields supported by package stanzas. - -**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 planer 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 planer is not allowed to -produce a solution in which a package remains unconfigured. - -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 planers 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: - -- **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 planer - error. Message fields might be multi-line, like the Description field - in the dpkg database. The first line conveys a short message, which - can be explained in more details using subsequent lines. - - -### Progress - -During dependency solving, an external planer may send progress -information to APT using **progress stanzas**. A progress stanza starts -with the Progress field and might contain the following fields: - -- **Progress:** (mandatory). The value of this field is a date and time - timestamp, in RFC 2822 format. The timestamp provides a time - annotation for the progress report. - -- **Percentage:** (optional). An integer from 0 to 100, representing the - completion of the installation planning process, as declared by the - planer. - -- **Message:** (optional). A textual message, meant to be read by the - APT user, telling what is going on within the installation planer - (e.g. the current phase of planning, as declared by the planer). - - -# Future extensions - -Potential future extensions to this protocol are to be discussed on -deity@lists.debian.org. -- cgit v1.2.3