guix.texi

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

@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)] [#: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}.

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))}.

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


@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, @ref{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: @ref{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 encrypted disks, the Logical Volume Manager (LVM), and swap
devices are 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-20140629.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.

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.

@end enumerate

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

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

@example
(use-modules (gnu))

(operating-system
  (host-name "foo")
  (timezone "Europe/Paris")
  (locale "en_US.UTF-8")

  ;; Assuming /dev/sdX is the target hard disk, and /dev/sdX1 the
  ;; target root file system.
  (bootloader (grub-configuration (device "/dev/sdX")))
  (file-systems (list (file-system
                        (device "/dev/sdX1")
                        (mount-point "/")
                        (type "ext4")))))
@end example

@noindent
For more information on @code{operating-system} declarations,
@xref{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, @xref{Invoking guix system}.  This command may trigger
downloads or builds of missing packages, which can take some time.

Once that command has completed---and hopefully succeeded!---you can
unmount @file{/mnt} and boot into the new system.  Cross fingers, and
join us on @code{#guix} on the Freenode IRC network or on
@file{guix-devel@@gnu.org} to share your experience---good or not so
good.

@subsection Building the Installation Image

The installation image described above was built using the @command{guix
system} command, specifically:

@example
guix system disk-image --image-size=800MiB gnu/system/install.scm
@end example

@xref{Invoking guix system}, for more information.  See
@file{gnu/system/install.scm} in the source tree for more information
about the installation image.

@node System Configuration
@section System Configuration

@cindex system configuration
The GNU system supports a consistent whole-system configuration
mechanism.  By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place.  Such
a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.

One of the advantages of putting all the system configuration under the
control of Guix is that it supports transactional system upgrades, and
makes it possible to roll-back to a previous system instantiation,
should something go wrong with the new one (@pxref{Features}).  Another
one is that it makes it easy to replicate the exact same configuration
across different machines, or at different points in time, without
having to resort to additional administration tools layered on top of
the system's own tools.
@c Yes, we're talking of Puppet, Chef, & co. here.  ↑

This section describes this mechanism.  First we focus on the system
administrator's viewpoint---explaining how the system is configured and
instantiated.  Then we show how this mechanism can be extended, for
instance to support new system services.

@menu
* Using the Configuration System::  Customizing your GNU system.
* File Systems::                Configuring file system mounts.
* User Accounts::               Specifying user accounts.
* Services::                    Specifying system services.
* Setuid Programs::             Programs running with root privileges.
* Initial RAM Disk::            Linux-Libre bootstrapping.
* Invoking guix system::        Instantiating a system configuration.
* Defining Services::           Adding new service definitions.
@end menu

@node Using the Configuration System
@subsection Using the Configuration System

The operating system is configured by providing an
@code{operating-system} declaration in a file that can then be passed to
the @command{guix system} command (@pxref{Invoking guix system}).  A
simple setup, with the default system services, the default Linux-Libre
kernel, initial RAM disk, and boot loader looks like this:

@findex operating-system
@lisp
(use-modules (gnu)   ; for 'user-account', '%base-services', etc.
             (gnu packages emacs)  ; for 'emacs'
             (gnu services ssh))   ; for 'lsh-service'

(operating-system
  (host-name "komputilo")
  (timezone "Europe/Paris")
  (locale "fr_FR.UTF-8")
  (bootloader (grub-configuration
                (device "/dev/sda")))
  (file-systems (list (file-system
                        (device "/dev/sda1") ; or partition label
                        (mount-point "/")
                        (type "ext3"))))
  (users (list (user-account
                (name "alice")
                (password "")
                (uid 1000) (group 100)
                (comment "Bob's sister")
                (home-directory "/home/alice"))))
  (packages (cons emacs %base-packages))
  (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
                  %base-services)))
@end lisp

This example should be self-describing.  Some of the fields defined
above, such as @code{host-name} and @code{bootloader}, are mandatory.
Others, such as @code{packages} and @code{services}, can be omitted, in
which case they get a default value.

@vindex %base-packages
The @code{packages} field lists
packages that will be globally visible on the system, for all user
accounts---i.e., in every user's @code{PATH} environment variable---in
addition to the per-user profiles (@pxref{Invoking guix package}).  The
@var{%base-packages} variable provides all the tools one would expect
for basic user and administrator tasks---including the GNU Core
Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
editor, @command{find}, @command{grep}, etc.  The example above adds
Emacs to those, taken from the @code{(gnu packages emacs)} module
(@pxref{Package Modules}).

@vindex %base-services
The @code{services} field lists @dfn{system services} to be made
available when the system starts (@pxref{Services}).
The @code{operating-system} declaration above specifies that, in
addition to the basic services, we want the @command{lshd} secure shell
daemon listening on port 2222, and allowing remote @code{root} logins
(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}).  Under the hood,
@code{lsh-service} arranges so that @code{lshd} is started with the
right command-line options, possibly with supporting configuration files
generated as needed (@pxref{Defining Services}).

Assuming the above snippet is stored in the @file{my-system-config.scm}
file, the @command{guix system reconfigure my-system-config.scm} command
instantiates that configuration, and makes it the default GRUB boot
entry (@pxref{Invoking guix system}).  The normal way to change the
system's configuration is by updating this file and re-running the
@command{guix system} command.

At the Scheme level, the bulk of an @code{operating-system} declaration
is instantiated with the following monadic procedure (@pxref{The Store
Monad}):

@deffn {Monadic Procedure} operating-system-derivation os
Return a derivation that builds @var{os}, an @code{operating-system}
object (@pxref{Derivations}).

The output of the derivation is a single directory that refers to all
the packages, configuration files, and other supporting files needed to
instantiate @var{os}.
@end deffn

@node File Systems
@subsection File Systems

The list of file systems to be mounted is specified in the
@code{file-systems} field of the operating system's declaration
(@pxref{Using the Configuration System}).  Each file system is declared
using the @code{file-system} form, like this:

@example
(file-system
  (mount-point "/home")
  (device "/dev/sda3")
  (type "ext4"))
@end example

As usual, some of the fields are mandatory---those shown in the example
above---while others can be omitted.  These are described below.

@deftp {Data Type} file-system
Objects of this type represent file systems to be mounted.  They
contain the following members:

@table @asis
@item @code{type}
This is a string specifying the type of the file system---e.g.,
@code{"ext4"}.

@item @code{mount-point}
This designates the place where the file system is to be mounted.

@item @code{device}
This names the ``source'' of the file system.  By default it is the name
of a node under @file{/dev}, but its meaning depends on the @code{title}
field described below.