doc: Start documenting derivations.
* doc/guix.texi (Defining Packages): Add cross-reference to "Derivations". (The Store): Add `build-derivations'. (Derivations): Populate.master
Ludovic Courtès
parent
1da983b9f0
commit
874e687428
139
doc/guix.texi
139
doc/guix.texi
|
|
@ -730,7 +730,9 @@ 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''.
|
||||
@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
|
||||
|
|
@ -809,13 +811,146 @@ path. @var{references} is the list of store paths referred to by the
|
|||
resulting store path.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
|
||||
Build @var{derivations} (a list of derivation paths), and return when
|
||||
the worker is done building them. Return @code{#t} on success.
|
||||
@end deffn
|
||||
|
||||
@c FIXME
|
||||
@i{This section is currently incomplete.}
|
||||
|
||||
@node Derivations
|
||||
@section Derivations
|
||||
|
||||
@code{(guix derivations)}
|
||||
@cindex derivations
|
||||
Low-level build actions and the environment in which they are performed
|
||||
are represented by @dfn{derivations}. A derivation contain the
|
||||
following pieces of information:
|
||||
|
||||
@itemize
|
||||
@item
|
||||
The outputs of the derivation---derivations produce at least one file or
|
||||
directory in the store, but may produce more.
|
||||
|
||||
@item
|
||||
The inputs of the derivations, which may be other derivations or plain
|
||||
files in the store (patches, build scripts, etc.)
|
||||
|
||||
@item
|
||||
The system type targeted by the derivation---e.g., @code{x86_64-linux}.
|
||||
|
||||
@item
|
||||
The file name of a build script in the store, along with the arguments
|
||||
to be passed.
|
||||
|
||||
@item
|
||||
A list of environment variables to be defined.
|
||||
|
||||
@end itemize
|
||||
|
||||
@cindex derivation path
|
||||
Derivations allow clients of the daemon to communicate build actions to
|
||||
the store. They exist in two forms: as an in-memory representation,
|
||||
both on the client- and daemon-side, and as files in the store whose
|
||||
name end in @code{.drv}---these files are referred to as @dfn{derivation
|
||||
paths}. Derivations paths can be passed to the @code{build-derivations}
|
||||
procedure to perform the build actions they prescribe (@pxref{The
|
||||
Store}).
|
||||
|
||||
The @code{(guix derivations)} module provides a representation of
|
||||
derivations as Scheme objects, along with procedures to create and
|
||||
otherwise manipulate derivations. The lowest-level primitive to create
|
||||
a derivation is the @code{derivation} procedure:
|
||||
|
||||
@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{system} @var{builder} @var{args} @var{env-vars} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f]
|
||||
Build a derivation with the given arguments. Return the resulting store
|
||||
path and @code{<derivation>} object.
|
||||
|
||||
When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
|
||||
@dfn{fixed-output derivation} is created---i.e., one whose result is
|
||||
known in advance, such as a file download.
|
||||
@end deffn
|
||||
|
||||
@noindent
|
||||
Here's an example with a shell script as its builder, assuming
|
||||
@var{store} is an open connection to the daemon, and @var{bash} points
|
||||
to a Bash executable in the store:
|
||||
|
||||
@lisp
|
||||
(use-modules (guix utils)
|
||||
(guix store)
|
||||
(guix derivations))
|
||||
|
||||
(call-with-values
|
||||
(lambda ()
|
||||
(let ((builder ; add the Bash script to the store
|
||||
(add-text-to-store store "my-builder.sh"
|
||||
"echo hello world > $out\n" '())))
|
||||
(derivation store "foo" (%current-system)
|
||||
bash `("-e" ,builder)
|
||||
'(("HOME" . "/homeless")) '())))
|
||||
list)
|
||||
@result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>)
|
||||
@end lisp
|
||||
|
||||
As can be guessed, this primitive is cumbersome to use directly. An
|
||||
improved variant is @code{build-expression->derivation}, which allows
|
||||
the caller to directly pass a Guile expression as the build script:
|
||||
|
||||
@deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:guile-for-build #f]
|
||||
Return a derivation that executes Scheme expression @var{exp} as a
|
||||
builder for derivation @var{name}. @var{inputs} must be a list of
|
||||
@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
|
||||
@code{"out"} is assumed. @var{modules} is a list of names of Guile
|
||||
modules from the current search path to be copied in the store,
|
||||
compiled, and made available in the load path during the execution of
|
||||
@var{exp}---e.g., @code{((guix build utils) (guix build
|
||||
gnu-build-system))}.
|
||||
|
||||
@var{exp} is evaluated in an environment where @code{%outputs} is bound
|
||||
to a list of output/path pairs, and where @code{%build-inputs} is bound
|
||||
to a list of string/output-path pairs made from @var{inputs}.
|
||||
Optionally, @var{env-vars} is a list of string pairs specifying the name
|
||||
and value of environment variables visible to the builder. The builder
|
||||
terminates by passing the result of @var{exp} to @code{exit}; thus, when
|
||||
@var{exp} returns @code{#f}, the build is considered to have failed.
|
||||
|
||||
@var{exp} is built using @var{guile-for-build} (a derivation). When
|
||||
@var{guile-for-build} is omitted or is @code{#f}, the value of the
|
||||
@code{%guile-for-build} fluid is used instead.
|
||||
@end deffn
|
||||
|
||||
@noindent
|
||||
Here's an example of a single-output derivation that creates a directory
|
||||
containing one file:
|
||||
|
||||
@lisp
|
||||
(let ((builder '(let ((out (assoc-ref %outputs "out")))
|
||||
(mkdir out) ; create /nix/store/@dots{}-goo
|
||||
(call-with-output-file (string-append out "/test")
|
||||
(lambda (p)
|
||||
(display '(hello guix) p))))))
|
||||
(build-expression->derivation store "goo" (%current-system)
|
||||
builder '()))
|
||||
|
||||
@result{} "/nix/store/@dots{}-goo.drv"
|
||||
@result{} #<<derivation> @dots{}>
|
||||
@end lisp
|
||||
|
||||
@cindex strata of code
|
||||
Remember that the build expression passed to
|
||||
@code{build-expression->derivation} is run by a separate Guile process
|
||||
than the one that calls @code{build-expression->derivation}: it is run
|
||||
by a Guile process launched by the daemon, typically in a chroot. So,
|
||||
while there is a single language for both the @dfn{host} and the build
|
||||
side, there are really two @dfn{strata} of code: the host-side, and the
|
||||
build-side code@footnote{The term @dfn{stratum} in this context was
|
||||
coined by Manuel Serrano et al. in the context of their work on Hop.}.
|
||||
This distinction is important to keep in mind, notably when using
|
||||
higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
|
||||
Packages}). For this reason, Guix modules that are meant to be used in
|
||||
the build stratum are kept in the @code{(guix build @dots{})} name
|
||||
space.
|
||||
|
||||
@c *********************************************************************
|
||||
@node Utilities
|
||||
|
|
|
|||
|
|
@ -610,16 +610,20 @@ they can refer to each other."
|
|||
(env-vars '())
|
||||
(modules '())
|
||||
guile-for-build)
|
||||
"Return a derivation that executes Scheme expression EXP as a builder for
|
||||
derivation NAME. INPUTS must be a list of (NAME DRV-PATH SUB-DRV) tuples;
|
||||
when SUB-DRV is omitted, \"out\" is assumed. EXP is evaluated in an
|
||||
environment where %OUTPUT is bound to the main output path, %OUTPUTS is bound
|
||||
to a list of output/path pairs, and where %BUILD-INPUTS is bound to an alist
|
||||
of string/output-path pairs made from INPUTS. Optionally, ENV-VARS is a list
|
||||
of string pairs specifying the name and value of environment variables
|
||||
visible to the builder. The builder terminates by passing the result of EXP
|
||||
to `exit'; thus, when EXP returns #f, the build is considered to have
|
||||
failed.
|
||||
"Return a derivation that executes Scheme expression EXP as a builder
|
||||
for derivation NAME. INPUTS must be a list of (NAME DRV-PATH SUB-DRV)
|
||||
tuples; when SUB-DRV is omitted, \"out\" is assumed. MODULES is a list
|
||||
of names of Guile modules from the current search path to be copied in
|
||||
the store, compiled, and made available in the load path during the
|
||||
execution of EXP.
|
||||
|
||||
EXP is evaluated in an environment where %OUTPUT is bound to the main
|
||||
output path, %OUTPUTS is bound to a list of output/path pairs, and where
|
||||
%BUILD-INPUTS is bound to an alist of string/output-path pairs made from
|
||||
INPUTS. Optionally, ENV-VARS is a list of string pairs specifying the
|
||||
name and value of environment variables visible to the builder. The
|
||||
builder terminates by passing the result of EXP to `exit'; thus, when
|
||||
EXP returns #f, the build is considered to have failed.
|
||||
|
||||
EXP is built using GUILE-FOR-BUILD (a derivation). When GUILE-FOR-BUILD is
|
||||
omitted or is #f, the value of the `%guile-for-build' fluid is used instead."
|
||||
|
|
|
|||
Loading…
Reference in New Issue