diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 170 |
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 |