From cb3c3b6fda20ecfe5e6b2644da7391eb03845e91 Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Wed, 4 Sep 2013 17:04:09 +0200 Subject: EDSP doc: fix typo in Request stanza description --- doc/external-dependency-solver-protocol.txt | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'doc/external-dependency-solver-protocol.txt') diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index 7a124d8f9..3f2da2195 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -114,12 +114,9 @@ and followed by a mixture of action and preference 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.4`. - -a unique request identifier, such as an -UUID. Request fields are mainly used to identify the beginning of a -request stanza; their actual values are otherwise not used by the EDSP -protocol. +be `EDSP 0.4`. 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 **action fields** are supported in request stanzas: -- cgit v1.2.3 From 25252738d5ad6042b356f2d6bec2ca52ef08a1e2 Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Wed, 4 Sep 2013 17:06:11 +0200 Subject: EDSP: bump protocol version to 0.5 --- doc/external-dependency-solver-protocol.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/external-dependency-solver-protocol.txt') diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index 3f2da2195..7d41571de 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -1,4 +1,4 @@ -# APT External Dependency Solver Protocol (EDSP) - version 0.4 +# 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 @@ -114,7 +114,7 @@ and followed by a mixture of action and preference 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.4`. Request fields are mainly used to identify the beginning +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. -- cgit v1.2.3 From caa3279367401965cbdd5e3a41c47945f3e263bd Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Wed, 4 Sep 2013 17:13:49 +0200 Subject: EDSP: add Architecture(s) multi-arch fields to the Request stanza --- doc/external-dependency-solver-protocol.txt | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'doc/external-dependency-solver-protocol.txt') diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index 7d41571de..477bc23ed 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -110,7 +110,8 @@ 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 and preference fields. +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 @@ -118,6 +119,16 @@ 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: + +- **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 -- cgit v1.2.3 From b5ea5d4a5b8f82afb7bbe4c3eee07ae36f2fba9c Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Thu, 5 Sep 2013 10:54:12 +0200 Subject: EDSP: add APT-Release field to Package stanzas --- doc/external-dependency-solver-protocol.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'doc/external-dependency-solver-protocol.txt') diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index 477bc23ed..790f2f1ee 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -209,6 +209,15 @@ field. The following fields are supported in package stanzas: should be removed by the solver only when the Autoremove action is requested (see Request section). +- **APT-Release:** (optional) The releases the package belongs to, according to + APT. The format of this field is multiline with one value per line and the + first line (the one containing the field name) empty. Each subsequent line + corresponds to one of the releases the package belongs to and looks like + this: `o=Debian,a=unstable,n=sid,l=Debian,c=main`. That is, each release line + is a comma-separated list of "key=value" pairs, each of which denotes a + Release file entry (Origin, Label, Codename, etc.) in the format of + APT_PREFERENCES(5). + ### Answer An answer from the external solver to APT is either a *solution* or an -- cgit v1.2.3 From 4010ee76cb1a771d57f1339df725e962df23900e Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Tue, 17 Jun 2014 17:03:27 +0200 Subject: EDSP doc: clarify that Install/Remove packages are arch-qualified --- doc/external-dependency-solver-protocol.txt | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'doc/external-dependency-solver-protocol.txt') diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index 790f2f1ee..eb7832120 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -5,6 +5,14 @@ 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 "arch:package" where "arch" is a dpkg +architecture and "package" a dpkg package name. + + ## Components - **APT**: we know this one. @@ -132,9 +140,9 @@ The following **configuration fields** are supported in request stanzas: 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 @@ -201,7 +209,7 @@ field. The following fields are supported in package stanzas: - **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 with the same architecture. - **APT-Automatic:** (optional, defaults to `no`). Allowed values: `yes`, `no`. When set to `yes`, the corresponding package is marked by -- cgit v1.2.3 From 22c3ac52252b6eafe0d31485b18730cfb53a8dc3 Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Tue, 17 Jun 2014 17:04:09 +0200 Subject: EDSP doc: (minor) consistently use 2 blank lines before headings Git-Dch: Ignore --- doc/external-dependency-solver-protocol.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/external-dependency-solver-protocol.txt') diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index eb7832120..7db1479b2 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -70,6 +70,7 @@ configuration documentation for more, and more up to date, information. - **Dir::Bin::Solvers**: absolute path of the directory where to look for external solvers. Defaults to `/usr/lib/apt/solvers`. + ## Protocol When configured to use an external solver, APT will resort to it to @@ -226,6 +227,7 @@ field. The following fields are supported in package stanzas: Release file entry (Origin, Label, Codename, etc.) in the format of APT_PREFERENCES(5). + ### Answer An answer from the external solver to APT is either a *solution* or an -- cgit v1.2.3 From 82ced5c894cd013721f432ae8da66114155e04c7 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Tue, 17 Jun 2014 19:25:03 +0200 Subject: EDSP doc: some typo and wording fixes Git-Dch: Ignore --- doc/external-dependency-solver-protocol.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'doc/external-dependency-solver-protocol.txt') diff --git a/doc/external-dependency-solver-protocol.txt b/doc/external-dependency-solver-protocol.txt index 7db1479b2..14e9528c8 100644 --- a/doc/external-dependency-solver-protocol.txt +++ b/doc/external-dependency-solver-protocol.txt @@ -9,8 +9,8 @@ External Dependency Solver Protocol". 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 "arch:package" where "arch" is a dpkg -architecture and "package" a dpkg package name. +identifiers of the form "package:arch" where "package" is a package name +and "arch" a dpkg architecture. ## Components @@ -210,7 +210,7 @@ field. The following fields are supported in package stanzas: - **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 and with the same architecture. + name and architecture. - **APT-Automatic:** (optional, defaults to `no`). Allowed values: `yes`, `no`. When set to `yes`, the corresponding package is marked by @@ -236,11 +236,11 @@ 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 -- cgit v1.2.3