aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2014-01-24 21:52:05 +0100
committerLudovic Courtès <ludo@gnu.org>2014-01-25 16:20:23 +0100
commit4ec2e92ddbcb06616094d054b6f19c73f617da27 (patch)
tree0270609e59b9744e7e304847a96f151dbc4370ad
parentb5d4a8113353cda2f3e569e5b326e7301c2512bd (diff)
downloadguix-4ec2e92ddbcb06616094d054b6f19c73f617da27.tar
guix-4ec2e92ddbcb06616094d054b6f19c73f617da27.tar.gz
doc: More about offloading.
* doc/guix.texi (Daemon Offload Setup): Start with "When desired". Say more on what can go in 'machines.scm', and mention Guile-Avahi. (Invoking guix-daemon): Document '--no-build-hook'. (Invoking guix build): Add xref to "Daemon Offload Setup".
-rw-r--r--doc/guix.texi38
1 files changed, 27 insertions, 11 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 48e4631836..325467c82d 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -279,7 +279,9 @@ much harder to view them as @emph{pure} functions.
@subsection Using the Offload Facility
@cindex offloading
-The build daemon can @dfn{offload} derivation builds to other machines
+@cindex build hook
+When desired, the build daemon can @dfn{offload}
+derivation builds to other machines
running Guix, using the @code{offload} @dfn{build hook}. When that
feature is enabled, a list of user-specified build machines is read from
@file{/etc/guix/machines.scm}; anytime a build is requested, for
@@ -290,9 +292,7 @@ prerequisites for the build are copied over SSH to the target machine,
which then proceeds with the build; upon success the output(s) of the
build are copied back to the initial machine.
-The @file{/etc/guix/machines.scm} is---not surprisingly!---a Scheme file
-whose return value must be a list of @code{build-machine} objects. In
-practice, it typically looks like this:
+The @file{/etc/guix/machines.scm} file typically looks like this:
@example
(list (build-machine
@@ -313,8 +313,17 @@ practice, it typically looks like this:
@noindent
In the example above we specify a list of two build machines, one for
the @code{x86_64} architecture and one for the @code{mips64el}
-architecture. The compulsory fields for a @code{build-machine}
-declaration are:
+architecture.
+
+In fact, this file is---not surprisingly!---a Scheme file that is
+evaluated when the @code{offload} hook is started. Its return value
+must be a list of @code{build-machine} objects. While this example
+shows a fixed list of build machines, one could imagine, say, using
+DNS-SD to return a list of potential build machines discovered in the
+local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
+Avahi in Guile Scheme Programs}).
+
+The compulsory fields for a @code{build-machine} declaration are:
@table @code
@@ -332,7 +341,7 @@ allow non-interactive logins.
@end table
@noindent
-A number of optional fields may be optionally specified:
+A number of optional fields may be specified:
@table @code
@@ -426,6 +435,14 @@ When the daemon runs with @code{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).
+@cindex build hook
+@item --no-build-hook
+Do not use the @dfn{build hook}.
+
+The build hook is a helper program that the daemon can start and to
+which it submits build requests. This mechanism is used to offload
+builds to other machines (@pxref{Daemon Offload Setup}).
+
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
@@ -1776,10 +1793,9 @@ Do not use substitutes for build products. That is, always build things
locally instead of allowing downloads of pre-built binaries.
@item --no-build-hook
-Do not attempt to offload builds @i{via} the daemon's ``build hook''.
-That is, always build things locally instead of offloading builds to
-remote machines.
-@c TODO: Add xref to build hook doc.
+Do not attempt to offload builds @i{via} the daemon's ``build hook''
+(@pxref{Daemon Offload Setup}). That is, always build things locally
+instead of offloading builds to remote machines.
@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than