guix.texi

Return a derivation that builds a @var{guile} script to start the X server
from @var{xorg-server}.  Usually the X server is started by a login manager.

@var{drivers} must be either the empty list, in which case Xorg chooses a
graphics driver automatically, or a list of driver names that will be tried in
this order---e.g., @code{("modesetting" "vesa")}.

Likewise, when @var{resolutions} is the empty list, Xorg chooses an
appropriate screen resolution; otherwise, it must be a list of
resolutions---e.g., @code{((1024 768) (640 480))}.
@end deffn

@node Desktop Services
@subsubsection Desktop Services

The @code{(gnu services desktop)} module provides services that are
usually useful in the context of a ``desktop'' setup---that is, on a
machine running a graphical display server, possibly with graphical user
interfaces, etc.

To simplify things, the module defines a variable containing the set of
services that users typically expect on a machine with a graphical
environment and networking:

@defvr {Scheme Variable} %desktop-services
This is a list of services that builds upon @var{%base-services} and
adds or adjust services for a typical ``desktop'' setup.

In particular, it adds a graphical login manager (@pxref{X Window,
@code{slim-service}}), a network management tool (@pxref{Networking
Services, @code{wicd-service}}), energy and color management services,
an NTP client and an SSH server (@pxref{Networking Services}), the Avahi
daemon, and has the name service switch service configured to be able to
use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
@end defvr

The @var{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).

The actual service definitions provided by @code{(gnu services desktop)}
are described below.

@deffn {Monadic Procedure} dbus-service @var{services} @
                         [#:dbus @var{dbus}]
Return a service that runs the ``system bus'', using @var{dbus}, with
support for @var{services}.

@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
facility.  Its system bus is used to allow system services to communicate
and be notified of system-wide events.

@var{services} must be a list of packages that provide an
@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
and policy files.  For example, to allow avahi-daemon to use the system bus,
@var{services} must be equal to @code{(list avahi)}.
@end deffn

@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
                         [#:watts-up-pro? #f] @
                         [#:poll-batteries? #t] @
                         [#:ignore-lid? #f] @
                         [#:use-percentage-for-policy? #f] @
                         [#:percentage-low 10] @
                         [#:percentage-critical 3] @
                         [#:percentage-action 2] @
                         [#:time-low 1200] @
                         [#:time-critical 300] @
                         [#:time-action 120] @
                         [#:critical-power-action 'hybrid-sleep]
Return a service that runs @uref{http://upower.freedesktop.org/,
@command{upowerd}}, a system-wide monitor for power consumption and battery
levels, with the given configuration settings.  It implements the
@code{org.freedesktop.UPower} D-Bus interface, and is notably used by
GNOME.
@end deffn

@deffn {Monadic Procedure} colord-service [#:colord @var{colord}]
Return a service that runs @command{colord}, a system service with a D-Bus
interface to manage the color profiles of input and output devices such as
screens and scanners.  It is notably used by the GNOME Color Manager graphical
tool.  See @uref{http://www.freedesktop.org/software/colord/, the colord web
site} for more information.
@end deffn

@node Database Services
@subsubsection Database Services

The @code{(gnu services databases)} module provides the following service.

@deffn {Monadic Procedure} postgresql-service [#:postgresql postgresql] @
       [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
Return a service that runs @var{postgresql}, the PostgreSQL database
server.

The PostgreSQL daemon loads its runtime configuration from
@var{config-file} and stores the database cluster in
@var{data-directory}.
@end deffn

@node Various Services
@subsubsection Various Services

The @code{(gnu services lirc)} module provides the following service.

@deffn {Monadic Procedure} lirc-service [#:lirc lirc] @
       [#:device #f] [#:driver #f] [#:config-file #f] @
       [#:extra-options '()]
Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
decodes infrared signals from remote controls.

Optionally, @var{device}, @var{driver} and @var{config-file}
(configuration file name) may be specified.  See @command{lircd} manual
for details.

Finally, @var{extra-options} is a list of additional command-line options
passed to @command{lircd}.
@end deffn


@node Setuid Programs
@subsection Setuid Programs

@cindex setuid programs
Some programs need to run with ``root'' privileges, even when they are
launched by unprivileged users.  A notorious example is the
@command{passwd} programs, which can users can run to change their
password, and which requires write access to the @file{/etc/passwd} and
@file{/etc/shadow} files---something normally restricted to root, for
obvious security reasons.  To address that, these executables are
@dfn{setuid-root}, meaning that they always run with root privileges
(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
for more info about the setuid mechanisms.)

The store itself @emph{cannot} contain setuid programs: that would be a
security issue since any user on the system can write derivations that
populate the store (@pxref{The Store}).  Thus, a different mechanism is
used: instead of changing the setuid bit directly on files that are in
the store, we let the system administrator @emph{declare} which programs
should be setuid root.

The @code{setuid-programs} field of an @code{operating-system}
declaration contains a list of G-expressions denoting the names of
programs to be setuid-root (@pxref{Using the Configuration System}).
For instance, the @command{passwd} program, which is part of the Shadow
package, can be designated by this G-expression (@pxref{G-Expressions}):

@example
#~(string-append #$shadow "/bin/passwd")
@end example

A default set of setuid programs is defined by the
@code{%setuid-programs} variable of the @code{(gnu system)} module.

@defvr {Scheme Variable} %setuid-programs
A list of G-expressions denoting common programs that are setuid-root.

The list includes commands such as @command{passwd}, @command{ping},
@command{su}, and @command{sudo}.
@end defvr

Under the hood, the actual setuid programs are created in the
@file{/run/setuid-programs} directory at system activation time.  The
files in this directory refer to the ``real'' binaries, which are in the
store.

@node Name Service Switch
@subsection Name Service Switch

@cindex name service switch
@cindex NSS
The @code{(gnu system nss)} module provides bindings to the
configuration file of libc's @dfn{name service switch} or @dfn{NSS}
(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
Manual}).  In a nutshell, the NSS is a mechanism that allows libc to be
extended with new ``name'' lookup methods for system databases, which
includes host names, service names, user accounts, and more (@pxref{Name
Service Switch, System Databases and Name Service Switch,, libc, The GNU
C Library Reference Manual}).

The NSS configuration specifies, for each system database, which lookup
method is to be used, and how the various methods are chained
together---for instance, under which circumstances NSS should try the
next method in the list.  The NSS configuration is given in the
@code{name-service-switch} field of @code{operating-system} declarations
(@pxref{operating-system Reference, @code{name-service-switch}}).

@cindex nss-mdns
@cindex .local, host name lookup
As an example, the declaration below configures the NSS to use the
@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
back-end}, which supports host name lookups over multicast DNS (mDNS)
for host names ending in @code{.local}:

@example
(name-service-switch
   (hosts (list %files    ;first, check /etc/hosts

                ;; If the above did not succeed, try
                ;; with 'mdns_minimal'.
                (name-service
                  (name "mdns_minimal")

                  ;; 'mdns_minimal' is authoritative for
                  ;; '.local'.  When it returns "not found",
                  ;; no need to try the next methods.
                  (reaction (lookup-specification
                             (not-found => return))))

                ;; Then fall back to DNS.
                (name-service
                  (name "dns"))

                ;; Finally, try with the "full" 'mdns'.
                (name-service
                  (name "mdns")))))
@end example

Don't worry: the @code{%mdns-host-lookup-nss} variable (see below)
contains this configuration, so you won't have to type it if all you
want is to have @code{.local} host lookup working.

Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration,
@code{nscd-service} must be told where to find the @code{nss-mdns}
shared library (@pxref{Base Services, @code{nscd-service}}).  Since the
@code{nscd} service is part of @var{%base-services}, you may want to
customize it by adding this snippet in the operating system
configuration file:

@example
(use-modules (guix) (gnu))

(define %my-base-services
  ;; Replace the default nscd service with one that knows
  ;; about nss-mdns.
  (map (lambda (mservice)
         ;; "Bind" the MSERVICE monadic value to inspect it.
         (mlet %store-monad ((service mservice))
           (if (member 'nscd (service-provision service))
               (nscd-service (nscd-configuration)
                             #:name-services (list nss-mdns))
               mservice)))
       %base-services))
@end example

@noindent
@dots{} and then refer to @var{%my-base-services} instead of
@var{%base-services} in the @code{operating-system} declaration.
Lastly, this relies on the availability of the Avahi service
(@pxref{Desktop Services, @code{avahi-service}}).

For convenience, the following variables provide typical NSS
configurations.

@defvr {Scheme Variable} %default-nss
This is the default name service switch configuration, a
@code{name-service-switch} object.
@end defvr

@defvr {Scheme Variable} %mdns-host-lookup-nss
This is the name service switch configuration with support for host name
lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
@end defvr

The reference for name service switch configuration is given below.  It
is a direct mapping of the C library's configuration file format, so
please refer to the C library manual for more information (@pxref{NSS
Configuration File,,, libc, The GNU C Library Reference Manual}).
Compared to libc's NSS configuration file format, it has the advantage
not only of adding this warm parenthetic feel that we like, but also
static checks: you'll know about syntax errors and typos as soon as you
run @command{guix system}.

@deftp {Data Type} name-service-switch

This is the data type representation the configuration of libc's name
service switch (NSS).  Each field below represents one of the supported
system databases.

@table @code
@item aliases
@itemx ethers
@itemx group
@itemx gshadow
@itemx hosts
@itemx initgroups
@itemx netgroup
@itemx networks
@itemx password
@itemx public-key
@itemx rpc
@itemx services
@itemx shadow
The system databases handled by the NSS.  Each of these fields must be a
list of @code{<name-service>} objects (see below.)
@end table
@end deftp

@deftp {Data Type} name-service

This is the data type representing an actual name service and the
associated lookup action.

@table @code
@item name
A string denoting the name service (@pxref{Services in the NSS
configuration,,, libc, The GNU C Library Reference Manual}).

Note that name services listed here must be visible to nscd.  This is
achieved by passing the @code{#:name-services} argument to
@code{nscd-service} the list of packages providing the needed name
services (@pxref{Base Services, @code{nscd-service}}).

@item reaction
An action specified using the @code{lookup-specification} macro
(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
Reference Manual}).  For example:

@example
(lookup-specification (unavailable => continue)
                      (success => return))
@end example
@end table
@end deftp

@node Initial RAM Disk
@subsection Initial RAM Disk

@cindex initial RAM disk (initrd)
@cindex initrd (initial RAM disk)
For bootstrapping purposes, the Linux-Libre kernel is passed an
@dfn{initial RAM disk}, or @dfn{initrd}.  An initrd contains a temporary
root file system, as well as an initialization script.  The latter is
responsible for mounting the real root file system, and for loading any
kernel modules that may be needed to achieve that.

The @code{initrd} field of an @code{operating-system} declaration allows
you to specify which initrd you would like to use.  The @code{(gnu
system linux-initrd)} module provides two ways to build an initrd: the
high-level @code{base-initrd} procedure, and the low-level
@code{expression->initrd} procedure.

The @code{base-initrd} procedure is intended to cover most common uses.
For example, if you want to add a bunch of kernel modules to be loaded
at boot time, you can define the @code{initrd} field of the operating
system declaration like this:

@example
(initrd (lambda (file-systems . rest)
          ;; Create a standard initrd that has modules "foo.ko"
          ;; and "bar.ko", as well as their dependencies, in
          ;; addition to the modules available by default.
          (apply base-initrd file-systems
                 #:extra-modules '("foo" "bar")
                 rest)))
@end example

The @code{base-initrd} procedure also handles common use cases that
involves using the system as a QEMU guest, or as a ``live'' system whose
root file system is volatile.

@deffn {Monadic Procedure} base-initrd @var{file-systems} @
       [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
       [#:extra-modules '()] [#:mapped-devices '()]
Return a monadic derivation that builds a generic initrd.  @var{file-systems} is
a list of file-systems to be mounted by the initrd, possibly in addition to
the root file system specified on the kernel command line via @code{--root}.
@var{mapped-devices} is a list of device mappings to realize before
@var{file-systems} are mounted (@pxref{Mapped Devices}).

When @var{qemu-networking?} is true, set up networking with the standard QEMU
parameters.  When @var{virtio?} is true, load additional modules so the initrd can
be used as a QEMU guest with para-virtualized I/O drivers.

When @var{volatile-root?} is true, the root file system is writable but any changes
to it are lost.

The initrd is automatically populated with all the kernel modules necessary
for @var{file-systems} and for the given options.  However, additional kernel
modules can be listed in @var{extra-modules}.  They will be added to the initrd, and
loaded at boot time in the order in which they appear.
@end deffn

Needless to say, the initrds we produce and use embed a
statically-linked Guile, and the initialization program is a Guile
program.  That gives a lot of flexibility.  The
@code{expression->initrd} procedure builds such an initrd, given the
program to run in that initrd.

@deffn {Monadic Procedure} expression->initrd @var{exp} @
       [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
       [#:modules '()]
Return a derivation that builds a Linux initrd (a gzipped cpio archive)
containing @var{guile} and that evaluates @var{exp}, a G-expression,
upon booting.  All the derivations referenced by @var{exp} are
automatically copied to the initrd.

@var{modules} is a list of Guile module names to be embedded in the
initrd.
@end deffn

@node GRUB Configuration
@subsection GRUB Configuration

@cindex GRUB
@cindex boot loader

The operating system uses GNU@tie{}GRUB as its boot loader
(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}).  It is
configured using @code{grub-configuration} declarations.  This data type
is exported by the @code{(gnu system grub)} module, and described below.

@deftp {Data Type} grub-configuration
The type of a GRUB configuration declaration.

@table @asis

@item @code{device}
This is a string denoting the boot device.  It must be a device name
understood by the @command{grub-install} command, such as
@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
GNU GRUB Manual}).

@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
entries to appear in the GRUB boot menu, in addition to the current
system entry and the entry pointing to previous system generations.

@item @code{default-entry} (default: @code{0})
The index of the default boot menu entry.  Index 0 is for the current
system's entry.

@item @code{timeout} (default: @code{5})
The number of seconds to wait for keyboard input before booting.  Set to
0 to boot immediately, and to -1 to wait indefinitely.

@item @code{theme} (default: @var{%default-theme})
The @code{grub-theme} object describing the theme to use.
@end table

@end deftp

Should you want to list additional boot menu entries @i{via} the
@code{menu-entries} field above, you will need to create them with the
@code{menu-entry} form:

@deftp {Data Type} menu-entry
The type of an entry in the GRUB boot menu.

@table @asis

@item @code{label}
The label to show in the menu---e.g., @code{"GNU"}.

@item @code{linux}
The Linux kernel to boot.

@item @code{linux-arguments} (default: @code{()})
The list of extra Linux kernel command-line arguments---e.g.,
@code{("console=ttyS0")}.

@item @code{initrd}
A G-Expression or string denoting the file name of the initial RAM disk
to use (@pxref{G-Expressions}).

@end table
@end deftp

@c FIXME: Write documentation once it's stable.
Themes are created using the @code{grub-theme} form, which is not
documented yet.

@defvr {Scheme Variable} %default-theme
This is the default GRUB theme used by the operating system, with a
fancy background image displaying the GNU and Guix logos.
@end defvr


@node Invoking guix system
@subsection Invoking @code{guix system}

Once you have written an operating system declaration, as seen in the
previous section, it can be @dfn{instantiated} using the @command{guix
system} command.  The synopsis is:

@example
guix system @var{options}@dots{} @var{action} @var{file}
@end example

@var{file} must be the name of a file containing an
@code{operating-system} declaration.  @var{action} specifies how the
operating system is instantiate.  Currently the following values are
supported:

@table @code
@item reconfigure
Build the operating system described in @var{file}, activate it, and
switch to it@footnote{This action is usable only on systems already
running GNU.}.

This effects all the configuration specified in @var{file}: user
accounts, system services, global package list, setuid programs, etc.

It also adds a GRUB menu entry for the new OS configuration, and moves
entries for older configurations to a submenu---unless
@option{--no-grub} is passed.

@c The paragraph below refers to the problem discussed at
@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
It is highly recommended to run @command{guix pull} once before you run
@command{guix system reconfigure} for the first time (@pxref{Invoking
guix pull}).  Failing to do that you would see an older version of Guix
once @command{reconfigure} has completed.

@item build
Build the operating system's derivation, which includes all the
configuration files and programs needed to boot and run the system.
This action does not actually install anything.

@item init
Populate the given directory with all the files necessary to run the
operating system specified in @var{file}.  This is useful for first-time
installations of GSD.  For instance:

@example
guix system init my-os-config.scm /mnt
@end example

copies to @file{/mnt} all the store items required by the configuration
specified in @file{my-os-config.scm}.  This includes configuration
files, packages, and so on.  It also creates other essential files
needed for the system to operate correctly---e.g., the @file{/etc},
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.

This command also installs GRUB on the device specified in
@file{my-os-config}, unless the @option{--no-grub} option was passed.

@item vm
@cindex virtual machine
@cindex VM
Build a virtual machine that contain the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
Arguments given to the script are passed as is to QEMU.

The VM shares its store with the host system.

Additional file systems can be shared between the host and the VM using
the @code{--share} and @code{--expose} command-line options: the former
specifies a directory to be shared with write access, while the latter
provides read-only access to the shared directory.

The example below creates a VM in which the user's home directory is
accessible read-only, and where the @file{/exchange} directory is a
read-write mapping of the host's @file{$HOME/tmp}:

@example
guix system vm my-config.scm \
   --expose=$HOME --share=$HOME/tmp=/exchange
@end example

On GNU/Linux, the default is to boot directly to the kernel; this has
the advantage of requiring only a very tiny root disk image since the
host's store can then be mounted.

The @code{--full-boot} option forces a complete boot sequence, starting
with the bootloader.  This requires more disk space since a root image
containing at least the kernel, initrd, and bootloader data files must
be created.  The @code{--image-size} option can be used to specify the
image's size.

@item vm-image
@itemx disk-image
Return a virtual machine or disk image of the operating system declared
in @var{file} that stands alone.  Use the @option{--image-size} option
to specify the size of the image.

When using @code{vm-image}, the returned image is in qcow2 format, which
the QEMU emulator can efficiently use.

When using @code{disk-image}, a raw disk image is produced; it can be
copied as is to a USB stick, for instance.  Assuming @code{/dev/sdc} is
the device corresponding to a USB stick, one can copy the image on it
using the following command:

@example
# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
@end example

@end table

@var{options} can contain any of the common build options provided by
@command{guix build} (@pxref{Invoking guix build}).  In addition,
@var{options} can contain one of the following:

@table @option
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system} instead of the host's system type.
This works as per @command{guix build} (@pxref{Invoking guix build}).

@item --image-size=@var{size}
For the @code{vm-image} and @code{disk-image} actions, create an image
of the given @var{size}.  @var{size} may be a number of bytes, or it may
include a unit as a suffix (@pxref{Block size, size specifications,,
coreutils, GNU Coreutils}).
@end table

Note that all the actions above, except @code{build} and @code{init},
rely on KVM support in the Linux-Libre kernel.  Specifically, the
machine should have hardware virtualization support, the corresponding
KVM kernel module should be loaded, and the @file{/dev/kvm} device node
must exist and be readable and writable by the user and by the daemon's
build users.

@node Defining Services
@subsection Defining Services

The @code{(gnu services @dots{})} modules define several procedures that allow
users to declare the operating system's services (@pxref{Using the
Configuration System}).  These procedures are @emph{monadic
procedures}---i.e., procedures that return a monadic value in the store
monad (@pxref{The Store Monad}).  For examples of such procedures,
@xref{Services}.

@cindex service definition
The monadic value returned by those procedures is a @dfn{service
definition}---a structure as returned by the @code{service} form.
Service definitions specifies the inputs the service depends on, and an
expression to start and stop the service.  Behind the scenes, service
definitions are ``translated'' into the form suitable for the
configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
dmd Manual}).

As an example, here is what the @code{nscd-service} procedure looks
like:

@lisp
(define (nscd-service)
  (with-monad %store-monad
    (return (service
             (documentation "Run libc's name service cache daemon.")
             (provision '(nscd))
             (activate #~(begin
                           (use-modules (guix build utils))
                           (mkdir-p "/var/run/nscd")))
             (start #~(make-forkexec-constructor
                       (string-append #$glibc "/sbin/nscd")
                       "-f" "/dev/null" "--foreground"))
             (stop #~(make-kill-destructor))
             (respawn? #f)))))
@end lisp

@noindent
The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
(@pxref{G-Expressions}).  The @code{activate} field contains a script to
run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
directory exists before @command{nscd} is started.

The @code{start} and @code{stop} fields refer to dmd's facilities to
start and stop processes (@pxref{Service De- and Constructors,,, dmd,
GNU dmd Manual}).  The @code{provision} field specifies the name under
which this service is known to dmd, and @code{documentation} specifies
on-line documentation.  Thus, the commands @command{deco start ncsd},
@command{deco stop nscd}, and @command{deco doc nscd} will do what you
would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).


@node Installing Debugging Files
@section 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 package -i 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 those packages
whose definition explicitly declares a @code{debug} output.  This may be
changed to opt-out in the future, if our build farm servers can handle
the load.  To check whether a package has a @code{debug} output, use
@command{guix package --list-available} (@pxref{Invoking guix package}).


@node Security Updates
@section Security Updates

@quotation Note
As of version @value{VERSION}, the feature described in this section is
experimental.
@end quotation

@cindex security updates
Occasionally, important security vulnerabilities are discovered in core
software packages and must be patched.  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 that, 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 @var{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:

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

From there on, any package depending directly or indirectly on Bash that
is installed will automatically be ``rewritten'' to refer to
@var{bash-fixed} instead of @var{bash}.  This grafting process takes
time proportional to the size of the package, but expect less than a
minute for an ``average'' package on a recent machine.

Currently, the graft and the package it replaces (@var{bash-fixed} and
@var{bash} in the example above) must have the exact same @code{name}
and @code{version} fields.  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.


@node Package Modules
@section Package Modules

From a programming viewpoint, the package definitions of the
GNU distribution are provided by Guile modules in the @code{(gnu packages
@dots{})} name space@footnote{Note that packages under the @code{(gnu
packages @dots{})} module name space are not necessarily ``GNU
packages''.  This module naming scheme follows the usual Guile module
naming convention: @code{gnu} means that these modules are distributed
as part of the GNU system, and @code{packages} identifies modules that
define packages.}  (@pxref{Modules, Guile modules,, guile, GNU Guile
Reference Manual}).  For instance, the @code{(gnu packages emacs)}
module exports a variable named @code{emacs}, which is bound to a
@code{<package>} object (@pxref{Defining Packages}).

The @code{(gnu packages @dots{})} module name space is
automatically scanned for packages by the command-line tools.  For
instance, when running @code{guix package -i emacs}, all the @code{(gnu
packages @dots{})} modules are scanned until one that exports a package
object whose name is @code{emacs} is found.  This package search
facility is implemented in the @code{(gnu packages)} module.

@cindex customization, of packages
@cindex package module search path
Users can store package definitions in modules with different
names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
name and module name must match.  @xref{Modules and the File System,,,
guile, GNU Guile Reference Manual}, for details.}  These package definitions
will not be visible by default.  Thus, users can invoke commands such as
@command{guix package} and @command{guix build} have to be used with the
@code{-e} option so that they know where to find the package, or use the
@code{-L} option of these commands to make those modules visible
(@pxref{Invoking guix build, @code{--load-path}}), or define the
@code{GUIX_PACKAGE_PATH} environment variable.  This environment
variable makes it easy to extend or customize the distribution and is
honored by all the user interfaces.

@defvr {Environment Variable} GUIX_PACKAGE_PATH
This is a colon-separated list of directories to search for package
modules.  Directories listed in this variable take precedence over the
distribution's own modules.
@end defvr

The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
each package is built based solely on other packages in the
distribution.  The root of this dependency graph is a small set of
@dfn{bootstrap binaries}, provided by the @code{(gnu packages
bootstrap)} module.  For more information on bootstrapping,
@pxref{Bootstrapping}.

@node Packaging Guidelines
@section Packaging Guidelines

The GNU distribution is nascent and may well lack some of your favorite
packages.  This section describes how you can help make the distribution
grow.  @xref{Contributing}, for additional information on how you can
help.

Free software packages are usually distributed in the form of
@dfn{source code tarballs}---typically @file{tar.gz} files that contain
all the source files.  Adding a package to the distribution means
essentially two things: adding a @dfn{recipe} that describes how to
build the package, including a list of other packages required to build
it, and adding @dfn{package meta-data} along with that recipe, such as a
description and licensing information.

In Guix all this information is embodied in @dfn{package definitions}.
Package definitions provide a high-level view of the package.  They are
written using the syntax of the Scheme programming language; in fact,
for each package we define a variable bound to the package definition,
and export that variable from a module (@pxref{Package Modules}).
However, in-depth Scheme knowledge is @emph{not} a prerequisite for
creating packages.  For more information on package definitions,
@pxref{Defining Packages}.

Once a package definition is in place, stored in a file in the Guix
source tree, it can be tested using the @command{guix build} command
(@pxref{Invoking guix build}).  For example, assuming the new package is
called @code{gnew}, you may run this command from the Guix build tree:

@example
./pre-inst-env guix build gnew --keep-failed
@end example

Using @code{--keep-failed} makes it easier to debug build failures since
it provides access to the failed build tree.  Another useful
command-line option when debugging is @code{--log-file}, to access the
build log.

If the package is unknown to the @command{guix} command, it may be that
the source file contains a syntax error, or lacks a @code{define-public}
clause to export the package variable.  To figure it out, you may load
the module from Guile to get more information about the actual error:

@example
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
@end example

Once your package builds correctly, please send us a patch
(@pxref{Contributing}).  Well, if you need help, we will be happy to
help you too.  Once the patch is committed in the Guix repository, the
new package automatically gets built on the supported platforms by
@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
system}.

@cindex substituter
Users can obtain the new package definition simply by running
@command{guix pull} (@pxref{Invoking guix pull}).  When
@code{hydra.gnu.org} is done building the package, installing the
package automatically downloads binaries from there
(@pxref{Substitutes}).  The only place where human intervention is
needed is to review and apply the patch.


@menu
* Software Freedom::            What may go into the distribution.
* Package Naming::              What's in a name?
* Version Numbers::             When the name is not enough.
* Python Modules::              Taming the snake.
* Perl Modules::                Little pearls.
* Fonts::                       Fond of fonts.
@end menu

@node Software Freedom
@subsection Software Freedom

@c Adapted from http://www.gnu.org/philosophy/philosophy.html.

The GNU operating system has been developed so that users can have
freedom in their computing.  GNU is @dfn{free software}, meaning that
users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
essential freedoms}: to run the program, to study and change the program
in source code form, to redistribute exact copies, and to distribute
modified versions.  Packages found in the GNU distribution provide only
software that conveys these four freedoms.

In addition, the GNU distribution follow the
@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
software distribution guidelines}.  Among other things, these guidelines
reject non-free firmware, recommendations of non-free software, and
discuss ways to deal with trademarks and patents.

Some packages contain a small and optional subset that violates the
above guidelines, for instance because this subset is itself non-free
code.  When that happens, the offending items are removed with
appropriate patches or code snippets in the package definition's
@code{origin} form (@pxref{Defining Packages}).  That way, @code{guix
build --source} returns the ``freed'' source rather than the unmodified
upstream source.


@node Package Naming
@subsection Package Naming

A package has actually two names associated with it:
First, there is the name of the @emph{Scheme variable}, the one following
@code{define-public}.  By this name, the package can be made known in the
Scheme code, for instance as input to another package.  Second, there is
the string in the @code{name} field of a package definition.  This name
is used by package management commands such as
@command{guix package} and @command{guix build}.

Both are usually the same and correspond to the lowercase conversion of
the project name chosen upstream, with underscores replaced with
hyphens.  For instance, GNUnet is available as @code{gnunet}, and
SDL_net as @code{sdl-net}.

We do not add @code{lib} prefixes for library packages, unless these are
already part of the official project name.  But @pxref{Python
Modules} and @ref{Perl Modules} for special rules concerning modules for
the Python and Perl languages.

Font package names are handled differently, @pxref{Fonts}.


@node Version Numbers
@subsection Version Numbers

We usually package only the latest version of a given free software
project.  But sometimes, for instance for incompatible library versions,
two (or more) versions of the same package are needed.  These require
different Scheme variable names.  We use the name as defined
in @ref{Package Naming}
for the most recent version; previous versions use the same name, suffixed
by @code{-} and the smallest prefix of the version number that may
distinguish the two versions.

The name inside the package definition is the same for all versions of a
package and does not contain any version number.

For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:

@example
(define-public gtk+
  (package
   (name "gtk+")
   (version "3.9.12")
   ...))
(define-public gtk+-2
  (package
   (name "gtk+")
   (version "2.24.20")
   ...))
@end example
If we also wanted GTK+ 3.8.2, this would be packaged as
@example
(define-public gtk+-3.8
  (package