aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMarius Bakke <mbakke@fastmail.com>2018-09-09 17:40:35 +0200
committerMarius Bakke <mbakke@fastmail.com>2018-09-09 17:40:35 +0200
commit0aeb13485055975d71ec8283040f007c79599bba (patch)
treea06139136c809b00d166d6d66bdf757f20566704 /doc
parentb03f270e3d5ab5315b50ef3ebac35735cc28d4a2 (diff)
parent0084744b3af0a6f8e125120143f57567902339a8 (diff)
downloadpatches-0aeb13485055975d71ec8283040f007c79599bba.tar
patches-0aeb13485055975d71ec8283040f007c79599bba.tar.gz
Merge branch 'master' into core-updates
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi120
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