Newer
Older
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
@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
@chapter Utilities
@menu
* Invoking guix build:: Building packages from the command line.
@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{/nix/store/@dots{}-coreutils-8.19.drv}. 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 @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.
@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{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
the host's system type.
An example use of this is on Linux-based systems, which can emulate
different personalities. For instance, passing
@code{--system=i686-linux} on an @code{x86_64-linux} system allows users
to build packages in a complete 32-bit environment.
@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given
packages.
@item --keep-failed
@itemx -K
Keep the build tree of failed builds. Thus, if a build fail, its build
tree is kept under @file{/tmp}, in a directory whose name is shown at
the end of the build log. This is useful when debugging build issues.
@item --dry-run
@itemx -n
Do not build the derivations.
@item --no-substitutes
Build instead of resorting to pre-built substitutes.
@item --cores=@var{n}
@itemx -c @var{n}
Allow the use of up to @var{n} CPU cores for the build. The special
value @code{0} means to use as many CPU cores as available.
@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
collector root.
@item --verbosity=@var{level}
Use the given verbosity level. @var{level} must be an integer between 0
and 5; higher means more verbose output. Setting a level of 4 or more
may be helpful when debugging setup issues with the build daemon.
Behind the scenes, @command{guix build} is essentially an interface to
the @code{package-derivation} procedure of the @code{(guix packages)}
module, and to the @code{build-derivations} procedure of the @code{(guix
store)} module.
@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution
Guix comes with a distribution of free software@footnote{The term
``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.} that form the basis of the GNU system. This
includes core GNU packages such as GNU libc, GCC, and Binutils, as well
as many GNU and non-GNU applications. The complete list of available
packages can be seen by running @command{guix package} (@pxref{Invoking
guix package}):
guix package --list-available
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
@end example
The package definitions of the distribution may are provided by Guile
modules in the @code{(gnu packages ...)} name space---for instance, the
@code{(gnu packages emacs)} module exports a variable named
@code{emacs}, which is bound to a @code{<package>} object
(@pxref{Defining Packages}). The @code{(gnu packages)} module provides
facilities for searching for packages.
The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
each package is built based solely on other packages in the
distribution. The root of this dependency graph is a small set of
@dfn{bootstrap binaries}, provided by the @code{(gnu packages
bootstrap)} module. These are statically-linked binaries of the core
tools without which building anything at all would be impossible.
Our goal is to build a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.
Building this distribution is a cooperative effort, and you are invited
to join! Please get in touch with us on @email{bug-guix@@gnu.org}. We
welcome ideas, bug reports, patches, and anything that may be helpful to
the project.
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
@c *********************************************************************
@node Acknowledgments
@chapter Acknowledgments
Guix is based on the Nix package manager, which was designed and
implemented by Eelco Dolstra. Nix pioneered functional package
management, and promoted unprecedented features, such as transactional
package upgrades and rollbacks, per-user profiles, and referentially
transparent build processes. Without this work, Guix would not exist.
The Nix-based software distributions, Nixpkgs and NixOS, have also been
an inspiration for Guix.
@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl-1.3.texi
@c *********************************************************************
@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Function Index
@unnumbered Function Index
@printindex fn
@bye
@c Local Variables:
@c ispell-local-dictionary: "american";
@c End: