aboutsummaryrefslogtreecommitdiff
path: root/CODE-OF-CONDUCT
blob: ef90330cdacb9ecf7dbf38a03cdb490db131a4ad (about) (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
Contributor Covenant Code of Conduct

  Note: In the sequel, "project" refers to GNU Guix, and "project
  maintainer(s)" refers to maintainer(s) of GNU Guix.

Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
education, socio-economic status, nationality, personal appearance, race,
religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment
include:


* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members


Examples of unacceptable behavior by participants include:


* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others’ private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting


Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at guix-maintainers@gnu.org. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project’s leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
try * Guix: (guix). Manage installed software and system configuration. * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages. * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space. * guix pull: (guix)Invoking guix pull. Update the list of available packages. * guix system: (guix)Invoking guix system. Manage the operating system configuration. * guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts. @end direntry @dircategory Software development @direntry * guix shell: (guix)Invoking guix shell. Creating software environments. * guix environment: (guix)Invoking guix environment. Building development environments with Guix. * guix build: (guix)Invoking guix build. Building packages. * guix pack: (guix)Invoking guix pack. Creating binary bundles. @end direntry @titlepage @title GNU Guix Reference Manual @subtitle Using the GNU Guix Functional Package Manager @author The GNU Guix Developers @page @vskip 0pt plus 1filll Edition @value{EDITION} @* @value{UPDATED} @* @insertcopying @end titlepage @contents @c ********************************************************************* @node Top @top GNU Guix This document describes GNU Guix version @value{VERSION}, a functional package management tool written for the GNU system. @c TRANSLATORS: You can replace the following paragraph with information on @c how to join your own translation team and how to report issues with the @c translation. This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN, GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), Brazilian Portuguese (@pxref{Top,,, guix.pt_BR, Manual de referência do GNU Guix}), and Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you would like to translate it in your native language, consider joining @uref{https://translate.fedoraproject.org/projects/guix/documentation-manual, Weblate} (@pxref{Translating Guix}). @menu * Introduction:: What is Guix about? * Installation:: Installing Guix. * System Installation:: Installing the whole operating system. * Getting Started:: Your first steps. * Package Management:: Package installation, upgrade, etc. * Channels:: Customizing the package collection. * Development:: Guix-aided software development. * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. * Foreign Architectures:: Build for foreign architectures. * System Configuration:: Configuring the operating system. * System Troubleshooting Tips:: When things don't go as planned. * Home Configuration:: Configuring the home environment. * Documentation:: Browsing software user manuals. * Platforms:: Defining platforms. * System Images:: Creating system images. * Installing Debugging Files:: Feeding the debugger. * Using TeX and LaTeX:: Typesetting. * Security Updates:: Deploying security fixes quickly. * Bootstrapping:: GNU/Linux built from scratch. * Porting:: Targeting another platform or kernel. * Contributing:: Your help needed! * Acknowledgments:: Thanks! * GNU Free Documentation License:: The license of this manual. * Concept Index:: Concepts. * Programming Index:: Data types, functions, and variables. @detailmenu --- The Detailed Node Listing --- Introduction * Managing Software the Guix Way:: What's special. * GNU Distribution:: The packages and tools. Installation * Binary Installation:: Getting Guix running in no time! * Setting Up the Daemon:: Preparing the build daemon's environment. * Invoking guix-daemon:: Running the build daemon. * Application Setup:: Application-specific setup. * Upgrading Guix:: Upgrading Guix and its build daemon. Setting Up the Daemon * Build Environment Setup:: Preparing the isolated build environment. * Daemon Offload Setup:: Offloading builds to remote machines. * SELinux Support:: Using an SELinux policy for the daemon. System Installation * 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. Manual Installation * Keyboard Layout and Networking and Partitioning:: Initial setup. * Proceeding with the Installation:: Installing. Package Management * 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 locate:: Locating packages that provide a file. * 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. Substitutes * Official Substitute Servers:: One particular source of substitutes. * Substitute Server Authorization:: How to enable or disable substitutes. * Getting Substitutes from Other Servers:: Substitute diversity. * Substitute Authentication:: How Guix verifies substitutes. * Proxy Settings:: How to get substitutes via proxy. * Substitution Failure:: What happens when substitution fails. * On Trusting Binaries:: How can you trust that binary blob? Channels * Specifying Additional Channels:: Extending the package collection. * Using a Custom Guix Channel:: Using a customized Guix. * Replicating Guix:: Running the @emph{exact same} Guix. * Channel Authentication:: How Guix verifies what it fetches. * Channels with Substitutes:: Using channels with available substitutes. * Creating a Channel:: How to write your custom channel. * Package Modules in a Sub-directory:: Specifying the channel's package modules location. * Declaring Channel Dependencies:: How to depend on other channels. * Specifying Channel Authorizations:: Defining channel authors authorizations. * Primary URL:: Distinguishing mirror to original. * Writing Channel News:: Communicating information to channel's users. Development * Invoking guix shell:: Spawning one-off software environments. * Invoking guix environment:: Setting up development environments. * Invoking guix pack:: Creating software bundles. * The GCC toolchain:: Working with languages supported by GCC. * Invoking guix git authenticate:: Authenticating Git repositories. Programming Interface * Package Modules:: Packages from the programmer's viewpoint. * Defining Packages:: Defining new packages. * Defining Package Variants:: Customizing packages. * Writing Manifests:: The bill of materials of your environment. * Build Systems:: Specifying how packages are built. * Build Phases:: Phases of the build process of a package. * Build Utilities:: Helpers for your package definitions and more. * Search Paths:: Declaring search path environment variables. * The Store:: Manipulating the package store. * Derivations:: Low-level interface to package derivations. * The Store Monad:: Purely functional interface to the store. * G-Expressions:: Manipulating build expressions. * Invoking guix repl:: Programming Guix in Guile * Using Guix Interactively:: Fine-grain interaction at the REPL. Defining Packages * package Reference:: The package data type. * origin Reference:: The origin data type. Utilities * Invoking guix build:: Building packages from the command line. * Invoking guix edit:: Editing package definitions. * Invoking guix download:: Downloading a file and printing its hash. * Invoking guix hash:: Computing the cryptographic hash of a file. * Invoking guix import:: Importing package definitions. * Invoking guix refresh:: Updating package definitions. * Invoking guix style:: Styling package definitions. * Invoking guix lint:: Finding errors in package definitions. * Invoking guix size:: Profiling disk usage. * Invoking guix graph:: Visualizing the graph of packages. * Invoking guix publish:: Sharing substitutes. * Invoking guix challenge:: Challenging substitute servers. * Invoking guix copy:: Copying to and from a remote store. * Invoking guix container:: Process isolation. * Invoking guix weather:: Assessing substitute availability. * Invoking guix processes:: Listing client processes. Invoking @command{guix build} * Common Build Options:: Build options for most commands. * Package Transformation Options:: Creating variants of packages. * Additional Build Options:: Options specific to 'guix build'. * Debugging Build Failures:: Real life packaging experience. Foreign Architectures * Cross-Compilation:: Cross-compiling for another architecture. * Native Builds:: Targeting another architecture through native builds. System Configuration * Getting Started with the System:: Your first steps. * 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. * Swap Space:: Backing RAM with disk space. * User Accounts:: Specifying user accounts. * Keyboard Layout:: How the system interprets key strokes. * Locales:: Language and cultural convention settings. * Services:: Specifying system services. * Privileged Programs:: Programs running with elevated privileges. * X.509 Certificates:: Authenticating HTTPS servers. * Name Service Switch:: Configuring libc's name service switch. * Initial RAM Disk:: Linux-Libre bootstrapping. * Bootloader Configuration:: Configuring the boot loader. * Invoking guix system:: Instantiating a system configuration. * Invoking guix deploy:: Deploying a system configuration to a remote host. * Running Guix in a VM:: How to run Guix System in a virtual machine. * Defining Services:: Adding new service definitions. File Systems * Btrfs file system:: Services * Base Services:: Essential system services. * Scheduled Job Execution:: The mcron service. * Log Rotation:: The rottlog service. * Networking Setup:: Setting up network interfaces. * Networking Services:: Firewall, SSH daemon, etc. * Unattended Upgrades:: Automated system upgrades. * X Window:: Graphical display. * Printing Services:: Local and remote printer support. * Desktop Services:: D-Bus and desktop services. * Sound Services:: ALSA and Pulseaudio services. * File Search Services:: Tools to search for files. * Database Services:: SQL databases, key-value stores, etc. * Mail Services:: IMAP, POP3, SMTP, and all that. * Messaging Services:: Messaging services. * Telephony Services:: Telephony services. * File-Sharing Services:: File-sharing services. * Monitoring Services:: Monitoring services. * Kerberos Services:: Kerberos services. * LDAP Services:: LDAP services. * Web Services:: Web servers. * Certificate Services:: TLS certificates via Let's Encrypt. * DNS Services:: DNS daemons. * VNC Services:: VNC daemons. * VPN Services:: VPN daemons. * Network File System:: NFS related services. * Samba Services:: Samba services. * Continuous Integration:: Cuirass and Laminar services. * Power Management Services:: Extending battery life. * Audio Services:: The MPD. * Virtualization Services:: Virtualization services. * Version Control Services:: Providing remote access to Git repositories. * Game Services:: Game servers. * PAM Mount Service:: Service to mount volumes when logging in. * Guix Services:: Services relating specifically to Guix. * Linux Services:: Services tied to the Linux kernel. * Hurd Services:: Services specific for a Hurd System. * Miscellaneous Services:: Other services. Defining Services * Service Composition:: The model for composing services. * Service Types and Services:: Types and services. * Service Reference:: API reference. * Shepherd Services:: A particular type of service. * Complex Configurations:: Defining bindings for complex configurations. System Troubleshooting Tips * Chrooting into an existing system:: Home Configuration * Declaring the Home Environment:: Customizing your Home. * Configuring the Shell:: Enabling home environment. * Home Services:: Specifying home services. * Invoking guix home:: Instantiating a home configuration. Home Services * Essential Home Services:: Environment variables, packages, on-* scripts. * Shells: Shells Home Services. POSIX shells, Bash, Zsh. * Mcron: Mcron Home Service. Scheduled User's Job Execution. * Power Management: Power Management Home Services. Services for battery power. * Shepherd: Shepherd Home Service. Managing User's Daemons. * SSH: Secure Shell. Setting up the secure shell client. * GPG: GNU Privacy Guard. Setting up GPG and related tools. * Desktop: Desktop Home Services. Services for graphical environments. * Guix: Guix Home Services. Services for Guix. * Fonts: Fonts Home Services. Services for managing User's fonts. * Sound: Sound Home Services. Dealing with audio. * Mail: Mail Home Services. Services for managing mail. * Messaging: Messaging Home Services. Services for managing messaging. * Media: Media Home Services. Services for managing media. * Networking: Networking Home Services. Networking services. * Miscellaneous: Miscellaneous Home Services. More services. Platforms * platform Reference:: Detail of platform declarations. * Supported Platforms:: Description of the supported platforms. Creating System Images * image Reference:: Detail of image declarations. * Instantiate an Image:: How to instantiate an image record. * image-type Reference:: Detail of image types declaration. * Image Modules:: Definition of image modules. @code{image} Reference * partition Reference:: Installing Debugging Files * Separate Debug Info:: Installing 'debug' outputs. * Rebuilding Debug Info:: Building missing debug info. Bootstrapping * Full-Source Bootstrap:: A Bootstrap worthy of GNU. * Preparing to Use the Bootstrap Binaries:: Building that what matters most. @end detailmenu @end menu @c ********************************************************************* @node Introduction @chapter Introduction @cindex purpose GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' using the international phonetic alphabet (IPA).} is a package management tool for and distribution of the GNU system. Guix makes it easy for unprivileged users to install, upgrade, or remove software packages, to roll back to a previous package set, to build packages from source, and generally assists with the creation and maintenance of software environments. @cindex Guix System @cindex GuixSD, now Guix System @cindex Guix System Distribution, now Guix System You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it complements the available tools without interference (@pxref{Installation}), or you can use it as a standalone operating system distribution, @dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix System Distribution'' or ``GuixSD''. We now consider it makes more sense to group everything under the ``Guix'' banner since, after all, Guix System is readily available through the @command{guix system} command, even if you're using a different distro underneath!}. @xref{GNU Distribution}. @menu * Managing Software the Guix Way:: What's special. * GNU Distribution:: The packages and tools. @end menu @node Managing Software the Guix Way @section Managing Software the Guix Way @cindex user interfaces Guix provides a command-line package management interface (@pxref{Package Management}), tools to help with software development (@pxref{Development}), command-line utilities for more advanced usage (@pxref{Utilities}), as well as Scheme programming interfaces (@pxref{Programming Interface}). @cindex build daemon Its @dfn{build daemon} is responsible for building packages on behalf of users (@pxref{Setting Up the Daemon}) and for downloading pre-built binaries from authorized sources (@pxref{Substitutes}). @cindex extensibility of the distribution @cindex customization, of packages Guix includes package definitions for many GNU and non-GNU packages, all of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the user's computing freedom}. It is @emph{extensible}: users can write their own package definitions (@pxref{Defining Packages}) and make them available as independent package modules (@pxref{Package Modules}). It is also @emph{customizable}: users can @emph{derive} specialized package definitions from existing ones, including from the command line (@pxref{Package Transformation Options}). @cindex functional package management @cindex isolation Under the hood, Guix implements the @dfn{functional package management} discipline pioneered by Nix (@pxref{Acknowledgments}). In Guix, the package build and installation process is seen as a @emph{function}, in the mathematical sense. That function takes inputs, such as build scripts, a compiler, and libraries, and returns an installed package. As a pure function, its result depends solely on its inputs---for instance, it cannot refer to software or scripts that were not explicitly passed as inputs. A build function always produces the same result when passed a given set of inputs. It cannot alter the environment of the running system in any way; for instance, it cannot create, modify, or delete files outside of its build and installation directories. This is achieved by running build processes in isolated environments (or @dfn{containers}), where only their explicit inputs are visible. @cindex store The result of package build functions is @dfn{cached} in the file system, in a special directory called @dfn{the store} (@pxref{The Store}). Each package is installed in a directory of its own in the store---by default under @file{/gnu/store}. The directory name contains a hash of all the inputs used to build that package; thus, changing an input yields a different directory name. This approach is the foundation for the salient features of Guix: support for transactional package upgrade and rollback, per-user installation, and garbage collection of packages (@pxref{Features}). @node GNU Distribution @section GNU Distribution @cindex Guix System Guix comes with a distribution of the GNU system consisting entirely of free software@footnote{The term ``free'' here refers to the @url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to users of that software}.}. The distribution can be installed on its own (@pxref{System Installation}), but it is also possible to install Guix as a package manager on top of an installed GNU/Linux system (@pxref{Installation}). When we need to distinguish between the two, we refer to the standalone distribution as Guix@tie{}System. The distribution provides core GNU packages such as GNU libc, GCC, and Binutils, as well as many GNU and non-GNU applications. The complete list of available packages can be browsed @url{https://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. @item i586-gnu @uref{https://hurd.gnu.org, GNU/Hurd} on the Intel 32-bit architecture (IA32). This configuration is experimental and under development. The easiest way for you to give it a try is by setting up an instance of @code{hurd-vm-service-type} on your GNU/Linux machine (@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}). @xref{Contributing}, on how to help! @item mips64el-linux (unsupported) little-endian 64-bit MIPS processors, specifically the Loongson series, n32 ABI, and Linux-Libre kernel. This configuration is no longer fully supported; in particular, there is no ongoing work to ensure that this architecture still works. Should someone decide they wish to revive this architecture then the code is still available. @item powerpc-linux (unsupported) big-endian 32-bit PowerPC processors, specifically the PowerPC G4 with AltiVec support, and Linux-Libre kernel. This configuration is not fully supported and there is no ongoing work to ensure this architecture works. @item powerpc64le-linux little-endian 64-bit Power ISA processors, Linux-Libre kernel. This includes POWER9 systems such as the @uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom, RYF Talos II mainboard}. This platform is available as a "technology preview": although it is supported, substitutes are not yet available from the build farm (@pxref{Substitutes}), and some packages may fail to build (@pxref{Tracking Bugs and Changes}). That said, the Guix community is actively working on improving this support, and now is a great time to try it and get involved! @item riscv64-linux little-endian 64-bit RISC-V processors, specifically RV64GC, and Linux-Libre kernel. This platform is available as a "technology preview": although it is supported, substitutes are not yet available from the build farm (@pxref{Substitutes}), and some packages may fail to build (@pxref{Tracking Bugs and Changes}). That said, the Guix community is actively working on improving this support, and now is a great time to try it and get involved! @end table With Guix@tie{}System, you @emph{declare} all aspects of the operating system configuration and Guix takes care of instantiating the configuration in a transactional, reproducible, and stateless fashion (@pxref{System Configuration}). Guix System uses the Linux-libre kernel, the Shepherd initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}), the well-known GNU utilities and tool chain, as well as the graphical environment or system services of your choice. Guix System is available on all the above platforms except @code{mips64el-linux}, @code{powerpc-linux}, @code{powerpc64le-linux} and @code{riscv64-linux}. @noindent For information on porting to other architectures or kernels, @pxref{Porting}. Building this distribution is a cooperative effort, and you are invited to join! @xref{Contributing}, for information about how you can help. @c ********************************************************************* @node Installation @chapter Installation @cindex installing Guix @cindex foreign distro @cindex Guix System You can install the package management tool Guix on top of an existing GNU/Linux or GNU/Hurd system@footnote{Hurd support is currently limited.}, referred to as a @dfn{foreign distro}. If, instead, you want to install the complete, standalone GNU system distribution, @dfn{Guix@tie{}System}, @pxref{System Installation}. This section is concerned only with the installation of Guix on a foreign distro. @quotation Important This section only applies to systems without Guix. Following it for existing Guix installations will overwrite important system files. @end quotation @cindex directories related to foreign distro When installed on a foreign distro, GNU@tie{}Guix complements the available tools without interference. Its data lives exclusively in two directories, usually @file{/gnu/store} and @file{/var/guix}; other files on your system, such as @file{/etc}, are left untouched. Once installed, Guix can be updated by running @command{guix pull} (@pxref{Invoking guix pull}). @menu * Binary Installation:: Getting Guix running in no time! * Setting Up the Daemon:: Preparing the build daemon's environment. * Invoking guix-daemon:: Running the build daemon. * Application Setup:: Application-specific setup. * Upgrading Guix:: Upgrading Guix and its build daemon. @end menu @node Binary Installation @section Binary Installation @cindex installing Guix from binaries @cindex installer script This section describes how to install Guix from a self-contained tarball providing binaries for Guix and for all its dependencies. This is often quicker than installing from source, described later (@pxref{Building from Git}). @quotation Important This section only applies to systems without Guix. Following it for existing Guix installations will overwrite important system files. @end quotation Some GNU/Linux distributions, such as Debian, Ubuntu, and openSUSE provide Guix through their own package managers. The version of Guix may be older than @value{VERSION} but you can update it afterwards by running @samp{guix pull}. We advise system administrators who install Guix, both from the installation script or @i{via} the native package manager of their foreign distribution, to also regularly read and follow security notices, as shown by @command{guix pull}. For Debian or derivatives such as Ubuntu or Trisquel, call: @example sudo apt install guix @end example Likewise, on openSUSE: @example sudo zypper install guix @end example If you are running Parabola, after enabling the pcr (Parabola Community Repo) repository, you can install Guix with: @example sudo pacman -S guix @end example The Guix project also provides a shell script, @file{guix-install.sh}, which automates the binary installation process without use of a foreign distro package manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}. Use of @file{guix-install.sh} requires Bash, GnuPG, GNU@tie{}tar, wget, and Xz. The script guides you through the following: @itemize @item Downloading and extracting the binary tarball @item Setting up the build daemon @item Making the ‘guix’ command available to non-root users @item Configuring substitute servers @end itemize As root, run: @example # cd /tmp # wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh # chmod +x guix-install.sh # ./guix-install.sh @end example The script to install Guix is also packaged in Parabola (in the pcr repository). You can install and run it with: @example sudo pacman -S guix-installer sudo guix-install.sh @end example @quotation Note By default, @file{guix-install.sh} will configure Guix to download pre-built package binaries, called @dfn{substitutes} (@pxref{Substitutes}), from the project's build farms. If you choose not to permit this, Guix will build @emph{everything} from source, making each installation and upgrade very expensive. @xref{On Trusting Binaries} for a discussion of why you may want to build packages from source. @cindex substitutes, authorization thereof To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you must authorize them. For example, @example # guix archive --authorize < \ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub # guix archive --authorize < \ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub @end example @end quotation When you're done installing Guix, @pxref{Application Setup} for extra configuration you might need, and @ref{Getting Started} for your first steps! @quotation Note The binary installation tarball can be (re)produced and verified simply by running the following command in the Guix source tree: @example make guix-binary.@var{system}.tar.xz @end example @noindent ...@: which, in turn, runs: @example guix pack -s @var{system} --localstatedir \ --profile-name=current-guix guix @end example @xref{Invoking guix pack}, for more info on this handy tool. @end quotation @cindex uninstalling Guix @cindex uninstallation, of Guix Should you eventually want to uninstall Guix, run the same script with the @option{--uninstall} flag: @example ./guix-install.sh --uninstall @end example With @option{--uninstall}, the script irreversibly deletes all the Guix files, configuration, and services. @node Setting Up the Daemon @section Setting Up the Daemon @cindex daemon During installation, the @dfn{build daemon} that must be running to use Guix has already been set up and you can run @command{guix} commands in your terminal program, @pxref{Getting Started}: @example guix build hello @end example If this runs through without error, feel free to skip this section. You should continue with the following section, @ref{Application Setup}. However, now would be a good time to replace outdated daemon versions, tweak it, perform builds on other machines (@pxref{Daemon Offload Setup}), or start it manually in special environments like ``chroots'' (@pxref{Chrooting into an existing system}) or WSL (not needed for WSL images created with Guix, @pxref{System Images, @code{wsl2-image-type}}). If you want to know more or optimize your system, this section is worth reading. Operations such as building a package or running the garbage collector are all performed by a specialized process, the build daemon, on behalf of clients. Only the daemon may access the store and its associated database. Thus, any operation that manipulates the store goes through the daemon. For instance, command-line tools such as @command{guix package} and @command{guix build} communicate with the daemon (@i{via} remote procedure calls) to instruct it what to do. The following sections explain how to prepare the build daemon's environment. @xref{Substitutes} for how to allow the daemon to download pre-built binaries. @menu * Build Environment Setup:: Preparing the isolated build environment. * Daemon Offload Setup:: Offloading builds to remote machines. * SELinux Support:: Using an SELinux policy for the daemon. @end menu @node Build Environment Setup @subsection Build Environment Setup @cindex build environment In a standard multi-user setup, Guix and its daemon---the @command{guix-daemon} program---are installed by the system administrator; @file{/gnu/store} is owned by @code{root} and @command{guix-daemon} runs as @code{root}. Unprivileged users may use Guix tools to build packages or otherwise access the store, and the daemon will do it on their behalf, ensuring that the store is kept in a consistent state, and allowing built packages to be shared among users. @cindex build users When @command{guix-daemon} runs as @code{root}, you may not want package build processes themselves to run as @code{root} too, for obvious security reasons. To avoid that, a special pool of @dfn{build users} should be created for use by build processes started by the daemon. These build users need not have a shell and a home directory: they will just be used when the daemon drops @code{root} privileges in build processes. Having several such users allows the daemon to launch distinct build processes under separate UIDs, which guarantees that they do not interfere with each other---an essential feature since builds are regarded as pure functions (@pxref{Introduction}). On a GNU/Linux system, a build user pool may be created like this (using Bash syntax and the @code{shadow} commands): @c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html @c for why `-G' is needed. @example # groupadd --system guixbuild # for i in $(seq -w 1 10); do useradd -g guixbuild -G guixbuild \ -d /var/empty -s $(which nologin) \ -c "Guix build user $i" --system \ guixbuilder$i; done @end example @noindent The number of build users determines how many build jobs may run in parallel, as specified by the @option{--max-jobs} option (@pxref{Invoking guix-daemon, @option{--max-jobs}}). To use @command{guix system vm} and related commands, you may need to add the build users to the @code{kvm} group so they can access @file{/dev/kvm}, using @code{-G guixbuild,kvm} instead of @code{-G guixbuild} (@pxref{Invoking guix system}). The @code{guix-daemon} program may then be run as @code{root} with the following command@footnote{If your machine uses the systemd init system, copying the @file{@var{prefix}/lib/systemd/system/guix-daemon.service} file to @file{/etc/systemd/system} will ensure that @command{guix-daemon} is automatically started. Similarly, if your machine uses the Upstart init system, copy the @file{@var{prefix}/lib/upstart/system/guix-daemon.conf} file to @file{/etc/init}.}: @example # guix-daemon --build-users-group=guixbuild @end example @cindex chroot @noindent This way, the daemon starts build processes in a chroot, under one of the @code{guixbuilder} users. On GNU/Linux, by default, the chroot environment contains nothing but: @c Keep this list in sync with libstore/build.cc! ----------------------- @itemize @item a minimal @code{/dev} directory, created mostly independently from the host @code{/dev}@footnote{``Mostly'', because while the set of files that appear in the chroot's @code{/dev} is fixed, most of these files can only be created if the host has them.}; @item the @code{/proc} directory; it only shows the processes of the container since a separate PID name space is used; @item @file{/etc/passwd} with an entry for the current user and an entry for user @file{nobody}; @item @file{/etc/group} with an entry for the user's group; @item @file{/etc/hosts} with an entry that maps @code{localhost} to @code{127.0.0.1}; @item a writable @file{/tmp} directory. @end itemize The chroot does not contain a @file{/home} directory, and the @env{HOME} environment variable is set to the non-existent @file{/homeless-shelter}. This helps to highlight inappropriate uses of @env{HOME} in the build scripts of packages. All this usually enough to ensure details of the environment do not influence build processes. In some exceptional cases where more control is needed---typically over the date, kernel, or CPU---you can resort to a virtual build machine (@pxref{build-vm, virtual build machines}). You can influence the directory where the daemon stores build trees @i{via} the @env{TMPDIR} environment variable. However, the build tree within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0}, where @var{name} is the derivation name---e.g., @code{coreutils-8.24}. This way, the value of @env{TMPDIR} does not leak inside build environments, which avoids discrepancies in cases where build processes capture the name of their build tree. @vindex http_proxy @vindex https_proxy The daemon also honors the @env{http_proxy} and @env{https_proxy} environment variables for HTTP and HTTPS downloads it performs, be it for fixed-output derivations (@pxref{Derivations}) or for substitutes (@pxref{Substitutes}). If you are installing Guix as an unprivileged user, it is still possible to run @command{guix-daemon} provided you pass @option{--disable-chroot}. However, build processes will not be isolated from one another, and not from the rest of the system. Thus, build processes may interfere with each other, and may access programs, libraries, and other files available on the system---making it much harder to view them as @emph{pure} functions. @node Daemon Offload Setup @subsection Using the Offload Facility @cindex offloading @cindex build hook When desired, the build daemon can @dfn{offload} derivation builds to other machines running Guix, using the @code{offload} @dfn{build hook}@footnote{This feature is available only when @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is present.}. When that feature is enabled, a list of user-specified build machines is read from @file{/etc/guix/machines.scm}; every time a build is requested, for instance via @code{guix build}, the daemon attempts to offload it to one of the machines that satisfy the constraints of the derivation, in particular its system types---e.g., @code{x86_64-linux}. A single machine can have multiple system types, either because its architecture natively supports it, via emulation (@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}), or both. Missing prerequisites for the build are copied over SSH to the target machine, which then proceeds with the build; upon success the output(s) of the build are copied back to the initial machine. The offload facility comes with a basic scheduler that attempts to select the best machine. The best machine is chosen among the available machines based on criteria such as: @enumerate @item The availability of a build slot. A build machine can have as many build slots (connections) as the value of the @code{parallel-builds} field of its @code{build-machine} object. @item Its relative speed, as defined via the @code{speed} field of its @code{build-machine} object. @item Its load. The normalized machine load must be lower than a threshold value, configurable via the @code{overload-threshold} field of its @code{build-machine} object. @item Disk space availability. More than a 100 MiB must be available. @end enumerate The @file{/etc/guix/machines.scm} file typically looks like this: @lisp (list (build-machine (name "eightysix.example.org") (systems (list "x86_64-linux" "i686-linux")) (host-key "ssh-ed25519 AAAAC3Nza@dots{}") (user "bob") (speed 2.)) ;incredibly fast! (build-machine (name "armeight.example.org") (systems (list "aarch64-linux")) (host-key "ssh-rsa AAAAB3Nza@dots{}") (user "alice") ;; Remember 'guix offload' is spawned by ;; 'guix-daemon' as root. (private-key "/root/.ssh/identity-for-guix"))) @end lisp @noindent In the example above we specify a list of two build machines, one for the @code{x86_64} and @code{i686} architectures and one for the @code{aarch64} architecture. In fact, this file is---not surprisingly!---a Scheme file that is evaluated when the @code{offload} hook is started. Its return value must be a list of @code{build-machine} objects. While this example shows a fixed list of build machines, one could imagine, say, using DNS-SD to return a list of potential build machines discovered in the local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme Programs}). The @code{build-machine} data type is detailed below. @deftp {Data Type} build-machine This data type represents build machines to which the daemon may offload builds. The important fields are: @table @code @item name The host name of the remote machine. @item systems The system types the remote machine supports---e.g., @code{(list "x86_64-linux" "i686-linux")}. @item user The user account on the remote machine to use when connecting over SSH. Note that the SSH key pair must @emph{not} be passphrase-protected, to allow non-interactive logins. @item host-key This must be the machine's SSH @dfn{public host key} in OpenSSH format. This is used to authenticate the machine when we connect to it. It is a long string that looks like this: @example ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org @end example If the machine is running the OpenSSH daemon, @command{sshd}, the host key can be found in a file such as @file{/etc/ssh/ssh_host_ed25519_key.pub}. If the machine is running the SSH daemon of GNU@tie{}lsh, @command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a similar file. It can be converted to the OpenSSH format using @command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}): @example $ lsh-export-key --openssh < /etc/lsh/host-key.pub ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{} @end example @end table A number of optional fields may be specified: @table @asis @item @code{port} (default: @code{22}) Port number of SSH server on the machine. @item @code{private-key} (default: @file{~root/.ssh/id_rsa}) The SSH private key file to use when connecting to the machine, in OpenSSH format. This key must not be protected with a passphrase. Note that the default value is the private key @emph{of the root account}. Make sure it exists if you use the default. @item @code{compression} (default: @code{"zlib@@openssh.com,zlib"}) @itemx @code{compression-level} (default: @code{3}) The SSH-level compression methods and compression level requested. Note that offloading relies on SSH compression to reduce bandwidth usage when transferring files to and from build machines. @item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"}) File name of the Unix-domain socket @command{guix-daemon} is listening to on that machine. @item @code{overload-threshold} (default: @code{0.8}) The load threshold above which a potential offload machine is disregarded by the offload scheduler. The value roughly translates to the total processor usage of the build machine, ranging from 0.0 (0%) to 1.0 (100%). It can also be disabled by setting @code{overload-threshold} to @code{#f}. @item @code{parallel-builds} (default: @code{1}) The number of builds that may run in parallel on the machine. @item @code{speed} (default: @code{1.0}) A ``relative speed factor''. The offload scheduler will tend to prefer machines with a higher speed factor. @item @code{features} (default: @code{'()}) A list of strings denoting specific features supported by the machine. An example is @code{"kvm"} for machines that have the KVM Linux modules and corresponding hardware support. Derivations can request features by name, and they will be scheduled on matching build machines. @end table @end deftp @quotation Note On Guix System, instead of managing @file{/etc/guix/machines.scm} independently, you can choose to specify build machines directly in the @code{operating-system} declaration, in the @code{build-machines} field of @code{guix-configuration}. @xref{guix-configuration-build-machines, @code{build-machines} field of @code{guix-configuration}}. @end quotation The @command{guix} command must be in the search path on the build machines. You can check whether this is the case by running: @example ssh build-machine guix repl --version @end example There is one last thing to do once @file{machines.scm} is in place. As explained above, when offloading, files are transferred back and forth between the machine stores. For this to work, you first need to generate a key pair on each machine to allow the daemon to export signed archives of files from the store (@pxref{Invoking guix archive}): @example # guix archive --generate-key @end example @quotation Note This key pair is not related to the SSH key pair that was previously mentioned in the description of the @code{build-machine} data type. @end quotation @noindent Each build machine must authorize the key of the master machine so that it accepts store items it receives from the master: @example # guix archive --authorize < master-public-key.txt @end example @noindent Likewise, the master machine must authorize the key of each build machine. All the fuss with keys is here to express pairwise mutual trust relations between the master and the build machines. Concretely, when the master receives files from a build machine (and @i{vice versa}), its build daemon can make sure they are genuine, have not been tampered with, and that they are signed by an authorized key. @cindex offload test To test whether your setup is operational, run this command on the master node: @example # guix offload test @end example This will attempt to connect to each of the build machines specified in @file{/etc/guix/machines.scm}, make sure Guix is available on each machine, attempt to export to the machine and import from it, and report any error in the process. If you want to test a different machine file, just specify it on the command line: @example # guix offload test machines-qualif.scm @end example Last, you can test the subset of the machines whose name matches a regular expression like this: @example # guix offload test machines.scm '\.gnu\.org$' @end example @cindex offload status To display the current load of all build hosts, run this command on the main node: @example # guix offload status @end example @node SELinux Support @subsection SELinux Support @cindex SELinux, daemon policy @cindex mandatory access control, SELinux @cindex security, guix-daemon Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that can be installed on a system where SELinux is enabled, in order to label Guix files and to specify the expected behavior of the daemon. Since Guix System does not provide an SELinux base policy, the daemon policy cannot be used on Guix System. @subsubsection Installing the SELinux policy @cindex SELinux, policy installation @quotation Note The @code{guix-install.sh} binary installation script offers to perform the steps below for you (@pxref{Binary Installation}). @end quotation To install the policy run this command as root: @example semodule -i /var/guix/profiles/per-user/root/current-guix/share/selinux/guix-daemon.cil @end example Then, as root, relabel the file system, possibly after making it writable: @example mount -o remount,rw /gnu/store restorecon -R /gnu /var/guix @end example At this point you can start or restart @command{guix-daemon}; on a distribution that uses systemd as its service manager, you can do that with: @example systemctl restart guix-daemon @end example Once the policy is installed, the file system has been relabeled, and the daemon has been restarted, it should be running in the @code{guix_daemon_t} context. You can confirm this with the following command: @example ps -Zax | grep guix-daemon @end example Monitor the SELinux log files as you run a command like @code{guix build hello} to convince yourself that SELinux permits all necessary operations. @subsubsection Limitations @cindex SELinux, limitations This policy is not perfect. Here is a list of limitations or quirks that should be considered when deploying the provided SELinux policy for the Guix daemon. @enumerate @item @code{guix_daemon_socket_t} isn’t actually used. None of the socket operations involve contexts that have anything to do with @code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label, but it would be preferable to define socket rules for only this label. @item @code{guix gc} cannot access arbitrary links to profiles. By design, the file label of the destination of a symlink is independent of the file label of the link itself. Although all profiles under @file{$localstatedir} are labelled, the links to these profiles inherit the label of the directory they are in. For links in the user’s home directory this will be @code{user_home_t}. But for links from the root user’s home directory, or @file{/tmp}, or the HTTP server’s working directory, etc, this won’t work. @code{guix gc} would be prevented from reading and following these links. @item The daemon’s feature to listen for TCP connections might no longer work. This might require extra rules, because SELinux treats network sockets differently from files. @item Currently all files with a name matching the regular expression @code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the label @code{guix_daemon_exec_t}; this means that @emph{any} file with that name in any profile would be permitted to run in the @code{guix_daemon_t} domain. This is not ideal. An attacker could build a package that provides this executable and convince a user to install and run it, which lifts it into the @code{guix_daemon_t} domain. At that point SELinux could not prevent it from accessing files that are allowed for processes in that domain. You will need to relabel the store directory after all upgrades to @file{guix-daemon}, such as after running @code{guix pull}. Assuming the store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu}, or by other means provided by your operating system. We could generate a much more restrictive policy at installation time, so that only the @emph{exact} file name of the currently installed @code{guix-daemon} executable would be labelled with @code{guix_daemon_exec_t}, instead of using a broad regular expression. The downside is that root would have to install or upgrade the policy at installation time whenever the Guix package that provides the effectively running @code{guix-daemon} executable is upgraded. @end enumerate @node Invoking guix-daemon @section Invoking @command{guix-daemon} @cindex @command{guix-daemon} The @command{guix-daemon} program implements all the functionality to access the store. This includes launching build processes, running the garbage collector, querying the availability of a build result, etc. It is normally run as @code{root} like this: @example # guix-daemon --build-users-group=guixbuild @end example @cindex socket activation, for @command{guix-daemon} This daemon can also be started following the systemd ``socket activation'' protocol (@pxref{Service De- and Constructors, @code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}). For details on how to set it up, @pxref{Setting Up the Daemon}. @cindex chroot @cindex container, build environment @cindex build environment @cindex reproducible builds By default, @command{guix-daemon} launches build processes under different UIDs, taken from the build group specified with @option{--build-users-group}. In addition, each build process is run in a chroot environment that only contains the subset of the store that the build process depends on, as specified by its derivation (@pxref{Programming Interface, derivation}), plus a set of specific system directories. By default, the latter contains @file{/dev} and @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a @dfn{container}: in addition to having its own file system tree, it has a separate mount name space, its own PID name space, network name space, etc. This helps achieve reproducible builds (@pxref{Features}). When the daemon performs a build on behalf of the user, it creates a build directory under @file{/tmp} or under the directory specified by its @env{TMPDIR} environment variable. This directory is shared with the container for the duration of the build, though within the container, the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}. The build directory is automatically deleted upon completion, unless the build failed and the client specified @option{--keep-failed} (@pxref{Common Build Options, @option{--keep-failed}}). The daemon listens for connections and spawns one sub-process for each session started by a client (one of the @command{guix} sub-commands). The @command{guix processes} command allows you to get an overview of the activity on your system by viewing each of the active sessions and clients. @xref{Invoking guix processes}, for more information. The following command-line options are supported: @table @code @item --build-users-group=@var{group} Take users from @var{group} to run build processes (@pxref{Setting Up the Daemon, build users}). @item --no-substitutes @cindex substitutes Do not use substitutes for build products. That is, always build things locally instead of allowing downloads of pre-built binaries (@pxref{Substitutes}). When the daemon runs with @option{--no-substitutes}, clients can still explicitly enable substitution @i{via} the @code{set-build-options} remote procedure call (@pxref{The Store}). @anchor{daemon-substitute-urls} @item --substitute-urls=@var{urls} Consider @var{urls} the default whitespace-separated list of substitute source URLs. When this option is omitted, @indicateurl{@value{SUBSTITUTE-URLS}} is used. This means that substitutes may be downloaded from @var{urls}, as long as they are signed by a trusted signature (@pxref{Substitutes}). @xref{Getting Substitutes from Other Servers}, for more information on how to configure the daemon to get substitutes from other servers. @cindex offloading @item --no-offload Do not use offload builds to other machines (@pxref{Daemon Offload Setup}). That is, always build things locally instead of offloading builds to remote machines. @item --cache-failures Cache build failures. By default, only successful builds are cached. When this option is used, @command{guix gc --list-failures} can be used to query the set of store items marked as failed; @command{guix gc --clear-failures} removes store items from the set of cached failures. @xref{Invoking guix gc}. @item --cores=@var{n} @itemx -c @var{n} Use @var{n} CPU cores to build each derivation; @code{0} means as many as available. The default value is @code{0}, but it may be overridden by clients, such as the @option{--cores} option of @command{guix build} (@pxref{Invoking guix build}). The effect is to define the @env{NIX_BUILD_CORES} environment variable in the build process, which can then use it to exploit internal parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}. @item --max-jobs=@var{n} @itemx -M @var{n} Allow at most @var{n} build jobs in parallel. The default value is @code{1}. Setting it to @code{0} means that no builds will be performed locally; instead, the daemon will offload builds (@pxref{Daemon Offload Setup}), or simply fail. @item --max-silent-time=@var{seconds} When the build or substitution process remains silent for more than @var{seconds}, terminate it and report a build failure. The default value is @code{3600} (one hour). The value specified here can be overridden by clients (@pxref{Common Build Options, @option{--max-silent-time}}). @item --timeout=@var{seconds} Likewise, when the build or substitution process lasts for more than @var{seconds}, terminate it and report a build failure. The default value is 24 hours. The value specified here can be overridden by clients (@pxref{Common Build Options, @option{--timeout}}). @item --rounds=@var{N} Build each derivation @var{n} times in a row, and raise an error if consecutive build results are not bit-for-bit identical. Note that this setting can be overridden by clients such as @command{guix build} (@pxref{Invoking guix build}). When used in conjunction with @option{--keep-failed}, the differing output is kept in the store, under @file{/gnu/store/@dots{}-check}. This makes it easy to look for differences between the two results. @item --debug Produce debugging output. This is useful to debug daemon start-up issues, but then it may be overridden by clients, for example the @option{--verbosity} option of @command{guix build} (@pxref{Invoking guix build}). @item --chroot-directory=@var{dir} Add @var{dir} to the build chroot. Doing this may change the result of build processes---for instance if they use optional dependencies found in @var{dir} when it is available, and not otherwise. For that reason, it is not recommended to do so. Instead, make sure that each derivation declares all the inputs that it needs. @item --disable-chroot Disable chroot builds. Using this option is not recommended since, again, it would allow build processes to gain access to undeclared dependencies. It is necessary, though, when @command{guix-daemon} is running under an unprivileged user account. @item --log-compression=@var{type} Compress build logs according to @var{type}, one of @code{gzip}, @code{bzip2}, or @code{none}. Unless @option{--lose-logs} is used, all the build logs are kept in the @var{localstatedir}. To save space, the daemon automatically compresses them with gzip by default. @item --discover[=yes|no] Whether to discover substitute servers on the local network using mDNS and DNS-SD. This feature is still experimental. However, here are a few considerations. @enumerate @item It might be faster/less expensive than fetching from remote servers; @item There are no security risks, only genuine substitutes will be used (@pxref{Substitute Authentication}); @item An attacker advertising @command{guix publish} on your LAN cannot serve you malicious binaries, but they can learn what software you’re installing; @item Servers may serve substitute over HTTP, unencrypted, so anyone on the LAN can see what software you’re installing. @end enumerate It is also possible to enable or disable substitute server discovery at run-time by running: @example herd discover guix-daemon on herd discover guix-daemon off @end example @item --disable-deduplication @cindex deduplication Disable automatic file ``deduplication'' in the store. By default, files added to the store are automatically ``deduplicated'': if a newly added file is identical to another one found in the store, the daemon makes the new file a hard link to the other file. This can noticeably reduce disk usage, at the expense of slightly increased input/output load at the end of a build process. This option disables this optimization. @item --gc-keep-outputs[=yes|no] Tell whether the garbage collector (GC) must keep outputs of live derivations. @cindex GC roots @cindex garbage collector roots When set to @code{yes}, the GC will keep the outputs of any live derivation available in the store---the @file{.drv} files. The default is @code{no}, meaning that derivation outputs are kept only if they are reachable from a GC root. @xref{Invoking guix gc}, for more on GC roots. @item --gc-keep-derivations[=yes|no] Tell whether the garbage collector (GC) must keep derivations corresponding to live outputs. When set to @code{yes}, as is the case by default, the GC keeps derivations---i.e., @file{.drv} files---as long as at least one of their outputs is live. This allows users to keep track of the origins of items in their store. Setting it to @code{no} saves a bit of disk space. In this way, setting @option{--gc-keep-derivations} to @code{yes} causes liveness to flow from outputs to derivations, and setting @option{--gc-keep-outputs} to @code{yes} causes liveness to flow from derivations to outputs. When both are set to @code{yes}, the effect is to keep all the build prerequisites (the sources, compiler, libraries, and other build-time tools) of live objects in the store, regardless of whether these prerequisites are reachable from a GC root. This is convenient for developers since it saves rebuilds or downloads. @item --impersonate-linux-2.6 On Linux-based systems, impersonate Linux 2.6. This means that the kernel's @command{uname} system call will report 2.6 as the release number. This might be helpful to build programs that (usually wrongfully) depend on the kernel version number. @item --lose-logs Do not keep build logs. By default they are kept under @file{@var{localstatedir}/guix/log}. @item --system=@var{system} Assume @var{system} as the current system type. By default it is the architecture/kernel pair found at configure time, such as @code{x86_64-linux}. @item --listen=@var{endpoint} Listen for connections on @var{endpoint}. @var{endpoint} is interpreted as the file name of a Unix-domain socket if it starts with @code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a host name or host name and port to listen to. Here are a few examples: @table @code @item --listen=/gnu/var/daemon Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket, creating it if needed. @item --listen=localhost @cindex daemon, remote access @cindex remote access to the daemon @cindex daemon, cluster setup @cindex clusters, daemon setup Listen for TCP connections on the network interface corresponding to @code{localhost}, on port 44146. @item --listen=128.0.0.42:1234 Listen for TCP connections on the network interface corresponding to @code{128.0.0.42}, on port 1234. @end table This option can be repeated multiple times, in which case @command{guix-daemon} accepts connections on all the specified endpoints. Users can tell client commands what endpoint to connect to by setting the @env{GUIX_DAEMON_SOCKET} environment variable (@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}). @quotation Note The daemon protocol is @emph{unauthenticated and unencrypted}. Using @option{--listen=@var{host}} is suitable on local networks, such as clusters, where only trusted nodes may connect to the build daemon. In other cases where remote access to the daemon is needed, we recommend using Unix-domain sockets along with SSH. @end quotation When @option{--listen} is omitted, @command{guix-daemon} listens for connections on the Unix-domain socket located at @file{@var{localstatedir}/guix/daemon-socket/socket}. @end table @node Application Setup @section Application Setup @cindex foreign distro When using Guix on top of GNU/Linux distribution other than Guix System---a so-called @dfn{foreign distro}---a few additional steps are needed to get everything in place. Here are some of them. @subsection Locales @anchor{locales-and-locpath} @cindex locales, when not on Guix System @vindex LOCPATH @vindex GUIX_LOCPATH Packages installed @i{via} Guix will not use the locale data of the host system. Instead, you must first install one of the locale packages available with Guix and then define the @env{GUIX_LOCPATH} environment variable: @example $ guix install glibc-locales $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale @end example Note that the @code{glibc-locales} package contains data for all the locales supported by the GNU@tie{}libc and weighs in at around 930@tie{}MiB@footnote{The size of the @code{glibc-locales} package is reduced down to about 213@tie{}MiB with store deduplication and further down to about 67@tie{}MiB when using a zstd-compressed Btrfs file system.}. If you only need a few locales, you can define your custom locales package via the @code{make-glibc-utf8-locales} procedure from the @code{(gnu packages base)} module. The following example defines a package containing the various Canadian UTF-8 locales known to the GNU@tie{}libc, that weighs around 14@tie{}MiB: @lisp (use-modules (gnu packages base)) (define my-glibc-locales (make-glibc-utf8-locales glibc #:locales (list "en_CA" "fr_CA" "ik_CA" "iu_CA" "shs_CA") #:name "glibc-canadian-utf8-locales")) @end lisp The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH} (@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference Manual}). There are two important differences though: @enumerate @item @env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc provided by foreign distros. Thus, using @env{GUIX_LOCPATH} allows you to make sure the programs of the foreign distro will not end up loading incompatible locale data. @item libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where @code{X.Y} is the libc version---e.g., @code{2.22}. This means that, should your Guix profile contain a mixture of programs linked against different libc version, each libc version will only try to load locale data in the right format. @end enumerate This is important because the locale data format used by different libc versions may be incompatible. @subsection Name Service Switch @cindex name service switch, glibc @cindex NSS (name service switch), glibc @cindex @abbr{nscd, name service cache daemon} When using Guix on a foreign distro, we @emph{strongly recommend} that the system run the GNU C library's @dfn{name service cache daemon}, @command{nscd}, which should be listening on the @file{/var/run/nscd/socket} socket. Failing to do that, applications installed with Guix may fail to look up host names or user accounts, or may even crash. The next paragraphs explain why. @cindex @file{nsswitch.conf} The GNU C library implements a @dfn{name service switch} (NSS), which is an extensible mechanism for ``name lookups'' in general: host name resolution, user accounts, and more (@pxref{Name Service Switch,,, libc, The GNU C Library Reference Manual}). @cindex Network information service (NIS) @cindex NIS (Network information service) Being extensible, the NSS supports @dfn{plugins}, which provide new name lookup implementations: for example, the @code{nss-mdns} plugin allow resolution of @code{.local} host names, the @code{nis} plugin allows user account lookup using the Network information service (NIS), and so on. These extra ``lookup services'' are configured system-wide in @file{/etc/nsswitch.conf}, and all the programs running on the system honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C Reference Manual}). When they perform a name lookup---for instance by calling the @code{getaddrinfo} function in C---applications first try to connect to the nscd; on success, nscd performs name lookups on their behalf. If the nscd is not running, then they perform the name lookup by themselves, by loading the name lookup services into their own address space and running it. These name lookup services---the @file{libnss_*.so} files---are @code{dlopen}'d, but they may come from the host system's C library, rather than from the C library the application is linked against (the C library coming from Guix). And this is where the problem is: if your application is linked against Guix's C library (say, glibc 2.24) and tries to load NSS plugins from another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will likely crash or have its name lookups fail unexpectedly. Running @command{nscd} on the system, among other advantages, eliminates this binary incompatibility problem because those @code{libnss_*.so} files are loaded in the @command{nscd} process, not in applications themselves. @subsection X11 Fonts @cindex fonts The majority of graphical applications use Fontconfig to locate and load fonts and perform X11-client-side rendering. The @code{fontconfig} package in Guix looks for fonts in @file{$HOME/.guix-profile} by default. Thus, to allow graphical applications installed with Guix to display fonts, you have to install fonts with Guix as well. Essential font packages include @code{font-ghostscript}, @code{font-dejavu}, and @code{font-gnu-freefont}. @cindex @code{fc-cache} @cindex font cache Once you have installed or removed fonts, or when you notice an application that does not find fonts, you may need to install Fontconfig and to force an update of its font cache by running: @example guix install fontconfig fc-cache -rv @end example To display text written in Chinese languages, Japanese, or Korean in graphical applications, consider installing @code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former has multiple outputs, one per language family (@pxref{Packages with Multiple Outputs}). For instance, the following command installs fonts for Chinese languages: @example guix install font-adobe-source-han-sans:cn @end example @cindex @code{xterm} Older programs such as @command{xterm} do not use Fontconfig and instead rely on server-side font rendering. Such programs require to specify a full name of a font using XLFD (X Logical Font Description), like this: @example -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 @end example To be able to use such full names for the TrueType fonts installed in your Guix profile, you need to extend the font path of the X server: @c Note: 'xset' does not accept symlinks so the trick below arranges to @c get at the real directory. See <https://bugs.gnu.org/30655>. @example xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) @end example @cindex @code{xlsfonts} After that, you can run @code{xlsfonts} (from @code{xlsfonts} package) to make sure your TrueType fonts are listed there. @subsection X.509 Certificates @cindex @code{nss-certs} The @code{nss-certs} package provides X.509 certificates, which allow programs to authenticate Web servers accessed over HTTPS. When using Guix on a foreign distro, you can install this package and define the relevant environment variables so that packages know where to look for certificates. @xref{X.509 Certificates}, for detailed information. @subsection Emacs Packages @cindex @code{emacs} When you install Emacs packages with Guix, the Elisp files are placed under the @file{share/emacs/site-lisp/} directory of the profile in which they are installed. The Elisp libraries are made available to Emacs through the @env{EMACSLOADPATH} environment variable, which is set when installing Emacs itself. @cindex guix-emacs-autoload-packages, refreshing Emacs packages Additionally, autoload definitions are automatically evaluated at the initialization of Emacs, by the Guix-specific @code{guix-emacs-autoload-packages} procedure. This procedure can be interactively invoked to have newly installed Emacs packages discovered, without having to restart Emacs. If, for some reason, you want to avoid auto-loading the Emacs packages installed with Guix, you can do so by running Emacs with the @option{--no-site-file} option (@pxref{Init File,,, emacs, The GNU Emacs Manual}). @quotation Note Most Emacs variants are now capable of doing native compilation. The approach taken by Guix Emacs however differs greatly from the approach taken upstream. Upstream Emacs compiles packages just-in-time and typically places shared object files in a special folder within your @code{user-emacs-directory}. These shared objects within said folder are organized in a flat hierarchy, and their file names contain two hashes to verify the original file name and contents of the source code. Guix Emacs on the other hand prefers to compile packages ahead-of-time. Shared objects retain much of the original file name and no hashes are added to verify the original file name or the contents of the file. Crucially, this allows Guix Emacs and packages built against it to be grafted (@pxref{Security Updates, grafts}), but at the same time, Guix Emacs lacks the hash-based verification of source code baked into upstream Emacs. As this naming schema is trivial to exploit, we disable just-in-time compilation. Further note, that @code{emacs-minimal}---the default Emacs for building packages---has been configured without native compilation. To natively compile your emacs packages ahead of time, use a transformation like @option{--with-input=emacs-minimal=emacs}. @end quotation @node Upgrading Guix @section Upgrading Guix @cindex Upgrading Guix, on a foreign distro To upgrade Guix, run: @example guix pull @end example @xref{Invoking guix pull}, for more information. @cindex upgrading Guix for the root user, on a foreign distro @cindex upgrading the Guix daemon, on a foreign distro @cindex @command{guix pull} for the root user, on a foreign distro On a foreign distro, you can upgrade the build daemon by running: @example sudo -i guix pull @end example @noindent followed by (assuming your distro uses the systemd service management tool): @example systemctl restart guix-daemon.service @end example On Guix System, upgrading the daemon is achieved by reconfiguring the system (@pxref{Invoking guix system, @code{guix system reconfigure}}). @c TODO What else? @c ********************************************************************* @node System Installation @chapter System Installation @cindex installing Guix System @cindex Guix System, installation This section explains how to install Guix System on a machine. Guix, as a 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. Alternatively, 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 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. More and more system services are provided (@pxref{Services}). Nevertheless, before you proceed with the installation, be aware that some services you rely on may still be missing from version @value{VERSION}. 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}}). The installer warns you early on if it detects devices that are known @emph{not} to work due to the lack of free firmware or free drivers. @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}, 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.sig $ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.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 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. @unnumberedsubsec Burning on a DVD 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. @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}. Sadly, on some machines, the installation medium cannot be properly booted and you only see a black screen after booting even after you waited for ten minutes. This may indicate that your machine cannot run Guix System; perhaps you instead want to install Guix on a foreign distro (@pxref{Binary Installation}). But don't give up just yet; a possible workaround is pressing the @kbd{e} key in the GRUB boot menu and appending @option{nomodeset} to the Linux bootline. Sometimes the black screen issue can also be resolved by connecting a different display. @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 is also a full-blown Guix System. This 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. @anchor{manual-installation-networking} @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, F2FS, and XFS 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 to format it as a LUKS partition would be along these lines: @example cryptsetup luksFormat /dev/sda2 cryptsetup open /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{Swap Space}), 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 mg (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 targets 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{targets} field contain the names of the devices, like @code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths are 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! You can upgrade the system whenever you want by running: @example guix pull sudo guix system reconfigure /etc/config.scm @end example @noindent This builds a new system @dfn{generation} with the latest packages and services. Now, @pxref{Getting Started with the System}, and join us on @code{#guix} on the Libera.Chat 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 a 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,readonly=on,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 @cindex profile You've installed your first package, congrats! The package is now visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a profile is a directory containing installed packages. 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, @env{GUIX_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. You can also manage the configuration of your entire @dfn{home environment}---your user ``dot files'', services, and packages---using Guix Home. @xref{Home Configuration}, to learn more about it! @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. Just like for packages, you can always @emph{roll back} to a previous generation @emph{of the whole system}. @xref{Getting Started with the System}, to learn how to manage your system. 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 locate:: Locating packages that provide a file. * 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 transactional upgrades and roll-back (@pxref{Getting Started with the System}). All packages in the package store may be @emph{garbage-collected}. Guix can determine which packages are still referenced by user profiles, and remove those that are provably no longer referenced (@pxref{Invoking guix gc}). Users may also explicitly remove old generations of their profile so that the packages they refer to can be collected. @cindex reproducibility @cindex reproducible builds Guix takes a @dfn{purely functional} approach to package management, as described in the introduction (@pxref{Introduction}). Each @file{/gnu/store} package directory name contains a hash of all the inputs that were used to build that package---compiler, libraries, build scripts, etc. This direct correspondence allows users to make sure a given package installation matches the current state of their distribution. It also helps maximize @dfn{build reproducibility}: thanks to the isolated build environments that are used, a given build is likely to yield bit-identical files when performed on different machines (@pxref{Invoking guix-daemon, container}). @cindex substitutes This foundation allows Guix to support @dfn{transparent binary/source deployment}. When a pre-built binary for a @file{/gnu/store} item is available from an external source---a @dfn{substitute}, Guix just downloads it and unpacks it; otherwise, it builds the package from source, locally (@pxref{Substitutes}). Because build results are usually bit-for-bit reproducible, users do not have to trust servers that provide substitutes: they can force a local build and @emph{challenge} providers (@pxref{Invoking guix challenge}). Control over the build environment is a feature that is also useful for developers. The @command{guix shell} command allows developers of a package to quickly set up the right development environment for their package, without having to manually install the dependencies of the package into their profile (@pxref{Invoking guix shell}). @cindex replication, of software environments @cindex provenance tracking, of software artifacts All of Guix and its package definitions is version-controlled, and @command{guix pull} allows you to ``travel in time'' on the history of Guix itself (@pxref{Invoking guix pull}). This makes it possible to replicate a Guix instance on a different machine or at a later point in time, which in turn allows you to @emph{replicate complete software environments}, while retaining precise @dfn{provenance tracking} of the software. @node Invoking guix package @section Invoking @command{guix package} @cindex installing packages @cindex removing packages @cindex package installation @cindex package removal @cindex profile @cindex @command{guix package} The @command{guix package} command is the tool that allows users to install, upgrade, and remove packages, as well as rolling back to previous configurations. These operations work on a user @dfn{profile}---a directory of installed packages. Each user has a default profile in @file{$HOME/.guix-profile}. The command operates only on the user's own profile, and works with normal user privileges (@pxref{Features}). Its syntax is: @example guix package @var{options} @end example @cindex transactions Primarily, @var{options} specifies the operations to be performed during the transaction. Upon completion, a new profile is created, but previous @dfn{generations} of the profile remain available, should the user want to roll back. For example, to remove @code{lua} and install @code{guile} and @code{guile-cairo} in a single transaction: @example guix package -r lua -i guile guile-cairo @end example @cindex aliases, for @command{guix package} For your convenience, we also provide the following aliases: @itemize @item @command{guix search} is an alias for @command{guix package -s}, @item @command{guix install} is an alias for @command{guix package -i}, @item @command{guix remove} is an alias for @command{guix package -r}, @item @command{guix upgrade} is an alias for @command{guix package -u}, @item and @command{guix show} is an alias for @command{guix package --show=}. @end itemize These aliases are less expressive than @command{guix package} and provide fewer options, so in some cases you'll probably want to use @command{guix package} directly. @command{guix package} also supports a @dfn{declarative approach} whereby the user specifies the exact set of packages to be available and passes it @i{via} the @option{--manifest} option (@pxref{profile-manifest, @option{--manifest}}). @cindex profile For each user, a symlink to the user's default profile is automatically created in @file{$HOME/.guix-profile}. This symlink always points to the current generation of the user's default profile. Thus, users can add @file{$HOME/.guix-profile/bin} to their @env{PATH} environment variable, and so on. @cindex search paths If you are not using Guix System, consider adding the following lines to your @file{~/.bash_profile} (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned shells get all the right environment variable definitions: @example GUIX_PROFILE="$HOME/.guix-profile" ; \ source "$GUIX_PROFILE/etc/profile" @end example In a multi-user setup, user profiles are stored in a place registered as a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That directory is normally @code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where @var{localstatedir} is the value passed to @code{configure} as @option{--localstatedir}, and @var{user} is the user name. The @file{per-user} directory is created when @command{guix-daemon} is started, and the @var{user} sub-directory is created by @command{guix package}. The @var{options} can be among the following: @table @code @item --install=@var{package} @dots{} @itemx -i @var{package} @dots{} Install the specified @var{package}s. Each @var{package} may specify a simple package name, such as @code{guile}, optionally followed by an at-sign and version number, such as @code{guile@@3.0.7} or simply @code{guile@@3.0}. In the latter case, the newest version prefixed by @code{3.0} is selected. If no version number is specified, the newest available version will be selected. In addition, such a @var{package} specification may contain a colon, followed by the name of one of the outputs of the package, as in @code{gcc:doc} or @code{binutils@@2.22:lib} (@pxref{Packages with Multiple Outputs}). Packages with a corresponding name (and optionally version) are searched for among the GNU distribution modules (@pxref{Package Modules}). Alternatively, a @var{package} can directly specify a store file name such as @file{/gnu/store/...-guile-3.0.7}, as produced by, e.g., @code{guix build}. @cindex propagated inputs Sometimes packages have @dfn{propagated inputs}: these are dependencies that automatically get installed along with the required package (@pxref{package-propagated-inputs, @code{propagated-inputs} in @code{package} objects}, for information about propagated inputs in package definitions). @anchor{package-cmd-propagated-inputs} An example is the GNU MPC library: its C header files refer to those of the GNU MPFR library, which in turn refer to those of the GMP library. Thus, when installing MPC, the MPFR and GMP libraries also get installed in the profile; removing MPC also removes MPFR and GMP---unless they had also been explicitly installed by the user. Besides, packages sometimes rely on the definition of environment variables for their search paths (see explanation of @option{--search-paths} below). Any missing or possibly incorrect environment variable definitions are reported here. @item --install-from-expression=@var{exp} @itemx -e @var{exp} Install the package @var{exp} evaluates to. @var{exp} must be a Scheme expression that evaluates to a @code{<package>} object. This option is notably useful to disambiguate between same-named variants of a package, with expressions such as @code{(@@ (gnu packages commencement) guile-final)}. Note that this option installs the first output of the specified package, which may be insufficient when needing a specific output of a multiple-output package. @item --install-from-file=@var{file} @itemx -f @var{file} Install the package that the code within @var{file} evaluates to. As an example, @var{file} might contain a definition like this (@pxref{Defining Packages}): @lisp @include package-hello.scm @end lisp Developers may find it useful to include such a @file{guix.scm} file in the root of their project source tree that can be used to test development snapshots and create reproducible development environments (@pxref{Invoking guix shell}). The @var{file} may also contain a JSON representation of one or more package definitions. Running @code{guix package -f} on @file{hello.json} with the following contents would result in installing the package @code{greeter} after building @code{myhello}: @example @verbatiminclude package-hello.json @end example @item --remove=@var{package} @dots{} @itemx -r @var{package} @dots{} Remove the specified @var{package}s. As for @option{--install}, each @var{package} may specify a version number and/or output name in addition to the package name. For instance, @samp{-r glibc:debug} would remove the @code{debug} output of @code{glibc}. @item --upgrade[=@var{regexp} @dots{}] @itemx -u [@var{regexp} @dots{}] @cindex upgrading packages Upgrade all the installed packages. If one or more @var{regexp}s are specified, upgrade only installed packages whose name matches a @var{regexp}. Also see the @option{--do-not-upgrade} option below. Note that this upgrades package to the latest version of packages found in the distribution currently installed. To update your distribution, you should regularly run @command{guix pull} (@pxref{Invoking guix pull}). @cindex package transformations, upgrades When upgrading, package transformations that were originally applied when creating the profile are automatically re-applied (@pxref{Package Transformation Options}). For example, assume you first installed Emacs from the tip of its development branch with: @example guix install emacs-next --with-branch=emacs-next=master @end example Next time you run @command{guix upgrade}, Guix will again pull the tip of the Emacs development branch and build @code{emacs-next} from that checkout. Note that transformation options such as @option{--with-branch} and @option{--with-source} depend on external state; it is up to you to ensure that they work as expected. You can also discard a transformations that apply to a package by running: @example guix install @var{package} @end example @item --do-not-upgrade[=@var{regexp} @dots{}] When used together with the @option{--upgrade} option, do @emph{not} upgrade any packages whose name matches a @var{regexp}. For example, to upgrade all packages in the current profile except those containing the substring ``emacs'': @example $ guix package --upgrade . --do-not-upgrade emacs @end example @item @anchor{profile-manifest}--manifest=@var{file} @itemx -m @var{file} @cindex profile declaration @cindex profile manifest Create a new generation of the profile from the manifest object returned by the Scheme code in @var{file}. This option can be repeated several times, in which case the manifests are concatenated. This allows you to @emph{declare} the profile's contents rather than constructing it through a sequence of @option{--install} and similar commands. The advantage is that @var{file} can be put under version control, copied to different machines to reproduce the same profile, and so on. @var{file} must return a @dfn{manifest} object, which is roughly a list of packages: @findex packages->manifest @lisp (use-package-modules guile emacs) (packages->manifest (list emacs guile-2.0 ;; Use a specific package output. (list guile-2.0 "debug"))) @end lisp @xref{Writing Manifests}, for information on how to write a manifest. @xref{export-manifest, @option{--export-manifest}}, to learn how to obtain a manifest file from an existing profile. @item --roll-back @cindex rolling back @cindex undoing transactions @cindex transactions, undoing Roll back to the previous @dfn{generation} of the profile---i.e., undo the last transaction. When combined with options such as @option{--install}, roll back occurs before any other actions. When rolling back from the first generation that actually contains installed packages, the profile is made to point to the @dfn{zeroth generation}, which contains no files apart from its own metadata. After having rolled back, installing, removing, or upgrading packages overwrites previous future generations. Thus, the history of the generations in a profile is always linear. @item --switch-generation=@var{pattern} @itemx -S @var{pattern} @cindex generations Switch to a particular generation defined by @var{pattern}. @var{pattern} may be either a generation number or a number prefixed with ``+'' or ``-''. The latter means: move forward/backward by a specified number of generations. For example, if you want to return to the latest generation after @option{--roll-back}, use @option{--switch-generation=+1}. The difference between @option{--roll-back} and @option{--switch-generation=-1} is that @option{--switch-generation} will not make a zeroth generation, so if a specified generation does not exist, the current generation will not be changed. @item --search-paths[=@var{kind}] @cindex search paths Report environment variable definitions, in Bash syntax, that may be needed in order to use the set of installed packages. These environment variables are used to specify @dfn{search paths} for files used by some of the installed packages. For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH} environment variables to be defined so it can look for headers and libraries in the user's profile (@pxref{Environment Variables,,, gcc, Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C library are installed in the profile, then @option{--search-paths} will suggest setting these variables to @file{@var{profile}/include} and @file{@var{profile}/lib}, respectively (@pxref{Search Paths}, for info on search path specifications associated with packages.) The typical use case is to define these environment variables in the shell: @example $ eval $(guix package --search-paths) @end example @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix}, meaning that the returned environment variable definitions will either be exact settings, or prefixes or suffixes of the current value of these variables. When omitted, @var{kind} defaults to @code{exact}. This option can also be used to compute the @emph{combined} search paths of several profiles. Consider this example: @example $ guix package -p foo -i guile $ guix package -p bar -i guile-json $ guix package -p foo -p bar --search-paths @end example The last command above reports about the @env{GUILE_LOAD_PATH} variable, even though, taken individually, neither @file{foo} nor @file{bar} would lead to that recommendation. @cindex profile, choosing @item --profile=@var{profile} @itemx -p @var{profile} Use @var{profile} instead of the user's default profile. @var{profile} must be the name of a file that will be created upon completion. Concretely, @var{profile} will be a mere symbolic link (``symlink'') pointing to the actual profile where packages are installed: @example $ guix install hello -p ~/code/my-profile @dots{} $ ~/code/my-profile/bin/hello Hello, world! @end example All it takes to get rid of the profile is to remove this symlink and its siblings that point to specific generations: @example $ rm ~/code/my-profile ~/code/my-profile-*-link @end example @item --list-profiles List all the user's profiles: @example $ guix package --list-profiles /home/charlie/.guix-profile /home/charlie/code/my-profile /home/charlie/code/devel-profile /home/charlie/tmp/test @end example When running as root, list all the profiles of all the users. @cindex collisions, in a profile @cindex colliding packages in profiles @cindex profile collisions @item --allow-collisions Allow colliding packages in the new profile. Use at your own risk! By default, @command{guix package} reports as an error @dfn{collisions} in the profile. Collisions happen when two or more different versions or variants of a given package end up in the profile. @item --bootstrap Use the bootstrap Guile to build the profile. This option is only useful to distribution developers. @end table In addition to these actions, @command{guix package} supports the following options to query the current state of a profile, or the availability of packages: @table @option @item --search=@var{regexp} @itemx -s @var{regexp} @anchor{guix-search} @cindex searching for packages List the available packages whose name, synopsis, or description matches @var{regexp} (in a case-insensitive fashion), sorted by relevance. Print all the metadata of matching packages in @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). This allows specific fields to be extracted using the @command{recsel} command, for instance: @example $ guix package -s malloc | recsel -p name,version,relevance name: jemalloc version: 4.5.0 relevance: 6 name: glibc version: 2.25 relevance: 1 name: libgc version: 7.6.0 relevance: 1 @end example Similarly, to show the name of all the packages available under the terms of the GNU@tie{}LGPL version 3: @example $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' name: elfutils name: gmp @dots{} @end example It is also possible to refine search results using several @code{-s} flags to @command{guix package}, or several arguments to @command{guix search}. For example, the following command returns a list of board games (this time using the @command{guix search} alias): @example $ guix search '\<board\>' game | recsel -p name name: gnubg @dots{} @end example If we were to omit @code{-s game}, we would also get software packages that deal with printed circuit boards; removing the angle brackets around @code{board} would further add packages that have to do with keyboards. And now for a more elaborate example. The following command searches for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby libraries, and prints the name and synopsis of the matching packages: @example $ guix search crypto library | \ recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis @end example @noindent @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more information on @dfn{selection expressions} for @code{recsel -e}. @item --show=@var{package} Show details about @var{package}, taken from the list of available packages, in @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). @example $ guix package --show=guile | recsel -p name,version name: guile version: 3.0.5 name: guile version: 3.0.2 name: guile version: 2.2.7 @dots{} @end example You may also specify the full name of a package to only get details about a specific version of it (this time using the @command{guix show} alias): @example $ guix show guile@@3.0.5 | recsel -p name,version name: guile version: 3.0.5 @end example @item --list-installed[=@var{regexp}] @itemx -I [@var{regexp}] List the currently installed packages in the specified profile, with the most recently installed packages shown last. When @var{regexp} is specified, list only installed packages whose name matches @var{regexp}. For each installed package, print the following items, separated by tabs: the package name, its version string, the part of the package that is installed (for instance, @code{out} for the default output, @code{include} for its headers, etc.), and the path of this package in the store. @item --list-available[=@var{regexp}] @itemx -A [@var{regexp}] List packages currently available in the distribution for this system (@pxref{GNU Distribution}). When @var{regexp} is specified, list only available packages whose name matches @var{regexp}. For each package, print the following items separated by tabs: its name, its version string, the parts of the package (@pxref{Packages with Multiple Outputs}), and the source location of its definition. @item --list-generations[=@var{pattern}] @itemx -l [@var{pattern}] @cindex generations Return a list of generations along with their creation dates; for each generation, show the installed packages, with the most recently installed packages shown last. Note that the zeroth generation is never shown. For each installed package, print the following items, separated by tabs: the name of a package, its version string, the part of the package that is installed (@pxref{Packages with Multiple Outputs}), and the location of this package in the store. When @var{pattern} is used, the command returns only matching generations. Valid patterns include: @itemize @item @emph{Integers and comma-separated integers}. Both patterns denote generation numbers. For instance, @option{--list-generations=1} returns the first one. And @option{--list-generations=1,8,2} outputs three generations in the specified order. Neither spaces nor trailing commas are allowed. @item @emph{Ranges}. @option{--list-generations=2..9} prints the specified generations and everything in between. Note that the start of a range must be smaller than its end. It is also possible to omit the endpoint. For example, @option{--list-generations=2..}, returns all generations starting from the second one. @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks, or months by passing an integer along with the first letter of the duration. For example, @option{--list-generations=20d} lists generations that are up to 20 days old. @end itemize @item --delete-generations[=@var{pattern}] @itemx -d [@var{pattern}] When @var{pattern} is omitted, delete all generations except the current one. This command accepts the same patterns as @option{--list-generations}. When @var{pattern} is specified, delete the matching generations. When @var{pattern} specifies a duration, generations @emph{older} than the specified duration match. For instance, @option{--delete-generations=1m} deletes generations that are more than one month old. If the current generation matches, it is @emph{not} deleted. Also, the zeroth generation is never deleted. Note that deleting generations prevents rolling back to them. Consequently, this command must be used with care. @cindex manifest, exporting @anchor{export-manifest} @item --export-manifest Write to standard output a manifest suitable for @option{--manifest} corresponding to the chosen profile(s). This option is meant to help you migrate from the ``imperative'' operating mode---running @command{guix install}, @command{guix upgrade}, etc.---to the declarative mode that @option{--manifest} offers. Be aware that the resulting manifest @emph{approximates} what your profile actually contains; for instance, depending on how your profile was created, it can refer to packages or package versions that are not exactly what you specified. Keep in mind that a manifest is purely symbolic: it only contains package names and possibly versions, and their meaning varies over time. If you wish to ``pin'' channels to the revisions that were used to build the profile(s), see @option{--export-channels} below. @cindex pinning, channel revisions of a profile @item --export-channels Write to standard output the list of channels used by the chosen profile(s), in a format suitable for @command{guix pull --channels} or @command{guix time-machine --channels} (@pxref{Channels}). Together with @option{--export-manifest}, this option provides information allowing you to replicate the current profile (@pxref{Replicating Guix}). However, note that the output of this command @emph{approximates} what was actually used to build this profile. In particular, a single profile might have been built from several different revisions of the same channel. In that case, @option{--export-manifest} chooses the last one and writes the list of other revisions in a comment. If you really need to pick packages from different channel revisions, you can use inferiors in your manifest to do so (@pxref{Inferiors}). Together with @option{--export-manifest}, this is a good starting point if you are willing to migrate from the ``imperative'' model to the fully declarative model consisting of a manifest file along with a channels file pinning the exact channel revision(s) you want. @end table Finally, since @command{guix package} may actually start build processes, it supports all the common build options (@pxref{Common Build Options}). It also supports package transformation options, such as @option{--with-source}, and preserves them across upgrades (@pxref{Package Transformation Options}). @node Substitutes @section Substitutes @cindex substitutes @cindex pre-built binaries Guix supports transparent source/binary deployment, which means that it can either build things locally, or download pre-built items from a server, or both. We call these pre-built items @dfn{substitutes}---they are substitutes for local build results. In many cases, downloading a substitute is much faster than building things locally. Substitutes can be anything resulting from a derivation build (@pxref{Derivations}). Of course, in the common case, they are pre-built package binaries, but source tarballs, for instance, which also result from derivation builds, can be available as substitutes. @menu * Official Substitute Servers:: One particular source of substitutes. * Substitute Server Authorization:: How to enable or disable substitutes. * Getting Substitutes from Other Servers:: Substitute diversity. * Substitute Authentication:: How Guix verifies substitutes. * Proxy Settings:: How to get substitutes via proxy. * Substitution Failure:: What happens when substitution fails. * On Trusting Binaries:: How can you trust that binary blob? @end menu @node Official Substitute Servers @subsection Official Substitute Servers @cindex build farm @code{@value{SUBSTITUTE-SERVER-1}} and @code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build farms that build packages from Guix continuously for some architectures, and make them available as substitutes. These are the default source of substitutes; which can be overridden by passing the @option{--substitute-urls} option either to @command{guix-daemon} (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) or to client tools such as @command{guix package} (@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). Substitute URLs can be either HTTP or HTTPS. HTTPS is recommended because communications are encrypted; conversely, using HTTP makes all communications visible to an eavesdropper, who could use the information gathered to determine, for instance, whether your system has unpatched security vulnerabilities. Substitutes from the official build farms are enabled by default when using Guix System (@pxref{GNU Distribution}). However, they are disabled by default when using Guix on a foreign distribution, unless you have explicitly enabled them via one of the recommended installation steps (@pxref{Installation}). The following paragraphs describe how to enable or disable substitutes for the official build farm; the same procedure can also be used to enable substitutes for any other substitute server. @node Substitute Server Authorization @subsection Substitute Server Authorization @cindex security @cindex substitutes, authorization thereof @cindex access control list (ACL), for substitutes @cindex ACL (access control list), for substitutes To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you must add the relevant public key to the access control list (ACL) of archive imports, using the @command{guix archive} command (@pxref{Invoking guix archive}). Doing so implies that you trust the substitute server to not be compromised and to serve genuine substitutes. @quotation Note If you are using Guix System, you can skip this section: Guix System authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and @code{@value{SUBSTITUTE-SERVER-2}} by default. @end quotation The public keys for each of the project maintained substitute servers are installed along with Guix, in @code{@var{prefix}/share/guix/}, where @var{prefix} is the installation prefix of Guix. If you installed Guix from source, make sure you checked the GPG signature of @file{guix-@value{VERSION}.tar.gz}, which contains this public key file. Then, you can run something like this: @example # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub @end example Once this is in place, the output of a command like @code{guix build} should change from something like: @example $ guix build emacs --dry-run The following derivations would be built: /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv @dots{} @end example @noindent to something like: @example $ guix build emacs --dry-run 112.3 MB would be downloaded: /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7 @dots{} @end example @noindent The text changed from ``The following derivations would be built'' to ``112.3 MB would be downloaded''. This indicates that substitutes from the configured substitute servers are usable and will be downloaded, when possible, for future builds. @cindex substitutes, how to disable The substitute mechanism can be disabled globally by running @code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking guix-daemon}). It can also be disabled temporarily by passing the @option{--no-substitutes} option to @command{guix package}, @command{guix build}, and other command-line tools. @node Getting Substitutes from Other Servers @subsection Getting Substitutes from Other Servers @c Note: This section name appears in a hint printed by 'guix weather'. @cindex substitute servers, adding more Guix can look up and fetch substitutes from several servers. This is useful when you are using packages from additional channels for which the official server does not have substitutes but another server provides them. Another situation where this is useful is when you would prefer to download from your organization's substitute server, resorting to the official server only as a fallback or dismissing it altogether. You can give Guix a list of substitute server URLs and it will check them in the specified order. You also need to explicitly authorize the public keys of substitute servers to instruct Guix to accept the substitutes they sign. On Guix System, this is achieved by modifying the configuration of the @code{guix} service. Since the @code{guix} service is part of the default lists of services, @code{%base-services} and @code{%desktop-services}, you can use @code{modify-services} to change its configuration and add the URLs and substitute keys that you want (@pxref{Service Reference, @code{modify-services}}). As an example, suppose you want to fetch substitutes from @code{guix.example.org} and to authorize the signing key of that server, in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and @code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system configuration will look something like: @lisp (operating-system ;; @dots{} (services ;; Assume we're starting from '%desktop-services'. Replace it ;; with the list of services you're actually using. (modify-services %desktop-services (guix-service-type config => (guix-configuration (inherit config) (substitute-urls (append (list "https://guix.example.org") %default-substitute-urls)) (authorized-keys (append (list (local-file "./key.pub")) %default-authorized-guix-keys))))))) @end lisp This assumes that the file @file{key.pub} contains the signing key of @code{guix.example.org}. With this change in place in your operating system configuration file (say @file{/etc/config.scm}), you can reconfigure and restart the @code{guix-daemon} service or reboot so the changes take effect: @example $ sudo guix system reconfigure /etc/config.scm $ sudo herd restart guix-daemon @end example If you're running Guix on a ``foreign distro'', you would instead take the following steps to get substitutes from additional servers: @enumerate @item Edit the service configuration file for @code{guix-daemon}; when using systemd, this is normally @file{/etc/systemd/system/guix-daemon.service}. Add the @option{--substitute-urls} option on the @command{guix-daemon} command line and list the URLs of interest (@pxref{daemon-substitute-urls, @code{guix-daemon --substitute-urls}}): @example @dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}' @end example @item Restart the daemon. For systemd, it goes like this: @example systemctl daemon-reload systemctl restart guix-daemon.service @end example @item Authorize the key of the new server (@pxref{Invoking guix archive}): @example guix archive --authorize < key.pub @end example Again this assumes @file{key.pub} contains the public key that @code{guix.example.org} uses to sign substitutes. @end enumerate Now you're all set! Substitutes will be preferably taken from @code{https://guix.example.org}, using @code{@value{SUBSTITUTE-SERVER-1}} then @code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you can list as many substitute servers as you like, with the caveat that substitute lookup can be slowed down if too many servers need to be contacted. @quotation Troubleshooting To diagnose problems, you can run @command{guix weather}. For example, running: @example guix weather coreutils @end example @noindent not only tells you which of the currently-configured servers has substitutes for the @code{coreutils} package, it also reports whether one of these servers is unauthorized. @xref{Invoking guix weather}, for more information. @end quotation Note that there are also situations where one may want to add the URL of a substitute server @emph{without} authorizing its key. @xref{Substitute Authentication}, to understand this fine point. @node Substitute Authentication @subsection Substitute Authentication @cindex digital signatures Guix detects and raises an error when attempting to use a substitute that has been tampered with. Likewise, it ignores substitutes that are not signed, or that are not signed by one of the keys listed in the ACL. There is one exception though: if an unauthorized server provides substitutes that are @emph{bit-for-bit identical} to those provided by an authorized server, then the unauthorized server becomes eligible for downloads. For example, assume we have chosen two substitute servers with this option: @example --substitute-urls="https://a.example.org https://b.example.org" @end example @noindent @cindex reproducible builds If the ACL contains only the key for @samp{b.example.org}, and if @samp{a.example.org} happens to serve the @emph{exact same} substitutes, then Guix will download substitutes from @samp{a.example.org} because it comes first in the list and can be considered a mirror of @samp{b.example.org}. In practice, independent build machines usually produce the same binaries, thanks to bit-reproducible builds (see below). When using HTTPS, the server's X.509 certificate is @emph{not} validated (in other words, the server is not authenticated), contrary to what HTTPS clients such as Web browsers usually do. This is because Guix authenticates substitute information itself, as explained above, which is what we care about (whereas X.509 certificates are about authenticating bindings between domain names and public keys). @node Proxy Settings @subsection Proxy Settings @vindex http_proxy @vindex https_proxy Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and @env{https_proxy} environment variables can be set in the environment of @command{guix-daemon} and are honored for downloads of substitutes. Note that the value of those environment variables in the environment where @command{guix build}, @command{guix package}, and other client commands are run has @emph{absolutely no effect}. @node Substitution Failure @subsection Substitution Failure Even when a substitute for a derivation is available, sometimes the substitution attempt will fail. This can happen for a variety of reasons: the substitute server might be offline, the substitute may recently have been deleted, the connection might have been interrupted, etc. When substitutes are enabled and a substitute for a derivation is available, but the substitution attempt fails, Guix will attempt to build the derivation locally depending on whether or not @option{--fallback} was given (@pxref{fallback-option,, common build option @option{--fallback}}). Specifically, if @option{--fallback} was omitted, then no local build will be performed, and the derivation is considered to have failed. However, if @option{--fallback} was given, then Guix will attempt to build the derivation locally, and the success or failure of the derivation depends on the success or failure of the local build. Note that when substitutes are disabled or no substitute is available for the derivation in question, a local build will @emph{always} be performed, regardless of whether or not @option{--fallback} was given. To get an idea of how many substitutes are available right now, you can try running the @command{guix weather} command (@pxref{Invoking guix weather}). This command provides statistics on the substitutes provided by a server. @node On Trusting Binaries @subsection On Trusting Binaries @cindex trust, of pre-built binaries Today, each individual's control over their own computing is at the mercy of institutions, corporations, and groups with enough power and determination to subvert the computing infrastructure and exploit its weaknesses. While using substitutes can be convenient, we encourage users to also build on their own, or even run their own build farm, such that the project run substitute servers are less of an interesting target. One way to help is by publishing the software you build using @command{guix publish} so that others have one more choice of server to download substitutes from (@pxref{Invoking guix publish}). Guix has the foundations to maximize build reproducibility (@pxref{Features}). In most cases, independent builds of a given package or derivation should yield bit-identical results. Thus, through a diverse set of independent package builds, we can strengthen the integrity of our systems. The @command{guix challenge} command aims to help users assess substitute servers, and to assist developers in finding out about non-deterministic package builds (@pxref{Invoking guix challenge}). Similarly, the @option{--check} option of @command{guix build} allows users to check whether previously-installed substitutes are genuine by rebuilding them locally (@pxref{build-check, @command{guix build --check}}). In the future, we want Guix to have support to publish and retrieve binaries to/from other users, in a peer-to-peer fashion. If you would like to discuss this project, join us on @email{guix-devel@@gnu.org}. @node Packages with Multiple Outputs @section Packages with Multiple Outputs @cindex multiple-output packages @cindex package outputs @cindex outputs Often, packages defined in Guix have a single @dfn{output}---i.e., the source package leads to exactly one directory in the store. When running @command{guix install glibc}, one installs the default output of the GNU libc package; the default output is called @code{out}, but its name can be omitted as shown in this command. In this particular case, the default output of @code{glibc} contains all the C header files, shared libraries, static libraries, Info documentation, and other supporting files. Sometimes it is more appropriate to separate the various types of files produced from a single source package into separate outputs. For instance, the GLib C library (used by GTK+ and related packages) installs more than 20 MiB of reference documentation as HTML pages. To save space for users who do not need it, the documentation goes to a separate output, called @code{doc}. To install the main GLib output, which contains everything but the documentation, one would run: @example guix install glib @end example @cindex documentation The command to install its documentation is: @example guix install glib:doc @end example While the colon syntax works for command-line specification of package outputs, it will not work when using a package @emph{variable} in Scheme code. For example, to add the documentation of @code{glib} to the globally installed packages of an @code{operating-system} (see @ref{operating-system Reference}), a list of two items, the first one being the package @emph{variable} and the second one the name of the output to select (a string), must be used instead: @lisp (use-modules (gnu packages glib)) ;; glib-with-documentation is the Guile symbol for the glib package (operating-system ... (packages (append (list (list glib-with-documentation "doc")) %base-packages))) @end lisp Some packages install programs with different ``dependency footprints''. For instance, the WordNet package installs both command-line tools and graphical user interfaces (GUIs). The former depend solely on the C library, whereas the latter depend on Tcl/Tk and the underlying X libraries. In this case, we leave the command-line tools in the default output, whereas the GUIs are in a separate output. This allows users who do not need the GUIs to save space. The @command{guix size} command can help find out about such situations (@pxref{Invoking guix size}). @command{guix graph} can also be helpful (@pxref{Invoking guix graph}). There are several such multiple-output packages in the GNU distribution. Other conventional output names include @code{lib} for libraries and possibly header files, @code{bin} for stand-alone programs, and @code{debug} for debugging information (@pxref{Installing Debugging Files}). The outputs of a package are listed in the third column of the output of @command{guix package --list-available} (@pxref{Invoking guix package}). @node Invoking guix locate @section Invoking @command{guix locate} @cindex file, searching in packages @cindex file search @cindex searching for packages There's so much free software out there that sooner or later, you will need to search for packages. The @command{guix search} command that we've seen before (@pxref{Invoking guix package}) lets you search by keywords: @example guix search video editor @end example @cindex searching for packages, by file name Sometimes, you instead want to find which package provides a given file, and this is where @command{guix locate} comes in. Here is how you can find which package provides the @command{ls} command: @example $ guix locate ls coreutils@@9.1 /gnu/store/@dots{}-coreutils-9.1/bin/ls @end example Of course the command works for any file, not just commands: @example $ guix locate unistr.h icu4c@@71.1 /gnu/store/@dots{}/include/unicode/unistr.h libunistring@@1.0 /gnu/store/@dots{}/include/unistr.h @end example You may also specify @dfn{glob patterns} with wildcards. For example, here is how you would search for packages providing @file{.service} files: @example $ guix locate -g '*.service' man-db@@2.11.1 @dots{}/lib/systemd/system/man-db.service wpa-supplicant@@2.10 @dots{}/system-services/fi.w1.wpa_supplicant1.service @end example The @command{guix locate} command relies on a database that maps file names to package names. By default, it automatically creates that database if it does not exist yet by traversing packages available @emph{locally}, which can take a few minutes (depending on the size of your store and the speed of your storage device). @quotation Note For now, @command{guix locate} builds its database based on purely local knowledge---meaning that you will not find packages that never reached your store. Eventually it will support downloading a pre-built database so you can potentially find more packages. @end quotation By default, @command{guix locate} first tries to look for a system-wide database, usually under @file{/var/cache/guix/locate}; if it does not exist or is too old, it falls back to the per-user database, by default under @file{~/.cache/guix/locate}. On a multi-user system, administrators may want to periodically update the system-wide database so that all users can benefit from it, for instance by setting up @code{package-database-service-type} (@pxref{File Search Services, @code{package-database-service-type}}). The general syntax is: @example guix locate [@var{options}@dots{}] @var{file}@dots{} @end example @noindent ... where @var{file} is the name of a file to search for (specifically, the ``base name'' of the file: files whose parent directories are called @var{file} are not matched). The available options are as follows: @table @code @item --glob @item -g Interpret @var{file}@dots{} as @dfn{glob patterns}---patterns that may include wildcards, such as @samp{*.scm} to denote all files ending in @samp{.scm}. @item --stats Display database statistics. @item --update @itemx -u Update the file database. By default, the database is automatically updated when it is too old. @item --clear Clear the database and re-populate it. This option lets you start anew, ensuring old data is removed from the database, which also avoids having an endlessly growing database. By default @command{guix locate} automatically does that periodically, though infrequently. @item --database=@var{file} Use @var{file} as the database, creating it if necessary. By default, @command{guix locate} picks the database under @file{~/.cache/guix} or @file{/var/cache/guix}, whichever is the most recent one. @item --method=@var{method} @itemx -m @var{method} Use @var{method} to select the set of packages to index. Possible values are: @table @code @item manifests This is the default method: it works by traversing profiles on the machine and recording packages it encounters---packages you or other users of the machine installed, directly or indirectly. It is fast but it can miss other packages available in the store but not referred to by any profile. @item store This is a slower but more exhaustive method: it checks among all the existing packages those that are available in the store and records them. @end table @end table @node Invoking guix gc @section Invoking @command{guix gc} @cindex garbage collector @cindex disk space @cindex @command{guix gc} Packages that are installed, but not used, may be @dfn{garbage-collected}. The @command{guix gc} command allows users to explicitly run the garbage collector to reclaim space from the @file{/gnu/store} directory. It is the @emph{only} way to remove files from @file{/gnu/store}---removing files or directories manually may break it beyond repair! @cindex GC roots @cindex garbage collector roots The garbage collector has a set of known @dfn{roots}: any file under @file{/gnu/store} reachable from a root is considered @dfn{live} and cannot be deleted; any other file is considered @dfn{dead} and may be deleted. The set of garbage collector roots (``GC roots'' for short) includes default user profiles; by default, the symlinks under @file{/var/guix/gcroots} represent these GC roots. New GC roots can be added with @command{guix build --root}, for example (@pxref{Invoking guix build}). The @command{guix gc --list-roots} command lists them. Prior to running @code{guix gc --collect-garbage} to make space, it is often useful to remove old generations from user profiles; that way, old package builds referenced by those generations can be reclaimed. This is achieved by running @code{guix package --delete-generations} (@pxref{Invoking guix package}). Our recommendation is to run a garbage collection periodically, or when you are short on disk space. For instance, to guarantee that at least 5@tie{}GB are available on your disk, simply run: @example guix gc -F 5G @end example It is perfectly safe to run as a non-interactive periodic job (@pxref{Scheduled Job Execution}, for how to set up such a job). Running @command{guix gc} with no arguments will collect as much garbage as it can, but that is often inconvenient: you may find yourself having to rebuild or re-download software that is ``dead'' from the GC viewpoint but that is necessary to build other pieces of software---e.g., the compiler tool chain. The @command{guix gc} command has three modes of operation: it can be used to garbage-collect any dead files (the default), to delete specific files (the @option{--delete} option), to print garbage-collector information, or for more advanced queries. The garbage collection options are as follows: @table @code @item --collect-garbage[=@var{min}] @itemx -C [@var{min}] Collect garbage---i.e., unreachable @file{/gnu/store} files and sub-directories. This is the default operation when no option is specified. When @var{min} is given, stop once @var{min} bytes have been collected. @var{min} may be a number of bytes, or it may include a unit as a suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}). When @var{min} is omitted, collect all the garbage. @item --free-space=@var{free} @itemx -F @var{free} Collect garbage until @var{free} space is available under @file{/gnu/store}, if possible; @var{free} denotes storage space, such as @code{500MiB}, as described above. When @var{free} or more is already available in @file{/gnu/store}, do nothing and exit immediately. @item --delete-generations[=@var{duration}] @itemx -d [@var{duration}] Before starting the garbage collection process, delete all the generations older than @var{duration}, for all the user profiles and home environment generations; when run as root, this applies to all the profiles @emph{of all the users}. For example, this command deletes all the generations of all your profiles that are older than 2 months (except generations that are current), and then proceeds to free space until at least 10 GiB are available: @example guix gc -d 2m -F 10G @end example @item --delete @itemx -D Attempt to delete all the store files and directories specified as arguments. This fails if some of the files are not in the store, or if they are still live. @item --list-failures List store items corresponding to cached build failures. This prints nothing unless the daemon was started with @option{--cache-failures} (@pxref{Invoking guix-daemon, @option{--cache-failures}}). @item --list-roots List the GC roots owned by the user; when run as root, list @emph{all} the GC roots. @item --list-busy List store items in use by currently running processes. These store items are effectively considered GC roots: they cannot be deleted. @item --clear-failures Remove the specified store items from the failed-build cache. Again, this option only makes sense when the daemon is started with @option{--cache-failures}. Otherwise, it does nothing. @item --list-dead Show the list of dead files and directories still present in the store---i.e., files and directories no longer reachable from any root. @item --list-live Show the list of live store files and directories. @end table In addition, the references among existing store files can be queried: @table @code @item --references @itemx --referrers @cindex package dependencies List the references (respectively, the referrers) of store files given as arguments. @item --requisites @itemx -R @cindex closure List the requisites of the store files passed as arguments. Requisites include the store files themselves, their references, and the references of these, recursively. In other words, the returned list is the @dfn{transitive closure} of the store files. @xref{Invoking guix size}, for a tool to profile the size of the closure of an element. @xref{Invoking guix graph}, for a tool to visualize the graph of references. @item --derivers @cindex derivation Return the derivation(s) leading to the given store items (@pxref{Derivations}). For example, this command: @example guix gc --derivers $(guix package -I ^emacs$ | cut -f4) @end example @noindent returns the @file{.drv} file(s) leading to the @code{emacs} package installed in your profile. Note that there may be zero matching @file{.drv} files, for instance because these files have been garbage-collected. There can also be more than one matching @file{.drv} due to fixed-output derivations. @end table Lastly, the following options allow you to check the integrity of the store and to control disk usage. @table @option @item --verify[=@var{options}] @cindex integrity, of the store @cindex integrity checking Verify the integrity of the store. By default, make sure that all the store items marked as valid in the database of the daemon actually exist in @file{/gnu/store}. When provided, @var{options} must be a comma-separated list containing one or more of @code{contents} and @code{repair}. When passing @option{--verify=contents}, the daemon computes the content hash of each store item and compares it against its hash in the database. Hash mismatches are reported as data corruptions. Because it traverses @emph{all the files in the store}, this command can take a long time, especially on systems with a slow disk drive. @cindex repairing the store @cindex corruption, recovering from Using @option{--verify=repair} or @option{--verify=contents,repair} causes the daemon to try to repair corrupt store items by fetching substitutes for them (@pxref{Substitutes}). Because repairing is not atomic, and thus potentially dangerous, it is available only to the system administrator. A lightweight alternative, when you know exactly which items in the store are corrupt, is @command{guix build --repair} (@pxref{Invoking guix build}). @item --optimize @cindex deduplication Optimize the store by hard-linking identical files---this is @dfn{deduplication}. The daemon performs deduplication after each successful build or archive import, unless it was started with @option{--disable-deduplication} (@pxref{Invoking guix-daemon, @option{--disable-deduplication}}). Thus, this option is primarily useful when the daemon was running with @option{--disable-deduplication}. @item --vacuum-database @cindex vacuum the store database @comment Avoid words like 'repair,' 'compress,' and 'optimize.' Guix uses an sqlite database to keep track of the items in (@pxref{The Store}). Over time it is possible that the database may grow to a large size and become fragmented. As a result, one may wish to clear the freed space and join the partially used pages in the database left behind from removed packages or after running the garbage collector. Running @command{sudo guix gc --vacuum-database} will lock the database and @code{VACUUM} the store, defragmenting the database and purging freed pages, unlocking the database when it finishes. @end table @node Invoking guix pull @section Invoking @command{guix pull} @cindex upgrading Guix @cindex updating Guix @cindex @command{guix pull} @cindex pull @cindex security, @command{guix pull} @cindex authenticity, of code obtained with @command{guix pull} Packages are installed or upgraded to the latest version available in the distribution currently available on your local machine. To update that distribution, along with the Guix tools, you must run @command{guix pull}: the command downloads the latest Guix source code and package descriptions, and deploys it. Source code is downloaded from a @uref{https://git-scm.com/book/en/, Git} repository, by default the official GNU@tie{}Guix repository, though this can be customized. @command{guix pull} ensures that the code it downloads is @emph{authentic} by verifying that commits are signed by Guix developers. Specifically, @command{guix pull} downloads code from the @dfn{channels} (@pxref{Channels}) specified by one of the following, in this order: @enumerate @item the @option{--channels} option; @item the user's @file{~/.config/guix/channels.scm} file, unless @option{-q} is passed; @item the system-wide @file{/etc/guix/channels.scm} file, unless @option{-q} is passed (on Guix System, this file can be declared in the operating system configuration, @pxref{guix-configuration-channels, @code{channels} field of @code{guix-configuration}}); @item the built-in default channels specified in the @code{%default-channels} variable. @end enumerate On completion, @command{guix package} will use packages and package versions from this just-retrieved copy of Guix. Not only that, but all the Guix commands and Scheme modules will also be taken from that latest version. New @command{guix} sub-commands added by the update also become available. Any user can update their Guix copy using @command{guix pull}, and the effect is limited to the user who ran @command{guix pull}. For instance, when user @code{root} runs @command{guix pull}, this has no effect on the version of Guix that user @code{alice} sees, and vice versa. The result of running @command{guix pull} is a @dfn{profile} available under @file{~/.config/guix/current} containing the latest Guix. The @option{--list-generations} or @option{-l} option lists past generations produced by @command{guix pull}, along with details about their provenance: @example $ guix pull -l Generation 1 Jun 10 2018 00:18:18 guix 65956ad repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe Generation 2 Jun 11 2018 11:02:49 guix e0cc7f6 repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d Generation 3 Jun 13 2018 23:31:07 (current) guix 844cc1c repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: 844cc1c8f394f03b404c5bb3aee086922373490c @end example @xref{Invoking guix describe, @command{guix describe}}, for other ways to describe the current status of Guix. This @code{~/.config/guix/current} profile works exactly like the profiles created by @command{guix package} (@pxref{Invoking guix package}). That is, you can list generations, roll back to the previous generation---i.e., the previous Guix---and so on: @example $ guix pull --roll-back switched from generation 3 to 2 $ guix pull --delete-generations=1 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link @end example You can also use @command{guix package} (@pxref{Invoking guix package}) to manage the profile by naming it explicitly: @example $ guix package -p ~/.config/guix/current --roll-back switched from generation 3 to 2 $ guix package -p ~/.config/guix/current --delete-generations=1 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link @end example The @command{guix pull} command is usually invoked with no arguments, but it supports the following options: @table @code @item --url=@var{url} @itemx --commit=@var{commit} @itemx --branch=@var{branch} Download code for the @code{guix} channel from the specified @var{url}, at the given @var{commit} (a valid Git commit ID represented as a hexadecimal string or the name of a tag), or @var{branch}. @cindex @file{channels.scm}, configuration file @cindex configuration file for channels These options are provided for convenience, but you can also specify your configuration in the @file{~/.config/guix/channels.scm} file or using the @option{--channels} option (see below). @item --channels=@var{file} @itemx -C @var{file} Read the list of channels from @var{file} instead of @file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}. @var{file} must contain Scheme code that evaluates to a list of channel objects. @xref{Channels}, for more information. @item --no-channel-files @itemx -q Inhibit loading of the user and system channel files, @file{~/.config/guix/channels.scm} and @file{/etc/guix/channels.scm}. @cindex channel news @item --news @itemx -N Display news written by channel authors for their users for changes made since the previous generation (@pxref{Channels, Writing Channel News}). When @option{--details} is passed, additionally display new and upgraded packages. You can view that information for previous generations with @command{guix pull -l}. @item --list-generations[=@var{pattern}] @itemx -l [@var{pattern}] List all the generations of @file{~/.config/guix/current} or, if @var{pattern} is provided, the subset of generations that match @var{pattern}. The syntax of @var{pattern} is the same as with @code{guix package --list-generations} (@pxref{Invoking guix package}). By default, this prints information about the channels used in each revision as well as the corresponding news entries. If you pass @option{--details}, it will also print the list of packages added and upgraded in each generation compared to the previous one. @item --details Instruct @option{--list-generations} or @option{--news} to display more information about the differences between subsequent generations---see above. @item --roll-back @cindex rolling back @cindex undoing transactions @cindex transactions, undoing Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e., undo the last transaction. @item --switch-generation=@var{pattern} @itemx -S @var{pattern} @cindex generations Switch to a particular generation defined by @var{pattern}. @var{pattern} may be either a generation number or a number prefixed with ``+'' or ``-''. The latter means: move forward/backward by a specified number of generations. For example, if you want to return to the latest generation after @option{--roll-back}, use @option{--switch-generation=+1}. @item --delete-generations[=@var{pattern}] @itemx -d [@var{pattern}] When @var{pattern} is omitted, delete all generations except the current one. This command accepts the same patterns as @option{--list-generations}. When @var{pattern} is specified, delete the matching generations. When @var{pattern} specifies a duration, generations @emph{older} than the specified duration match. For instance, @option{--delete-generations=1m} deletes generations that are more than one month old. If the current generation matches, it is @emph{not} deleted. Note that deleting generations prevents rolling back to them. Consequently, this command must be used with care. @xref{Invoking guix describe}, for a way to display information about the current generation only. @item --profile=@var{profile} @itemx -p @var{profile} Use @var{profile} instead of @file{~/.config/guix/current}. @item --dry-run @itemx -n Show which channel commit(s) would be used and what would be built or substituted but do not actually do it. @item --allow-downgrades Allow pulling older or unrelated revisions of channels than those currently in use. @cindex downgrade attacks, protection against By default, @command{guix pull} protects against so-called ``downgrade attacks'' whereby the Git repository of a channel would be reset to an earlier or unrelated revision of itself, potentially leading you to install older, known-vulnerable versions of software packages. @quotation Note Make sure you understand its security implications before using @option{--allow-downgrades}. @end quotation @item --disable-authentication Allow pulling channel code without authenticating it. @cindex authentication, of channel code By default, @command{guix pull} authenticates code downloaded from channels by verifying that its commits are signed by authorized developers, and raises an error if this is not the case. This option instructs it to not perform any such verification. @quotation Note Make sure you understand its security implications before using @option{--disable-authentication}. @end quotation @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the system type of the build host. @item --bootstrap Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers. @end table The @dfn{channel} mechanism allows you to instruct @command{guix pull} which repository and branch to pull from, as well as @emph{additional} repositories containing package modules that should be deployed. @xref{Channels}, for more information. In addition, @command{guix pull} supports all the common build options (@pxref{Common Build Options}). @node Invoking guix time-machine @section Invoking @command{guix time-machine} @cindex @command{guix time-machine} @cindex pinning, channels @cindex replicating Guix @cindex reproducibility, of Guix The @command{guix time-machine} command provides access to other revisions of Guix, for example to install older versions of packages, or to reproduce a computation in an identical environment. The revision of Guix to be used is defined by a commit or by a channel description file created by @command{guix describe} (@pxref{Invoking guix describe}). Let's assume that you want to travel to those days of November 2020 when version 1.2.0 of Guix was released and, once you're there, run the @command{guile} of that time: @example guix time-machine --commit=v1.2.0 -- \ environment -C --ad-hoc guile -- guile @end example The command above fetches Guix@tie{}1.2.0 (and possibly other channels specified by your @file{channels.scm} configuration files---see below) and runs its @command{guix environment} command to spawn an environment in a container running @command{guile} (@command{guix environment} has since been subsumed by @command{guix shell}; @pxref{Invoking guix shell}). It's like driving a DeLorean@footnote{If you don't know what a DeLorean is, consider traveling back to the 1980's. (@uref{https://www.imdb.com/title/tt0088763/, Back to the Future (1985)})}! The first @command{guix time-machine} invocation can be expensive: it may have to download or even build a large number of packages; the result is cached though and subsequent commands targeting the same commit are almost instantaneous. As for @command{guix pull}, in the absence of any options, @command{time-machine} fetches the latest commits of the channels specified in @file{~/.config/guix/channels.scm}, @file{/etc/guix/channels.scm}, or the default channels; the @option{-q} option lets you ignore these configuration files. The command: @example guix time-machine -q -- build hello @end example will thus build the package @code{hello} as defined in the main branch of Guix, without any additional channel, which is in general a newer revision of Guix than you have installed. Time travel works in both directions! @quotation Note The history of Guix is immutable and @command{guix time-machine} provides the exact same software as they are in a specific Guix revision. Naturally, no security fixes are provided for old versions of Guix or its channels. A careless use of @command{guix time-machine} opens the door to security vulnerabilities. @xref{Invoking guix pull, @option{--allow-downgrades}}. @end quotation @c Keep this paragraph in sync with 'time-machine.scm'. @command{guix time-machine} raises an error when attempting to travel to commits older than ``v0.16.0'' (commit @samp{4a0b87f0}), dated Dec.@: 2018. This is one of the oldest commits supporting the channel mechanism that makes ``time travel'' possible. @quotation Note Although it should technically be possible to travel to such an old commit, the ease to do so will largely depend on the availability of binary substitutes. When traveling to a distant past, some packages may not easily build from source anymore. One such example are old versions of OpenSSL whose tests would fail after a certain date. This particular problem can be worked around by running a @dfn{virtual build machine} with its clock set to the right time (@pxref{build-vm, Virtual Build Machines}). @end quotation The general syntax is: @example guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{} @end example where @var{command} and @var{arg}@dots{} are passed unmodified to the @command{guix} command of the specified revision. The @var{options} that define this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}): @table @code @item --url=@var{url} @itemx --commit=@var{commit} @itemx --branch=@var{branch} Use the @code{guix} channel from the specified @var{url}, at the given @var{commit} (a valid Git commit ID represented as a hexadecimal string or the name of a tag), or @var{branch}. @item --channels=@var{file} @itemx -C @var{file} Read the list of channels from @var{file}. @var{file} must contain Scheme code that evaluates to a list of channel objects. @xref{Channels} for more information. @item --no-channel-files @itemx -q Inhibit loading of the user and system channel files, @file{~/.config/guix/channels.scm} and @file{/etc/guix/channels.scm}. Thus, @command{guix time-machine -q} is equivalent to the following Bash command, using the ``process substitution'' syntax (@pxref{Process Substitution,,, bash, The GNU Bash Reference Manual}): @example guix time-machine -C <(echo %default-channels) @dots{} @end example @end table Note that @command{guix time-machine} can trigger builds of channels and their dependencies, and these are controlled by the standard build options (@pxref{Common Build Options}). @node Inferiors @section Inferiors @c TODO: Remove this once we're more confident about API stability. @quotation Note The functionality described here is a ``technology preview'' as of version @value{VERSION}. As such, the interface is subject to change. @end quotation @cindex inferiors @cindex composition of Guix revisions Sometimes you might need to mix packages from the revision of Guix you're currently running with packages available in a different revision of Guix. Guix @dfn{inferiors} allow you to achieve that by composing different Guix revisions in arbitrary ways. @cindex inferior packages Technically, an ``inferior'' is essentially a separate Guix process connected to your main Guix process through a REPL (@pxref{Invoking guix repl}). The @code{(guix inferior)} module allows you to create inferiors and to communicate with them. It also provides a high-level interface to browse and manipulate the packages that an inferior provides---@dfn{inferior packages}. When combined with channels (@pxref{Channels}), inferiors provide a simple way to interact with a separate revision of Guix. For example, let's assume you want to install in your profile the current @code{guile} package, along with the @code{guile-json} as it existed in an older revision of Guix---perhaps because the newer @code{guile-json} has an incompatible API and you want to run your code against the old API@. To do that, you could write a manifest for use by @code{guix package --manifest} (@pxref{Writing Manifests}); in that manifest, you would create an inferior for that old Guix revision you care about, and you would look up the @code{guile-json} package in the inferior: @lisp (use-modules (guix inferior) (guix channels) (srfi srfi-1)) ;for 'first' (define channels ;; This is the old revision from which we want to ;; extract guile-json. (list (channel (name 'guix) (url "https://git.savannah.gnu.org/git/guix.git") (commit "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) (define inferior ;; An inferior representing the above revision. (inferior-for-channels channels)) ;; Now create a manifest with the current "guile" package ;; and the old "guile-json" package. (packages->manifest (list (first (lookup-inferior-packages inferior "guile-json")) (specification->package "guile"))) @end lisp On its first run, @command{guix package --manifest} might have to build the channel you specified before it can create the inferior; subsequent runs will be much faster because the Guix revision will be cached. The @code{(guix inferior)} module provides the following procedures to open an inferior: @deffn {Procedure} inferior-for-channels channels [#:cache-directory] [#:ttl] Return an inferior for @var{channels}, a list of channels. Use the cache at @var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds. This procedure opens a new connection to the build daemon. As a side effect, this procedure may build or substitute binaries for @var{channels}, which can take time. @end deffn @deffn {Procedure} open-inferior directory [#:command "bin/guix"] Open the inferior Guix in @var{directory}, running @code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if the inferior could not be launched. @end deffn @cindex inferior packages The procedures listed below allow you to obtain and manipulate inferior packages. @deffn {Procedure} inferior-packages inferior Return the list of packages known to @var{inferior}. @end deffn @deffn {Procedure} lookup-inferior-packages inferior name [version] Return the sorted list of inferior packages matching @var{name} in @var{inferior}, with highest version numbers first. If @var{version} is true, return only packages with a version number prefixed by @var{version}. @end deffn @deffn {Procedure} inferior-package? obj Return true if @var{obj} is an inferior package. @end deffn @deffn {Procedure} inferior-package-name package @deffnx {Procedure} inferior-package-version package @deffnx {Procedure} inferior-package-synopsis package @deffnx {Procedure} inferior-package-description package @deffnx {Procedure} inferior-package-home-page package @deffnx {Procedure} inferior-package-location package @deffnx {Procedure} inferior-package-inputs package @deffnx {Procedure} inferior-package-native-inputs package @deffnx {Procedure} inferior-package-propagated-inputs package @deffnx {Procedure} inferior-package-transitive-propagated-inputs package @deffnx {Procedure} inferior-package-native-search-paths package @deffnx {Procedure} inferior-package-transitive-native-search-paths package @deffnx {Procedure} inferior-package-search-paths package These procedures are the counterpart of package record accessors (@pxref{package Reference}). Most of them work by querying the inferior @var{package} comes from, so the inferior must still be live when you call these procedures. @end deffn Inferior packages can be used transparently like any other package or file-like object in G-expressions (@pxref{G-Expressions}). They are also transparently handled by the @code{packages->manifest} procedure, which is commonly used in manifests (@pxref{Invoking guix package, the @option{--manifest} option of @command{guix package}}). Thus you can insert an inferior package pretty much anywhere you would insert a regular package: in manifests, in the @code{packages} field of your @code{operating-system} declaration, and so on. @node Invoking guix describe @section Invoking @command{guix describe} @cindex reproducibility @cindex replicating Guix @cindex @command{guix describe} Often you may want to answer questions like: ``Which revision of Guix am I using?'' or ``Which channels am I using?'' This is useful information in many situations: if you want to @emph{replicate} an environment on a different machine or user account, if you want to report a bug or to determine what change in the channels you are using caused it, or if you want to record your system state for reproducibility purposes. The @command{guix describe} command answers these questions. When run from a @command{guix pull}ed @command{guix}, @command{guix describe} displays the channel(s) that it was built from, including their repository URL and commit IDs (@pxref{Channels}): @example $ guix describe Generation 10 Sep 03 2018 17:32:44 (current) guix e0fa68c repository URL: https://git.savannah.gnu.org/git/guix.git branch: master commit: e0fa68c7718fffd33d81af415279d6ddb518f727 @end example If you're familiar with the Git version control system, this is similar in spirit to @command{git describe}; the output is also similar to that of @command{guix pull --list-generations}, but limited to the current generation (@pxref{Invoking guix pull, the @option{--list-generations} option}). Because the Git commit ID shown above una