eipp: rename stanza 'Install' to 'Unpack'

Freeing 'Install' for future use as an interface for "dpkg --install",
which is currently not used by any existent planer, so the
implementation of it itself will be delayed until then.

3 files changed, 44 insertions, 5 deletions

diff --git a/apt-pkg/edsp.cc b/apt-pkg/edsp.cc
index 1c6be8afe..805a37bb3 100644
--- a/apt-pkg/edsp.cc
+++ b/apt-pkg/edsp.cc
@@ -1314,8 +1314,8 @@ bool EIPP::ReadResponse(int const input, pkgPackageManager * const PM, OpProgres
 	 std::cerr << "The following information might help you to understand what is wrong:" << std::endl;
 	 std::cerr << msg << std::endl << std::endl;
 	 return false;
-      } else if (section.Exists("Install") == true)
-	 type = "Install";
+      } else if (section.Exists("Unpack") == true)
+	 type = "Unpack";
       else if (section.Exists("Configure") == true)
 	 type = "Configure";
       else if (section.Exists("Remove") == true)
@@ -1340,7 +1340,7 @@ bool EIPP::ReadResponse(int const input, pkgPackageManager * const PM, OpProgres
 
       pkgCache::VerIterator Ver(PM->Cache.GetCache(), PM->Cache.GetCache().VerP + VerIdx[id]);
       auto const Pkg = Ver.ParentPkg();
-      if (strcmp(type, "Install") == 0)
+      if (strcmp(type, "Unpack") == 0)
 	 PM->Install(Pkg, PM->FileNames[Pkg->ID]);
       else if (strcmp(type, "Configure") == 0)
 	 PM->Configure(Pkg);
diff --git a/cmdline/apt-internal-planer.cc b/cmdline/apt-internal-planer.cc
index 56d4f8afd..2d5f44c6a 100644
--- a/cmdline/apt-internal-planer.cc
+++ b/cmdline/apt-internal-planer.cc
@@ -72,7 +72,7 @@ protected:
    virtual bool Install(PkgIterator Pkg,std::string) APT_OVERRIDE
    {
       //std::cerr << "INSTALL: " << APT::PrettyPkg(&Cache, Pkg) << std::endl;
-      return EDSP::WriteSolutionStanza(output, "Install", Cache[Pkg].InstVerIter(Cache));
+      return EDSP::WriteSolutionStanza(output, "Unpack", Cache[Pkg].InstVerIter(Cache));
    }
    virtual bool Configure(PkgIterator Pkg) APT_OVERRIDE
    {
diff --git a/doc/external-installation-planer-protocol.txt b/doc/external-installation-planer-protocol.txt
index 2a0bdbee3..916982ca1 100644
--- a/doc/external-installation-planer-protocol.txt
+++ b/doc/external-installation-planer-protocol.txt
@@ -216,8 +216,47 @@ the user.
 
 #### Solution
 
-  TODO
+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