Newer
Older
@table @code
@item glib-or-gtk-wrap
The phase @code{glib-or-gtk-wrap} ensures that programs found under
@file{bin/} are able to find GLib's ``schemas'' and
@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
modules}. This is achieved by wrapping the programs in launch scripts
that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
environment variables.
Ludovic Courtès
committed
It is possible to exclude specific package outputs from that wrapping
process by listing their names in the
@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
when an output is known not to contain any GLib or GTK+ binaries, and
where wrapping would gratuitously add a dependency of that output on
GLib and GTK+.
@item glib-or-gtk-compile-schemas
The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
GSettings schemas} are compiled. Compilation is performed by the
@command{glib-compile-schemas} program. It is provided by the package
@code{glib:bin} which is automatically imported by the build system.
The @code{glib} package providing @command{glib-compile-schemas} can be
specified with the @code{#:glib} parameter.
@end table
Both phases are executed after the @code{install} phase.
@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 either
consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
followed by @code{Build} and @code{Build install}; or in running
@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
@code{make} and @code{make install}; depending on which of
@code{Build.PL} or @code{Makefile.PL} is present in the package
distribution. Preference is given to the former if both @code{Build.PL}
and @code{Makefile.PL} exist in the package distribution. This
preference can be reversed by specifying @code{#t} for the
@code{#:make-maker?} parameter.
The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
passes flags specified by the @code{#:make-maker-flags} or
@code{#:module-build-flags} parameter, respectively.
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
@defvr {Scheme Variable} ruby-build-system
This variable is exported by @code{(guix build-system ruby)}. It
implements the RubyGems build procedure used by Ruby packages, which
involves running @code{gem build} followed by @code{gem install}.
Which Ruby package is used can be specified with the @code{#:ruby}
parameter.
@end defvr
@defvr {Scheme Variable} waf-build-system
This variable is exported by @code{(guix build-system waf)}. It
implements a build procedure around the @code{waf} script. The common
phases---@code{configure}, @code{build}, and @code{install}---are
implemented by passing their names as arguments to the @code{waf}
script.
The @code{waf} script is executed by the Python interpreter. Which
Python package is used to run the script can be specified with the
@code{#:python} parameter.
@end defvr
@defvr {Scheme Variable} haskell-build-system
This variable is exported by @code{(guix build-system haskell)}. It
implements the Cabal build procedure used by Haskell packages, which
involves running @code{runhaskell Setup.hs configure
--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
Instead of installing the package by running @code{runhaskell Setup.hs
install}, to avoid trying to register libraries in the read-only
compiler store directory, the build system uses @code{runhaskell
Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
addition, the build system generates the package documentation by
running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
is passed. Optional Haddock parameters can be passed with the help of
the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
not found, the build system looks for @code{Setup.lhs} instead.
Which Haskell compiler is used can be specified with the @code{#:haskell}
parameter which defaults to @code{ghc}.
@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
@cindex store
@cindex store paths
Conceptually, the @dfn{store} is where derivations that have been
successfully built are stored---by default, under @file{/gnu/store}.
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
Sub-directories in the store are referred to as @dfn{store paths}. The
store has an associated database that contains information such has the
store paths referred to by each store path, and the list of @emph{valid}
store paths---paths that result from a successful build.
The store is always accessed by the daemon on behalf of its clients
(@pxref{Invoking guix-daemon}). To manipulate the store, clients
connect to the daemon over a Unix-domain socket, send it requests, and
read the result---these are remote procedure calls, or RPCs.
The @code{(guix store)} module provides procedures to connect to the
daemon, and to perform RPCs. These are described below.
@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
Connect to the daemon over the Unix-domain socket at @var{file}. When
@var{reserve-space?} is true, instruct it to reserve a little bit of
extra space on the file system so that the garbage collector can still
operate, should the disk become full. Return a server object.
@var{file} defaults to @var{%default-socket-path}, which is the normal
location given the options that were passed to @command{configure}.
@end deffn
@deffn {Scheme Procedure} close-connection @var{server}
Close the connection to @var{server}.
@end deffn
@defvr {Scheme Variable} current-build-output-port
This variable is bound to a SRFI-39 parameter, which refers to the port
where build and error logs sent by the daemon should be written.
@end defvr
Procedures that make RPCs all take a server object as their first
argument.
@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
Return @code{#t} when @var{path} is a valid store path.
@end deffn
@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
Add @var{text} under file @var{name} in the store, and return its store
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 @code{<derivation>} objects or
derivation paths), and return when the worker is done building them.
Return @code{#t} on success.
Note that the @code{(guix monads)} module provides a monad as well as
monadic versions of the above procedures, with the goal of making it
more convenient to work with code that accesses the store (@pxref{The
Store Monad}).
@c FIXME
@i{This section is currently incomplete.}
@node Derivations
@section Derivations
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
@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{builder} @
@var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
[#:system (%current-system)] [#:references-graphs #f] @
[#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f]
Build a derivation with the given arguments, and return the resulting
@code{<derivation>} object.
When @var{hash} and @var{hash-algo} are given, a
@dfn{fixed-output derivation} is created---i.e., one whose result is
known in advance, such as a file download. If, in addition,
@var{recursive?} is true, then that fixed output may be an executable
file or a directory and @var{hash} must be the hash of an archive
containing this output.
When @var{references-graphs} is true, it must be a list of file
name/store path pairs. In that case, the reference graph of each store
path is exported in the build environment in the corresponding file, in
a simple text format.
When @var{allowed-references} is true, it must be a list of store items
or outputs that the derivation's output may refer to.
When @var{leaked-env-vars} is true, it must be a list of strings
denoting environment variables that are allowed to ``leak'' from the
daemon's environment to the build environment. This is only applicable
to fixed-output derivations---i.e., when @var{hash} is true. The main
use is to allow variables such as @code{http_proxy} to be passed to
derivations that download files.
When @var{local-build?} is true, declare that the derivation is not a
good candidate for offloading and should rather be built locally
(@pxref{Daemon Offload Setup}). This is the case for small derivations
where the costs of data transfers would outweigh the benefits.
@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))
(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"
bash `("-e" ,builder)
#:env-vars '(("HOME" . "/homeless"))))
@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
As can be guessed, this primitive is cumbersome to use directly. A
better approach is to write build scripts in Scheme, of course! The
best course of action for that is to write the build code as a
``G-expression'', and to pass it to @code{gexp->derivation}. For more
information, @pxref{G-Expressions}.
Once upon a time, @code{gexp->derivation} did not exist and constructing
derivations with build code written in Scheme was achieved with
@code{build-expression->derivation}, documented below. This procedure
is now deprecated in favor of the much nicer @code{gexp->derivation}.
Ludovic Courtès
committed
@deffn {Scheme Procedure} build-expression->derivation @var{store} @
@var{name} @var{exp} @
[#:system (%current-system)] [#:inputs '()] @
[#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
Ludovic Courtès
committed
[#:references-graphs #f] [#:allowed-references #f] @
[#:local-build? #f] [#: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.
Ludovic Courtès
committed
See the @code{derivation} procedure for the meaning of
@var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
@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 /gnu/store/@dots{}-goo
(call-with-output-file (string-append out "/test")
(lambda (p)
(display '(hello guix) p))))))
Ludovic Courtès
committed
(build-expression->derivation store "goo" builder))
@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
@node The Store Monad
@section The Store Monad
@cindex monad
The procedures that operate on the store described in the previous
sections all take an open connection to the build daemon as their first
argument. Although the underlying model is functional, they either have
side effects or depend on the current state of the store.
The former is inconvenient: the connection to the build daemon has to be
carried around in all those functions, making it impossible to compose
functions that do not take that parameter with functions that do. The
latter can be problematic: since store operations have side effects
and/or depend on external state, they have to be properly sequenced.
@cindex monadic values
@cindex monadic functions
This is where the @code{(guix monads)} module comes in. This module
provides a framework for working with @dfn{monads}, and a particularly
useful monad for our uses, the @dfn{store monad}. Monads are a
construct that allows two things: associating ``context'' with values
(in our case, the context is the store), and building sequences of
computations (here computations include accesses to the store.) Values
in a monad---values that carry this additional context---are called
@dfn{monadic values}; procedures that return such values are called
@dfn{monadic procedures}.
Consider this ``normal'' procedure:
@example
(define (sh-symlink store)
;; Return a derivation that symlinks the 'bash' executable.
(let* ((drv (package-derivation store bash))
(out (derivation->output-path drv))
(sh (string-append out "/bin/bash")))
(build-expression->derivation store "sh"
`(symlink ,sh %output))))
Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
as a monadic function:
(mlet %store-monad ((drv (package->derivation bash)))
(gexp->derivation "sh"
#~(symlink (string-append #$drv "/bin/bash")
#$output))))
There several things to note in the second version: the @code{store}
parameter is now implicit and is ``threaded'' in the calls to the
@code{package->derivation} and @code{gexp->derivation} monadic
procedures, and the monadic value returned by @code{package->derivation}
is @dfn{bound} using @code{mlet} instead of plain @code{let}.
As it turns out, the call to @code{package->derivation} can even be
omitted since it will take place implicitly, as we will see later
(@pxref{G-Expressions}):
@example
(define (sh-symlink)
(gexp->derivation "sh"
#~(symlink (string-append #$bash "/bin/bash")
#$output)))
@end example
Calling the monadic @code{sh-symlink} has no effect. To get the desired
effect, one must use @code{run-with-store}:
@example
(run-with-store (open-connection) (sh-symlink))
@result{} /gnu/store/...-sh-symlink
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
Note that the @code{(guix monad-repl)} module extends Guile's REPL with
new ``meta-commands'' to make it easier to deal with monadic procedures:
@code{run-in-store}, and @code{enter-store-monad}. The former, is used
to ``run'' a single monadic value through the store:
@example
scheme@@(guile-user)> ,run-in-store (package->derivation hello)
$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
@end example
The latter enters a recursive REPL, where all the return values are
automatically run through the store:
@example
scheme@@(guile-user)> ,enter-store-monad
store-monad@@(guile-user) [1]> (package->derivation hello)
$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
$3 = "/gnu/store/@dots{}-foo"
store-monad@@(guile-user) [1]> ,q
scheme@@(guile-user)>
@end example
@noindent
Note that non-monadic values cannot be returned in the
@code{store-monad} REPL.
The main syntactic forms to deal with monads in general are provided by
the @code{(guix monads)} module and are described below.
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
in @var{monad}.
@end deffn
@deffn {Scheme Syntax} return @var{val}
Return a monadic value that encapsulates @var{val}.
@end deffn
@deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
procedure @var{mproc}@footnote{This operation is commonly referred to as
``bind'', but that name denotes an unrelated procedure in Guile. Thus
we use this somewhat cryptic symbol inherited from the Haskell
language.}.
@end deffn
@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
@var{body} ...
@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
@var{body} ...
Bind the variables @var{var} to the monadic values @var{mval} in
@var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
``normal'' value @var{val}, as per @code{let}.
@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
@end deffn
@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
Bind @var{mexp} and the following monadic expressions in sequence,
returning the result of the last expression.
This is akin to @code{mlet}, except that the return values of the
monadic expressions are ignored. In that sense, it is analogous to
@code{begin}, but applied to monadic expressions.
@end deffn
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
@cindex state monad
The @code{(guix monads)} module provides the @dfn{state monad}, which
allows an additional value---the state---to be @emph{threaded} through
monadic procedure calls.
@defvr {Scheme Variable} %state-monad
The state monad. Procedures in the state monad can access and change
the state that is threaded.
Consider the example below. The @code{square} procedure returns a value
in the state monad. It returns the square of its argument, but also
increments the current state value:
@example
(define (square x)
(mlet %state-monad ((count (current-state)))
(mbegin %state-monad
(set-current-state (+ 1 count))
(return (* x x)))))
(run-with-state (sequence %state-monad (map square (iota 3))) 0)
@result{} (0 1 4)
@result{} 3
@end example
When ``run'' through @var{%state-monad}, we obtain that additional state
value, which is the number of @code{square} calls.
@end defvr
@deffn {Monadic Procedure} current-state
Return the current state as a monadic value.
@end deffn
@deffn {Monadic Procedure} set-current-state @var{value}
Set the current state to @var{value} and return the previous state as a
monadic value.
@end deffn
@deffn {Monadic Procedure} state-push @var{value}
Push @var{value} to the current state, which is assumed to be a list,
and return the previous state as a monadic value.
@end deffn
@deffn {Monadic Procedure} state-pop
Pop a value from the current state and return it as a monadic value.
The state is assumed to be a list.
@end deffn
@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
Run monadic value @var{mval} starting with @var{state} as the initial
state. Return two values: the resulting value, and the resulting state.
@end deffn
The main interface to the store monad, provided by the @code{(guix
store)} module, is as follows.
The store monad---an alias for @var{%state-monad}.
Values in the store monad encapsulate accesses to the store. When its
effect is needed, a value of the store monad must be ``evaluated'' by
passing it to the @code{run-with-store} procedure (see below.)
@end defvr
@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
Run @var{mval}, a monadic value in the store monad, in @var{store}, an
open store connection.
@end deffn
@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
Return as a monadic value the absolute file name in the store of the file
containing @var{text}, a string. @var{references} is a list of store items that the
resulting text file refers to; it defaults to the empty list.
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
[#:recursive? #t]
Return the name of @var{file} once interned in the store. Use
@var{name} as its store name, or the basename of @var{file} if
@var{name} is omitted.
When @var{recursive?} is true, the contents of @var{file} are added
recursively; if @var{file} designates a flat file and @var{recursive?}
is true, its contents are added, and its permission bits are kept.
The example below adds a file to the store, under two different names:
@example
(run-with-store (open-connection)
(mlet %store-monad ((a (interned-file "README"))
(b (interned-file "README" "LEGU-MIN")))
(return (list a b))))
@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
@end example
@end deffn
The @code{(guix packages)} module exports the following package-related
monadic procedures:
@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
[#:system (%current-system)] [#:target #f] @
[#:output "out"] Return as a monadic
value in the absolute file name of @var{file} within the @var{output}
directory of @var{package}. When @var{file} is omitted, return the name
of the @var{output} directory of @var{package}. When @var{target} is
true, use it as a cross-compilation target triplet.
@end deffn
@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
@deffnx {Monadic Procedure} package->cross-derivation @var{package} @
@var{target} [@var{system}]
Monadic version of @code{package-derivation} and
@code{package-cross-derivation} (@pxref{Defining Packages}).
@node G-Expressions
@section G-Expressions
@cindex G-expression
@cindex build code quoting
So we have ``derivations'', which represent a sequence of build actions
to be performed to produce an item in the store (@pxref{Derivations}).
Those build actions are performed when asking the daemon to actually
build the derivations; they are run by the daemon in a container
(@pxref{Invoking guix-daemon}).
@cindex strata of code
It should come as no surprise that we like to write those build actions
in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
code@footnote{The term @dfn{stratum} in this context was coined by
Manuel Serrano et al.@: in the context of their work on Hop. Oleg
Kiselyov, who has written insightful
@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
on this topic}, refers to this kind of code generation as
@dfn{staging}.}: the ``host code''---code that defines packages, talks
to the daemon, etc.---and the ``build code''---code that actually
performs build actions, such as making directories, invoking
@command{make}, etc.
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
To describe a derivation and its build actions, one typically needs to
embed build code inside host code. It boils down to manipulating build
code as data, and Scheme's homoiconicity---code has a direct
representation as data---comes in handy for that. But we need more than
Scheme's normal @code{quasiquote} mechanism to construct build
expressions.
The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
S-expressions adapted to build expressions. G-expressions, or
@dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
@code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
@code{#$}, and @code{#$@@}), which are comparable respectively to
@code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
(@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
Reference Manual}). However, there are major differences:
@itemize
@item
Gexps are meant to be written to a file and run or manipulated by other
processes.
@item
When a high-level object such as a package or derivation is unquoted
inside a gexp, the result is as if its output file name had been
introduced.
@item
Gexps carry information about the packages or derivations they refer to,
and these dependencies are automatically added as inputs to the build
processes that use them.
@end itemize
Actually this mechanism is not limited to package and derivation
objects; @dfn{compilers} able to ``lower'' other high-level objects to
derivations can be defined, such that these objects can also be inserted
into gexps. Another useful type of high-level object that can be
inserted in a gexp is @dfn{local files}, which allows files from the
local file system to be added to the store and referred to by
derivations and such (see @code{local-file} below.)
To illustrate the idea, here is an example of a gexp:
@example
(define build-exp
#~(begin
(mkdir #$output)
(chdir #$output)
(symlink (string-append #$coreutils "/bin/ls")
"list-files")))
@end example
This gexp can be passed to @code{gexp->derivation}; we obtain a
derivation that builds a directory containing exactly one symlink to
@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
@example
(gexp->derivation "the-thing" build-exp)
@end example
As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
substituted to the reference to the @var{coreutils} package in the
actual build code, and @var{coreutils} is automatically made an input to
the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
output)}) is replaced by a string containing the derivation's output
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
directory name.
@cindex cross compilation
In a cross-compilation context, it is useful to distinguish between
references to the @emph{native} build of a package---that can run on the
host---versus references to cross builds of a package. To that end, the
@code{#+} plays the same role as @code{#$}, but is a reference to a
native package build:
@example
(gexp->derivation "vi"
#~(begin
(mkdir #$output)
(system* (string-append #+coreutils "/bin/ln")
"-s"
(string-append #$emacs "/bin/emacs")
(string-append #$output "/bin/vi")))
#:target "mips64el-linux")
@end example
@noindent
In the example above, the native build of @var{coreutils} is used, so
that @command{ln} can actually run on the host; but then the
cross-compiled build of @var{emacs} is referenced.
The syntactic form to construct gexps is summarized below.
@deffn {Scheme Syntax} #~@var{exp}
@deffnx {Scheme Syntax} (gexp @var{exp})
Return a G-expression containing @var{exp}. @var{exp} may contain one
or more of the following forms:
@table @code
@item #$@var{obj}
@itemx (ungexp @var{obj})
Introduce a reference to @var{obj}. @var{obj} may have one of the
supported types, for example a package or a
derivation, in which case the @code{ungexp} form is replaced by its
output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
If @var{obj} is a list, it is traversed and references to supported
objects are substituted similarly.
If @var{obj} is another gexp, its contents are inserted and its
dependencies are added to those of the containing gexp.
If @var{obj} is another kind of object, it is inserted as is.
@item #$@var{obj}:@var{output}
@itemx (ungexp @var{obj} @var{output})
This is like the form above, but referring explicitly to the
@var{output} of @var{obj}---this is useful when @var{obj} produces
multiple outputs (@pxref{Packages with Multiple Outputs}).
@item #+@var{obj}
@itemx #+@var{obj}:output
@itemx (ungexp-native @var{obj})
@itemx (ungexp-native @var{obj} @var{output})
Same as @code{ungexp}, but produces a reference to the @emph{native}
build of @var{obj} when used in a cross compilation context.
@item #$output[:@var{output}]
@itemx (ungexp output [@var{output}])
Insert a reference to derivation output @var{output}, or to the main
output when @var{output} is omitted.
This only makes sense for gexps passed to @code{gexp->derivation}.
@item #$@@@var{lst}
@itemx (ungexp-splicing @var{lst})
Like the above, but splices the contents of @var{lst} inside the
containing list.
@item #+@@@var{lst}
@itemx (ungexp-native-splicing @var{lst})
Like the above, but refers to native builds of the objects listed in
@var{lst}.
@end table
G-expressions created by @code{gexp} or @code{#~} are run-time objects
of the @code{gexp?} type (see below.)
@end deffn
@deffn {Scheme Procedure} gexp? @var{obj}
Return @code{#t} if @var{obj} is a G-expression.
@end deffn
G-expressions are meant to be written to disk, either as code building
some derivation, or as plain files in the store. The monadic procedures
below allow you to do that (@pxref{The Store Monad}, for more
information about monads.)
@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
[#:system (%current-system)] [#:target #f] [#:graft? #t] @
[#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
[#:module-path @var{%load-path}] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:leaked-env-vars #f] @
[#:local-build? #f] [#:guile-for-build #f]
Return a derivation @var{name} that runs @var{exp} (a gexp) with
@var{guile-for-build} (a derivation) on @var{system}. When @var{target}
is true, it is used as the cross-compilation target triplet for packages
referred to by @var{exp}.
Make @var{modules} available in the evaluation context of @var{exp};
@var{modules} is a list of names of Guile modules searched in
@var{module-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{graft?} determines whether packages referred to by @var{exp} should be grafted when
applicable.
When @var{references-graphs} is true, it must be a list of tuples of one of the
following forms:
@example
(@var{file-name} @var{package})
(@var{file-name} @var{package} @var{output})
(@var{file-name} @var{derivation})
(@var{file-name} @var{derivation} @var{output})
(@var{file-name} @var{store-item})
@end example
The right-hand-side of each element of @var{references-graphs} is automatically made
an input of the build process of @var{exp}. In the build environment, each
@var{file-name} contains the reference graph of the corresponding item, in a simple
text format.
@var{allowed-references} must be either @code{#f} or a list of output names and packages.
In the latter case, the list denotes store items that the result is allowed to
refer to. Any reference to another store item will lead to a build error.
The other arguments are as for @code{derivation} (@pxref{Derivations}).
@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
[#:recursive? #t]
Return an object representing local file @var{file} to add to the store; this
object can be used in a gexp. @var{file} will be added to the store under @var{name}--by
default the base name of @var{file}.
When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
designates a flat file and @var{recursive?} is true, its contents are added, and its
permission bits are kept.
This is the declarative counterpart of the @code{interned-file} monadic
procedure (@pxref{The Store Monad, @code{interned-file}}).
@end deffn
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
Return an executable script @var{name} that runs @var{exp} using
@var{guile} with @var{modules} in its search path.
The example below builds a script that simply invokes the @command{ls}
command:
@example
(use-modules (guix gexp) (gnu packages base))
(gexp->script "list-files"
#~(execl (string-append #$coreutils "/bin/ls")
"ls"))
@end example
When ``running'' it through the store (@pxref{The Store Monad,
@code{run-with-store}}), we obtain a derivation that produces an
executable file @file{/gnu/store/@dots{}-list-files} along these lines:
@example
#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
!#
(execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
"ls")
@end example
@end deffn
@deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
Return a derivation that builds a file @var{name} containing @var{exp}.
The resulting file holds references to all the dependencies of @var{exp}
or a subset thereof.
@end deffn
@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
Return as a monadic value a derivation that builds a text file
containing all of @var{text}. @var{text} may list, in addition to
strings, objects of any type that can be used in a gexp: packages,
derivations, local file objects, etc. The resulting store file holds
references to all these.
This variant should be preferred over @code{text-file} anytime the file
to create will reference items from the store. This is typically the
case when building a configuration file that embeds store file names,
like this:
@example
(define (profile.sh)
;; Return the name of a shell script in the store that
;; initializes the 'PATH' environment variable.
(text-file* "profile.sh"
"export PATH=" coreutils "/bin:"
grep "/bin:" sed "/bin\n"))
@end example
In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
preventing them from being garbage-collected during its lifetime.
@end deffn
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
@code{(guix build @dots{})} name space.
@c *********************************************************************
@node Utilities
@chapter Utilities
This section describes tools primarily targeted at developers and users
who write new package definitions. They complement the Scheme
programming interface of Guix in a convenient way.
* Invoking guix build:: Building packages from the command line.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
@node Invoking guix build
@section Invoking @command{guix build}
The @command{guix build} command builds packages or derivations and
their dependencies, and prints the resulting store paths. Note that it
does not modify the user's profile---this is the job of the
@command{guix package} command (@pxref{Invoking guix package}). Thus,
it is mainly useful for distribution developers.
The general syntax is:
guix build @var{options} @var{package-or-derivation}@dots{}
@end example
@var{package-or-derivation} may be either the name of a package found in
the software distribution such as @code{coreutils} or
@code{coreutils-8.20}, or a derivation such as
@file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
package with the corresponding name (and optionally version) is searched
for among the GNU distribution modules (@pxref{Package Modules}).
Alternatively, the @code{--expression} option may be used to specify a
Scheme expression that evaluates to a package; this is useful when
disambiguation among several same-named packages or package variants is
needed.
The @var{options} may be zero or more of the following:
@table @code
@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package or derivation @var{expr} evaluates to.
For example, @var{expr} may be @code{(@@ (gnu packages guile)
guile-1.8)}, which unambiguously designates this specific variant of
version 1.8 of Guile.
Alternately, @var{expr} may be a G-expression, in which case it is used
as a build program passed to @code{gexp->derivation}
(@pxref{G-Expressions}).
Lastly, @var{expr} may refer to a zero-argument monadic procedure
(@pxref{The Store Monad}). The procedure must return a derivation as a
monadic value, which is then passed through @code{run-with-store}.
@item --source
@itemx -S
Build the packages' source derivations, rather than the packages
themselves.
For instance, @code{guix build -S gcc} returns something like
@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
The returned source tarball is the result of applying any patches and
code snippets specified in the package's @code{origin} (@pxref{Defining
Packages}).
@item --sources
Fetch and return the source of @var{package-or-derivation} and all their
dependencies, recursively. This is a handy way to obtain a local copy
of all the source code needed to build @var{packages}, allowing you to
eventually build them even without network access. It is an extension
of the @code{--source} option and can accept one of the following
optional argument values:
@table @code
@item package
This value causes the @code{--sources} option to behave in the same way