Newer
Older
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,
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
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.
@item
The @code{inputs} field specifies inputs to the build process---i.e.,
build-time or run-time dependencies of the package. Here, we define an
input called @code{"gawk"} whose value is that of the @var{gawk}
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.
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}).
Behind the scenes, a derivation corresponding to the @code{<package>}
object is first computed by the @code{package-derivation} procedure.
That derivation is stored in a @code{.drv} file under @file{/nix/store}.
The build actions it prescribes may then be realized by using the
@code{build-derivations} procedure (@pxref{The Store}).
@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
Return the @code{<derivation>} object of @var{package} for @var{system}
(@pxref{Derivations}).
@var{package} must be a valid @code{<package>} object, and @var{system}
must be a string denoting the target system type---e.g.,
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
must be a connection to the daemon, which operates on the store
(@pxref{The Store}).
@end deffn
@noindent
@cindex cross-compilation
Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:
@deffn {Scheme Procedure} package-cross-derivation @var{store} @
@var{package} @var{target} [@var{system}]
Return the @code{<derivation>} object of @var{package} cross-built from
@var{system} to @var{target}.
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
Configure and Build System}).
@end deffn
@node The Store
@section The Store
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
@cindex store
@cindex store paths
Conceptually, the @dfn{store} is where derivations that have been
successfully built are stored---by default, under @file{/nix/store}.
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
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
@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] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:references-graphs #f]
Build a derivation with the given arguments, and return the resulting
@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.
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.
@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 /nix/store/@dots{}-foo.drv => /nix/store/@dots{}-foo>
@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 '()] [#:references-graphs #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.
See the @code{derivation} procedure for the meaning of @var{references-graphs}.
@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{} #<derivation /nix/store/@dots{}-goo.drv => @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.
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
@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 includes 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 (profile.sh store)
;; Return the name of a shell script in the store that
;; initializes the 'PATH' environment variable.
(let* ((drv (package-derivation store coreutils))
(out (derivation->output-path drv)))
(add-text-to-store store "profile.sh"
(format #f "export PATH=~a/bin" out))))
@end example
Using @code{(guix monads)}, it may be rewritten as a monadic function:
@example
(define (profile.sh)
;; Same, but return a monadic value.
(mlet %store-monad ((bin (package-file coreutils "bin")))
(text-file "profile.sh"
(string-append "export PATH=" bin))))
@end example
There are two things to note in the second version: the @code{store}
parameter is now implicit, and the monadic value returned by
@code{package-file}---a wrapper around @code{package-derivation} and
@code{derivation->output-path}---is @dfn{bound} using @code{mlet}
instead of plain @code{let}.
Calling the monadic @code{profile.sh} has no effect. To get the desired
effect, one must use @code{run-with-store}:
@example
(run-with-store (open-connection) (profile.sh))
@result{} /nix/store/...-profile.sh
@end example
The main syntactic forms to deal with monads in general are described
below.
@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
The interface to the store monad provided by @code{(guix monads)} is as
follows.
@defvr {Scheme Variable} %store-monad
The store 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}
Return as a monadic value the absolute file name in the store of the file
containing @var{text}.
@end deffn
@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
[#:system (%current-system)] [#: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}.
@end deffn
@deffn {Monadic Procedure} derivation-expression @var{name} @var{system} @
@var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] @
[#:hash-algo #f] [#:env-vars '()] [#:modules '()] @
[#:references-graphs #f] [#:guile-for-build #f]
Monadic version of @code{build-expression->derivation}
(@pxref{Derivations}).
@end deffn
@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
Monadic version of @code{package-derivation} (@pxref{Defining
Packages}).
@end deffn
@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 refresh:: Updating package definitions.
@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.
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 --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 --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
configuration triplets,, configure, GNU Configure and Build System}).
@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 --fallback
When substituting a pre-built binary fails, fall back to building
packages locally.
Do not use substitutes for build products. That is, always build things
locally instead of allowing downloads of pre-built binaries.
@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
@var{seconds}, terminate it and report a build failure.
@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.
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
@node Invoking guix download
@section Invoking @command{guix download}
When writing a package definition, developers typically need to download
the package's source tarball, compute its SHA256 hash, and write that
hash in the package definition (@pxref{Defining Packages}). The
@command{guix download} tool helps with this task: it downloads a file
from the given URI, adds it to the store, and prints both its file name
in the store and its SHA256 hash.
The fact that the downloaded file is added to the store saves bandwidth:
when the developer eventually tries to build the newly defined package
with @command{guix build}, the source tarball will not have to be
downloaded again because it is already in the store. It is also a
convenient way to temporarily stash files, which may be deleted
eventually (@pxref{Invoking guix gc}).
The @command{guix download} command supports the same URIs as used in
package definitions. In particular, it supports @code{mirror://} URIs.
@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
Guile bindings for GnuTLS are available in the user's environment; when
they are not available, an error is raised.
The following option is available:
@table @code
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}. For more
information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
@end table
@node Invoking guix hash
@section Invoking @command{guix hash}
The @command{guix hash} command computes the SHA256 hash of a file.
It is primarily a convenience tool for anyone contributing to the
distribution: it computes the cryptographic hash of a file, which can be
used in the definition of a package (@pxref{Defining Packages}).
The general syntax is:
@example
guix hash @var{option} @var{file}
@end example
@command{guix hash} has the following option:
@table @code
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}.
Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
(@code{hex} and @code{hexadecimal} can be used as well).
If the @option{--format} option is not specified, @command{guix hash}
will output the hash in @code{nix-base32}. This representation is used
in the definitions of packages.
@end table
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
@node Invoking guix refresh
@section Invoking @command{guix refresh}
The primary audience of the @command{guix refresh} command is developers
of the GNU software distribution. By default, it reports any packages
provided by the distribution that are outdated compared to the latest
upstream version, like this:
@example
$ guix refresh
gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
@end example
It does so by browsing each package's FTP directory and determining the
highest version number of the source tarballs
therein@footnote{Currently, this only works for GNU packages.}.
When passed @code{--update}, it modifies distribution source files to
update the version numbers and source tarball hashes of those packages'
recipes (@pxref{Defining Packages}). This is achieved by downloading
each package's latest source tarball and its associated OpenPGP
signature, authenticating the downloaded tarball against its signature
using @command{gpg}, and finally computing its hash. When the public
key used to sign the tarball is missing from the user's keyring, an
attempt is made to automatically retrieve it from a public key server;
when it's successful, the key is added to the user's keyring; otherwise,
@command{guix refresh} reports an error.
The following options are supported:
@table @code
@item --update
@itemx -u
Update distribution source files (package recipes) in place.
@ref{Defining Packages}, for more information on package definitions.
@item --select=[@var{subset}]
@itemx -s @var{subset}
Select all the packages in @var{subset}, one of @code{core} or
@code{non-core}.
The @code{core} subset refers to all the packages at the core of the
distribution---i.e., packages that are used to build ``everything
else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
changing one of these packages in the distribution entails a rebuild of
all the others. Thus, such updates are an inconvenience to users in
terms of build time or bandwidth used to achieve the upgrade.
The @code{non-core} subset refers to the remaining packages. It is
typically useful in cases where an update of the core packages would be
inconvenient.
@end table
In addition, @command{guix refresh} can be passed one or more package
names, as in this example:
@example
guix refresh -u emacs idutils
@end example
@noindent
The command above specifically updates the @code{emacs} and
@code{idutils} packages. The @code{--select} option would have no
effect in this case.
The following options can be used to customize GnuPG operation:
@table @code
@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.
@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command. @var{command} is searched
for in @code{$PATH}.
@end table
@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
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.
@menu
* Installing Debugging Files:: Feeding the debugger.
* Package Modules:: Packages from the programmer's viewpoint.
* Packaging Guidelines:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
@end menu
Building this distribution is a cooperative effort, and you are invited
to join! @ref{Contributing}, for information about how you can help.
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
@node Installing Debugging Files
@section Installing Debugging Files
Program binaries, as produced by the GCC compilers for instance, are
typically written in the ELF format, with a section containing
@dfn{debugging information}. Debugging information is what allows the
debugger, GDB, to map binary code to source code; it is required to
debug a compiled program in good conditions.
The problem with debugging information is that is takes up a fair amount
of disk space. For example, debugging information for the GNU C Library
weighs in at more than 60 MiB. Thus, as a user, keeping all the
debugging info of all the installed programs is usually not an option.
Yet, space savings should not come at the cost of an impediment to
debugging---especially in the GNU system, which should make it easier
for users to exert their computing freedom (@pxref{GNU Distribution}).
Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
mechanism that allows users to get the best of both worlds: debugging
information can be stripped from the binaries and stored in separate
files. GDB is then able to load debugging information from those files,
when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
with GDB}).
The GNU distribution takes advantage of this by storing debugging
information in the @code{lib/debug} sub-directory of a separate package
output unimaginatively called @code{debug} (@pxref{Packages with
Multiple Outputs}). Users can choose to install the @code{debug} output
of a package when they need it. For instance, the following command
installs the debugging information for the GNU C Library and for GNU
Guile:
@example
guix package -i glibc:debug -i guile:debug
@end example
GDB must then be told to look for debug files in the user's profile, by
setting the @code{debug-file-directory} variable (consider setting it
from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
GDB}):
@example
(gdb) set debug-file-directory ~/.guix-profile/lib/debug
@end example
From there on, GDB will pick up debugging information from the
@code{.debug} files under @file{~/.guix-profile/lib/debug}.
@c XXX: keep me up-to-date
The @code{debug} output mechanism in Guix is implemented by the
@code{gnu-build-system} (@pxref{Defining Packages}). Currently, it is
opt-in---debugging information is available only for those packages
whose definition explicitly declares a @code{debug} output. This may be
changed to opt-out in the future, if our build farm servers can handle
the load. To check whether a package has a @code{debug} output, use
@command{guix package --list-available} (@pxref{Invoking guix package}).
@node Package Modules
@section Package Modules
From a programming viewpoint, the package definitions of the
distribution are provided by Guile modules in the @code{(gnu packages
...)} name space (@pxref{Modules, Guile modules,, guile, GNU Guile
Reference Manual}). 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. For more information on bootstrapping,
@ref{Bootstrapping}.
@node Packaging Guidelines
@section Packaging Guidelines
The GNU distribution is nascent and may well lack some of your favorite
packages. This section describes how you can help make the distribution
grow. @xref{Contributing}, for additional information on how you can
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
help.
Free software packages are usually distributed in the form of
@dfn{source code tarballs}---typically @file{tar.gz} files that contain
all the source files. Adding a package to the distribution means
essentially two things: adding a @dfn{recipe} that describes how to
build the package, including a list of other packages required to build
it, and adding @dfn{package meta-data} along with that recipe, such as a
description and licensing information.
In Guix all this information is embodied in @dfn{package definitions}.
Package definitions provide a high-level view of the package. They are
written using the syntax of the Scheme programming language; in fact,
for each package we define a variable bound to the package definition,
and export that variable from a module (@pxref{Package Modules}).
However, in-depth Scheme knowledge is @emph{not} a prerequisite for
creating packages. For more information on package definitions,
@ref{Defining Packages}.
Once a package definition is in place, stored in a file in the Guix
source tree, it can be tested using the @command{guix build} command
(@pxref{Invoking guix build}). For example, assuming the new package is
called @code{gnew}, you may run this command from the Guix build tree:
@example
./pre-inst-env guix build gnew --keep-failed
@end example
Using @code{--keep-failed} makes it easier to debug build failures since
it provides access to the failed build tree.
Once your package builds correctly, please send us a patch
(@pxref{Contributing}). Well, if you need help, we will be happy to
help you too. Once the patch is committed in the Guix repository, the
new package automatically gets built on the supported platforms by
@url{http://hydra.gnu.org/gnu/master, our continuous integration
system}.
@cindex substituter
Users can obtain the new package definition simply by running
@command{guix pull} (@pxref{Invoking guix pull}). When
@code{hydra.gnu.org} is done building the package, installing the
package automatically downloads binaries from there (except when using
@code{--no-substitutes}). The only place where human intervention is
needed is to review and apply the patch.
* Software Freedom:: What may go into the distribution.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
* Python Modules:: Taming the snake.
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
@end menu
@node Software Freedom
@subsection Software Freedom
@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
The GNU operating system has been developed so that users can have
freedom in their computing. GNU is @dfn{free software}, meaning that
users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
essential freedoms}: to run the program, to study and change the program
in source code form, to redistribute exact copies, and to distribute
modified versions. Packages found in the GNU distribution provide only
software that conveys these four freedoms.
In addition, the GNU distribution follow the
@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
software distribution guidelines}. Among other things, these guidelines
reject non-free firmware, recommendations of non-free software, and
discuss ways to deal with trademarks and patents.
Some packages contain a small and optional subset that violates the
above guidelines, for instance because this subset is itself non-free
code. When that happens, the offending items are removed with
appropriate patches or code snippets in the package definition's
@code{origin} form (@pxref{Defining Packages}). That way, @code{guix
build --source} returns the ``freed'' source rather than the unmodified
upstream source.
@node Package Naming
@subsection Package Naming
A package has actually two names associated with it:
First, there is the name of the @emph{Scheme variable}, the one following
@code{define-public}. By this name, the package can be made known in the
Scheme code, for instance as input to another package. Second, there is
the string in the @code{name} field of a package definition. This name
is used by package management commands such as
@command{guix package} and @command{guix build}.
Both are usually the same and correspond to the lowercase conversion of the
project name chosen upstream. For instance, the GNUnet project is packaged
as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
unless these are already part of the official project name. But see
@ref{Python Modules} for special rules concerning modules for
the Python language.
@node Version Numbers
@subsection Version Numbers
We usually package only the latest version of a given free software
project. But sometimes, for instance for incompatible library versions,
two (or more) versions of the same package are needed. These require
different Scheme variable names. We use the name as defined
in @ref{Package Naming}
for the most recent version; previous versions use the same name, suffixed
by @code{-} and the smallest prefix of the version number that may
distinguish the two versions.
The name inside the package definition is the same for all versions of a
package and does not contain any version number.
For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
@example
(define-public gtk+
(package
(name "gtk+")
(version "3.9.12")
...))
(define-public gtk+-2
(package
(name "gtk+")
(version "2.24.20")
...))
@end example
If we also wanted GTK+ 3.8.2, this would be packaged as
@example
(define-public gtk+-3.8
(package
(name "gtk+")
(version "3.8.2")
...))
@end example
@node Python Modules
@subsection Python Modules
We currently package Python 2 and Python 3, under the Scheme variable names
@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
To avoid confusion and naming clashes with other programming languages, it
seems desirable that the name of a package for a Python module contains
the word @code{python}.
Some modules are compatible with only one version of Python, others with both.
If the package Foo compiles only with Python 3, we name it
@code{python-foo}; if it compiles only with Python 2, we name it
@code{python2-foo}. If it is compatible with both versions, we create two
packages with the corresponding names.
If a project already contains the word @code{python}, we drop this;
for instance, the module python-dateutil is packaged under the names
@code{python-dateutil} and @code{python2-dateutil}.
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
@node Bootstrapping
@section Bootstrapping
@c Adapted from the ELS 2013 paper.
@cindex bootstrapping
Bootstrapping in our context refers to how the distribution gets built
``from nothing''. Remember that the build environment of a derivation
contains nothing but its declared inputs (@pxref{Introduction}). So
there's an obvious chicken-and-egg problem: how does the first package
get built? How does the first compiler get compiled? Note that this is
a question of interest only to the curious hacker, not to the regular
user, so you can shamelessly skip this section if you consider yourself
a ``regular user''.
@cindex bootstrap binaries
The GNU system is primarily made of C code, with libc at its core. The
GNU build system itself assumes the availability of a Bourne shell and
command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
`grep'. Furthermore, build programs---programs that run