Merge branch 'master' into core-updates

Conflicts:
	gnu-system.am

1 files changed, 135 insertions, 35 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 91fa07f1a8..78736fadf2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -502,6 +502,30 @@ the daemon makes the new file a hard link to the other file.  This
 slightly increases the input/output load at the end of a build process.
 This option disables this.
 
+@item --gc-keep-outputs[=yes|no]
+Tell whether the garbage collector (GC) must keep outputs of live
+derivations.
+
+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.
+
+@item --gc-keep-derivations[=yes|no]
+Tell whether the garbage collector (GC) must keep derivations
+corresponding to live outputs.
+
+When set to ``yes'', as is the case by default, the GC keeps
+derivations---i.e., @code{.drv} files---as long as at least one of their
+outputs is live.  This allows users to keep track of the origins of
+items in their store.  Setting it to ``no'' saves a bit of disk space.
+
+Note that when both @code{--gc-keep-derivations} and
+@code{--gc-keep-outputs} are used, the effect is to keep all the build
+prerequisites (the sources, compiler, libraries, and other build-time
+tools) of live objects in the store, regardless of whether these
+prerequisites are live.  This is convenient for developers since it
+saves rebuilds or downloads.
+
 @item --impersonate-linux-2.6
 On Linux-based systems, impersonate Linux 2.6.  This means that the
 kernel's @code{uname} system call will report 2.6 as the release number.
@@ -1071,11 +1095,19 @@ the target machine's store.  The @code{--missing} option can help figure
 out which items are missing from the target's store.
 
 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
-comparable in spirit to `tar'.  When exporting, the daemon digitally
-signs the contents of the archive, and that digital signature is
-appended.  When importing, the daemon verifies the signature and rejects
-the import in case of an invalid signature or if the signing key is not
-authorized.
+comparable in spirit to `tar', but with a few noteworthy differences
+that make it more appropriate for our purposes.  First, rather than
+recording all Unix meta-data for each file, the Nar format only mentions
+the file type (regular, directory, or symbolic link); Unix permissions
+and owner/group are dismissed.  Second, the order in which directory
+entries are stored always follows the order of file names according to
+the C locale collation order.  This makes archive production fully
+deterministic.
+
+When exporting, the daemon digitally signs the contents of the archive,
+and that digital signature is appended.  When importing, the daemon
+verifies the signature and rejects the import in case of an invalid
+signature or if the signing key is not authorized.
 @c FIXME: Add xref to daemon doc about signatures.
 
 The main options are:
@@ -1454,15 +1486,18 @@ a derivation is the @code{derivation} procedure:
 
 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
   @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
-  [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] @
+  [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
   [#:system (%current-system)] [#:references-graphs #f] @
   [#:local-build? #f]
 Build a derivation with the given arguments, and return the resulting
 @code{<derivation>} object.
 
-When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
+When @var{hash} and @var{hash-algo} are given, a
 @dfn{fixed-output derivation} is created---i.e., one whose result is
-known in advance, such as a file download.
+known in advance, such as a file download.  If, in addition,
+@var{recursive?} is true, then that fixed output may be an executable
+file or a directory and @var{hash} must be the hash of an archive
+containing this output.
 
 When @var{references-graphs} is true, it must be a list of file
 name/store path pairs.  In that case, the reference graph of each store
@@ -1502,7 +1537,7 @@ the caller to directly pass a Guile expression as the build script:
        @var{name} @var{exp} @
        [#:system (%current-system)] [#:inputs '()] @
        [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
-       [#:env-vars '()] [#:modules '()] @
+       [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
        [#:references-graphs #f] [#:local-build? #f] [#:guile-for-build #f]
 Return a derivation that executes Scheme expression @var{exp} as a
 builder for derivation @var{name}.  @var{inputs} must be a list of
@@ -1590,23 +1625,22 @@ in a monad---values that carry this additional context---are called
 Consider this ``normal'' procedure:
 
 @example
-(define (profile.sh store)
-  ;; Return the name of a shell script in the store that
-  ;; initializes the 'PATH' environment variable.
-  (let* ((drv (package-derivation store coreutils))
-         (out (derivation->output-path drv)))
-    (add-text-to-store store "profile.sh"
-                       (format #f "export PATH=~a/bin" out))))
+(define (sh-symlink store)
+  ;; Return a derivation that symlinks the 'bash' executable.
+  (let* ((drv (package-derivation store bash))
+         (out (derivation->output-path drv))
+         (sh  (string-append out "/bin/bash")))
+    (build-expression->derivation store "sh"
+                                  `(symlink ,sh %output))))
 @end example
 
 Using @code{(guix monads)}, it may be rewritten as a monadic function:
 
 @example
-(define (profile.sh)
+(define (sh-symlink)
   ;; Same, but return a monadic value.
-  (mlet %store-monad ((bin (package-file coreutils "bin")))
-    (text-file "profile.sh"
-               (string-append "export PATH=" bin))))
+  (mlet %store-monad ((sh (package-file bash "bin")))
+    (derivation-expression "sh" `(symlink ,sh %output))))
 @end example
 
 There are two things to note in the second version: the @code{store}
@@ -1672,7 +1706,32 @@ open store connection.
 
 @deffn {Monadic Procedure} text-file @var{name} @var{text}
 Return as a monadic value the absolute file name in the store of the file
-containing @var{text}.
+containing @var{text}, a string.
+@end deffn
+
+@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
+Return as a monadic value a derivation that builds a text file
+containing all of @var{text}.  @var{text} may list, in addition to
+strings, packages, derivations, and store file names; the resulting
+store file holds references to all these.
+
+This variant should be preferred over @code{text-file} anytime the file
+to create will reference items from the store.  This is typically the
+case when building a configuration file that embeds store file names,
+like this:
+
+@example
+(define (profile.sh)
+  ;; Return the name of a shell script in the store that
+  ;; initializes the 'PATH' environment variable.
+  (text-file* "profile.sh"
+              "export PATH=" coreutils "/bin:"
+              grep "/bin:" sed "/bin\n"))
+@end example
+
+In this example, the resulting @file{/nix/store/@dots{}-profile.sh} file
+will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
+preventing them from being garbage-collected during its lifetime.
 @end deffn
 
 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
@@ -1910,6 +1969,19 @@ If the @option{--format} option is not specified, @command{guix hash}
 will output the hash in @code{nix-base32}.  This representation is used
 in the definitions of packages.
 
+@item --recursive
+@itemx -r
+Compute the hash on @var{file} recursively.
+
+In this case, the hash is computed on an archive containing @var{file},
+including its children if it is a directory.  Some of @var{file}'s
+meta-data is part of the archive; for instance, when @var{file} is a
+regular file, the hash is different depending on whether @var{file} is
+executable or not.  Meta-data such as time stamps has no impact on the
+hash (@pxref{Invoking guix archive}).
+@c FIXME: Replace xref above with xref to an ``Archive'' section when
+@c it exists.
+
 @end table
 
 @node Invoking guix refresh
@@ -2499,8 +2571,9 @@ instantiated.  Then we show how this mechanism can be extended, for
 instance to support new system services.
 
 @menu
-* Using the Configuration System::      Customizing your GNU system.
-* Defining Services::                   Adding new service definitions.
+* Using the Configuration System::  Customizing your GNU system.
+* Invoking guix system::        Instantiating a system configuration.
+* Defining Services::           Adding new service definitions.
 @end menu
 
 @node Using the Configuration System
@@ -2513,9 +2586,9 @@ Linux-Libre kernel, initial RAM disk, and boot loader looks like this:
 
 @findex operating-system
 @lisp
-(use-modules (gnu system)
+(use-modules (gnu services base)   ; for '%base-services'
+             (gnu services ssh)    ; for 'lsh-service'
              (gnu system shadow)   ; for 'user-account'
-             (gnu system service)  ; for 'lsh-service'
              (gnu packages base)   ; Coreutils, grep, etc.
              (gnu packages bash)   ; Bash
              (gnu packages admin)  ; dmd, Inetutils
@@ -2542,7 +2615,7 @@ Linux-Libre kernel, initial RAM disk, and boot loader looks like this:
                    procps psmisc
                    zile less))
    (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
-                   %standard-services))))
+                   %base-services))))
 @end lisp
 
 This example should be self-describing.  The @code{packages} field lists
@@ -2552,9 +2625,10 @@ visible on the system, for all user accounts---i.e., in every user's
 @code{PATH} environment variable---in addition to the per-user profiles
 (@pxref{Invoking guix package}).
 
+@vindex %base-services
 The @code{services} field lists @dfn{system services} to be made
-available when the system starts.  The @var{%standard-services} list,
-from the @code{(gnu system)} module, provides the basic services one
+available when the system starts.  The @var{%base-services} list,
+from the @code{(gnu services base)} module, provides the basic services one
 would expect from a GNU system: a login service (mingetty) on each tty,
 syslogd, libc's name service cache daemon (nscd), etc.
 
@@ -2566,13 +2640,12 @@ daemon listening on port 2222, and allowing remote @code{root} logins
 right command-line options, possibly with supporting configuration files
 generated as needed (@pxref{Defining Services}).
 
-@c TODO: update when that command exists
 Assuming the above snippet is stored in the @file{my-system-config.scm}
-file, the (yet unwritten!) @command{guix system --boot
-my-system-config.scm} command instantiates that configuration, and makes
-it the default GRUB boot entry.  The normal way to change the system's
-configuration is by updating this file and re-running the @command{guix
-system} command.
+file, the @command{guix system boot my-system-config.scm} command
+instantiates that configuration, and makes it the default GRUB boot
+entry (@pxref{Invoking guix system}).  The normal way to change the
+system's configuration is by updating this file and re-running the
+@command{guix system} command.
 
 At the Scheme level, the bulk of an @code{operating-system} declaration
 is instantiated with the following monadic procedure (@pxref{The Store
@@ -2587,11 +2660,38 @@ the packages, configuration files, and other supporting files needed to
 instantiate @var{os}.
 @end deffn
 
+@node Invoking guix system
+@subsection Invoking @code{guix system}
+
+Once you have written an operating system declaration, as seen in the
+previous section, it can be @dfn{instantiated} using the @command{guix
+system} command.  The synopsis is:
+
+@example
+guix system @var{options}@dots{} @var{action} @var{file}
+@end example
+
+@var{file} must be the name of a file containing an
+@code{operating-system} declaration.  @var{action} specifies how the
+operating system is instantiate.  Currently only one value is supported:
+
+@table @code
+@item vm
+@cindex virtual machine
+Build a virtual machine that contain the operating system declared in
+@var{file}, and return a script to run that virtual machine (VM).
+
+The VM shares its store with the host system.
+@end table
+
+@var{options} can contain any of the common build options provided by
+@command{guix build} (@pxref{Invoking guix build}).
+
 
 @node Defining Services
 @subsection Defining Services
 
-The @code{(gnu system dmd)} module defines several procedures that allow
+The @code{(gnu services @dots{})} modules define several procedures that allow
 users to declare the operating system's services (@pxref{Using the
 Configuration System}).  These procedures are @emph{monadic
 procedures}---i.e., procedures that return a monadic value in the store