diff options
| -rw-r--r-- | doc/guix.texi | 59 | ||||
| -rw-r--r-- | guix/store.scm | 8 |
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) |