Merge branch 'master' into core-updates

1 files changed, 211 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index b925485be5..6b4b06f46d 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.
+@xref{Inferiors}, for another way to take advantage of these super powers.
+
+@node Inferiors
+@section Inferiors
+
+@c TODO: Remove this once we're more confident about API stability.
+@quotation Note
+The functionality described here is a ``technology preview'' as of version
+@value{VERSION}.  As such, the interface is subject to change.
+@end quotation
+
+@cindex inferiors
+@cindex 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.
+
+@cindex 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
+@code{(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 provides---@dfn{inferior 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 API@.  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:
+
+@lisp
+(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")))
+@end 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:
+
+@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
+   [#:cache-directory] [#:ttl]
+Return an inferior for @var{channels}, a list of channels.  Use the cache at
+@var{cache-directory}, 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
+@var{channels}, which can take time.
+@end deffn
+
+@deffn {Scheme Procedure} open-inferior @var{directory} @
+  [#:command "bin/guix"]
+Open the inferior Guix in @var{directory}, running
+@code{@var{directory}/@var{command} repl} or equivalent.  Return @code{#f} if
+the inferior could not be launched.
+@end deffn
+
+@cindex inferior packages
+The procedures listed below allow you to obtain and manipulate inferior
+packages.
+
+@deffn {Scheme Procedure} inferior-packages @var{inferior}
+Return the list of packages known to @var{inferior}.
+@end deffn
+
+@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
+   [@var{version}]
+Return the sorted list of inferior packages matching @var{name} in
+@var{inferior}, with highest version numbers first.  If @var{version} is true,
+return only packages with a version number prefixed by @var{version}.
+@end deffn
+
+@deffn {Scheme Procedure} inferior-package? @var{obj}
+Return true if @var{obj} is an inferior package.
+@end deffn
+
+@deffn {Scheme Procedure} inferior-package-name @var{package}
+@deffnx {Scheme Procedure} inferior-package-version @var{package}
+@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
+@deffnx {Scheme Procedure} inferior-package-description @var{package}
+@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
+@deffnx {Scheme Procedure} inferior-package-location @var{package}
+@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
+@deffnx {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
+@var{package} comes from, so the inferior must still be live when you call
+these procedures.
+@end 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
+@option{--manifest} 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}
@@ -16757,6 +16888,86 @@ body of a named location block cannot contain location blocks.
 @end table
 @end deftp
 
+@subsubheading Varnish Cache
+@cindex Varnish
+Varnish is a fast cache server that sits in between web applications
+and end users.  It proxies requests from clients and caches the
+accessed URLs such that multiple requests for the same resource only
+creates one request to the back-end.
+
+@defvr {Scheme Variable} varnish-service-type
+Service type for the Varnish daemon.
+@end defvr
+
+@deftp {Data Type} varnish-configuration
+Data type representing the @code{varnish} service configuration.
+This type has the following parameters:
+
+@table @asis
+@item @code{package} (default: @code{varnish})
+The Varnish package to use.
+
+@item @code{name} (default: @code{"default"})
+A name for this Varnish instance.  Varnish will create a directory in
+@file{/var/varnish/} with this name and keep temporary files there.  If
+the name starts with a forward slash, it is interpreted as an absolute
+directory name.
+
+Pass the @code{-n} argument to other Varnish programs to connect to the
+named instance, e.g. @command{varnishncsa -n default}.
+
+@item @code{backend} (default: @code{"localhost:8080"})
+The backend to use.  This option has no effect if @code{vcl} is set.
+
+@item @code{vcl} (default: #f)
+The @dfn{VCL} (Varnish Configuration Language) program to run.  If this
+is @code{#f}, Varnish will proxy @code{backend} using the default
+configuration.  Otherwise this must be a file-like object with valid
+VCL syntax.
+
+@c Varnish does not support HTTPS, so keep this URL to avoid confusion.
+For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you
+can do something along these lines:
+
+@example
+(define %gnu-mirror
+  (plain-file
+   "gnu.vcl"
+   "vcl 4.1;
+backend gnu @{ .host = "www.gnu.org"; @}"))
+
+(operating-system
+  ...
+  (services (cons (service varnish-service-type
+                           (varnish-configuration
+                            (listen '(":80"))
+                            (vcl %gnu-mirror)))
+                  %base-services)))
+@end example
+
+The configuration of an already running Varnish instance can be inspected
+and changed using the @command{varnishadm} program.
+
+Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and
+@url{https://book.varnish-software.com/4.0/,Varnish Book} for
+comprehensive documentation on Varnish and its configuration language.
+
+@item @code{listen} (default: @code{'("localhost:80")})
+List of addresses Varnish will listen on.
+
+@item @code{storage} (default: @code{'("malloc,128m")})
+List of storage backends that will be available in VCL.
+
+@item @code{parameters} (default: @code{'()})
+List of run-time parameters in the form @code{'(("parameter" . "value"))}.
+
+@item @code{extra-options} (default: @code{'()})
+Additional arguments to pass to the @command{varnishd} process.
+
+@end table
+@end deftp
+
+@subsubheading FastCGI
 @cindex fastcgi
 @cindex fcgiwrap
 FastCGI is an interface between the front-end and the back-end of a web