[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
13/15: doc: Clarify "Replicating Guix" section.
From: |
guix-commits |
Subject: |
13/15: doc: Clarify "Replicating Guix" section. |
Date: |
Fri, 22 Jul 2022 18:40:52 -0400 (EDT) |
civodul pushed a commit to branch master
in repository guix.
commit 6c42db835105ac6ec2fa786fd621d8d43ce0e45e
Author: Ludovic Courtès <ludovic.courtes@inria.fr>
AuthorDate: Tue Jul 19 23:48:32 2022 +0200
doc: Clarify "Replicating Guix" section.
* doc/guix.texi (Specifying Additional Channels): Replace 'guix pull
--list-generations' example with 'guix describe'.
(Replicating Guix): Rewrite to insist on 'guix describe', to include
an example capturing channels and another one restoring them, and
mention "lock files".
---
doc/guix.texi | 63 ++++++++++++++++++++++++++++++++++++-----------------------
1 file changed, 39 insertions(+), 24 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index cdecdf5b82..6e867839a4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5277,8 +5277,7 @@ but also the package modules from your own repository.
The result in
modules:
@example
-$ guix pull --list-generations
-@dots{}
+$ guix describe
Generation 19 Aug 27 2018 16:20:48
guix d894ab8
repository URL: https://git.savannah.gnu.org/git/guix.git
@@ -5288,16 +5287,13 @@ Generation 19 Aug 27 2018 16:20:48
repository URL: https://example.org/variant-packages.git
branch: master
commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
- 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
- 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
@end example
@noindent
-The output of @command{guix pull} above shows that Generation@tie{}19 includes
-both Guix and packages from the @code{variant-personal-packages} channel.
Among
-the new and upgraded packages that are listed, some like @code{variant-gimp}
and
-@code{variant-emacs-with-cool-features} might come from
-@code{variant-packages}, while others come from the Guix default channel.
+The output of @command{guix describe} above shows that we're now running
+Generation@tie{}19 and that it includes
+both Guix and packages from the @code{variant-personal-packages} channel
+(@pxref{Invoking guix describe}).
@node Using a Custom Guix Channel
@section Using a Custom Guix Channel
@@ -5327,10 +5323,11 @@ addressed below (@pxref{Channel Authentication}).
@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix
-The @command{guix pull --list-generations} output above shows precisely which
-commits were used to build this instance of Guix. We can thus replicate it,
-say, on another machine, by providing a channel specification in
-@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
+The @command{guix describe} command shows precisely which commits were
+used to build the instance of Guix we're using (@pxref{Invoking guix
+describe}). We can replicate this instance on another machine or at a
+different point in time by providing a channel specification ``pinned''
+to these commits that looks like this:
@lisp
;; Deploy specific commits of my channels of interest.
@@ -5344,18 +5341,36 @@ say, on another machine, by providing a channel
specification in
(commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
-The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}). The resulting
-file can be used with the @option{-C} option of @command{guix pull}
-(@pxref{Invoking guix pull}) or @command{guix time-machine}
-(@pxref{Invoking guix time-machine}).
+To obtain this pinned channel specification, the easiest way is to run
+@command{guix describe} and to save its output in the @code{channels}
+format in a file, like so:
+
+@example
+guix describe -f channels > channels.scm
+@end example
+
+The resulting @file{channels.scm} file can be passed to the @option{-C}
+option of @command{guix pull} (@pxref{Invoking guix pull}) or
+@command{guix time-machine} (@pxref{Invoking guix time-machine}), as in
+this example:
+
+@example
+guix time-machine -C channels.scm -- shell python -- python3
+@end example
+
+Given the @file{channels.scm} file, the command above will always fetch
+the @emph{exact same Guix instance}, then use that instance to run the
+exact same Python (@pxref{Invoking guix shell}). On any machine, at any
+time, it ends up running the exact same binaries, bit for bit.
-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
-command on the other machine. It also means both machines have access to all
-the source code of Guix and, transitively, to all the source code of every
-package it defines.
+@cindex lock files
+Pinned channels address a problem similar to ``lock files'' as
+implemented by some deployment tools---they let you pin and reproduce a
+set of packages. In the case of Guix though, you are effectively
+pinning the entire package set as defined at the given channel commits;
+in fact, you are pinning all of Guix, including its core modules and
+command-line tools. You're also getting strong guarantees that you are,
+indeed, obtaining the exact same software.
This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at
- branch master updated (c9a37f57cb -> 32a0036343), guix-commits, 2022/07/22
- 03/15: guix gc: '--delete-generations' now deletes old Home generations., guix-commits, 2022/07/22
- 02/15: home: Add 'home-generation-base'., guix-commits, 2022/07/22
- 04/15: gnu: eigen: Update to 3.4.0., guix-commits, 2022/07/22
- 05/15: gnu: clojure-tools-cli: Update to 1.0.206., guix-commits, 2022/07/22
- 07/15: gnu: clojure-tools-deps-alpha: Update to 0.14.1212., guix-commits, 2022/07/22
- 06/15: gnu: clojure-tools-gitlibs: Update to 2.4.181., guix-commits, 2022/07/22
- 08/15: gnu: clojure-tools: Update to 1.11.1.1149., guix-commits, 2022/07/22
- 10/15: gnu: clojure-algo-generic: Fix test failing under AOT in Clojure 1.11.1., guix-commits, 2022/07/22
- 11/15: gnu: clojure-core-match: Update to 1.0.0., guix-commits, 2022/07/22
- 13/15: doc: Clarify "Replicating Guix" section.,
guix-commits <=
- 09/15: gnu: clojure: Update to 1.11.1., guix-commits, 2022/07/22
- 12/15: gnu: clojure-instaparse: Update to 1.4.12., guix-commits, 2022/07/22
- 01/15: deploy: Honor '--dry-run'., guix-commits, 2022/07/22
- 14/15: gnu: git: Update to 2.37.1., guix-commits, 2022/07/22
- 15/15: gnu: iotop: Update to 1.22., guix-commits, 2022/07/22