Archived
1
0
Fork 0

doc: Move list of build phases to "Build Phases".

Before this change, the 'gnu-build-system' phases were listed in the
"Build Systems" section, and then summarized in the "Build Phases"
section.  This moves everything to "Build Phases".

* doc/guix.texi (Build Systems): Move phase table to...
(Build Phases): ... here.  Rearrange surrounding text.
This commit is contained in:
Ludovic Courtès 2021-04-11 15:02:23 +02:00
parent a514b4ab19
commit eb613eff58
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5

View file

@ -7298,55 +7298,7 @@ standards, GNU Coding Standards}).
In a nutshell, packages using it are configured, built, and installed with In a nutshell, packages using it are configured, built, and installed with
the usual @code{./configure && make && make check && make install} the usual @code{./configure && make && make check && make install}
command sequence. In practice, a few additional steps are often needed. command sequence. In practice, a few additional steps are often needed.
All these steps are split up in separate @dfn{phases}, 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 @option{--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-build?} 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
@code{%standard-phases} as the default list of build phases.
@code{%standard-phases} is a list of symbol/procedure pairs, where the
procedure implements the actual phase.
@xref{Build Phases}, for more info on build phases and ways to customize @xref{Build Phases}, for more info on build phases and ways to customize
them. them.
@ -8250,16 +8202,53 @@ exception is the ``bare-bones'' @code{trivial-build-system}
(@pxref{Build Systems}). (@pxref{Build Systems}).
As discussed in the previous section, those build systems provide a As discussed in the previous section, those build systems provide a
standard list of phases. For @code{gnu-build-system}, the standard standard list of phases. For @code{gnu-build-system}, the main build
phases include an @code{unpack} phase to unpack the source code tarball, phases are the following:
a @command{configure} phase to run @code{./configure}, a @code{build}
phase to run @command{make}, and (among others) an @code{install} phase @table @code
to run @command{make install}; @pxref{Build Systems}, for a more @item unpack
detailed view of these phases. Likewise, @code{cmake-build-system} Unpack the source tarball, and change the current directory to the
inherits these phases, but its @code{configure} phase runs extracted source tree. If the source is actually a directory, copy it
@command{cmake} instead of @command{./configure}. Other build systems, to the build tree, and enter that directory.
such as @code{python-build-system}, have a wholly different list of
standard phases. All this code runs on the @dfn{build side}: it is @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 @option{--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-build?} 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
Other build systems have similar phases, with some variations. For
example, @code{cmake-build-system} has same-named phases but its
@code{configure} phases runs @code{cmake} instead of @code{./configure}.
Others, such as @code{python-build-system}, have a wholly different list
of standard phases. All this code runs on the @dfn{build side}: it is
evaluated when you actually build the package, in a dedicated build evaluated when you actually build the package, in a dedicated build
process spawned by the build daemon (@pxref{Invoking guix-daemon}). process spawned by the build daemon (@pxref{Invoking guix-daemon}).
@ -8270,6 +8259,7 @@ is a procedure that accepts an arbitrary number of arguments. By
convention, those procedures receive information about the build in the convention, those procedures receive information about the build in the
form of @dfn{keyword parameters}, which they can use or ignore. form of @dfn{keyword parameters}, which they can use or ignore.
@vindex %standard-phases
For example, here is how @code{(guix build gnu-build-system)} defines For example, here is how @code{(guix build gnu-build-system)} defines
@code{%standard-phases}, the variable holding its alist of build @code{%standard-phases}, the variable holding its alist of build
phases@footnote{We present a simplified view of those build phases, but phases@footnote{We present a simplified view of those build phases, but