guix.texi

list of available packages can be browsed
@url{http://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):

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

Our goal is to provide 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.

Packages are 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 armhf-linux
ARMv7-A architecture with hard float, Thumb-2 and NEON,
using the EABI hard-float application binary interface (ABI),
and Linux-Libre kernel.

@item aarch64-linux
little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.  This is
currently in an experimental stage, with limited support.
@xref{Contributing}, for how to help!

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

@end table

GuixSD itself is currently only available on @code{i686} and @code{x86_64}.

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

@menu
* System Installation::         Installing the whole operating system.
* System Configuration::        Configuring the operating system.
* Documentation::                Browsing software user manuals.
* Installing Debugging Files::  Feeding the debugger.
* Security Updates::            Deploying security fixes quickly.
* 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!  @xref{Contributing}, for information about how you can help.

@node System Installation
@section System Installation

@cindex installing GuixSD
@cindex Guix System Distribution
This section explains how to install the Guix System Distribution (GuixSD)
on a machine.  The Guix package manager can
also be installed on top of a running GNU/Linux system,
@pxref{Installation}.

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

Alternately, run @command{info info} in another tty to keep the manual
available.
@end quotation
@end ifinfo

@menu
* Limitations::                 What you can expect.
* Hardware Considerations::     Supported hardware.
* USB Stick Installation::      Preparing the installation medium.
* Preparing for Installation::  Networking, partitioning, etc.
* Proceeding with the Installation::  The real thing.
* Installing GuixSD in a VM::   GuixSD playground.
* Building the Installation Image::  How this comes to be.
@end menu

@node Limitations
@subsection Limitations

As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
not production-ready.  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
the more established GNU/Linux distributions}.  We hope you can soon switch
to the GuixSD 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
Support for the Logical Volume Manager (LVM) is missing.

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

@item
More than 5,000 packages are available, but you may
occasionally find that a useful package is missing.

@item
GNOME, Xfce, and Enlightenment are available (@pxref{Desktop Services}),
as well as a number of X11 window managers.  However, some graphical
applications may be missing, as well as KDE.
@end itemize

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


@node Hardware Considerations
@subsection Hardware Considerations

@cindex hardware support on GuixSD
GNU@tie{}GuixSD focuses on respecting the user's computing freedom.  It
builds around the kernel Linux-libre, which means that only hardware for
which free software drivers and firmware exist is supported.  Nowadays,
a wide range of off-the-shelf hardware is supported on
GNU/Linux-libre---from keyboards to graphics cards to scanners and
Ethernet controllers.  Unfortunately, there are still areas where
hardware vendors deny users control over their own computing, and such
hardware is not supported on GuixSD.

@cindex WiFi, hardware support
One of the main areas where free drivers or firmware are lacking is WiFi
devices.  WiFi devices known to work include those using Atheros chips
(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
driver, and those using Broadcom/AirForce chips (BCM43xx with
Wireless-Core Revision 5), which corresponds to the @code{b43-open}
Linux-libre driver.  Free firmware exists for both and is available
out-of-the-box on GuixSD, as part of @var{%base-firmware}
(@pxref{operating-system Reference, @code{firmware}}).

@cindex RYF, Respects Your Freedom
The @uref{https://www.fsf.org/, Free Software Foundation} runs
@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
certification program for hardware products that respect your freedom
and your privacy and ensure that you have control over your device.  We
encourage you to check the list of RYF-certified devices.

Another useful resource is the @uref{https://www.h-node.org/, H-Node}
web site.  It contains a catalog of hardware devices with information
about their support in GNU/Linux.


@node USB Stick Installation
@subsection USB Stick Installation

An installation image for USB sticks can be downloaded from
@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-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

@c start duplication of authentication part from ``Binary Installation''
Make sure to download the associated @file{.sig} file and to verify the
authenticity of the image against it, along these lines:

@example
$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
$ gpg --verify guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
@end example

If that command fails because you do not have the required public key,
then run this command to import it:

@example
$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example

@noindent
and rerun the @code{gpg --verify} command.
@c end duplication

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 guixsd-usb-install-@value{VERSION}.@var{system}.xz
@end example

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

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

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

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

@xref{Installing GuixSD in a VM}, if, instead, you would like to install
GuixSD in a virtual machine (VM).

@node Preparing for Installation
@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{Top,,, info-stnd,
Stand-alone GNU Info}).  The installation system runs the GPM mouse
daemon, which allows you to select text with the left mouse button and
to paste it with the middle button.

@quotation Note
Installation requires access to the Internet so that any missing
dependencies of your system configuration can be downloaded.  See the
``Networking'' section below.
@end quotation

The installation system includes many common tools needed for this task.
But it is also a full-blown GuixSD system, which means that you can
install additional packages, should you need it, using @command{guix
package} (@pxref{Invoking guix package}).

@subsubsection Keyboard Layout

@cindex keyboard layout
The installation image uses the US qwerty keyboard layout.  If you want
to change it, you can use the @command{loadkeys} command.  For example,
the following command selects the Dvorak keyboard layout:

@example
loadkeys dvorak
@end example

See the files under @file{/run/current-system/profile/share/keymaps} for
a list of available keyboard layouts.  Run @command{man loadkeys} for
more information.

@subsubsection Networking

Run the following command see what your network interfaces are called:

@example
ifconfig -a
@end example

@noindent
@dots{} or, using the GNU/Linux-specific @command{ip} command:

@example
ip a
@end example

@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
Wired interfaces have a name starting with @samp{e}; for example, the
interface corresponding to the first on-board Ethernet controller is
called @samp{eno1}.  Wireless interfaces have a name starting with
@samp{w}, like @samp{w1p2s0}.

@table @asis
@item Wired connection
To configure a wired network run the following command, substituting
@var{interface} with the name of the wired interface you want to use.

@example
ifconfig @var{interface} up
@end example

@item Wireless connection
@cindex wireless
@cindex WiFi
To configure wireless networking, you can create a configuration file
for the @command{wpa_supplicant} configuration tool (its location is not
important) using one of the available text editors such as
@command{zile}:

@example
zile wpa_supplicant.conf
@end example

As an example, the following stanza can go to this file and will work
for many wireless networks, provided you give the actual SSID and
passphrase for the network you are connecting to:

@example
network=@{
  ssid="@var{my-ssid}"
  key_mgmt=WPA-PSK
  psk="the network's secret passphrase"
@}
@end example

Start the wireless service and run it in the background with the
following command (substitute @var{interface} with the name of the
network interface you want to use):

@example
wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
@end example

Run @command{man wpa_supplicant} for more information.
@end table

@cindex DHCP
At this point, you need to acquire an IP address.  On a network where IP
addresses are automatically assigned @i{via} DHCP, you can run:

@example
dhclient -v @var{interface}
@end example

Try to ping a server to see if networking is up and running:

@example
ping -c 3 gnu.org
@end example

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

@subsubsection Disk Partitioning

Unless this has already been done, the next step is to partition, and
then format the target partition(s).

The installation image includes several partitioning tools, including
Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
@command{fdisk}, and @command{cfdisk}.  Run it and set up your disk with
the partition layout you want:

@example
cfdisk
@end example

If your disk uses the GUID Partition Table (GPT) format and you plan to
install BIOS-based GRUB (which is the default), make sure a BIOS Boot
Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
manual}).

Once you are done partitioning the target hard disk drive, you have to
create a file system on the relevant partition(s)@footnote{Currently
GuixSD only supports ext4 and btrfs file systems.  In particular, code
that reads partition UUIDs and labels only works for these file system
types.}.

Preferably, assign partitions a label so that you can easily and
reliably refer to them in @code{file-system} declarations (@pxref{File
Systems}).  This is typically done using the @code{-L} option of
@command{mkfs.ext4} and related commands.  So, assuming the target root
partition lives at @file{/dev/sda1}, a file system with the label
@code{my-root} can be created with:

@example
mkfs.ext4 -L my-root /dev/sda1
@end example

@cindex encrypted disk
If you are instead planning to encrypt the root partition, you can use
the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
@code{man cryptsetup}} for more information.)  Assuming you want to
store the root partition on @file{/dev/sda1}, the command sequence would
be along these lines:

@example
cryptsetup luksFormat /dev/sda1
cryptsetup open --type luks /dev/sda1 my-partition
mkfs.ext4 -L my-root /dev/mapper/my-partition
@end example

Once that is done, mount the target root partition under @file{/mnt}
with a command like (again, assuming @code{my-root} is the label of the
root partition):

@example
mount LABEL=my-root /mnt
@end example

Finally, if you plan to use one or more swap partitions (@pxref{Memory
Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
sure to initialize them with @command{mkswap}.  Assuming you have one
swap partition on @file{/dev/sda2}, you would run:

@example
mkswap /dev/sda2
swapon /dev/sda2
@end example

Alternatively, you may use a swap file.  For example, assuming that in
the new system you want to use the file @file{/swapfile} as a swap file,
you would run@footnote{This example will work for many types of file
systems (e.g., ext4).  However, for copy-on-write file systems (e.g.,
btrfs), the required steps may be different.  For details, see the
manual pages for @command{mkswap} and @command{swapon}.}:

@example
# This is 10 GiB of swap space.  Adjust "count" to change the size.
dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
# For security, make the file readable and writable only by root.
chmod 600 /mnt/swapfile
mkswap /mnt/swapfile
swapon /mnt/swapfile
@end example

Note that if you have encrypted the root partition and created a swap
file in its file system as described above, then the encryption also
protects the swap file, just like any other file in that file system.

@node Proceeding with the Installation
@subsection Proceeding with the Installation

With the target partitions ready and the target root mounted on
@file{/mnt}, we're ready to go.  First, run:

@example
herd start cow-store /mnt
@end example

This makes @file{/gnu/store} copy-on-write, such that packages added to it
during the installation phase are written to the target disk on @file{/mnt}
rather than kept in memory.  This is necessary because the first phase of
the @command{guix system init} command (see below) entails downloads or
builds to @file{/gnu/store} which, initially, is an in-memory file system.

Next, you have to edit a file and
provide the declaration of the operating system to be installed.  To
that end, the installation system comes with three text editors: GNU nano
(@pxref{Top,,, nano, GNU nano Manual}), GNU Zile (an Emacs clone), and
nvi (a clone of the original BSD @command{vi} editor).
We strongly recommend storing that file on the target root file system, say,
as @file{/mnt/etc/config.scm}.  Failing to do that, you will have lost your
configuration file once you have rebooted into the newly-installed system.

@xref{Using the Configuration System}, for an overview of the
configuration file.  The example configurations discussed in that
section are available under @file{/etc/configuration} in the
installation image.  Thus, to get started with a system configuration
providing a graphical display server (a ``desktop'' system), you can run
something along these lines:

@example
# mkdir /mnt/etc
# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
# zile /mnt/etc/config.scm
@end example

You should pay attention to what your configuration file contains, and
in particular:

@itemize
@item
Make sure the @code{grub-configuration} form refers to the device you
want to install GRUB on.

@item
Be sure that your partition labels match the value of their respective
@code{device} fields in your @code{file-system} configuration, assuming
your @code{file-system} configuration sets the value of @code{title} to
@code{'label}.

@item
If there are encrypted or RAID partitions, make sure to add a
@code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
@end itemize

Once you are done preparing the configuration file, 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 copies all the necessary files and installs GRUB on
@file{/dev/sdX}, unless you pass the @option{--no-bootloader} option.  For
more information, @pxref{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 run
@command{reboot} and boot into the new system.  The @code{root} password
in the new system is initially empty; other users' passwords need to be
initialized by running the @command{passwd} command as @code{root},
unless your configuration specifies otherwise
(@pxref{user-account-password, user account passwords}).

@cindex upgrading GuixSD
From then on, you can update GuixSD whenever you want by running
@command{guix pull} as @code{root} (@pxref{Invoking guix pull}), and
then running @command{guix system reconfigure} to build a new system
generation with the latest packages and services (@pxref{Invoking guix
system}).  We recommend doing that regularly so that your system
includes the latest security updates (@pxref{Security Updates}).

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.

@node Installing GuixSD in a VM
@subsection Installing GuixSD in a Virtual Machine

@cindex virtual machine, GuixSD installation
If you'd like to install GuixSD in a virtual machine (VM) rather than on
your beloved machine, this section is for you.

To boot a @uref{http://qemu.org/,QEMU} VM for installing GuixSD in a
disk image, follow these steps:

@enumerate
@item
First, retrieve and decompress the GuixSD installation image as
described previously (@pxref{USB Stick Installation}).

@item
Create a disk image that will hold the installed system.  To make a
qcow2-formatted disk image, use the @command{qemu-img} command:

@example
qemu-img create -f qcow2 guixsd.img 5G
@end example

This will create a 5GB file.

@item
Boot the USB installation image in an VM:

@example
qemu-system-x86_64 -m 1024 -smp 1 \
  -net user -net nic,model=virtio -boot menu=on \
  -drive file=guixsd.img \
  -drive file=guixsd-usb-install-@value{VERSION}.@var{system}
@end example

In the VM console, quickly press the @kbd{F12} key to enter the boot
menu.  Then press the @kbd{2} key and the @kbd{RET} key to validate your
selection.

@item
You're now root in the VM, proceed with the installation process.
@xref{Preparing for Installation}, and follow the instructions.
@end enumerate

Once installation is complete, you can boot the system that's on your
@file{guixsd.img} image.  @xref{Running GuixSD in a VM}, for how to do
that.

@node Building the Installation Image
@subsection Building the Installation Image

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

@c FIXME: 1G is too much; see <http://bugs.gnu.org/23077>.
@example
guix system disk-image --image-size=1G gnu/system/install.scm
@end example

Have a look at @file{gnu/system/install.scm} in the source tree,
and see also @ref{Invoking guix system} for more information
about the installation image.

@node System Configuration
@section System Configuration

@cindex system configuration
The Guix System Distribution 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
advantage 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 own tools of the system.
@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.
* operating-system Reference::  Detail of operating-system declarations.
* File Systems::                Configuring file system mounts.
* Mapped Devices::              Block device extra processing.
* User Accounts::               Specifying user accounts.
* Locales::                     Language and cultural convention settings.
* Services::                    Specifying system services.
* Setuid Programs::             Programs running with root privileges.
* X.509 Certificates::          Authenticating HTTPS servers.
* Name Service Switch::         Configuring libc's name service switch.
* Initial RAM Disk::            Linux-Libre bootstrapping.
* GRUB Configuration::          Configuring the boot loader.
* Invoking guix system::        Instantiating a system configuration.
* Running GuixSD in a VM::      How to run GuixSD in a virtual machine.
* 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
@include os-config-bare-bones.texi
@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.

Below we discuss the effect of some of the most important fields
(@pxref{operating-system Reference}, for details about all the available
fields), and how to @dfn{instantiate} the operating system using
@command{guix system}.

@unnumberedsubsubsec Globally-Visible Packages

@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 tcpdump to those, taken from the @code{(gnu
packages admin)} module (@pxref{Package Modules}).

@findex specification->package
Referring to packages by variable name, like @var{tcpdump} above, has
the advantage of being unambiguous; it also allows typos and such to be
diagnosed right away as ``unbound variables''.  The downside is that one
needs to know which module defines which package, and to augment the
@code{use-package-modules} line accordingly.  To avoid that, one can use
the @code{specification->package} procedure of the @code{(gnu packages)}
module, which returns the best package for a given name or name and
version:

@lisp
(use-modules (gnu packages))

(operating-system
  ;; ...
  (packages (append (map specification->package
                         '("tcpdump" "htop" "gnupg@@2.0"))
                    %base-packages)))
@end lisp

@unnumberedsubsubsec System Services

@cindex services
@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 (@pxref{Networking Services,
@code{lsh-service}}).  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}).

@cindex customization, of services
@findex modify-services
Occasionally, instead of using the base services as is, you will want to
customize them.  To do this, use @code{modify-services} (@pxref{Service
Reference, @code{modify-services}}) to modify the list.

For example, suppose you want to modify @code{guix-daemon} and Mingetty
(the console log-in) in the @var{%base-services} list (@pxref{Base
Services, @code{%base-services}}).  To do that, you can write the
following in your operating system declaration:

@lisp
(define %my-services
  ;; My very own list of services.
  (modify-services %base-services
    (guix-service-type config =>
                       (guix-configuration
                        (inherit config)
                        (use-substitutes? #f)
                        (extra-options '("--gc-keep-derivations"))))
    (mingetty-service-type config =>
                           (mingetty-configuration
                            (inherit config)))))

(operating-system
  ;; @dots{}
  (services %my-services))
@end lisp

This changes the configuration---i.e., the service parameters---of the
@code{guix-service-type} instance, and that of all the
@code{mingetty-service-type} instances in the @var{%base-services} list.
Observe how this is accomplished: first, we arrange for the original
configuration to be bound to the identifier @code{config} in the
@var{body}, and then we write the @var{body} so that it evaluates to the
desired configuration.  In particular, notice how we use @code{inherit}
to create a new configuration which has the same values as the old
configuration, but with a few modifications.

@cindex encrypted disk
The configuration for a typical ``desktop'' usage, with an encrypted
root partition, the X11 display
server, GNOME and Xfce (users can choose which of these desktop
environments to use at the log-in screen by pressing @kbd{F1}), network
management, power management, and more, would look like this:

@lisp
@include os-config-desktop.texi
@end lisp

A graphical environment with a choice of lightweight window managers
instead of full-blown desktop environments would look like this:

@lisp
@include os-config-lightweight-desktop.texi
@end lisp

@xref{Desktop Services}, for the exact list of services provided by
@var{%desktop-services}.  @xref{X.509 Certificates}, for background
information about the @code{nss-certs} package that is used here.

Again, @var{%desktop-services} is just a list of service objects.  If
you want to remove services from there, you can do so using the
procedures for list filtering (@pxref{SRFI-1 Filtering and
Partitioning,,, guile, GNU Guile Reference Manual}).  For instance, the
following expression returns a list that contains all the services in
@var{%desktop-services} minus the Avahi service:

@example
(remove (lambda (service)
          (eq? (service-kind service) avahi-service-type))
        %desktop-services)
@end example

@unnumberedsubsubsec Instantiating the System

Assuming the @code{operating-system} declaration
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 configuration is by updating this
file and re-running @command{guix system reconfigure}.  One should never
have to touch files in @file{/etc} or to run commands that modify the
system state such as @command{useradd} or @command{grub-install}.  In
fact, you must avoid that since that would not only void your warranty
but also prevent you from rolling back to previous versions of your
system, should you ever need to.

@cindex roll-back, of the operating system
Speaking of roll-back, each time you run @command{guix system
reconfigure}, a new @dfn{generation} of the system is created---without
modifying or deleting previous generations.  Old system generations get
an entry in the GRUB boot menu, allowing you to boot them in case
something went wrong with the latest generation.  Reassuring, no?  The
@command{guix system list-generations} command lists the system
generations available on disk.  It is also possible to roll back the
system via the commands @command{guix system roll-back} and
@command{guix system switch-generation}.

Although the command @command{guix system reconfigure} will not modify
previous generations, must take care when the current generation is not
the latest (e.g., after invoking @command{guix system roll-back}), since
the operation might overwrite a later generation (@pxref{Invoking guix
system}).

@unnumberedsubsubsec The Programming Interface

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

This procedure is provided by the @code{(gnu system)} module.  Along
with @code{(gnu services)} (@pxref{Services}), this module contains the
guts of GuixSD.  Make sure to visit it!


@node operating-system Reference
@subsection @code{operating-system} Reference

This section summarizes all the options available in
@code{operating-system} declarations (@pxref{Using the Configuration
System}).

@deftp {Data Type} operating-system
This is the data type representing an operating system configuration.
By that, we mean all the global system configuration, not per-user
configuration (@pxref{Using the Configuration System}).

@table @asis
@item @code{kernel} (default: @var{linux-libre})
The package object of the operating system kernel to use@footnote{Currently
only the Linux-libre kernel is supported.  In the future, it will be
possible to use the GNU@tie{}Hurd.}.

@item @code{kernel-arguments} (default: @code{'()})
List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}.

@item @code{bootloader}
The system bootloader configuration object.  @xref{GRUB Configuration}.

@item @code{initrd} (default: @code{base-initrd})
@cindex initrd
@cindex initial RAM disk
A two-argument monadic procedure that returns an initial RAM disk for
the Linux kernel.  @xref{Initial RAM Disk}.

@item @code{firmware} (default: @var{%base-firmware})
@cindex firmware
List of firmware packages loadable by the operating system kernel.

The default includes firmware needed for Atheros- and Broadcom-based
WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
respectively).  @xref{Hardware Considerations}, for more info on
supported hardware.

@item @code{host-name}
The host name.

@item @code{hosts-file}
@cindex hosts file
A file-like object (@pxref{G-Expressions, file-like objects}) for use as
@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
Reference Manual}).  The default is a file with entries for
@code{localhost} and @var{host-name}.

@item @code{mapped-devices} (default: @code{'()})
A list of mapped devices.  @xref{Mapped Devices}.

@item @code{file-systems}
A list of file systems.  @xref{File Systems}.

@item @code{swap-devices} (default: @code{'()})
@cindex swap devices
A list of strings identifying devices or files to be used for ``swap
space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference
Manual}).  For example, @code{'("/dev/sda3")} or @code{'("/swapfile")}.
It is possible to specify a swap file in a file system on a mapped
device, provided that the necessary device mapping and file system are
also specified.  @xref{Mapped Devices} and @ref{File Systems}.

@item @code{users} (default: @code{%base-user-accounts})
@itemx @code{groups} (default: @var{%base-groups})
List of user accounts and groups.  @xref{User Accounts}.

@item @code{skeletons} (default: @code{(default-skeletons)})
A list target file name/file-like object tuples (@pxref{G-Expressions,
file-like objects}).  These are the skeleton files that will be added to
the home directory of newly-created user accounts.

For instance, a valid value may look like this:

@example
`((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
  (".guile" ,(plain-file "guile"
                         "(use-modules (ice-9 readline))
                          (activate-readline)")))
@end example

@item @code{issue} (default: @var{%default-issue})
A string denoting the contents of the @file{/etc/issue} file, which is
displayed when users log in on a text console.

@item @code{packages} (default: @var{%base-packages})
The set of packages installed in the global profile, which is accessible
at @file{/run/current-system/profile}.

The default set includes core utilities and it is good practice to
install non-core utilities in user profiles (@pxref{Invoking guix
package}).

@item @code{timezone}
A timezone identifying string---e.g., @code{"Europe/Paris"}.

You can run the @command{tzselect} command to find out which timezone
string corresponds to your region.  Choosing an invalid timezone name
causes @command{guix system} to fail.

@item @code{locale} (default: @code{"en_US.utf8"})
The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
Library Reference Manual}).  @xref{Locales}, for more information.

@item @code{locale-definitions} (default: @var{%default-locale-definitions})
The list of locale definitions to be compiled and that may be used at
run time.  @xref{Locales}.

@item @code{locale-libcs} (default: @code{(list @var{glibc})})
The list of GNU@tie{}libc packages whose locale data and tools are used
to build the locale definitions.  @xref{Locales}, for compatibility
considerations that justify this option.

@item @code{name-service-switch} (default: @var{%default-nss})
Configuration of the libc name service switch (NSS)---a
@code{<name-service-switch>} object.  @xref{Name Service Switch}, for
details.

@item @code{services} (default: @var{%base-services})
A list of service objects denoting system services.  @xref{Services}.

@item @code{pam-services} (default: @code{(base-pam-services)})
@cindex PAM
@cindex pluggable authentication modules
Linux @dfn{pluggable authentication module} (PAM) services.
@c FIXME: Add xref to PAM services section.

@item @code{setuid-programs} (default: @var{%setuid-programs})
List of string-valued G-expressions denoting setuid programs.
@xref{Setuid Programs}.

@item @code{sudoers-file} (default: @var{%sudoers-specification})
@cindex sudoers file
The contents of the @file{/etc/sudoers} file as a file-like object
(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).

This file specifies which users can use the @command{sudo} command, what
they are allowed to do, and what privileges they may gain.  The default
is that only @code{root} and members of the @code{wheel} group may use
@code{sudo}.

@end table
@end deftp

@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 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")