aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2013-01-15 23:32:13 +0100
committerLudovic Courtès <ludo@gnu.org>2013-01-15 23:32:13 +0100
commite531ac2ad9b9933711523cd2c76c1b9ad90d7041 (patch)
tree5a0ea9b5fd30ce8b6e0e684c873e82eff60a96d9
parent156b5010ff80265ef3ebe538c7b90b909838945f (diff)
downloadguix-e531ac2ad9b9933711523cd2c76c1b9ad90d7041.tar
guix-e531ac2ad9b9933711523cd2c76c1b9ad90d7041.tar.gz
doc: Start documenting (guix store).
* doc/guix.texi (The Store): Populate. (Introduction): Add cross-reference. Change "package store" to "the store".
-rw-r--r--doc/guix.texi59
-rw-r--r--guix/store.scm8
2 files changed, 62 insertions, 5 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 7de7f4f0c2..1252caaf08 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -116,10 +116,10 @@ of its build and installation directories. This is achieved by running
build processes in dedicated ``chroots'', where only their explicit
inputs are visible.
-@cindex package store
+@cindex store
The result of package build functions is @dfn{cached} in the file
-system, in a special directory called the @dfn{package store}. In
-practice, each package is installed in a directory of its own, in the
+system, in a special directory called @dfn{the store} (@pxref{The
+Store}). Each package is installed in a directory of its own, in the
store---by default under @file{/nix/store}. The directory name contains
a hash of all the inputs used to build that package; thus, changing an
input yields a different directory name.
@@ -750,7 +750,58 @@ must be a connection to the daemon, which operates on the store
@node The Store
@section The Store
-@code{(guix store)}
+@cindex store
+@cindex store paths
+
+Conceptually, the @dfn{store} is where derivations that have been
+successfully built are stored---by default, under @file{/nix/store}.
+Sub-directories in the store are referred to as @dfn{store paths}. The
+store has an associated database that contains information such has 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
+(@pxref{Invoking guix-daemon}). To manipulate the store, clients
+connect to the daemon over a Unix-domain socket, send it requests, and
+read the result---these are remote procedure calls, or RPCs.
+
+The @code{(guix store)} module provides procedures to connect to the
+daemon, and to perform RPCs. These are described below.
+
+@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
+Connect to the daemon over the Unix-domain socket at @var{file}. When
+@var{reserve-space?} is true, instruct it to reserve a little bit of
+extra space on the file system so that the garbage collector can still
+operate, should the disk become full. Return a server object.
+
+@var{file} defaults to @var{%default-socket-path}, which is the normal
+location given the options that were passed to @command{configure}.
+@end deffn
+
+@deffn {Scheme Procedure} close-connection @var{server}
+Close the connection to @var{server}.
+@end deffn
+
+@defvr {Scheme Variable} current-build-output-port
+This variable is bound to a SRFI-39 parameter, which refers to the port
+where build and error logs sent by the daemon should be written.
+@end defvr
+
+Procedures that make RPCs all take a server object as their first
+argument.
+
+@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
+Return @code{#t} when @var{path} is a valid store path.
+@end deffn
+
+@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
+Add @var{text} under file @var{name} in the store, and return its store
+path. @var{references} is the list of store paths referred to by the
+resulting store path.
+@end deffn
+
+@c FIXME
+@i{This section is currently incomplete.}
@node Derivations
@section Derivations
diff --git a/guix/store.scm b/guix/store.scm
index 5111d8f50a..c7eb9a7605 100644
--- a/guix/store.scm
+++ b/guix/store.scm
@@ -308,6 +308,10 @@
(define* (open-connection #:optional (file %default-socket-path)
#:key (reserve-space? #t))
+ "Connect to the daemon over the Unix-domain socket at FILE. When
+RESERVE-SPACE? is true, instruct it to reserve a little bit of extra
+space on the file system so that the garbage collector can still
+operate, should the disk become full. Return a server object."
(let ((s (with-fluids ((%default-port-encoding #f))
;; This trick allows use of the `scm_c_read' optimization.
(socket PF_UNIX SOCK_STREAM 0)))
@@ -446,7 +450,9 @@ again until #t is returned or an error is raised."
(define-operation (add-text-to-store (string name) (string text)
(string-list references))
- "Add TEXT under file NAME in the store."
+ "Add TEXT under file NAME in the store, and return its store path.
+REFERENCES is the list of store paths referred to by the resulting store
+path."
store-path)
(define-operation (add-to-store (string basename)