01/03: doc: Add note on store immutability.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 1ddee42472ecdad3d2dbbc2482aab5e3add3abdd
Author: Ludovic Courtès <address@hidden>
Date:   Wed Mar 9 14:47:31 2016 +0100

    doc: Add note on store immutability.
    
    * doc/guix.texi (The Store): Mention "store items" and the database
    location.  Add note on the store's immutability.
---
 doc/guix.texi |   26 ++++++++++++++++++++------
 1 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 7945415..06b40fa 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2878,20 +2878,34 @@ with @code{build-expression->derivation} 
(@pxref{Derivations,
 @section The Store
 
 @cindex store
address@hidden store items
 @cindex store paths
 
 Conceptually, the @dfn{store} is the place where derivations that have
 been built successfully are stored---by default, @file{/gnu/store}.
-Sub-directories in the store are referred to as @dfn{store paths}.  The
-store has an associated database that contains information such as the
-store paths referred to by each store path, and the list of @emph{valid}
-store paths---paths that result from a successful build.
-
-The store is always accessed by the daemon on behalf of its clients
+Sub-directories in the store are referred to as @dfn{store items} or
+sometimes @dfn{store paths}.  The store has an associated database that
+contains information such as the store paths referred to by each store
+path, and the list of @emph{valid} store items---results of successful
+builds.  This database resides in @file{/var/guix/db} (or under whatever
+state directory was specified @i{via} @option{--localstatedir} at
+configure time).
+
+The store is @emph{always} accessed by the daemon on behalf of its clients
 (@pxref{Invoking guix-daemon}).  To manipulate the store, clients
 connect to the daemon over a Unix-domain socket, send requests to it,
 and read the result---these are remote procedure calls, or RPCs.
 
address@hidden Note
+Users must @emph{never} modify files under @file{/gnu/store} directly.
+This would lead to inconsistencies and break the immutability
+assumptions of Guix's functional model (@pxref{Introduction}).
+
address@hidden guix gc, @command{guix gc --verify}}, for information on
+how to check the integrity of the store and attempt recovery from
+accidental modifications.
address@hidden quotation
+
 The @code{(guix store)} module provides procedures to connect to the
 daemon, and to perform RPCs.  These are described below.