From 6a98b9f34e6190a2e1d11bedd5853aa94cf25ca7 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Sun, 12 Nov 2017 21:41:34 +0100 Subject: doc: Better explain GC roots. Fixes . Reported by J. Eppler . * doc/guix.texi (Invoking guix-daemon): Add index entries for GC roots. Add xref to "Invoking guix gc". (Invoking guix gc): Add the string "GC roots"; mention /var/guix/gcroots. (Additional Build Options): Add index entries. Better explain --root. (Invoking guix environment): Add xref to "Invoking guix gc". --- doc/guix.texi | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 11a9de6897..0bc2be1fd1 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1236,9 +1236,12 @@ this optimization. Tell whether the garbage collector (GC) must keep outputs of live derivations. +@cindex GC roots +@cindex garbage collector roots When set to ``yes'', the GC will keep the outputs of any live derivation available in the store---the @code{.drv} files. The default is ``no'', meaning that derivation outputs are kept only if they are GC roots. +@xref{Invoking guix gc}, for more on GC roots. @item --gc-keep-derivations[=yes|no] Tell whether the garbage collector (GC) must keep derivations @@ -2338,12 +2341,16 @@ collector to reclaim space from the @file{/gnu/store} directory. It is the @emph{only} way to remove files from @file{/gnu/store}---removing files or directories manually may break it beyond repair! +@cindex GC roots +@cindex garbage collector roots The garbage collector has a set of known @dfn{roots}: any file under @file{/gnu/store} reachable from a root is considered @dfn{live} and cannot be deleted; any other file is considered @dfn{dead} and may be -deleted. The set of garbage collector roots includes default user -profiles, and may be augmented with @command{guix build --root}, for -example (@pxref{Invoking guix build}). +deleted. The set of garbage collector roots (``GC roots'' for short) +includes default user profiles; by default, the symlinks under +@file{/var/guix/gcroots} represent these GC roots. New GC roots can be +added with @command{guix build --root}, for example (@pxref{Invoking +guix build}). Prior to running @code{guix gc --collect-garbage} to make space, it is often useful to remove old generations from user profiles; that way, old @@ -5535,9 +5542,17 @@ packages. @item --root=@var{file} @itemx -r @var{file} +@cindex GC roots, adding +@cindex garbage collector roots, adding Make @var{file} a symlink to the result, and register it as a garbage collector root. +Consequently, the results of this @command{guix build} invocation are +protected from garbage collection until @var{file} is removed. When +that option is omitted, build results are eligible for garbage +collection as soon as the build completes. @xref{Invoking guix gc}, for +more on GC roots. + @item --log-file Return the build log file names or URLs for the given @var{package-or-derivation}, or raise an error if build logs are @@ -6902,7 +6917,8 @@ collection, to make it ``persistent''. When this option is omitted, the environment is protected from garbage collection only for the duration of the @command{guix environment} session. This means that next time you recreate the same environment, -you could have to rebuild or re-download packages. +you could have to rebuild or re-download packages. @xref{Invoking guix +gc}, for more on GC roots. @item --expression=@var{expr} @itemx -e @var{expr} -- cgit v1.2.3