summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2014-03-07 10:21:34 +0100
committerLudovic Courtès <ludo@gnu.org>2014-03-08 00:18:21 +0100
commite7f34eb0dc5a5302726857a77de3cf5f6635c1b7 (patch)
treeef7074092ebe485a5d048b5b8e07a43a68705f28
parent583103416dc868826ef573b55c2e6657cd62eb36 (diff)
doc: Explain what's special about the (gnu packages ...) name space.
* doc/guix.texi (Invoking guix package): Explain where packages are searched for and link to "Package Modules". (Defining Packages) <example>: Use 'define-module' clause instead of 'use-modules'. Explain why and link to "Package Modules". (Invoking guix build): Explain where packages aer searched for and link to "Package Modules". (Package Modules): Explain that (gnu packages ...) is scanned.
-rw-r--r--doc/guix.texi50
1 files changed, 37 insertions, 13 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index baa1990484..97a725a5d4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -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
@@ -1212,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
@@ -1237,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
@@ -1778,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{/nix/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:
@@ -2183,7 +2196,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
@@ -2192,8 +2205,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