diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 195 |
1 files changed, 117 insertions, 78 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 78736fadf2..701b5400f8 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -102,7 +102,7 @@ explicit inputs are visible. The result of package build functions is @dfn{cached} in the file 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 +store---by default under @file{/gnu/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. @@ -165,7 +165,7 @@ between both. To do so, you must pass @command{configure} not only the same @code{--with-store-dir} value, but also the same @code{--localstatedir} value. The latter is essential because it specifies where the database that stores metadata about the store is -located, among other things. The default values are +located, among other things. The default values for Nix are @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}. Note that @code{--disable-daemon} is not required if your goal is to share the store with Nix. @@ -195,7 +195,7 @@ environment. In a standard multi-user setup, Guix and its daemon---the @command{guix-daemon} program---are installed by the system -administrator; @file{/nix/store} is owned by @code{root} and +administrator; @file{/gnu/store} is owned by @code{root} and @command{guix-daemon} runs as @code{root}. Unprivileged users may use Guix tools to build packages or otherwise access the store, and the daemon will do it on their behalf, ensuring that the store is kept in a @@ -577,7 +577,7 @@ management tools it provides. When using Guix, each package ends up in the @dfn{package store}, in its own directory---something that resembles -@file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string. +@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string. Instead of referring to these directories, users have their own @dfn{profile}, which points to the packages that they actually want to @@ -586,10 +586,10 @@ use. These profiles are stored within each user's home directory, at For example, @code{alice} installs GCC 4.7.2. As a result, @file{/home/alice/.guix-profile/bin/gcc} points to -@file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine, +@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine, @code{bob} had already installed GCC 4.8.0. The profile of @code{bob} simply continues to point to -@file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC +@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC coexist on the same system without any interference. The @command{guix package} command is the central tool to manage @@ -621,7 +621,7 @@ collected. @cindex reproducible builds Finally, Guix takes a @dfn{purely functional} approach to package management, as described in the introduction (@pxref{Introduction}). -Each @file{/nix/store} package directory name contains a hash of all the +Each @file{/gnu/store} package directory name contains a hash of all the inputs that were used to build that package---compiler, libraries, build scripts, etc. This direct correspondence allows users to make sure a given package installation matches the current state of their @@ -632,7 +632,7 @@ machines (@pxref{Invoking guix-daemon, container}). @cindex substitute This foundation allows Guix to support @dfn{transparent binary/source -deployment}. When a pre-built binary for a @file{/nix/store} path is +deployment}. When a pre-built binary for a @file{/gnu/store} path is available from an external source---a @dfn{substitute}, Guix just downloads it@footnote{@c XXX: Remove me when outdated. As of version @value{VERSION}, substitutes are downloaded from @@ -699,7 +699,9 @@ such as @code{guile-1.8.8}. If no version number is specified, the newest available version will be selected. In addition, @var{package} may contain a colon, followed by the name of one of the outputs of the package, as in @code{gcc:doc} or @code{binutils-2.22:lib} -(@pxref{Packages with Multiple Outputs}). +(@pxref{Packages with Multiple Outputs}). Packages with a corresponding +name (and optionally version) are searched for among the GNU +distribution modules (@pxref{Package Modules}). @cindex propagated inputs Sometimes packages have @dfn{propagated inputs}: these are dependencies @@ -789,21 +791,6 @@ suggest setting these variables to @code{@var{profile}/include} and @itemx -p @var{profile} Use @var{profile} instead of the user's default profile. -@item --dry-run -@itemx -n -Show what would be done without actually doing it. - -@item --fallback -When substituting a pre-built binary fails, fall back to building -packages locally. - -@item --no-substitutes -Do not use substitutes for build products. That is, always build things -locally instead of allowing downloads of pre-built binaries. - -@item --max-silent-time=@var{seconds} -Same as for @command{guix build} (@pxref{Invoking guix build}). - @item --verbose Produce verbose output. In particular, emit the environment's build log on the standard error port. @@ -918,6 +905,10 @@ Consequently, this command must be used with care. @end table +Finally, since @command{guix package} may actually start build +processes, it supports all the common build options that @command{guix +build} supports (@pxref{Invoking guix build, common build options}). + @node Packages with Multiple Outputs @section Packages with Multiple Outputs @@ -974,10 +965,10 @@ guix package}). @cindex garbage collector Packages that are installed but not used may be @dfn{garbage-collected}. The @command{guix gc} command allows users to explicitly run the garbage -collector to reclaim space from the @file{/nix/store} directory. +collector to reclaim space from the @file{/gnu/store} directory. The garbage collector has a set of known @dfn{roots}: any file under -@file{/nix/store} reachable from a root is considered @dfn{live} and +@file{/gnu/store} reachable from a root is considered @dfn{live} and cannot be deleted; any other file is considered @dfn{dead} and may be deleted. The set of garbage collector roots includes default user profiles, and may be augmented with @command{guix build --root}, for @@ -997,7 +988,7 @@ information. The available options are listed below: @table @code @item --collect-garbage[=@var{min}] @itemx -C [@var{min}] -Collect garbage---i.e., unreachable @file{/nix/store} files and +Collect garbage---i.e., unreachable @file{/gnu/store} files and sub-directories. This is the default operation when no option is specified. @@ -1170,13 +1161,13 @@ containing the @code{gui} output of the @code{git} package and the main output of @code{emacs}: @example -guix archive --export git:gui /nix/store/...-emacs-24.3 > great.nar +guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar @end example If the specified packages are not built yet, @command{guix archive} automatically builds them. The build process may be controlled with the same options that can be passed to the @command{guix build} command -(@pxref{Invoking guix build}). +(@pxref{Invoking guix build, common build options}). @c ********************************************************************* @@ -1192,7 +1183,7 @@ turned into concrete build actions. Build actions are performed by the Guix daemon, on behalf of users. In a standard setup, the daemon has write access to the store---the -@file{/nix/store} directory---whereas users do not. The recommended +@file{/gnu/store} directory---whereas users do not. The recommended setup also has the daemon perform builds in chroots, under a specific build users, to minimize interference with the rest of the system. @@ -1223,10 +1214,11 @@ example, the package definition, or @dfn{recipe}, for the GNU Hello package looks like this: @example -(use-modules (guix packages) - (guix download) - (guix build-system gnu) - (guix licenses)) +(define-module (gnu packages hello) + #:use-module (guix packages) + #:use-module (guix download) + #:use-module (guix build-system gnu) + #:use-module (guix licenses)) (define hello (package @@ -1248,13 +1240,19 @@ package looks like this: @noindent Without being a Scheme expert, the reader may have guessed the meaning -of the various fields here. This expression binds variable @var{hello} +of the various fields here. This expression binds variable @code{hello} to a @code{<package>} object, which is essentially a record (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}). This package object can be inspected using procedures found in the @code{(guix packages)} module; for instance, @code{(package-name hello)} returns---surprise!---@code{"hello"}. +In the example above, @var{hello} is defined into a module of its own, +@code{(gnu packages hello)}. Technically, this is not strictly +necessary, but it is convenient to do so: all the packages defined in +modules under @code{(gnu packages @dots{})} are automatically known to +the command-line tools (@pxref{Package Modules}). + There are a few points worth noting in the above package definition: @itemize @@ -1342,7 +1340,7 @@ definition to a new upstream version can be partly automated by the Behind the scenes, a derivation corresponding to the @code{<package>} object is first computed by the @code{package-derivation} procedure. -That derivation is stored in a @code{.drv} file under @file{/nix/store}. +That derivation is stored in a @code{.drv} file under @file{/gnu/store}. The build actions it prescribes may then be realized by using the @code{build-derivations} procedure (@pxref{The Store}). @@ -1381,7 +1379,7 @@ Configure and Build System}). @cindex store paths Conceptually, the @dfn{store} is where derivations that have been -successfully built are stored---by default, under @file{/nix/store}. +successfully built are stored---by default, under @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 has the store paths referred to by each store path, and the list of @emph{valid} @@ -1526,7 +1524,7 @@ to a Bash executable in the store: (derivation store "foo" bash `("-e" ,builder) #:env-vars '(("HOME" . "/homeless")))) -@result{} #<derivation /nix/store/@dots{}-foo.drv => /nix/store/@dots{}-foo> +@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo> @end lisp As can be guessed, this primitive is cumbersome to use directly. An @@ -1570,13 +1568,13 @@ containing one file: @lisp (let ((builder '(let ((out (assoc-ref %outputs "out"))) - (mkdir out) ; create /nix/store/@dots{}-goo + (mkdir out) ; create /gnu/store/@dots{}-goo (call-with-output-file (string-append out "/test") (lambda (p) (display '(hello guix) p)))))) (build-expression->derivation store "goo" builder)) -@result{} #<derivation /nix/store/@dots{}-goo.drv => @dots{}> +@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}> @end lisp @cindex strata of code @@ -1654,7 +1652,7 @@ effect, one must use @code{run-with-store}: @example (run-with-store (open-connection) (profile.sh)) -@result{} /nix/store/...-profile.sh +@result{} /gnu/store/...-profile.sh @end example The main syntactic forms to deal with monads in general are described @@ -1729,7 +1727,7 @@ like this: grep "/bin:" sed "/bin\n")) @end example -In this example, the resulting @file{/nix/store/@dots{}-profile.sh} file +In this example, the resulting @file{/gnu/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 @@ -1789,10 +1787,14 @@ guix build @var{options} @var{package-or-derivation}@dots{} @var{package-or-derivation} may be either the name of a package found in the software distribution such as @code{coreutils} or @code{coreutils-8.20}, or a derivation such as -@file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the -@code{--expression} option may be used to specify a Scheme expression -that evaluates to a package; this is useful when disambiguation among -several same-named packages or package variants is needed. +@file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a +package with the corresponding name (and optionally version) is searched +for among the GNU distribution modules (@pxref{Package Modules}). + +Alternatively, the @code{--expression} option may be used to specify a +Scheme expression that evaluates to a package; this is useful when +disambiguation among several same-named packages or package variants is +needed. The @var{options} may be zero or more of the following: @@ -1816,7 +1818,7 @@ Build the packages' source derivations, rather than the packages themselves. For instance, @code{guix build -S gcc} returns something like -@file{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball. +@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball. The returned source tarball is the result of applying any patches and code snippets specified in the package's @code{origin} (@pxref{Defining @@ -1843,6 +1845,37 @@ configuration triplets,, configure, GNU Configure and Build System}). Return the derivation paths, not the output paths, of the given packages. +@item --root=@var{file} +@itemx -r @var{file} +Make @var{file} a symlink to the result, and register it as a garbage +collector root. + +@item --log-file +Return the build log file names for the given +@var{package-or-derivation}s, or raise an error if build logs are +missing. + +This works regardless of how packages or derivations are specified. For +instance, the following invocations are equivalent: + +@example +guix build --log-file `guix build -d guile` +guix build --log-file `guix build guile` +guix build --log-file guile +guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' +@end example + + +@end table + +@cindex common build options +In addition, a number of options that control the build process are +common to @command{guix build} and other commands that can spawn builds, +such as @command{guix package} or @command{guix archive}. These are the +following: + +@table @code + @item --keep-failed @itemx -K Keep the build tree of failed builds. Thus, if a build fail, its build @@ -1870,36 +1903,22 @@ instead of offloading builds to remote machines. When the build or substitution process remains silent for more than @var{seconds}, terminate it and report a build failure. -@item --cores=@var{n} -@itemx -c @var{n} -Allow the use of up to @var{n} CPU cores for the build. The special -value @code{0} means to use as many CPU cores as available. +@item --timeout=@var{seconds} +Likewise, when the build or substitution process lasts for more than +@var{seconds}, terminate it and report a build failure. -@item --root=@var{file} -@itemx -r @var{file} -Make @var{file} a symlink to the result, and register it as a garbage -collector root. +By default there is no timeout. This behavior can be restored with +@code{--timeout=0}. @item --verbosity=@var{level} Use the given verbosity level. @var{level} must be an integer between 0 and 5; higher means more verbose output. Setting a level of 4 or more may be helpful when debugging setup issues with the build daemon. -@item --log-file -Return the build log file names for the given -@var{package-or-derivation}s, or raise an error if build logs are -missing. - -This works regardless of how packages or derivations are specified. For -instance, the following invocations are equivalent: - -@example -guix build --log-file `guix build -d guile` -guix build --log-file `guix build guile` -guix build --log-file guile -guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' -@end example - +@item --cores=@var{n} +@itemx -c @var{n} +Allow the use of up to @var{n} CPU cores for the build. The special +value @code{0} means to use as many CPU cores as available. @end table @@ -2184,7 +2203,7 @@ the load. To check whether a package has a @code{debug} output, use @section Package Modules From a programming viewpoint, the package definitions of the -distribution are provided by Guile modules in the @code{(gnu packages +GNU distribution are provided by Guile modules in the @code{(gnu packages @dots{})} name space@footnote{Note that packages under the @code{(gnu packages @dots{})} module name space are not necessarily ``GNU packages''. This module naming scheme follows the usual Guile module @@ -2193,8 +2212,19 @@ as part of the GNU system, and @code{packages} identifies modules that define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile Reference Manual}). For instance, the @code{(gnu packages emacs)} module exports a variable named @code{emacs}, which is bound to a -@code{<package>} object (@pxref{Defining Packages}). The @code{(gnu -packages)} module provides facilities for searching for packages. +@code{<package>} object (@pxref{Defining Packages}). + +The @code{(gnu packages @dots{})} module name space is special: it is +automatically scanned for packages by the command-line tools. For +instance, when running @code{guix package -i emacs}, all the @code{(gnu +packages @dots{})} modules are scanned until one that exports a package +object whose name is @code{emacs} is found. This package search +facility is implemented in the @code{(gnu packages)} module. + +Users can store package definitions in modules with different +names---e.g., @code{(my-packages emacs)}. In that case, commands such +as @command{guix package} and @command{guix build} have to be used with +the @code{-e} option so that they know where to find the package. The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: each package is built based solely on other packages in the @@ -2240,6 +2270,15 @@ called @code{gnew}, you may run this command from the Guix build tree: Using @code{--keep-failed} makes it easier to debug build failures since it provides access to the failed build tree. +If the package is unknown to the @command{guix} command, it may be that +the source file contains a syntax error, or lacks a @code{define-public} +clause to export the package variable. To figure it out, you may load +the module from Guile to get more information about the actual error: + +@example +./pre-inst-env guile -c '(use-modules (gnu packages gnew))' +@end example + Once your package builds correctly, please send us a patch (@pxref{Contributing}). Well, if you need help, we will be happy to help you too. Once the patch is committed in the Guix repository, the @@ -2452,7 +2491,7 @@ etc., at which point we have a working C tool chain. Bootstrapping is complete when we have a full tool chain that does not depend on the pre-built bootstrap tools discussed above. This no-dependency requirement is verified by checking whether the files of -the final tool chain contain references to the @file{/nix/store} +the final tool chain contain references to the @file{/gnu/store} directories of the bootstrap inputs. The process that leads to this ``final'' tool chain is described by the package definitions found in the @code{(gnu packages base)} module. @@ -2754,10 +2793,10 @@ deco,,, dmd, GNU dmd Manual}). @chapter Contributing This project is a cooperative effort, and we need your help to make it -grow! Please get in touch with us on @email{guix-devel@@gnu.org}. We -welcome ideas, bug reports, patches, and anything that may be helpful to -the project. We particularly welcome help on packaging -(@pxref{Packaging Guidelines}). +grow! Please get in touch with us on @email{guix-devel@@gnu.org} and +@code{#guix} on the Freenode IRC network. We welcome ideas, bug +reports, patches, and anything that may be helpful to the project. We +particularly welcome help on packaging (@pxref{Packaging Guidelines}). Please see the @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING, |