move special READMEs into doc/ and format as md

The formatting is very basic and more should probably be done, but we at
least get the files out of the root directory which in case of the
various READMEs was confusing salsa which one display as (central) README.

1 files changed, 301 insertions, 0 deletions

diff --git a/doc/external-installation-planner-protocol.md b/doc/external-installation-planner-protocol.md
new file mode 100644
index 000000000..4bad9da0a
--- /dev/null
+++ b/doc/external-installation-planner-protocol.md
@@ -0,0 +1,301 @@
+# 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
+
+- **APT**: we know this one.
+- APT is equipped with its own **internal planner** for the order of
+  package installation (and removal) which is identified by the string
+  `internal`.
+- **External planner**: an *external* software component able to plan an
+  installation on behalf of APT.
+
+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.
+
+- **APT::Planner**: the name of the planner to be used for dependency
+  solving.  Defaults to `internal`
+
+- **Dir::Bin::Planners**: absolute path of the directory where to look
+  for external solvers. Defaults to `/usr/lib/apt/planners`.
+
+
+## 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:
+
+- **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:
+
+- **Planner:** (optional, defaults to the empty string) a purely
+  informational string specifying to which planner this request was send
+  initially.
+
+- **Immediate-Configuration:** (option, unset by default) A boolean
+  value defining if the planner 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 planner 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 planner (if set to yes) to temporarily
+  remove an essential package. Associated with the APT::Force-LoopBreak
+  configuration option its main use is highlighting that planners 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 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:
+
+- 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 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:
+
+- **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 planner
+  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 planner 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 from the UTC timezone, in RFC 2822 format (see 'date -uR' as
+  an example). 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
+  planner.
+
+- **Message:** (optional). A textual message, meant to be read by the
+  APT user, telling what is going on within the installation planner
+  (e.g. the current phase of planning, as declared by the planner).
+
+
+# Future extensions
+
+Potential future extensions to this protocol are to be discussed on
+deity@lists.debian.org.