aboutsummaryrefslogtreecommitdiff
path: root/tests/bournish.scm
diff options
context:
space:
mode:
authorKyle Meyer <kyle@kyleam.com>2021-01-27 19:55:12 -0500
committerEfraim Flashner <efraim@flashner.co.il>2021-01-28 20:34:45 +0200
commit7495843d3ca08f33beb0f057a9d672899184a8e1 (patch)
treed371dbbd0ea94407579f76a4246e4fa67a9bc8ef /tests/bournish.scm
parentc2538db5617032788ac2f140496d00d8107579c8 (diff)
downloadguix-7495843d3ca08f33beb0f057a9d672899184a8e1.tar.gz
guix-7495843d3ca08f33beb0f057a9d672899184a8e1.zip
gnu: git-annex: Update to 8.20210127.
* gnu/packages/haskell-apps.scm (git-annex): Update to 8.20210127. Signed-off-by: Efraim Flashner <efraim@flashner.co.il>
Diffstat (limited to 'tests/bournish.scm')
0 files changed, 0 insertions, 0 deletions
generated by cgit
yright @copyright{} 2020 John Soo@* Copyright @copyright{} 2020 Jonathan Brielmaier@* Copyright @copyright{} 2020 Edgar Vincent@* Copyright @copyright{} 2021, 2022 Maxime Devos@* Copyright @copyright{} 2021 B. Wilson@* Copyright @copyright{} 2021 Xinglu Chen@* Copyright @copyright{} 2021 Raghav Gururajan@* Copyright @copyright{} 2021 Domagoj Stolfa@* Copyright @copyright{} 2021 Hui Lu@* Copyright @copyright{} 2021 pukkamustard@* Copyright @copyright{} 2021 Alice Brenon@* Copyright @copyright{} 2021-2023 Josselin Poiret@* Copyright @copyright{} 2021, 2023 muradm@* Copyright @copyright{} 2021, 2022 Andrew Tropin@* Copyright @copyright{} 2021 Sarah Morgensen@* Copyright @copyright{} 2022 Remco van 't Veer@* Copyright @copyright{} 2022 Aleksandr Vityazev@* Copyright @copyright{} 2022 Philip M@sup{c}Grath@* Copyright @copyright{} 2022 Karl Hallsby@* Copyright @copyright{} 2022 Justin Veilleux@* Copyright @copyright{} 2022 Reily Siegel@* Copyright @copyright{} 2022 Simon Streit@* Copyright @copyright{} 2022 (@* Copyright @copyright{} 2022 John Kehayias@* Copyright @copyright{} 2022⁠–⁠2023 Bruno Victal@* Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@* Copyright @copyright{} 2023-2024 Giacomo Leidi@* Copyright @copyright{} 2022 Antero Mejr@* Copyright @copyright{} 2023 Karl Hallsby@* Copyright @copyright{} 2023 Nathaniel Nicandro@* Copyright @copyright{} 2023 Tanguy Le Carrour@* Copyright @copyright{} 2023, 2024 Zheng Junjie@* Copyright @copyright{} 2023 Brian Cully@* Copyright @copyright{} 2023 Felix Lechner@* Copyright @copyright{} 2023 Foundation Devices, Inc.@* Copyright @copyright{} 2023 Thomas Ieong@* Copyright @copyright{} 2023 Saku Laesvuori@* Copyright @copyright{} 2023 Graham James Addis@* Copyright @copyright{} 2023, 2024 Tomas Volf@* Copyright @copyright{} 2024 Herman Rimm@* Copyright @copyright{} 2024 Matthew Trzcinski@* Copyright @copyright{} 2024 Richard Sent@* Copyright @copyright{} 2024 Dariqq@* Copyright @copyright{} 2024 Denis 'GNUtoo' Carikli@* Copyright @copyright{} 2024 Fabio Natali@* Copyright @copyright{} 2024 Arnaud Daby-Seesaram@* Copyright @copyright{} 2024 Nigko Yerden@* Copyright @copyright{} 2024 Troy Figiel@* Copyright @copyright{} 2024 Sharlatan Hellseher@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end copying @dircategory System administration @direntry * 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. * Sway: Sway window manager. Setting up the Sway configuration. * 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 x86_64-gnu @uref{https://hurd.gnu.org, GNU/Hurd} on the @code{x86_64} Intel/AMD 64-bit architecture. This configuration is even more experimental and under heavy upstream development. @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. @cindex nsncd, replacement for nscd Note that @command{nscd} is no longer provided on some GNU/Linux distros, such as Arch Linux (as of Dec. 2024). @command{nsncd} can be used as a drop-in-replacement. See @uref{https://github.com/twosigma/nsncd, the nsncd repository} and @uref{https://flokli.de/posts/2022-11-18-nsncd/, this blog post} for more information. @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{W