01/03: doc: Mention 'specification->package'.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit f6c9fb1b38732fab867db086b0527b01adb03dce
Author: Ludovic Courtès <address@hidden>
Date:   Sat Nov 28 15:25:42 2015 +0100

    doc: Mention 'specification->package'.
    
    Suggested by Florian Paul Schmidt <address@hidden>.
    
    * doc/guix.texi (Using the Configuration System): Mention
    'specification->package'.
---
 doc/guix.texi |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index ab1e4be..f7adfaf 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5543,6 +5543,26 @@ editor, @command{find}, @command{grep}, etc.  The 
example above adds
 tcpdump to those, taken from the @code{(gnu packages admin)} module
 (@pxref{Package Modules}).
 
address@hidden specification->package
+Referring to packages by variable name, like @var{tcpdump} above, has
+the advantage of being unambiguous; it also allows typos and such to be
+diagnosed right away as ``unbound variables''.  The downside is that one
+needs to know which module defines which package, and to augment the
address@hidden line accordingly.  To avoid that, one can use
+the @code{specification->package} procedure of the @code{(gnu packages)}
+module, which returns the best package for a given name or name and
+version:
+
address@hidden
+(use-modules (gnu packages))
+
+(operating-system
+  ;; ...
+  (packages (append (map specification->package
+                         '("tcpdump" "htop" "gnupg-2.0"))
+                    %base-packages)))
address@hidden lisp
+
 @vindex %base-services
 The @code{services} field lists @dfn{system services} to be made
 available when the system starts (@pxref{Services}).