02/04: doc: Reword description of 'inputs' & co.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 70650c684aed96e7b7d42548ebb012f716554024
Author: Ludovic Courtès <address@hidden>
Date:   Sun Dec 13 14:42:38 2015 +0100

    doc: Reword description of 'inputs' & co.
    
    * doc/guix.texi (package Reference): Reword explanation of 'inputs',
    'native-inputs', and 'propagated-inputs'.  Add example.
---
 doc/guix.texi |   56 ++++++++++++++++++++++++++++++++++----------------------
 1 files changed, 34 insertions(+), 22 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 401e98b..e0235b9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2263,34 +2263,46 @@ The arguments that should be passed to the build 
system.  This is a
 list, typically containing sequential keyword-value pairs.
 
 @item @code{inputs} (default: @code{'()})
-Package or derivation inputs to the build.  This is a list of lists,
-where each list has the name of the input (a string) as its first
-element, a package or derivation object as its second element, and
-optionally the name of the output of the package or derivation that
-should be used, which defaults to @code{"out"}.
-
address@hidden @address@hidden (default: @code{'()})
address@hidden propagated inputs
-This field is like @code{inputs}, but the specified packages will be
-force-installed alongside the package they belong to
-(@pxref{package-cmd-propagated-inputs, @command{guix package}}, for
-information on how @command{guix package} deals with propagated inputs.)
address@hidden @code{native-inputs} (default: @code{'()})
address@hidden @code{propagated-inputs} (default: @code{'()})
address@hidden inputs, of packages
+These fields list dependencies of the package.  Each one is a list of
+tuples, where each tuple has a label for the input (a string) as its
+first element, a package, origin, or derivation as its second element,
+and optionally the name of the output thereof that should be used, which
+defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
+more on package outputs).  For example, the list below specifies 3
+inputs:
+
address@hidden
+`(("libffi" ,libffi)
+  ("libunistring" ,libunistring)
+  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
address@hidden example
+
address@hidden cross compilation, package dependencies
+The distinction between @code{native-inputs} and @code{inputs} is
+necessary when considering cross-compilation.  When cross-compiling,
+dependencies listed in @code{inputs} are built for the @emph{target}
+architecture; conversely, dependencies listed in @code{native-inputs}
+are built for the architecture of the @emph{build} machine.
+
address@hidden is typically where you would list tools needed at
+build time but not at run time, such as Autoconf, Automake, pkg-config,
+Gettext, or Bison.  @command{guix lint} can report likely mistakes in
+this area (@pxref{Invoking guix lint}).
+
address@hidden
+Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
+specified packages will be force-installed alongside the package they
+belong to (@pxref{package-cmd-propagated-inputs, @command{guix
+package}}, for information on how @command{guix package} deals with
+propagated inputs.)
 
 For example this is necessary when a library needs headers of another
 library to compile, or needs another shared library to be linked
 alongside itself when a program wants to link to it.
 
address@hidden @code{native-inputs} (default: @code{'()})
-This field is like @code{inputs}, but in case of a cross-compilation it
-will be ensured that packages for the architecture of the build machine
-are present, such that executables from them can be used during the
-build.
-
-This is typically where you would list tools needed at build time but
-not at run time, such as Autoconf, Automake, pkg-config, Gettext, or
-Bison.  @command{guix lint} can report likely mistakes in this area
-(@pxref{Invoking guix lint}).
-
 @item @code{self-native-input?} (default: @code{#f})
 This is a Boolean field telling whether the package should use itself as
 a native input when cross-compiling.