diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 120 |
1 files changed, 118 insertions, 2 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 307f915dbb..19a497c746 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. +* Invoking guix describe:: Display information about your Guix revision. * Invoking guix pack:: Creating software bundles. * Invoking guix archive:: Exporting and importing store files. @@ -620,7 +621,8 @@ GNU Guix depends on the following packages: @itemize @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.13 or later, including 2.2.x; -@item @url{http://gnupg.org/, GNU libgcrypt}; +@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version +0.1.0 or later; @item @uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings (@pxref{Guile Preparations, how to install the GnuTLS bindings for @@ -662,6 +664,7 @@ Unless @code{--disable-daemon} was passed to @command{configure}, the following packages are also needed: @itemize +@item @url{http://gnupg.org/, GNU libgcrypt}; @item @url{http://sqlite.org, SQLite 3}; @item @url{http://gcc.gnu.org, GCC's g++}, with support for the C++11 standard. @@ -1696,6 +1699,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. +* Invoking guix describe:: Display information about your Guix revision. * Invoking guix pack:: Creating software bundles. * Invoking guix archive:: Exporting and importing store files. @end menu @@ -1749,7 +1753,7 @@ collected. @cindex reproducibility @cindex reproducible builds -Finally, Guix takes a @dfn{purely functional} approach to package +Guix takes a @dfn{purely functional} approach to package management, as described in the introduction (@pxref{Introduction}). Each @file{/gnu/store} package directory name contains a hash of all the inputs that were used to build that package---compiler, libraries, build @@ -1777,6 +1781,15 @@ a package to quickly set up the right development environment for their package, without having to manually install the dependencies of the package into their profile (@pxref{Invoking guix environment}). +@cindex replication, of software environments +@cindex provenance tracking, of software artifacts +All of Guix and its package definitions is version-controlled, and +@command{guix pull} allows you to ``travel in time'' on the history of Guix +itself (@pxref{Invoking guix pull}). This makes it possible to replicate a +Guix instance on a different machine or at a later point in time, which in +turn allows you to @emph{replicate complete software environments}, while +retaining precise @dfn{provenance tracking} of the software. + @node Invoking guix package @section Invoking @command{guix package} @@ -2804,6 +2817,9 @@ Generation 3 Jun 13 2018 23:31:07 (current) 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{} @end example +@ref{Invoking guix describe, @command{guix describe}}, for other ways to +describe the current status of Guix. + This @code{~/.config/guix/current} profile works like any other profile created by @command{guix package} (@pxref{Invoking guix package}). That is, you can list generations, roll back to the previous @@ -2849,6 +2865,13 @@ is provided, the subset of generations that match @var{pattern}. The syntax of @var{pattern} is the same as with @code{guix package --list-generations} (@pxref{Invoking guix package}). +@ref{Invoking guix describe}, for a way to display information about the +current generation only. + +@item --profile=@var{profile} +@itemx -p @var{profile} +Use @var{profile} instead of @file{~/.config/guix/current}. + @item --bootstrap Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers. @@ -3017,6 +3040,9 @@ say, on another machine, by providing a channel specification in (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) @end lisp +The @command{guix describe --format=channels} command can even generate this +list of channels directly (@pxref{Invoking guix describe}). + At this point the two machines run the @emph{exact same Guix}, with access to the @emph{exact same packages}. The output of @command{guix build gimp} on one machine will be exactly the same, bit for bit, as the output of the same @@ -3028,6 +3054,78 @@ 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. +@node Invoking guix describe +@section Invoking @command{guix describe} + +@cindex reproducibility +@cindex replicating Guix +Often you may want to answer questions like: ``Which revision of Guix am I +using?'' or ``Which channels am I using?'' This is useful information in many +situations: if you want to @emph{replicate} an environment on a different +machine or user account, if you want to report a bug or to determine what +change in the channels you are using caused it, or if you want to record your +system state for reproducibility purposes. The @command{guix describe} +command answers these questions. + +When run from a @command{guix pull}ed @command{guix}, @command{guix describe} +displays the channel(s) that it was built from, including their repository URL +and commit IDs (@pxref{Channels}): + +@example +$ guix describe +Generation 10 Sep 03 2018 17:32:44 (current) + guix e0fa68c + repository URL: https://git.savannah.gnu.org/git/guix.git + branch: master + commit: e0fa68c7718fffd33d81af415279d6ddb518f727 +@end example + +If you're familiar with the Git version control system, this is similar in +spirit to @command{git describe}; the output is also similar to that of +@command{guix pull --list-generations}, but limited to the current generation +(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because +the Git commit ID shown above unambiguously refers to a snapshot of Guix, this +information is all it takes to describe the revision of Guix you're using, and +also to replicate it. + +To make it easier to replicate Guix, @command{guix describe} can also be asked +to return a list of channels instead of the human-readable description above: + +@example +$ guix describe -f channels +(list (channel + (name 'guix) + (url "https://git.savannah.gnu.org/git/guix.git") + (commit + "e0fa68c7718fffd33d81af415279d6ddb518f727"))) +@end example + +@noindent +You can save this to a file and feed it to @command{guix pull -C} on some +other machine or at a later point in time, which will instantiate @emph{this +exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}). +From there on, since you're able to deploy the same revision of Guix, you can +just as well @emph{replicate a complete software environment}. We humbly +think that this is @emph{awesome}, and we hope you'll like it too! + +The details of the options supported by @command{guix describe} are as +follows: + +@table @code +@item --format=@var{format} +@itemx -f @var{format} +Produce output in the specified @var{format}, one of: + +@table @code +@item human +produce human-readable output; +@item channels +produce a list of channel specifications that can be passed to @command{guix +pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking +guix pull}). +@end table +@end table + @node Invoking guix pack @section Invoking @command{guix pack} @@ -16823,6 +16921,13 @@ Extension package for @code{hpcguix-web}. @item @code{menu} (default: @code{'()}) Additional entry in page @code{menu}. + +@item @code{channels} (default: @code{%default-channels}) +List of channels from which the package list is built (@pxref{Channels}). + +@item @code{package-list-expiration} (default: @code{(* 12 3600)}) +The expiration time, in seconds, after which the package list is rebuilt from +the latest instances of the given channels. @end table See the hpcguix-web repository for a @@ -16846,6 +16951,17 @@ A typical hpcguix-web service declaration looks like this: (menu '(("/about" "ABOUT")))))))) @end example +@quotation Note +The hpcguix-web service periodically updates the package list it publishes by +pulling channels from Git. To that end, it needs to access X.509 certificates +so that it can authenticate Git servers when communicating over HTTPS, and it +assumes that @file{/etc/ssl/certs} contains those certificates. + +Thus, make sure to add @code{nss-certs} or another certificate package to the +@code{packages} field of your configuration. @ref{X.509 Certificates}, for +more information on X.509 certificates. +@end quotation + @node Certificate Services @subsubsection Certificate Services |