guix.texi

available.
@end quotation
@end ifinfo

@menu
* Limitations::                 What you can expect.
* Hardware Considerations::     Supported hardware.
* USB Stick and DVD Installation::  Preparing the installation medium.
* Preparing for Installation::  Networking, partitioning, etc.
* Guided Graphical Installation::  Easy graphical installation.
* Manual Installation::         Manual installation for wizards.
* After System Installation::   When installation succeeded.
* Installing Guix in a VM::     Guix System playground.
* Building the Installation Image::  How this comes to be.
@end menu

@node Limitations
@section Limitations

We consider Guix System to be ready for a wide range of ``desktop'' and server
use cases.  The reliability guarantees it provides---transactional upgrades
and rollbacks, reproducibility---make it a solid foundation.

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

@itemize
@item
More and more system services are provided (@pxref{Services}), but some
may be missing.

@item
GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
as well as a number of X11 window managers.  However, KDE is currently
missing.
@end itemize

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
@section Hardware Considerations

@cindex hardware support on Guix System
GNU@tie{}Guix 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 Guix System.

@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 Guix System, as part of @code{%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 and DVD Installation
@section USB Stick and DVD Installation

An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz},
where you can replace @code{x86_64-linux} with 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 @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz.sig
$ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.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
$ wget @value{OPENPGP-SIGNING-KEY-URL} \
      -qO - | gpg --import -
@end example

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

Take note that a warning like ``This key is not certified with a trusted
signature!'' is normal.

@c end duplication

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

@unnumberedsubsec Copying to a 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 guix-system-install-@value{VERSION}.x86_64-linux.iso.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=guix-system-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX status=progress
sync
@end example

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

@unnumberedsubsec Burning on a DVD

To copy the image to a DVD, follow these steps:

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

@example
xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz
@end example

@item
Insert a blank DVD into your machine, and determine
its device name.  Assuming that the DVD drive is known as @file{/dev/srX},
copy the image with:

@example
growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.x86_64-linux.iso
@end example

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

@unnumberedsubsec Booting

Once this is done, you should be able to reboot the system and boot from
the USB stick or DVD@.  The latter usually requires you to get in the
BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
In order to boot from Libreboot, switch to the command mode by pressing
the @kbd{c} key and type @command{search_grub usb}.

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


@node Preparing for Installation
@section Preparing for Installation

Once you have booted, you can use the guided graphical installer, which makes
it easy to get started (@pxref{Guided Graphical Installation}).  Alternatively,
if you are already familiar with GNU/Linux and if you want more control than
what the graphical installer provides, you can choose the ``manual''
installation process (@pxref{Manual Installation}).

The graphical installer is available on TTY1.  You can obtain root shells on
TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc.  TTY2 shows
this documentation and you can reach it with @kbd{ctrl-alt-f2}.  Documentation
is 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

@node Guided Graphical Installation
@section Guided Graphical Installation

The graphical installer is a text-based user interface.  It will guide you,
with dialog boxes, through the steps needed to install GNU@tie{}Guix System.

The first dialog boxes allow you to set up the system as you use it during the
installation: you can choose the language, keyboard layout, and set up
networking, which will be used during the installation.  The image below shows
the networking dialog.

@image{images/installer-network,5in,, networking setup with the graphical installer}

Later steps allow you to partition your hard disk, as shown in the image
below, to choose whether or not to use encrypted file systems, to enter the
host name and root password, and to create an additional account, among other
things.

@image{images/installer-partitions,5in,, partitioning with the graphical installer}

Note that, at any time, the installer allows you to exit the current
installation step and resume at a previous step, as show in the image below.

@image{images/installer-resume,5in,, resuming the installation process}

Once you're done, the installer produces an operating system configuration and
displays it (@pxref{Using the Configuration System}).  At that point you can
hit ``OK'' and installation will proceed.  On success, you can reboot into the
new system and enjoy.  @xref{After System Installation}, for what's next!


@node Manual Installation
@section Manual Installation

This section describes how you would ``manually'' install GNU@tie{}Guix System
on your machine.  This option requires familiarity with GNU/Linux, with the
shell, and with common administration tools.  If you think this is not for
you, consider using the guided graphical installer (@pxref{Guided Graphical
Installation}).

The installation system provides root shells on TTYs 3 to 6; press
@kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them.  It includes
many common tools needed to install the system.  But it is also a full-blown
Guix System, which means that you can install additional packages, should you
need it, using @command{guix package} (@pxref{Invoking guix package}).

@menu
* Keyboard Layout and Networking and Partitioning:: Initial setup.
* Proceeding with the Installation::  Installing.
@end menu

@node Keyboard Layout and Networking and Partitioning
@subsection Keyboard Layout, Networking, and Partitioning

Before you can install the system, you may want to adjust the keyboard layout,
set up networking, and partition your target hard disk.  This section will
guide you through this.

@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 to 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 address
@end example

@c https://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

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

@example
ip link set @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{nano}:

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

@cindex proxy, during system installation
If you need HTTP and HTTPS access to go through a proxy, run the
following command:

@example
herd set-http-proxy guix-daemon @var{URL}
@end example

@noindent
where @var{URL} is the proxy URL, for example
@code{http://example.org:8118}.

@cindex installing over SSH
If you want to, you can continue the installation remotely by starting
an SSH server:

@example
herd start ssh-daemon
@end example

Make sure to either set a password with @command{passwd}, or configure
OpenSSH public key authentication before logging in.

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

@cindex EFI, installation
@cindex UEFI, installation
@cindex ESP, EFI system partition
If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
(ESP) is required.  This partition can be mounted at @file{/boot/efi} for
instance and must have the @code{esp} flag set.  E.g., for @command{parted}:

@example
parted /dev/sda set 1 esp on
@end example

@quotation Note
@vindex grub-bootloader
@vindex grub-efi-bootloader
Unsure whether to use EFI- or BIOS-based GRUB?  If the directory
@file{/sys/firmware/efi} exists in the installation image, then you should
probably perform an EFI installation, using @code{grub-efi-bootloader}.
Otherwise you should use the BIOS-based GRUB, known as
@code{grub-bootloader}.  @xref{Bootloader Configuration}, for more info on
bootloaders.
@end quotation

Once you are done partitioning the target hard disk drive, you have to
create a file system on the relevant partition(s)@footnote{Currently
Guix System only supports ext4, btrfs, JFS, and F2FS file systems.  In
particular, code that reads file system UUIDs and labels only works for these
file system types.}.  For the ESP, if you have one and assuming it is
@file{/dev/sda1}, run:

@example
mkfs.fat -F32 /dev/sda1
@end example

For the root file system, ext4 is the most widely used format.  Other
file systems, such as Btrfs, support compression, which is reported to
nicely complement file deduplication that the daemon performs
independently of the file system (@pxref{Invoking guix-daemon,
deduplication}).

Preferably, assign file systems 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/sda2}, a file system with the label
@code{my-root} can be created with:

@example
mkfs.ext4 -L my-root /dev/sda2
@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/sda2}, the command sequence would
be along these lines:

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

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

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

Also mount any other file systems you would like to use on the target
system relative to this path.  If you have opted for @file{/boot/efi} as an
EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is
found by @code{guix system init} afterwards.

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/sda3}, you would run:

@example
mkswap /dev/sda3
swapon /dev/sda3
@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.  We
recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
supports syntax highlighting and parentheses matching; other editors
include 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
# nano /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{bootloader-configuration} form refers to the target
you want to install GRUB on.  It should mention @code{grub-bootloader} if
you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
for newer UEFI systems.  For legacy systems, the @code{target} field
names a device, like @code{/dev/sda}; for UEFI systems it names a path
to a mounted EFI partition, like @code{/boot/efi}; do make sure the path is
currently mounted and a @code{file-system} entry is specified in your
configuration.

@item
Be sure that your file system labels match the value of their respective
@code{device} fields in your @code{file-system} configuration, assuming
your @code{file-system} configuration uses the @code{file-system-label}
procedure in its @code{device} field.

@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}).
@xref{After System Installation}, for what's next!


@node After System Installation
@section After System Installation

Success, you've now booted into Guix System!  From then on, you can update the
system whenever you want by running, say:

@example
guix pull
sudo guix system reconfigure /etc/config.scm
@end example

@noindent
This builds 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}).

@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
@quotation Note
@cindex sudo vs. @command{guix pull}
Note that @command{sudo guix} runs your user's @command{guix} command and
@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged.  To
explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.

The difference matters here, because @command{guix pull} updates
the @command{guix} command and package definitions only for the user it is run
as.  This means that if you choose to use @command{guix system reconfigure} in
root's login shell, you'll need to @command{guix pull} separately.
@end quotation

Now, @pxref{Getting Started}, and
join us on @code{#guix} on the Freenode IRC network or on
@email{guix-devel@@gnu.org} to share your experience!


@node Installing Guix in a VM
@section Installing Guix in a Virtual Machine

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

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

@enumerate
@item
First, retrieve and decompress the Guix system installation image as
described previously (@pxref{USB Stick and DVD 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 guix-system.img 50G
@end example

The resulting file will be much smaller than 50 GB (typically less than
1 MB), but it will grow as the virtualized storage device is filled up.

@item
Boot the USB installation image in an VM:

@example
qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
  -nic user,model=virtio-net-pci -boot menu=on,order=d \
  -drive file=guix-system.img \
  -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
@end example

@code{-enable-kvm} is optional, but significantly improves performance,
@pxref{Running Guix in a VM}.

@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{guix-system.img} image.  @xref{Running Guix in a VM}, for how to do
that.

@node Building the Installation Image
@section Building the Installation Image

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

@example
guix system image -t iso9660 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.

@section Building the Installation Image for ARM Boards

Many ARM boards require a specific variant of the
@uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.

If you build a disk image and the bootloader is not available otherwise
(on another boot drive etc), it's advisable to build an image that
includes the bootloader, specifically:

@example
guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
@end example

@code{A20-OLinuXino-Lime2} is the name of the board.  If you specify an invalid
board, a list of possible boards will be printed.

@c *********************************************************************
@node Getting Started
@chapter Getting Started

Presumably, you've reached this section because either you have
installed Guix on top of another distribution (@pxref{Installation}), or
you've installed the standalone Guix System (@pxref{System
Installation}).  It's time for you to get started using Guix and this
section aims to help you do that and give you a feel of what it's like.

Guix is about installing software, so probably the first thing you'll
want to do is to actually look for software.  Let's say you're looking
for a text editor, you can run:

@example
guix search text editor
@end example

This command shows you a number of matching @dfn{packages}, each time
showing the package's name, version, a description, and additional info.
Once you've found out the one you want to use, let's say Emacs (ah ha!),
you can go ahead and install it (run this command as a regular user,
@emph{no need for root privileges}!):

@example
guix install emacs
@end example

You've installed your first package, congrats!  In the process, you've
probably noticed that Guix downloaded pre-built binaries; or, if you
explicitly chose to @emph{not} use pre-built binaries, then probably
Guix is still building software (@pxref{Substitutes}, for more info).

Unless you're using Guix System, the @command{guix install} command must
have printed this hint:

@example
hint: Consider setting the necessary environment variables by running:

     GUIX_PROFILE="$HOME/.guix-profile"
     . "$GUIX_PROFILE/etc/profile"

Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.
@end example

Indeed, you must now tell your shell where @command{emacs} and other
programs installed with Guix are to be found.  Pasting the two lines
above will do just that: it will add
@code{$HOME/.guix-profile/bin}---which is where the installed package
is---to the @code{PATH} environment variable.  You can paste these two
lines in your shell so they take effect right away, but more importantly
you should add them to @file{~/.bash_profile} (or equivalent file if you
do not use Bash) so that environment variables are set next time you
spawn a shell.  You only need to do this once and other search paths
environment variables will be taken care of similarly---e.g., if you
eventually install @code{python} and Python libraries, @code{PYTHONPATH}
will be defined.

You can go on installing packages at your will.  To list installed
packages, run:

@example
guix package --list-installed
@end example

To remove a package, you would unsurprisingly run @command{guix remove}.
A distinguishing feature is the ability to @dfn{roll back} any operation
you made---installation, removal, upgrade---by simply typing:

@example
guix package --roll-back
@end example

This is because each operation is in fact a @dfn{transaction} that
creates a new @dfn{generation}.  These generations and the difference
between them can be displayed by running:

@example
guix package --list-generations
@end example

Now you know the basics of package management!

@quotation Going further
@xref{Package Management}, for more about package management.  You may
like @dfn{declarative} package management with @command{guix package
--manifest}, managing separate @dfn{profiles} with @option{--profile},
deleting old generations, collecting garbage, and other nifty features
that will come in handy as you become more familiar with Guix.  If you
are a developer, @pxref{Development} for additional tools.  And if
you're curious, @pxref{Features}, to peek under the hood.
@end quotation

Once you've installed a set of packages, you will want to periodically
@emph{upgrade} them to the latest and greatest version.  To do that, you
will first pull the latest revision of Guix and its package collection:

@example
guix pull
@end example

The end result is a new @command{guix} command, under
@file{~/.config/guix/current/bin}.  Unless you're on Guix System, the
first time you run @command{guix pull}, be sure to follow the hint that
the command prints and, similar to what we saw above, paste these two
lines in your terminal and @file{.bash_profile}:

@example
GUIX_PROFILE="$HOME/.config/guix/current"
. "$GUIX_PROFILE/etc/profile"
@end example

@noindent
You must also instruct your shell to point to this new @command{guix}:

@example
hash guix
@end example

At this point, you're running a brand new Guix.  You can thus go ahead
and actually upgrade all the packages you previously installed:

@example
guix upgrade
@end example

As you run this command, you will see that binaries are downloaded (or
perhaps some packages are built), and eventually you end up with the
upgraded packages.  Should one of these upgraded packages not be to your
liking, remember you can always roll back!

You can display the exact revision of Guix you're currently using by
running:

@example
guix describe
@end example

The information it displays is @emph{all it takes to reproduce the exact
same Guix}, be it at a different point in time or on a different
machine.

@quotation Going further
@xref{Invoking guix pull}, for more information.  @xref{Channels}, on
how to specify additional @dfn{channels} to pull packages from, how to
replicate Guix, and more.  You may also find @command{time-machine}
handy (@pxref{Invoking guix time-machine}).
@end quotation

If you installed Guix System, one of the first things you'll want to do
is to upgrade your system.  Once you've run @command{guix pull} to get
the latest Guix, you can upgrade the system like this:

@example
sudo guix system reconfigure /etc/config.scm
@end example

Upon completion, the system runs the latest versions of its software
packages.  When you eventually reboot, you'll notice a sub-menu in the
bootloader that reads ``Old system generations'': it's what allows you
to boot @emph{an older generation of your system}, should the latest
generation be ``broken'' or otherwise unsatisfying.  Just like for
packages, you can always @emph{roll back} to a previous generation
@emph{of the whole system}:

@example
sudo guix system roll-back
@end example

There are many things you'll probably want to tweak on your system:
adding new user accounts, adding new system services, fiddling with the
configuration of those services, etc.  The system configuration is
@emph{entirely} described in the @file{/etc/config.scm} file.
@xref{Using the Configuration System}, to learn how to change it.

Now you know enough to get started!

@quotation Resources
The rest of this manual provides a reference for all things Guix.  Here
are some additional resources you may find useful:

@itemize
@item
@xref{Top,,, guix-cookbook, The GNU Guix Cookbook}, for a list of
``how-to'' style of recipes for a variety of applications.

@item
The @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference
Card} lists in two pages most of the commands and options you'll ever
need.

@item
The web site contains @uref{https://guix.gnu.org/en/videos/,
instructional videos} covering topics such as everyday use of Guix, how
to get help, and how to become a contributor.

@item
@xref{Documentation}, to learn how to access documentation on your
computer.
@end itemize

We hope you will enjoy Guix as much as the community enjoys building it!
@end quotation

@c *********************************************************************
@node Package Management
@chapter Package Management

@cindex packages
The purpose of GNU Guix is to allow users to easily install, upgrade, and
remove software packages, without having to know about their build
procedures or dependencies.  Guix also goes beyond this obvious set of
features.

This chapter describes the main features of Guix, as well as the
package management tools it provides.  Along with the command-line
interface described below (@pxref{Invoking guix package, @code{guix
package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
emacs-guix, The Emacs-Guix Reference Manual}), after installing
@code{emacs-guix} package (run @kbd{M-x guix-help} command to start
with it):

@example
guix install emacs-guix
@end example

@menu
* Features::                    How Guix will make your life brighter.
* Invoking guix package::       Package installation, removal, etc.
* Substitutes::                 Downloading pre-built binaries.
* Packages with Multiple Outputs::  Single source package, multiple outputs.
* Invoking guix gc::            Running the garbage collector.
* Invoking guix pull::          Fetching the latest Guix and distribution.
* Invoking guix time-machine::  Running an older revision of Guix.
* Inferiors::                   Interacting with another revision of Guix.
* Invoking guix describe::      Display information about your Guix revision.
* Invoking guix archive::       Exporting and importing store files.
@end menu

@node Features
@section Features

Here we assume you've already made your first steps with Guix
(@pxref{Getting Started}) and would like to get an overview about what's
going on under the hood.

When using Guix, each package ends up in the @dfn{package store}, in its
own directory---something that resembles
@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.

Instead of referring to these directories, users have their own
@dfn{profile}, which points to the packages that they actually want to
use.  These profiles are stored within each user's home directory, at
@code{$HOME/.guix-profile}.

For example, @code{alice} installs GCC 4.7.2.  As a result,
@file{/home/alice/.guix-profile/bin/gcc} points to
@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}.  Now, on the same machine,
@code{bob} had already installed GCC 4.8.0.  The profile of @code{bob}
simply continues to point to
@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
coexist on the same system without any interference.

The @command{guix package} command is the central tool to manage
packages (@pxref{Invoking guix package}).  It operates on the per-user
profiles, and can be used @emph{with normal user privileges}.

@cindex transactions
The command provides the obvious install, remove, and upgrade
operations.  Each invocation is actually a @emph{transaction}: either
the specified operation succeeds, or nothing happens.  Thus, if the
@command{guix package} process is terminated during the transaction,
or if a power outage occurs during the transaction, then the user's
profile remains in its previous state, and remains usable.

In addition, any package transaction may be @emph{rolled back}.  So, if,
for example, an upgrade installs a new version of a package that turns
out to have a serious bug, users may roll back to the previous instance
of their profile, which was known to work well.  Similarly, the global
system configuration on Guix is subject to