summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2014-04-05 17:01:06 +0200
committerLudovic Courtès <ludo@gnu.org>2014-04-05 17:02:21 +0200
commit7458bd0a4aabbef19070c234d38905ad05b19b32 (patch)
tree7c44d6430697a5a2338113b5f65562023634922e
parent59f21ee34ab47cf48969d4e49a84b54e615cbf76 (diff)
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'.
-rw-r--r--doc/guix.texi226
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}