doc: Add "Build Systems" section.

* doc/guix.texi (Defining Packages): Add 'arguments' field in the
  example; update 'synopsis' and 'description'.  Remove most of the
  description of 'build-system', and instead reference to the "Build
  Systems" node.  Briefly describe 'arguments' field, and remove more
  elaborate description.  Add cross-reference to "Packaging Guidelines".
  (Build Systems): New node.
  (Packaging Guidelines): Mention '--log-file'.

1 files changed, 183 insertions, 43 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index b49825fc1d..863fce8307 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1301,6 +1301,7 @@ package definitions.
 
 @menu
 * Defining Packages::           Defining new packages.
+* Build Systems::               Specifying how packages are built.
 * The Store::                   Manipulating the package store.
 * Derivations::                 Low-level interface to package derivations.
 * The Store Monad::             Purely functional interface to the store.
@@ -1332,9 +1333,10 @@ package looks like this:
              (sha256
               (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
     (build-system gnu-build-system)
+    (arguments `(#:configure-flags '("--enable-silent-rules")))
     (inputs `(("gawk" ,gawk)))
-    (synopsis "GNU Hello")
-    (description "Yeah...")
+    (synopsis "Hello, GNU world: An example GNU package")
+    (description "Guess what GNU Hello prints!")
     (home-page "http://www.gnu.org/software/hello/")
     (license gpl3+)))
 @end example
@@ -1379,22 +1381,17 @@ Scheme expression to modify the source code.
 
 @item
 @cindex GNU Build System
-The @code{build-system} field is set to @var{gnu-build-system}.  The
-@var{gnu-build-system} variable is defined in the @code{(guix
-build-system gnu)} module, and is bound to a @code{<build-system>}
-object.
-
-Naturally, @var{gnu-build-system} represents the familiar GNU Build
-System, and variants thereof (@pxref{Configuration, configuration and
-makefile conventions,, standards, GNU Coding Standards}).  In a
-nutshell, packages using the GNU Build System may be configured, built,
-and installed with the usual @code{./configure && make && make check &&
-make install} command sequence.  This is what @var{gnu-build-system}
-does.
-
-In addition, @var{gnu-build-system} ensures that the ``standard''
-environment for GNU packages is available.  This includes tools such as
-GCC, Coreutils, Bash, Make, Diffutils, and Patch.
+The @code{build-system} field specifies the procedure to build the
+package (@pxref{Build Systems}).  Here, @var{gnu-build-system}
+represents the familiar GNU Build System, where packages may be
+configured, built, and installed with the usual @code{./configure &&
+make && make check && make install} command sequence.
+
+@item
+The @code{arguments} field specifies options for the build system
+(@pxref{Build Systems}).  Here it is interpreted by
+@var{gnu-build-system} as a request run @file{configure} with the
+@code{--enable-silent-rules} flag.
 
 @item
 The @code{inputs} field specifies inputs to the build process---i.e.,
@@ -1404,40 +1401,23 @@ variable; @var{gawk} is itself bound to a @code{<package>} object.
 
 Note that GCC, Coreutils, Bash, and other essential tools do not need to
 be specified as inputs here.  Instead, @var{gnu-build-system} takes care
-of ensuring that they are present.
+of ensuring that they are present (@pxref{Build Systems}).
 
 However, any other dependencies need to be specified in the
 @code{inputs} field.  Any dependency not specified here will simply be
 unavailable to the build process, possibly leading to a build failure.
 @end itemize
 
-There are other fields that package definitions may provide.  Of
-particular interest is the @code{arguments} field.  When specified, it
-must be bound to a list of additional arguments to be passed to the
-build system.  For instance, the above definition could be augmented
-with the following field initializer:
-
-@example
-    (arguments `(#:tests? #f
-                 #:configure-flags '("--enable-silent-rules")))
-@end example
-
-@noindent
-These are keyword arguments (@pxref{Optional Arguments, keyword
-arguments in Guile,, guile, GNU Guile Reference Manual}).  They are
-passed to @var{gnu-build-system}, which interprets them as meaning ``do
-not run @code{make check}'', and ``run @file{configure} with the
-@code{--enable-silent-rules} flag''.  The value of these keyword
-parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
-Guile process launched by the daemon (@pxref{Derivations}).
-
 Once a package definition is in place@footnote{Simple package
 definitions like the one above may be automatically converted from the
 Nixpkgs distribution using the @command{guix import} command.}, the
 package may actually be built using the @code{guix build} command-line
-tool (@pxref{Invoking guix build}).  Eventually, updating the package
-definition to a new upstream version can be partly automated by the
-@command{guix refresh} command (@pxref{Invoking guix refresh}).
+tool (@pxref{Invoking guix build}).  @xref{Packaging Guidelines}, for
+more information on how to test package definitions.
+
+Eventually, updating the package definition to a new upstream version
+can be partly automated by the @command{guix refresh} command
+(@pxref{Invoking guix refresh}).
 
 Behind the scenes, a derivation corresponding to the @code{<package>}
 object is first computed by the @code{package-derivation} procedure.
@@ -1473,6 +1453,164 @@ Configure and Build System}).
 @end deffn
 
 
+@node Build Systems
+@section Build Systems
+
+@cindex build system
+Each package definition specifies a @dfn{build system} and arguments for
+that build system (@pxref{Defining Packages}).  This @code{build-system}
+field represents the build procedure of the package, as well implicit
+dependencies of that build procedure.
+
+Build systems are @code{<build-system>} objects.  The interface to
+create and manipulate them is provided by the @code{(guix build-system)}
+module, and actual build systems are exported by specific modules.
+
+Build systems accept an optional list of @dfn{arguments}.  In package
+definitions, these are passed @i{via} the @code{arguments} field
+(@pxref{Defining Packages}).  They are typically keyword arguments
+(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
+Guile Reference Manual}).  The value of these arguments is usually
+evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
+by the daemon (@pxref{Derivations}).
+
+The main build system is @var{gnu-build-system}, which implements the
+standard build procedure for GNU packages and many other packages.  It
+is provided by the @code{(guix build-system gnu)} module.
+
+@defvr {Scheme Variable} gnu-build-system
+@var{gnu-build-system} represents the GNU Build System, and variants
+thereof (@pxref{Configuration, configuration and makefile conventions,,
+standards, GNU Coding Standards}).
+
+@cindex build phases
+In a nutshell, packages using it configured, built, and installed with
+the usual @code{./configure && make && make check && make install}
+command sequence.  In practice, a few additional steps are often needed.
+All these steps are split up in separate @dfn{phases},
+notably@footnote{Please see the @code{(guix build gnu-build-system)}
+modules for more details about the build phases.}:
+
+@table @code
+@item unpack
+Unpack the source tarball, and change the current directory to the
+extracted source tree.  If the source is actually a directory, copy it
+to the build tree, and enter that directory.
+
+@item patch-source-shebangs
+Patch shebangs encountered in source files so they refer to the right
+store file names.  For instance, this changes @code{#!/bin/sh} to
+@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
+
+@item configure
+Run the @file{configure} script with a number of default options, such
+as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
+by the @code{#:configure-flags} argument.
+
+@item build
+Run @code{make} with the list of flags specified with
+@code{#:make-flags}.  If the @code{#:parallel-builds?} argument is true
+(the default), build with @code{make -j}.
+
+@item check
+Run @code{make check}, or some other target specified with
+@code{#:test-target}, unless @code{#:tests? #f} is passed.  If the
+@code{#:parallel-tests?} argument is true (the default), run @code{make
+check -j}.
+
+@item install
+Run @code{make install} with the flags listed in @code{#:make-flags}.
+
+@item patch-shebangs
+Patch shebangs on the installed executable files.
+
+@item strip
+Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
+is false), copying them to the @code{debug} output when available
+(@pxref{Installing Debugging Files}).
+@end table
+
+@vindex %standard-phases
+The build-side module @code{(guix build gnu-build-system)} defines
+@var{%standard-phases} as the default list of build phases.
+@var{%standard-phases} is a list of symbol/procedure pairs, where the
+procedure implements the actual phase.
+
+The list of phases used for a particular package can be changed with the
+@code{#:phases} parameter.  For instance, passing:
+
+@example
+#:phases (alist-delete 'configure %standard-phases)
+@end example
+
+means that all the phases described above will be used, expect the
+@code{configure} phase.
+
+In addition, this build system ensures that the ``standard'' environment
+for GNU packages is available.  This includes tools such as GCC, libc,
+Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
+build-system gnu)} module for a complete list.)  We call these the
+@dfn{implicit inputs} of a package, because package definitions don't
+have to mention them.
+@end defvr
+
+Other @code{<build-system>} objects are defined to support other
+conventions and tools used by free software packages.  They inherit most
+of @var{gnu-build-system}, and differ mainly in the set of inputs
+implicitly added to the build process, and in the list of phases
+executed.  Some of these build systems are listed below.
+
+@defvr {Scheme Variable} cmake-build-system
+This variable is exported by @code{(guix build-system cmake)}.  It
+implements the build procedure for packages using the
+@url{http://www.cmake.org, CMake build tool}.
+
+It automatically adds the @code{cmake} package to the set of inputs.
+Which package is used can be specified with the @code{#:cmake}
+parameter.
+@end defvr
+
+@defvr {Scheme Variable} python-build-system
+This variable is exported by @code{(guix build-system python)}.  It
+implements the more or less standard build procedure used by Python
+packages, which consists in running @code{python setup.py build} and
+then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
+
+For packages that install stand-alone Python programs under @code{bin/},
+it takes care of wrapping these programs so their @code{PYTHONPATH}
+environment variable points to all the Python libraries they depend on.
+
+Which Python package is used can be specified with the @code{#:python}
+parameter.
+@end defvr
+
+@defvr {Scheme Variable} perl-build-system
+This variable is exported by @code{(guix build-system perl)}.  It
+implements the standard build procedure for Perl packages, which
+consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
+followed by @code{make} and @code{make install}.
+
+The initial @code{perl Makefile.PL} invocation passes flags specified by
+the @code{#:make-maker-flags} parameter.
+
+Which Perl package is used can be specified with @code{#:perl}.
+@end defvr
+
+
+Lastly, for packages that do not need anything as sophisticated, a
+``trivial'' build system is provided.  It is trivial in the sense that
+it provides basically no support: it does not pull any implicit inputs,
+and does not have a notion of build phases.
+
+@defvr {Scheme Variable} trivial-build-system
+This variable is exported by @code{(guix build-system trivial)}.
+
+This build system requires a @code{#:builder} argument.  This argument
+must be a Scheme expression that builds the package's output(s)---as
+with @code{build-expression->derivation} (@pxref{Derivations,
+@code{build-expression->derivation}}).
+@end defvr
+
 @node The Store
 @section The Store
 
@@ -2398,7 +2536,9 @@ called @code{gnew}, you may run this command from the Guix build tree:
 @end example
 
 Using @code{--keep-failed} makes it easier to debug build failures since
-it provides access to the failed build tree.
+it provides access to the failed build tree.  Another useful
+command-line option when debugging is @code{--log-file}, to access the
+build log.
 
 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}