guix.texi

``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}, a string.
@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, packages, derivations, and store file names; 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

@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

@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}).
@end deffn


@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.

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 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

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
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 be 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 any package or derivation
references 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{package-or-derivation}:@var{output}
@itemx (ungexp @var{package-or-derivation} @var{output})
This is like the form above, but referring explicitly to the
@var{output} of @var{package-or-derivation}---this is useful when
@var{package-or-derivation} 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] [#:inputs '()] @
       [#:hash #f] [#:hash-algo #f] @
       [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
       [#:references-graphs #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 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))}.

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.

The other arguments are as for @code{derivation} (@pxref{Derivations}).
@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

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.

@menu
* 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.
* Invoking guix lint::          Finding errors in package definitions.
@end menu

@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:

@example
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 --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 --with-source=@var{source}
Use @var{source} as the source of the corresponding package.
@var{source} must be a file name or a URL, as for @command{guix
download} (@pxref{Invoking guix download}).

The ``corresponding package'' is taken to be one specified on the
command line whose name matches the base of @var{source}---e.g., if
@var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
package is @code{guile}.  Likewise, the version string is inferred from
@var{source}; in the previous example, it's @code{2.0.10}.

This option allows users to try out versions of packages other than the
one provided by the distribution.  The example below downloads
@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
the @code{ed} package:

@example
guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
@end example

As a developer, @code{--with-source} makes it easy to test release
candidates:

@example
guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
@end example


@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given
packages.

@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 --log-file
Return the build log file names for the given
@var{package-or-derivation}s, or raise an error if build logs are
missing.

This works regardless of how packages or derivations are specified.  For
instance, the following invocations are equivalent:

@example
guix build --log-file `guix build -d guile`
guix build --log-file `guix build guile`
guix build --log-file guile
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example


@end table

@cindex common build options
In addition, a number of options that control the build process are
common to @command{guix build} and other commands that can spawn builds,
such as @command{guix package} or @command{guix archive}.  These are the
following:

@table @code

@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).

This allows users to define their own packages and make them visible to
the command-line tools.

@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.

@item --no-substitutes
Do not use substitutes for build products.  That is, always build things
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).

@item --no-build-hook
Do not attempt to offload builds @i{via} the daemon's ``build hook''
(@pxref{Daemon Offload Setup}).  That is, always build things locally
instead of offloading builds to remote machines.

@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 --timeout=@var{seconds}
Likewise, when the build or substitution process lasts for more than
@var{seconds}, terminate it and report a build failure.

By default there is no timeout.  This behavior can be restored with
@code{--timeout=0}.

@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.

@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.

@end table

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.

@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.

@item --recursive
@itemx -r
Compute the hash on @var{file} recursively.

In this case, the hash is computed on an archive containing @var{file},
including its children if it is a directory.  Some of @var{file}'s
meta-data is part of the archive; for instance, when @var{file} is a
regular file, the hash is different depending on whether @var{file} is
executable or not.  Meta-data such as time stamps has no impact on the
hash (@pxref{Invoking guix archive}).
@c FIXME: Replace xref above with xref to an ``Archive'' section when
@c it exists.

@end table

@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.

When considering whether to upgrade a package, it is sometimes
convenient to know which packages would be affected by the upgrade and
should be checked for compatibility.  For this the following option may
be used when passing @command{guix refresh} one or more package names:

@table @code

@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
result of upgrading one or more packages.

@end table

Be aware that the @code{--list-dependent} option only
@emph{approximates} the rebuilds that would be required as a result of
an upgrade.  More rebuilds might be required under some circumstances.

@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
@end example

The command above lists a set of packages that could be built to check
for compatibility with an upgraded @code{flex} package.

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

@node Invoking guix lint
@section Invoking @command{guix lint}
The @command{guix lint} is meant to help package developers avoid common
errors and use a consistent style.  It runs a few checks on a given set of
packages in order to find common mistakes in their definitions.

The general syntax is:

@example
guix lint @var{options} @var{package}@dots{}
@end example

If no package is given on the command line, then all packages are checked.
The @var{options} may be zero or more of the following:

@table @code

@item --list-checkers
@itemx -l
List and describe all the available checkers that will be run on packages
and exit.

@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 forms 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 browsed
@url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):

@example
guix package --list-available
@end example

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.

The GNU distribution is currently available on the following platforms:

@table @code

@item x86_64-linux
Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;

@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel;

@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 application binary interface (ABI), and Linux-Libre kernel.

@end table

@noindent
For information on porting to other architectures or kernels,
@xref{Porting}.

@menu
* System Installation::         Installing the whole operating system.
* System Configuration::        Configuring a GNU system.
* 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.

@node System Installation
@section System Installation

This section explains how to install the complete GNU operating system
on a machine.  The Guix package manager can also be installed on top of
a running GNU/Linux system, @pxref{Installation}.

@ifinfo
@c This paragraph is for people reading this from tty2 of the
@c installation image.
You're reading this documentation with an Info reader.  For details on
how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
link that follows: @pxref{Help,,, info, Info: An Introduction}.  Hit
@kbd{l} afterwards to come back here.
@end ifinfo

@subsection Limitations

As of version @value{VERSION}, GNU@tie{}Guix and the GNU system
distribution are alpha software.  It may contain bugs and lack important
features.  Thus, if you are looking for a stable production system that
respects your freedom as a computer user, a good solution at this point
is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
more established GNU/Linux distributions}.  We hope you can soon switch
to the GNU system without fear, of course.  In the meantime, you can
also keep using your distribution and try out the package manager on top
of it (@pxref{Installation}).

Before you proceed with the installation, be aware of the following
noteworthy limitations applicable to version @value{VERSION}:

@itemize
@item
The installation process does not include a graphical user interface and
requires familiarity with GNU/Linux (see the following subsections to
get a feel of what that means.)

@item
The system does not yet provide graphical desktop environments such as
GNOME and KDE.

@item
Support for the Logical Volume Manager (LVM) is missing.

@item
Few system services are currently supported out-of-the-box
(@pxref{Services}).

@item
On the order of 1,000 packages are available, which means that you may
occasionally find that a useful package is missing.
@end itemize

You've been warned.  But more than a disclaimer, this is an invitation
to report issues (and success stories!), and join us in improving it.
@xref{Contributing}, for more info.

@subsection USB Stick Installation

An installation image for USB sticks can be downloaded from
@url{ftp://alpha.gnu.org/gnu/guix/gnu-usb-install-@value{VERSION}.@var{system}.xz},
where @var{system} is one of:

@table @code
@item x86_64-linux
for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;

@item i686-linux
for a 32-bit GNU/Linux system on Intel-compatible CPUs.
@end table

This image contains a single partition with the tools necessary for an
installation.  It is meant to be copied @emph{as is} to a large-enough
USB stick.

To copy the image to a USB stick, follow these steps:

@enumerate
@item
Decompress the image using the @command{xz} command:

@example
xz -d gnu-usb-install-@value{VERSION}.@var{system}.xz
@end example

@item
Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
its device name.  Assuming that USB stick is known as @file{/dev/sdX},
copy the image with:

@example
dd if=gnu-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
@end example

Access to @file{/dev/sdX} usually requires root privileges.
@end enumerate

Once this is done, you should be able to reboot the system and boot from
the USB stick.  The latter usually requires you to get in the BIOS' boot
menu, where you can choose to boot from the USB stick.

@subsection Preparing for Installation

Once you have successfully booted the image on the USB stick, you should
end up with a root prompt.  Several console TTYs are configured and can
be used to run commands as root.  TTY2 shows this documentation,
browsable using the Info reader commands (@pxref{Help,,, info, Info: An
Introduction}).

To install the system, you would:

@enumerate

@item
Configure the network, by running @command{dhclient eth0} (to get an
automatically assigned IP address from the wired network interface
controller), or using the @command{ifconfig} command.

The system automatically loads drivers for your network interface
controllers.

Setting up network access is almost always a requirement because the
image does not contain all the software and tools that may be needed.

@item
Unless this has already been done, you must partition and format the
target partitions.

Preferably, assign partitions a label so that you can easily and
reliably refer to them in @code{file-system} declarations (@pxref{File
Systems}).  This is typically done using the @code{-L} option of
@command{mkfs.ext4} and related commands.

The installation image includes Parted (@pxref{Overview,,, parted, GNU
Parted User Manual}), @command{fdisk}, and e2fsprogs, the suite of tools
to manipulate ext2/ext3/ext4 file systems.

@item
Once that is done, mount the target root partition under @file{/mnt}.

@item
Lastly, run @code{deco start cow-store /mnt}.

This will make @file{/gnu/store} copy-on-write, such that packages added
to it during the installation phase will be written to the target disk
rather than kept in memory.

@end enumerate


@subsection Proceeding with the Installation

With the target partitions ready, you now have to edit a file and
provide the declaration of the operating system to be installed.  To
that end, the installation system comes with two text editors: GNU nano
(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
It is better to store that file on the target root file system, say, as
@file{/mnt/etc/config.scm}.

A minimal operating system configuration, with just the bare minimum and
only a root account would look like this (on the installation system,
this example is available as @file{/etc/configuration-template.scm}):

@example
@include os-config.texi
@end example

@noindent
For more information on @code{operating-system} declarations,
@pxref{Using the Configuration System}.

Once that is done, the new system must be initialized (remember that the
target root file system is mounted under @file{/mnt}):

@example
guix system init /mnt/etc/config.scm /mnt
@end example

@noindent
This will copy all the necessary files, and install GRUB on
@file{/dev/sdX}, unless you pass the @option{--no-grub} option.  For
more information, @pxref{Invoking guix system}.  This command may trigger