From e7f34eb0dc5a5302726857a77de3cf5f6635c1b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Fri, 7 Mar 2014 10:21:34 +0100 Subject: [PATCH] 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) : 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. --- doc/guix.texi | 50 +++++++++++++++++++++++++++++++++++++------------- 1 file 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{} 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{} object (@pxref{Defining Packages}). The @code{(gnu -packages)} module provides facilities for searching for packages. +@code{} 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