nixo
/
guix-devel
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

doc: Better explain GC roots. 

Fixes <https://bugs.gnu.org/24194>.
Reported by J. Eppler <j.eppler@openmailbox.org>.

* 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".
This commit is contained in:
Ludovic Courtès 2017-11-12 21:41:34 +01:00
parent 2560aa7adb
commit 6a98b9f34e
No known key found for this signature in database
GPG Key ID: 090B11993D9AEBB5
1 changed files with 20 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/guix.texi
View File

@ -1236,9 +1236,12 @@ this optimization.
Tell whether the garbage collector (GC) must keep outputs of live Tell whether the garbage collector (GC) must keep outputs of live
derivations. derivations.
@cindex GC roots
@cindex garbage collector roots
When set to ``yes'', the GC will keep the outputs of any live derivation 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'', available in the store---the @code{.drv} files. The default is ``no'',
meaning that derivation outputs are kept only if they are GC roots. 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] @item --gc-keep-derivations[=yes|no]
Tell whether the garbage collector (GC) must keep derivations 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 the @emph{only} way to remove files from @file{/gnu/store}---removing
files or directories manually may break it beyond repair! 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 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 @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 cannot be deleted; any other file is considered @dfn{dead} and may be
deleted. The set of garbage collector roots includes default user deleted. The set of garbage collector roots (``GC roots'' for short)
profiles, and may be augmented with @command{guix build --root}, for includes default user profiles; by default, the symlinks under
example (@pxref{Invoking guix build}). @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 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 often useful to remove old generations from user profiles; that way, old
@ -5535,9 +5542,17 @@ packages.
@item --root=@var{file} @item --root=@var{file}
@itemx -r @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 Make @var{file} a symlink to the result, and register it as a garbage
collector root. 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 @item --log-file
Return the build log file names or URLs for the given Return the build log file names or URLs for the given
@var{package-or-derivation}, or raise an error if build logs are @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 When this option is omitted, the environment is protected from garbage
collection only for the duration of the @command{guix environment} collection only for the duration of the @command{guix environment}
session. This means that next time you recreate the same 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} @item --expression=@var{expr}
@itemx -e @var{expr} @itemx -e @var{expr}