summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2014-03-30 23:37:46 +0200
committerLudovic Courtès <ludo@gnu.org>2014-03-30 23:37:46 +0200
commitc4202d60b21dd62f5d63112b62e5139980b44b5a (patch)
tree4560eab53898a5657890c81b92688b0fc60feed9 /doc
parentbf59c06d36717178387e7451b39ba8423eadd3e8 (diff)
doc: Document substitutes.
* doc/guix.texi (Invoking guix-daemon): Add cross-reference to "Substitutes". (Features): Remove footnote about unauthenticated substitutes. Link to "Substitutes". (Substitutes): New node. (Invoking guix build): Link to "Substitutes". (Packaging Guidelines): Likewise.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi125
1 files changed, 111 insertions, 14 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index f97051e88c..5bd7dbdc8e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -428,7 +428,8 @@ the Daemon, build users}).
@item --no-substitutes
@cindex substitutes
Do not use substitutes for build products. That is, always build things
-locally instead of allowing downloads of pre-built binaries.
+locally instead of allowing downloads of pre-built binaries
+(@pxref{Substitutes}).
By default substitutes are used, unless the client---such as the
@command{guix package} command---is explicitly invoked with
@@ -569,6 +570,7 @@ management tools it provides.
@menu
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
+* Substitutes:: Downloading pre-built binaries.
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
@@ -633,18 +635,13 @@ thanks to the isolated build environments that are used, a given build
is likely to yield bit-identical files when performed on different
machines (@pxref{Invoking guix-daemon, container}).
-@cindex substitute
+@cindex substitutes
This foundation allows Guix to support @dfn{transparent binary/source
-deployment}. When a pre-built binary for a @file{/gnu/store} path is
+deployment}. When a pre-built binary for a @file{/gnu/store} item is
available from an external source---a @dfn{substitute}, Guix just
-downloads it@footnote{@c XXX: Remove me when outdated.
-As of version @value{VERSION}, substitutes are downloaded from
-@url{http://hydra.gnu.org/} but are @emph{not} authenticated---i.e.,
-Guix cannot tell whether binaries it downloaded have been tampered with,
-nor whether they come from the genuine @code{gnu.org} build farm. This
-will be fixed in future versions. In the meantime, concerned users can
-opt for @code{--no-substitutes} (@pxref{Invoking guix-daemon}).};
-otherwise, it builds the package from source, locally.
+downloads it and unpacks it;
+otherwise, it builds the package from source, locally
+(@pxref{Substitutes}).
@node Invoking guix package
@section Invoking @command{guix package}
@@ -912,6 +909,105 @@ Finally, since @command{guix package} may actually start build
processes, it supports all the common build options that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).
+@node Substitutes
+@section Substitutes
+
+@cindex substitutes
+@cindex pre-built binaries
+Guix supports transparent source/binary deployment, which means that it
+can either build things locally, or download pre-built items from a
+server. We call these pre-built items @dfn{substitutes}---they are
+substitutes for local build results. In many cases, downloading a
+substitute is much faster than building things locally.
+
+Substitutes can be anything resulting from a derivation build
+(@pxref{Derivations}). Of course, in the common case, they are
+pre-built package binaries, but source tarballs, for instance, which
+also result from derivation builds, can be available as substitutes.
+
+The @code{hydra.gnu.org} server is a front-end to a build farm that
+builds packages from the GNU distribution continuously for some
+architectures, and makes them available as substitutes.
+
+@cindex security
+@cindex digital signatures
+To allow Guix to download substitutes from @code{hydra.gnu.org}, you
+must add its public key to the access control list (ACL) of archive
+imports, using the @command{guix archive} command (@pxref{Invoking guix
+archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
+be compromised and to serve genuine substitutes.
+
+This public key is installed along with Guix, in
+@code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
+the installation prefix of Guix. If you installed Guix from source,
+make sure you checked the GPG signature of
+@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
+Then, you can run something like this:
+
+@example
+# guix archive --authorize < hydra.gnu.org.pub
+@end example
+
+Once this is in place, the output of a command like @code{guix build}
+should change from something like:
+
+@example
+$ guix build emacs --dry-run
+The following derivations would be built:
+ /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
+ /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
+ /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
+ /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
+@dots{}
+@end example
+
+@noindent
+to something like:
+
+@example
+$ guix build emacs --dry-run
+The following files would be downloaded:
+ /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
+ /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
+ /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
+ /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
+@dots{}
+@end example
+
+@noindent
+This indicates that substitutes from @code{hydra.gnu.org} are usable and
+will be downloaded, when possible, for future builds.
+
+Guix ignores substitutes that are not signed, or that are not signed by
+one of the keys listed in the ACL. It also detects and raise an error
+when attempting to use a substitute that has been tampered with.
+
+The substitute mechanism can be disabled globally by running
+@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
+guix-daemon}). It can also be disabled temporarily by passing the
+@code{--no-substitutes} option to @command{guix package}, @command{guix
+build}, and other command-line tools.
+
+
+Today, each individual's control over their own computing is at the
+mercy of institutions, corporations, and groups with enough power and
+determination to subvert the computing infrastructure and exploit its
+weaknesses. While using @code{hydra.gnu.org} substitutes can be
+convenient, we encourage users to also build on their own, or even run
+their own build farm, such that @code{hydra.gnu.org} is less of an
+interesting target.
+
+Guix has the foundations to maximize build reproducibility
+(@pxref{Features}). In most cases, independent builds of a given
+package or derivation should yield bit-identical results. Thus, through
+a diverse set of independent package builds, we can strengthen the
+integrity of our systems.
+
+In the future, we want Guix to have support to publish and retrieve
+binaries to/from other users, in a peer-to-peer fashion. If you would
+like to discuss this project, join us on @email{guix-devel@@gnu.org}.
+
+
@node Packages with Multiple Outputs
@section Packages with Multiple Outputs
@@ -1923,7 +2019,8 @@ packages locally.
@item --no-substitutes
Do not use substitutes for build products. That is, always build things
-locally instead of allowing downloads of pre-built binaries.
+locally instead of allowing downloads of pre-built binaries
+(@pxref{Substitutes}).
@item --no-build-hook
Do not attempt to offload builds @i{via} the daemon's ``build hook''
@@ -2321,8 +2418,8 @@ system}.
Users can obtain the new package definition simply by running
@command{guix pull} (@pxref{Invoking guix pull}). When
@code{hydra.gnu.org} is done building the package, installing the
-package automatically downloads binaries from there (except when using
-@code{--no-substitutes}). The only place where human intervention is
+package automatically downloads binaries from there
+(@pxref{Substitutes}). The only place where human intervention is
needed is to review and apply the patch.