futurile/guix-play
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Clarify "Replicating Guix" section.

Browse Source 
* 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".
This commit is contained in:
Ludovic Courtès 2022-07-19 23:48:32 +02:00 committed by Ludovic Courtès
parent 666f12f125
commit 6c42db8351
No known key found for this signature in database
GPG Key ID: 090B11993D9AEBB5
1 changed files with 39 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
doc/guix.texi
View File

@ -5277,8 +5277,7 @@ but also the package modules from your own repository. The result in
modules: modules:
@example @example
$ guix pull --list-generations $ guix describe
@dots{}
Generation 19 Aug 27 2018 16:20:48 Generation 19 Aug 27 2018 16:20:48
guix d894ab8 guix d894ab8
repository URL: https://git.savannah.gnu.org/git/guix.git 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 repository URL: https://example.org/variant-packages.git
branch: master branch: master
commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb 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 @end example
@noindent @noindent
The output of @command{guix pull} above shows that Generation@tie{}19 includes The output of @command{guix describe} above shows that we're now running
both Guix and packages from the @code{variant-personal-packages} channel. Among Generation@tie{}19 and that it includes
the new and upgraded packages that are listed, some like @code{variant-gimp} and both Guix and packages from the @code{variant-personal-packages} channel
@code{variant-emacs-with-cool-features} might come from (@pxref{Invoking guix describe}).
@code{variant-packages}, while others come from the Guix default channel.
@node Using a Custom Guix Channel @node Using a Custom Guix Channel
@section Using a Custom Guix Channel @section Using a Custom Guix Channel
@ -5327,10 +5323,11 @@ addressed below (@pxref{Channel Authentication}).
@cindex pinning, channels @cindex pinning, channels
@cindex replicating Guix @cindex replicating Guix
@cindex reproducibility, of Guix @cindex reproducibility, of Guix
The @command{guix pull --list-generations} output above shows precisely which The @command{guix describe} command shows precisely which commits were
commits were used to build this instance of Guix. We can thus replicate it, used to build the instance of Guix we're using (@pxref{Invoking guix
say, on another machine, by providing a channel specification in describe}). We can replicate this instance on another machine or at a
@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: different point in time by providing a channel specification ``pinned''
to these commits that looks like this:
@lisp @lisp
;; Deploy specific commits of my channels of interest. ;; Deploy specific commits of my channels of interest.
@ -5344,18 +5341,36 @@ say, on another machine, by providing a channel specification in
(commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp @end lisp
The @command{guix describe --format=channels} command can even generate this To obtain this pinned channel specification, the easiest way is to run
list of channels directly (@pxref{Invoking guix describe}). The resulting @command{guix describe} and to save its output in the @code{channels}
file can be used with the @option{-C} option of @command{guix pull} format in a file, like so:
(@pxref{Invoking guix pull}) or @command{guix time-machine}
(@pxref{Invoking guix time-machine}).
At this point the two machines run the @emph{exact same Guix}, with access to @example
the @emph{exact same packages}. The output of @command{guix build gimp} on guix describe -f channels > channels.scm
one machine will be exactly the same, bit for bit, as the output of the same @end example
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 The resulting @file{channels.scm} file can be passed to the @option{-C}
package it defines. 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.
@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 This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at artifacts with very fine grain, and to reproduce software environments at