guix.texi

$ qemu-system-x86_64 \
   -net user -net nic,model=virtio \
   -enable-kvm -m 1024 \
   -device virtio-blk,drive=myhd \
   -drive if=none,file=/tmp/qemu-image,id=myhd
@end example

Here is what each of these options means:

@table @code
@item qemu-system-x86_64
This specifies the hardware platform to emulate.  This should match the
host.

@item -net user
Enable the unprivileged user-mode network stack.  The guest OS can
access the host but not vice versa.  This is the simplest way to get the
guest OS online.

@item -net nic,model=virtio
You must create a network interface of a given model.  If you do not
create a NIC, the boot will fail.  Assuming your hardware platform is
x86_64, you can get a list of available NIC models by running
@command{qemu-system-x86_64 -net nic,model=help}.

@item -enable-kvm
If your system has hardware virtualization extensions, enabling the
virtual machine support (KVM) of the Linux kernel will make things run
faster.

@c To run Xfce + 'guix pull', we need at least 1G of RAM.
@item -m 1024
RAM available to the guest OS, in mebibytes.  Defaults to 128@tie{}MiB,
which may be insufficient for some operations.

@item -device virtio-blk,drive=myhd
Create a @code{virtio-blk} drive called ``myhd''.  @code{virtio-blk} is a
``paravirtualization'' mechanism for block devices that allows QEMU to achieve
better performance than if it were emulating a complete disk drive.  See the
QEMU and KVM documentation for more info.

@item -drive if=none,file=/tmp/qemu-image,id=myhd
Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing store the
the ``myhd'' drive.
@end table

The default @command{run-vm.sh} script that is returned by an invocation of
@command{guix system vm} does not add a @command{-net user} flag by default.
To get network access from within the vm add the @code{(dhcp-client-service)}
to your system definition and start the VM using
@command{`guix system vm config.scm` -net user}.  An important caveat of using
@command{-net user} for networking is that @command{ping} will not work, because
it uses the ICMP protocol.  You'll have to use a different command to check for
network connectivity, for example @command{guix download}.

@subsection Connecting Through SSH

@cindex SSH
@cindex SSH server
To enable SSH inside a VM you need to add an SSH server like
@code{openssh-service-type} to your VM (@pxref{Networking Services,
@code{openssh-service-type}}).  In addition you need to forward the SSH port,
22 by default, to the host.  You can do this with

@example
`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22
@end example

To connect to the VM you can run

@example
ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022
@end example

The @command{-p} tells @command{ssh} the port you want to connect to.
@command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from complaining
every time you modify your @command{config.scm} file and the
@command{-o StrictHostKeyChecking=no} prevents you from having to allow a
connection to an unknown host every time you connect.

@subsection Using @command{virt-viewer} with Spice

As an alternative to the default @command{qemu} graphical client you can
use the @command{remote-viewer} from the @command{virt-viewer} package.  To
connect pass the @command{-spice port=5930,disable-ticketing} flag to
@command{qemu}.  See previous section for further information on how to do this.

Spice also allows you to do some nice stuff like share your clipboard with your
VM.  To enable that you'll also have to pass the following flags to @command{qemu}:

@example
-device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
-chardev spicevmc,name=vdagent,id=vdagent
-device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,
name=com.redhat.spice.0
@end example

You'll also need to add the @pxref{Miscellaneous Services, Spice service}.

@node Defining Services
@section Defining Services

The previous sections show the available services and how one can combine
them in an @code{operating-system} declaration.  But how do we define
them in the first place?  And what is a service anyway?

@menu
* Service Composition::         The model for composing services.
* Service Types and Services::  Types and services.
* Service Reference::           API reference.
* Shepherd Services::           A particular type of service.
@end menu

@node Service Composition
@subsection Service Composition

@cindex services
@cindex daemons
Here we define a @dfn{service} as, broadly, something that extends the
functionality of the operating system.  Often a service is a process---a
@dfn{daemon}---started when the system boots: a secure shell server, a
Web server, the Guix build daemon, etc.  Sometimes a service is a daemon
whose execution can be triggered by another daemon---e.g., an FTP server
started by @command{inetd} or a D-Bus service activated by
@command{dbus-daemon}.  Occasionally, a service does not map to a
daemon.  For instance, the ``account'' service collects user accounts
and makes sure they exist when the system runs; the ``udev'' service
collects device management rules and makes them available to the eudev
daemon; the @file{/etc} service populates the @file{/etc} directory
of the system.

@cindex service extensions
Guix system services are connected by @dfn{extensions}.  For instance, the
secure shell service @emph{extends} the Shepherd---the
initialization system, running as PID@tie{}1---by giving it the command
lines to start and stop the secure shell daemon (@pxref{Networking
Services, @code{openssh-service-type}}); the UPower service extends the D-Bus
service by passing it its @file{.service} specification, and extends the
udev service by passing it device management rules (@pxref{Desktop
Services, @code{upower-service}}); the Guix daemon service extends the
Shepherd by passing it the command lines to start and stop the daemon,
and extends the account service by passing it a list of required build
user accounts (@pxref{Base Services}).

All in all, services and their ``extends'' relations form a directed
acyclic graph (DAG).  If we represent services as boxes and extensions
as arrows, a typical system might provide something like this:

@image{images/service-graph,,5in,Typical service extension graph.}

@cindex system service
At the bottom, we see the @dfn{system service}, which produces the
directory containing everything to run and boot the system, as returned
by the @command{guix system build} command.  @xref{Service Reference},
to learn about the other service types shown here.
@xref{system-extension-graph, the @command{guix system extension-graph}
command}, for information on how to generate this representation for a
particular operating system definition.

@cindex service types
Technically, developers can define @dfn{service types} to express these
relations.  There can be any number of services of a given type on the
system---for instance, a system running two instances of the GNU secure
shell server (lsh) has two instances of @code{lsh-service-type}, with
different parameters.

The following section describes the programming interface for service
types and services.

@node Service Types and Services
@subsection Service Types and Services

A @dfn{service type} is a node in the DAG described above.  Let us start
with a simple example, the service type for the Guix build daemon
(@pxref{Invoking guix-daemon}):

@lisp
(define guix-service-type
  (service-type
   (name 'guix)
   (extensions
    (list (service-extension shepherd-root-service-type guix-shepherd-service)
          (service-extension account-service-type guix-accounts)
          (service-extension activation-service-type guix-activation)))
   (default-value (guix-configuration))))
@end lisp

@noindent
It defines three things:

@enumerate
@item
A name, whose sole purpose is to make inspection and debugging easier.

@item
A list of @dfn{service extensions}, where each extension designates the
target service type and a procedure that, given the parameters of the
service, returns a list of objects to extend the service of that type.

Every service type has at least one service extension.  The only
exception is the @dfn{boot service type}, which is the ultimate service.

@item
Optionally, a default value for instances of this type.
@end enumerate

In this example, @code{guix-service-type} extends three services:

@table @code
@item shepherd-root-service-type
The @code{guix-shepherd-service} procedure defines how the Shepherd
service is extended.  Namely, it returns a @code{<shepherd-service>}
object that defines how @command{guix-daemon} is started and stopped
(@pxref{Shepherd Services}).

@item account-service-type
This extension for this service is computed by @code{guix-accounts},
which returns a list of @code{user-group} and @code{user-account}
objects representing the build user accounts (@pxref{Invoking
guix-daemon}).

@item activation-service-type
Here @code{guix-activation} is a procedure that returns a gexp, which is
a code snippet to run at ``activation time''---e.g., when the service is
booted.
@end table

A service of this type is instantiated like this:

@lisp
(service guix-service-type
         (guix-configuration
           (build-accounts 5)
           (use-substitutes? #f)))
@end lisp

The second argument to the @code{service} form is a value representing
the parameters of this specific service instance.
@xref{guix-configuration-type, @code{guix-configuration}}, for
information about the @code{guix-configuration} data type.  When the
value is omitted, the default value specified by
@code{guix-service-type} is used:

@lisp
(service guix-service-type)
@end lisp

@code{guix-service-type} is quite simple because it extends other
services but is not extensible itself.

@c @subsubsubsection Extensible Service Types

The service type for an @emph{extensible} service looks like this:

@lisp
(define udev-service-type
  (service-type (name 'udev)
                (extensions
                 (list (service-extension shepherd-root-service-type
                                          udev-shepherd-service)))

                (compose concatenate)       ;concatenate the list of rules
                (extend (lambda (config rules)
                          (match config
                            (($ <udev-configuration> udev initial-rules)
                             (udev-configuration
                              (udev udev)   ;the udev package to use
                              (rules (append initial-rules rules)))))))))
@end lisp

This is the service type for the
@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
management daemon}.  Compared to the previous example, in addition to an
extension of @code{shepherd-root-service-type}, we see two new fields:

@table @code
@item compose
This is the procedure to @dfn{compose} the list of extensions to
services of this type.

Services can extend the udev service by passing it lists of rules; we
compose those extensions simply by concatenating them.

@item extend
This procedure defines how the value of the service is @dfn{extended} with
the composition of the extensions.

Udev extensions are composed into a list of rules, but the udev service
value is itself a @code{<udev-configuration>} record.  So here, we
extend that record by appending the list of rules it contains to the
list of contributed rules.

@item description
This is a string giving an overview of the service type.  The string can
contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}).  The
@command{guix system search} command searches these strings and displays
them (@pxref{Invoking guix system}).
@end table

There can be only one instance of an extensible service type such as
@code{udev-service-type}.  If there were more, the
@code{service-extension} specifications would be ambiguous.

Still here?  The next section provides a reference of the programming
interface for services.

@node Service Reference
@subsection Service Reference

We have seen an overview of service types (@pxref{Service Types and
Services}).  This section provides a reference on how to manipulate
services and service types.  This interface is provided by the
@code{(gnu services)} module.

@deffn {Scheme Procedure} service @var{type} [@var{value}]
Return a new service of @var{type}, a @code{<service-type>} object (see
below.)  @var{value} can be any object; it represents the parameters of
this particular service instance.

When @var{value} is omitted, the default value specified by @var{type}
is used; if @var{type} does not specify a default value, an error is
raised.

For instance, this:

@lisp
(service openssh-service-type)
@end lisp

@noindent
is equivalent to this:

@lisp
(service openssh-service-type
         (openssh-configuration))
@end lisp

In both cases the result is an instance of @code{openssh-service-type}
with the default configuration.
@end deffn

@deffn {Scheme Procedure} service? @var{obj}
Return true if @var{obj} is a service.
@end deffn

@deffn {Scheme Procedure} service-kind @var{service}
Return the type of @var{service}---i.e., a @code{<service-type>} object.
@end deffn

@deffn {Scheme Procedure} service-value @var{service}
Return the value associated with @var{service}.  It represents its
parameters.
@end deffn

Here is an example of how a service is created and manipulated:

@lisp
(define s
  (service nginx-service-type
           (nginx-configuration
            (nginx nginx)
            (log-directory log-directory)
            (run-directory run-directory)
            (file config-file))))

(service? s)
@result{} #t

(eq? (service-kind s) nginx-service-type)
@result{} #t
@end lisp

The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as
@code{%base-services} (@pxref{Base Services, @code{%base-services}}).  It
evaluates to a list of services.  Of course, you could always use
standard list combinators such as @code{map} and @code{fold} to do that
(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
@code{modify-services} simply provides a more concise form for this
common pattern.

@deffn {Scheme Syntax} modify-services @var{services} @
  (@var{type} @var{variable} => @var{body}) @dots{}

Modify the services listed in @var{services} according to the given
clauses.  Each clause has the form:

@example
(@var{type} @var{variable} => @var{body})
@end example

where @var{type} is a service type---e.g.,
@code{guix-service-type}---and @var{variable} is an identifier that is
bound within the @var{body} to the service parameters---e.g., a
@code{guix-configuration} instance---of the original service of that
@var{type}.

The @var{body} should evaluate to the new service parameters, which will
be used to configure the new service.  This new service will replace the
original in the resulting list.  Because a service's service parameters
are created using @code{define-record-type*}, you can write a succinct
@var{body} that evaluates to the new service parameters by using the
@code{inherit} feature that @code{define-record-type*} provides.

@xref{Using the Configuration System}, for example usage.

@end deffn

Next comes the programming interface for service types.  This is
something you want to know when writing new service definitions, but not
necessarily when simply looking for ways to customize your
@code{operating-system} declaration.

@deftp {Data Type} service-type
@cindex service type
This is the representation of a @dfn{service type} (@pxref{Service Types
and Services}).

@table @asis
@item @code{name}
This is a symbol, used only to simplify inspection and debugging.

@item @code{extensions}
A non-empty list of @code{<service-extension>} objects (see below).

@item @code{compose} (default: @code{#f})
If this is @code{#f}, then the service type denotes services that cannot
be extended---i.e., services that do not receive ``values'' from other
services.

Otherwise, it must be a one-argument procedure.  The procedure is called
by @code{fold-services} and is passed a list of values collected from
extensions.  It may return any single value.

@item @code{extend} (default: @code{#f})
If this is @code{#f}, services of this type cannot be extended.

Otherwise, it must be a two-argument procedure: @code{fold-services}
calls it, passing it the initial value of the service as the first
argument and the result of applying @code{compose} to the extension
values as the second argument.  It must return a value that is a valid
parameter value for the service instance.
@end table

@xref{Service Types and Services}, for examples.
@end deftp

@deffn {Scheme Procedure} service-extension @var{target-type} @
                              @var{compute}
Return a new extension for services of type @var{target-type}.
@var{compute} must be a one-argument procedure: @code{fold-services}
calls it, passing it the value associated with the service that provides
the extension; it must return a valid value for the target service.
@end deffn

@deffn {Scheme Procedure} service-extension? @var{obj}
Return true if @var{obj} is a service extension.
@end deffn

Occasionally, you might want to simply extend an existing service.  This
involves creating a new service type and specifying the extension of
interest, which can be verbose; the @code{simple-service} procedure
provides a shorthand for this.

@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
Return a service that extends @var{target} with @var{value}.  This works
by creating a singleton service type @var{name}, of which the returned
service is an instance.

For example, this extends mcron (@pxref{Scheduled Job Execution}) with
an additional job:

@lisp
(simple-service 'my-mcron-job mcron-service-type
                #~(job '(next-hour (3)) "guix gc -F 2G"))
@end lisp
@end deffn

At the core of the service abstraction lies the @code{fold-services}
procedure, which is responsible for ``compiling'' a list of services
down to a single directory that contains everything needed to boot and
run the system---the directory shown by the @command{guix system build}
command (@pxref{Invoking guix system}).  In essence, it propagates
service extensions down the service graph, updating each node parameters
on the way, until it reaches the root node.

@deffn {Scheme Procedure} fold-services @var{services} @
                            [#:target-type @var{system-service-type}]
Fold @var{services} by propagating their extensions down to the root of
type @var{target-type}; return the root service adjusted accordingly.
@end deffn

Lastly, the @code{(gnu services)} module also defines several essential
service types, some of which are listed below.

@defvr {Scheme Variable} system-service-type
This is the root of the service graph.  It produces the system directory
as returned by the @command{guix system build} command.
@end defvr

@defvr {Scheme Variable} boot-service-type
The type of the ``boot service'', which produces the @dfn{boot script}.
The boot script is what the initial RAM disk runs when booting.
@end defvr

@defvr {Scheme Variable} etc-service-type
The type of the @file{/etc} service.  This service is used to create
files under @file{/etc} and can be extended by
passing it name/file tuples such as:

@lisp
(list `("issue" ,(plain-file "issue" "Welcome!\n")))
@end lisp

In this example, the effect would be to add an @file{/etc/issue} file
pointing to the given file.
@end defvr

@defvr {Scheme Variable} setuid-program-service-type
Type for the ``setuid-program service''.  This service collects lists of
executable file names, passed as gexps, and adds them to the set of
setuid-root programs on the system (@pxref{Setuid Programs}).
@end defvr

@defvr {Scheme Variable} profile-service-type
Type of the service that populates the @dfn{system profile}---i.e., the
programs under @file{/run/current-system/profile}.  Other services can
extend it by passing it lists of packages to add to the system profile.
@end defvr


@node Shepherd Services
@subsection Shepherd Services

@cindex shepherd services
@cindex PID 1
@cindex init system
The @code{(gnu services shepherd)} module provides a way to define
services managed by the GNU@tie{}Shepherd, which is the
initialization system---the first process that is started when the
system boots, also known as PID@tie{}1
(@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).

Services in the Shepherd can depend on each other.  For instance, the
SSH daemon may need to be started after the syslog daemon has been
started, which in turn can only happen once all the file systems have
been mounted.  The simple operating system defined earlier (@pxref{Using
the Configuration System}) results in a service graph like this:

@image{images/shepherd-graph,,5in,Typical shepherd service graph.}

You can actually generate such a graph for any operating system
definition using the @command{guix system shepherd-graph} command
(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).

The @code{%shepherd-root-service} is a service object representing
PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
by passing it lists of @code{<shepherd-service>} objects.

@deftp {Data Type} shepherd-service
The data type representing a service managed by the Shepherd.

@table @asis
@item @code{provision}
This is a list of symbols denoting what the service provides.

These are the names that may be passed to @command{herd start},
@command{herd status}, and similar commands (@pxref{Invoking herd,,,
shepherd, The GNU Shepherd Manual}).  @xref{Slots of services, the
@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.

@item @code{requirement} (default: @code{'()})
List of symbols denoting the Shepherd services this one depends on.

@cindex one-shot services, for the Shepherd
@item @code{one-shot?} (default: @code{#f})
Whether this service is @dfn{one-shot}.  One-shot services stop immediately
after their @code{start} action has completed.  @xref{Slots of services,,,
shepherd, The GNU Shepherd Manual}, for more info.

@item @code{respawn?} (default: @code{#t})
Whether to restart the service when it stops, for instance when the
underlying process dies.

@item @code{start}
@itemx @code{stop} (default: @code{#~(const #f)})
The @code{start} and @code{stop} fields refer to the Shepherd's
facilities to start and stop processes (@pxref{Service De- and
Constructors,,, shepherd, The GNU Shepherd Manual}).  They are given as
G-expressions that get expanded in the Shepherd configuration file
(@pxref{G-Expressions}).

@item @code{actions} (default: @code{'()})
@cindex actions, of Shepherd services
This is a list of @code{shepherd-action} objects (see below) defining
@dfn{actions} supported by the service, in addition to the standard
@code{start} and @code{stop} actions.  Actions listed here become available as
@command{herd} sub-commands:

@example
herd @var{action} @var{service} [@var{arguments}@dots{}]
@end example

@item @code{auto-start?} (default: @code{#t})
Whether this service should be started automatically by the Shepherd.  If it
is @code{#f} the service has to be started manually with @code{herd start}.

@item @code{documentation}
A documentation string, as shown when running:

@example
herd doc @var{service-name}
@end example

where @var{service-name} is one of the symbols in @code{provision}
(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).

@item @code{modules} (default: @code{%default-modules})
This is the list of modules that must be in scope when @code{start} and
@code{stop} are evaluated.

@end table
@end deftp

@deftp {Data Type} shepherd-action
This is the data type that defines additional actions implemented by a
Shepherd service (see above).

@table @code
@item name
Symbol naming the action.

@item documentation
This is a documentation string for the action.  It can be viewed by running:

@example
herd doc @var{service} action @var{action}
@end example

@item procedure
This should be a gexp that evaluates to a procedure of at least one argument,
which is the ``running value'' of the service (@pxref{Slots of services,,,
shepherd, The GNU Shepherd Manual}).
@end table

The following example defines an action called @code{say-hello} that kindly
greets the user:

@lisp
(shepherd-action
  (name 'say-hello)
  (documentation "Say hi!")
  (procedure #~(lambda (running . args)
                 (format #t "Hello, friend! arguments: ~s\n"
                         args)
                 #t)))
@end lisp

Assuming this action is added to the @code{example} service, then you can do:

@example
# herd say-hello example
Hello, friend! arguments: ()
# herd say-hello example a b c
Hello, friend! arguments: ("a" "b" "c")
@end example

This, as you can see, is a fairly sophisticated way to say hello.
@xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more
info on actions.
@end deftp

@defvr {Scheme Variable} shepherd-root-service-type
The service type for the Shepherd ``root service''---i.e., PID@tie{}1.

This is the service type that extensions target when they want to create
shepherd services (@pxref{Service Types and Services}, for an example).
Each extension must pass a list of @code{<shepherd-service>}.
@end defvr

@defvr {Scheme Variable} %shepherd-root-service
This service represents PID@tie{}1.
@end defvr


@node Documentation
@chapter Documentation

@cindex documentation, searching for
@cindex searching for documentation
@cindex Info, documentation format
@cindex man pages
@cindex manual pages
In most cases packages installed with Guix come with documentation.
There are two main documentation formats: ``Info'', a browseable
hypertext format used for GNU software, and ``manual pages'' (or ``man
pages''), the linear documentation format traditionally found on Unix.
Info manuals are accessed with the @command{info} command or with Emacs,
and man pages are accessed using @command{man}.

You can look for documentation of software installed on your system by
keyword.  For example, the following command searches for information
about ``TLS'' in Info manuals:

@example
$ info -k TLS
"(emacs)Network Security" -- STARTTLS
"(emacs)Network Security" -- TLS
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
@dots{}
@end example

@noindent
The command below searches for the same keyword in man pages:

@example
$ man -k TLS
SSL (7)              - OpenSSL SSL/TLS library
certtool (1)         - GnuTLS certificate tool
@dots {}
@end example

These searches are purely local to your computer so you have the
guarantee that documentation you find corresponds to what you have
actually installed, you can access it off-line, and your privacy is
respected.

Once you have these results, you can view the relevant documentation by
running, say:

@example
$ info "(gnutls)Core TLS API"
@end example

@noindent
or:

@example
$ man certtool
@end example

Info manuals contain sections and indices as well as hyperlinks like
those found in Web pages.  The @command{info} reader (@pxref{Top, Info
reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
(@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
bindings to navigate manuals.  @xref{Getting Started,,, info, Info: An
Introduction}, for an introduction to Info navigation.

@node Installing Debugging Files
@chapter Installing Debugging Files

@cindex 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 install glibc:debug 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}.

In addition, you will most likely want GDB to be able to show the source
code being debugged.  To do that, you will have to unpack the source
code of the package of interest (obtained with @code{guix build
--source}, @pxref{Invoking guix build}), and to point GDB to that source
directory using the @code{directory} command (@pxref{Source Path,
@code{directory},, gdb, Debugging with GDB}).

@c XXX: keep me up-to-date
The @code{debug} output mechanism in Guix is implemented by the
@code{gnu-build-system} (@pxref{Build Systems}).  Currently, it is
opt-in---debugging information is available only for the packages
with definitions explicitly declaring 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 Security Updates
@chapter Security Updates

@cindex security updates
@cindex security vulnerabilities
Occasionally, important security vulnerabilities are discovered in software
packages and must be patched.  Guix developers try hard to keep track of
known vulnerabilities and to apply fixes as soon as possible in the
@code{master} branch of Guix (we do not yet provide a ``stable'' branch
containing only security updates.)  The @command{guix lint} tool helps
developers find out about vulnerable versions of software packages in the
distribution:

@smallexample
$ guix lint -c cve
gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
@dots{}
@end smallexample

@xref{Invoking guix lint}, for more information.

Guix follows a functional
package management discipline (@pxref{Introduction}), which implies
that, when a package is changed, @emph{every package that depends on it}
must be rebuilt.  This can significantly slow down the deployment of
fixes in core packages such as libc or Bash, since basically the whole
distribution would need to be rebuilt.  Using pre-built binaries helps
(@pxref{Substitutes}), but deployment may still take more time than
desired.

@cindex grafts
To address this, Guix implements @dfn{grafts}, a mechanism that allows
for fast deployment of critical updates without the costs associated
with a whole-distribution rebuild.  The idea is to rebuild only the
package that needs to be patched, and then to ``graft'' it onto packages
explicitly installed by the user and that were previously referring to
the original package.  The cost of grafting is typically very low, and
order of magnitudes lower than a full rebuild of the dependency chain.

@cindex replacements of packages, for grafts
For instance, suppose a security update needs to be applied to Bash.
Guix developers will provide a package definition for the ``fixed''
Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining
Packages}).  Then, the original package definition is augmented with a
@code{replacement} field pointing to the package containing the bug fix:

@lisp
(define bash
  (package
    (name "bash")
    ;; @dots{}
    (replacement bash-fixed)))
@end lisp

From there on, any package depending directly or indirectly on Bash---as
reported by @command{guix gc --requisites} (@pxref{Invoking guix
gc})---that is installed is automatically ``rewritten'' to refer to
@code{bash-fixed} instead of @code{bash}.  This grafting process takes
time proportional to the size of the package, usually less than a
minute for an ``average'' package on a recent machine.  Grafting is
recursive: when an indirect dependency requires grafting, then grafting
``propagates'' up to the package that the user is installing.

Currently, the length of the name and version of the graft and that of
the package it replaces (@code{bash-fixed} and @code{bash} in the example
above) must be equal.  This restriction mostly comes from the fact that
grafting works by patching files, including binary files, directly.
Other restrictions may apply: for instance, when adding a graft to a
package providing a shared library, the original shared library and its
replacement must have the same @code{SONAME} and be binary-compatible.

The @option{--no-grafts} command-line option allows you to forcefully
avoid grafting (@pxref{Common Build Options, @option{--no-grafts}}).
Thus, the command:

@example
guix build bash --no-grafts
@end example

@noindent
returns the store file name of the original Bash, whereas:

@example
guix build bash
@end example

@noindent
returns the store file name of the ``fixed'', replacement Bash.  This
allows you to distinguish between the two variants of Bash.

To verify which Bash your whole profile refers to, you can run
(@pxref{Invoking guix gc}):

@example
guix gc -R `readlink -f ~/.guix-profile` | grep bash
@end example

@noindent
@dots{} and compare the store file names that you get with those above.
Likewise for a complete Guix system generation:

@example
guix gc -R `guix system build my-config.scm` | grep bash
@end example

Lastly, to check which Bash running processes are using, you can use the
@command{lsof} command:

@example
lsof | grep /gnu/store/.*bash
@end example


@node Bootstrapping
@chapter 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
@code{./configure}, @code{make}, etc.---are written in Guile Scheme
(@pxref{Derivations}).  Consequently, to be able to build anything at
all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
Binutils, libc, and the other packages mentioned above---the
@dfn{bootstrap binaries}.

These bootstrap binaries are ``taken for granted'', though we can also
re-create them if needed (more on that later).

@unnumberedsec Preparing to Use the Bootstrap Binaries

@c As of Emacs 24.3, Info-mode displays the image, but since it's a
@c large image, it's hard to scroll.  Oh well.
@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}

The figure above shows the very beginning of the dependency graph of the
distribution, corresponding to the package definitions of the @code{(gnu
packages bootstrap)} module.  A similar figure can be generated with
@command{guix graph} (@pxref{Invoking guix graph}), along the lines of:

@example
guix graph -t derivation \
  -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
  | dot -Tps > t.ps
@end example

At this level of detail, things are
slightly complex.  First, Guile itself consists of an ELF executable,
along with many source and compiled Scheme files that are dynamically
loaded when it runs.  This gets stored in the @file{guile-2.0.7.tar.xz}
tarball shown in this graph.  This tarball is part of Guix's ``source''
distribution, and gets inserted into the store with @code{add-to-store}
(@pxref{The Store}).

But how do we write a derivation that unpacks this tarball and adds it
to the store?  To solve this problem, the @code{guile-bootstrap-2.0.drv}
derivation---the first one that gets built---uses @code{bash} as its
builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
@code{tar} to unpack the tarball.  Thus, @file{bash}, @file{tar},
@file{xz}, and @file{mkdir} are statically-linked binaries, also part of
the Guix source distribution, whose sole purpose is to allow the Guile
tarball to be unpacked.

Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
Guile that can be used to run subsequent build programs.  Its first task
is to download tarballs containing the other pre-built binaries---this
is what the @code{.tar.xz.drv} derivations do.  Guix modules such as
@code{ftp-client.scm} are used for this purpose.  The
@code{module-import.drv} derivations import those modules in a directory