12/12: doc: Add section about inferiors.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 92a9f14b9d2ae08f5d8f30149963c1e326dd37a6
Author: Ludovic Courtès <address@hidden>
Date:   Fri Sep 21 17:03:52 2018 +0200

    doc: Add section about inferiors.
    
    * doc/guix.texi (Inferiors): New node.
    (Channels): Add xref to "Inferiors".
---
 doc/guix.texi | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index b925485..76ec718 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -147,6 +147,7 @@ Package Management
 * Invoking guix gc::            Running the garbage collector.
 * Invoking guix pull::          Fetching the latest Guix and distribution.
 * Channels::                    Customizing the package collection.
+* Inferiors::                   Interacting with another revision of Guix.
 * Invoking guix describe::      Display information about your Guix revision.
 * Invoking guix pack::          Creating software bundles.
 * Invoking guix archive::       Exporting and importing store files.
@@ -1699,6 +1700,7 @@ guix package -i emacs-guix
 * Invoking guix gc::            Running the garbage collector.
 * Invoking guix pull::          Fetching the latest Guix and distribution.
 * Channels::                    Customizing the package collection.
+* Inferiors::                   Interacting with another revision of Guix.
 * Invoking guix describe::      Display information about your Guix revision.
 * Invoking guix pack::          Creating software bundles.
 * Invoking guix archive::       Exporting and importing store files.
@@ -3053,6 +3055,135 @@ package it defines.
 This gives you super powers, allowing you to track the provenance of binary
 artifacts with very fine grain, and to reproduce software environments at
 will---some sort of ``meta reproducibility'' capabilities, if you will.
address@hidden, for another way to take advantage of these super powers.
+
address@hidden Inferiors
address@hidden Inferiors
+
address@hidden TODO: Remove this once we're more confident about API stability.
address@hidden Note
+The functionality described here is a ``technology preview'' as of version
address@hidden  As such, the interface is subject to change.
address@hidden quotation
+
address@hidden inferiors
address@hidden composition of Guix revisions
+Sometimes you might need to mix packages from the revision of Guix you're
+currently running with packages available in a different revision of Guix.
+Guix @dfn{inferiors} allow you to achieve that by composing different Guix
+revisions in arbitrary ways.
+
address@hidden inferior packages
+Technically, an ``inferior'' is essentially a separate Guix process connected
+to your main Guix process through a REPL (@pxref{Invoking guix repl}).  The
address@hidden(guix inferior)} module allows you to create inferiors and to
+communicate with them.  It also provides a high-level interface to browse and
+manipulate the packages that an inferior address@hidden packages}.
+
+When combined with channels (@pxref{Channels}), inferiors provide a simple way
+to interact with a separate revision of Guix.  For example, let's assume you
+want to install in your profile the current @code{guile} package, along with
+the @code{guile-json} as it existed in an older revision of Guix---perhaps
+because the newer @code{guile-json} has an incompatible API and you want to
+run your code against the old address@hidden  To do that, you could write a 
manifest for
+use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
+manifest, you would create an inferior for that old Guix revision you care
+about, and you would look up the @code{guile-json} package in the inferior:
+
address@hidden
+(use-modules (guix inferior) (guix channels)
+             (srfi srfi-1))   ;for 'first'
+
+(define channels
+  ;; This is the old revision from which we want to
+  ;; extract guile-json.
+  (list (channel
+         (name 'guix)
+         (url "https://git.savannah.gnu.org/git/guix.git";)
+         (commit
+          "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
+
+(define inferior
+  ;; An inferior representing the above revision.
+  (inferior-for-channels channels))
+
+;; Now create a manifest with the current "guile" package
+;; and the old "guile-json" package.
+(packages->manifest
+ (list (first (lookup-inferior-packages inferior "guile-json"))
+       (specification->package "guile")))
address@hidden lisp
+
+On its first run, @command{guix package --manifest} might have to build the
+channel you specified before it can create the inferior; subsequent runs will
+be much faster because the Guix revision will be cached.
+
+The @code{(guix inferior)} module provides the following procedures to open an
+inferior:
+
address@hidden {Scheme Procedure} inferior-for-channels @var{channels} @
+   [#:cache-directory] [#:ttl]
+Return an inferior for @var{channels}, a list of channels.  Use the cache at
address@hidden, where entries can be reclaimed after @var{ttl} seconds.
+This procedure opens a new connection to the build daemon.
+
+As a side effect, this procedure may build or substitute binaries for
address@hidden, which can take time.
address@hidden deffn
+
address@hidden {Scheme Procedure} open-inferior @var{directory} @
+  [#:command "bin/guix"]
+Open the inferior Guix in @var{directory}, running
address@hidden@var{directory}/@var{command} repl} or equivalent.  Return 
@code{#f} if
+the inferior could not be launched.
address@hidden deffn
+
address@hidden inferior packages
+The procedures listed below allow you to obtain and manipulate inferior
+packages.
+
address@hidden {Scheme Procedure} inferior-packages @var{inferior}
+Return the list of packages known to @var{inferior}.
address@hidden deffn
+
address@hidden {Scheme Procedure} lookup-inferior-packages @var{inferior} 
@var{name} @
+   address@hidden
+Return the sorted list of inferior packages matching @var{name} in
address@hidden, with highest version numbers first.  If @var{version} is true,
+return only packages with a version number prefixed by @var{version}.
address@hidden deffn
+
address@hidden {Scheme Procedure} inferior-package? @var{obj}
+Return true if @var{obj} is an inferior package.
address@hidden deffn
+
address@hidden {Scheme Procedure} inferior-package-name @var{package}
address@hidden {Scheme Procedure} inferior-package-version @var{package}
address@hidden {Scheme Procedure} inferior-package-synopsis @var{package}
address@hidden {Scheme Procedure} inferior-package-description @var{package}
address@hidden {Scheme Procedure} inferior-package-home-page @var{package}
address@hidden {Scheme Procedure} inferior-package-location @var{package}
address@hidden {Scheme Procedure} inferior-package-inputs @var{package}
address@hidden {Scheme Procedure} inferior-package-native-inputs @var{package}
address@hidden {Scheme Procedure} inferior-package-propagated-inputs 
@var{package}
address@hidden {Scheme Procedure} inferior-package-transitive-propagated-inputs 
@var{package}
address@hidden {Scheme Procedure} inferior-package-native-search-paths 
@var{package}
address@hidden {Scheme Procedure} 
inferior-package-transitive-native-search-paths @var{package}
address@hidden {Scheme Procedure} inferior-package-search-paths @var{package}
+These procedures are the counterpart of package record accessors
+(@pxref{package Reference}).  Most of them work by querying the inferior
address@hidden comes from, so the inferior must still be live when you call
+these procedures.
address@hidden deffn
+
+Inferior packages can be used transparently like any other package or
+file-like object in G-expressions (@pxref{G-Expressions}).  They are also
+transparently handled by the @code{packages->manifest} procedure, which is
+commonly use in manifests (@pxref{Invoking guix package, the
address@hidden option of @command{guix package}}).  Thus you can insert
+an inferior package pretty much anywhere you would insert a regular package:
+in manifests, in the @code{packages} field of your @code{operating-system}
+declaration, and so on.
 
 @node Invoking guix describe
 @section Invoking @command{guix describe}