aboutsummaryrefslogtreecommitdiff
path: root/.dir-locals.el
diff options
context:
space:
mode:
Diffstat (limited to '.dir-locals.el')
0 files changed, 0 insertions, 0 deletions
generated by cgit
2019, 2020, 2021, 2022 Marius Bakke@* Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@* Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023, 2024 Maxim Cournoyer@* Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@* Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 Andy Wingo@* Copyright @copyright{} 2017, 2018, 2019, 2020, 2023, 2024, 2025 Arun Isaac@* Copyright @copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* Copyright @copyright{} 2018, 2021, 2023 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright @copyright{} 2018, 2019 Gábor Boskovits@* Copyright @copyright{} 2018, 2019, 2020, 2022, 2023, 2024 Florian Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} 2018 Alex Vong@* Copyright @copyright{} 2019 Josh Holland@* Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@* Copyright @copyright{} 2019 Ivan Petkov@* Copyright @copyright{} 2019 Jakob L. Kreuze@* Copyright @copyright{} 2019 Kyle Andrews@* Copyright @copyright{} 2019 Alex Griffin@* Copyright @copyright{} 2019, 2020, 2021, 2022 Guillaume Le Vaillant@* Copyright @copyright{} 2020 Liliana Marie Prikler@* Copyright @copyright{} 2019, 2020, 2021, 2022, 2023 Simon Tournier@* Copyright @copyright{} 2020 Wiktor Żelazny@* Copyright @copyright{} 2020 Damien Cassou@* Copyright @copyright{} 2020 Jakub Kądziołka@* Copyright @copyright{} 2020 Jack Hill@* Copyright @copyright{} 2020 Naga Malleswari@* Copyright @copyright{} 2020, 2021 Brice Waegeneire@* Copyright @copyright{} 2020 R Veera Kumar@* Copyright @copyright{} 2020, 2021, 2022 Pierre Langlois@* Copyright @copyright{} 2020 pinoaffe@* Copyright @copyright{} 2020, 2023 André Batista@* Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@* Copyright @copyright{} 2020 raingloom@* Copyright @copyright{} 2020 Daniel Brooks@* Copyright @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-2025 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@* Copyright @copyright{} 2024 45mg@* Copyright @copyright{} 2025 Sören Tempel@* 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:: Archiving and deleting old logs. * 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{Writing Manifests}, for information on how to write a manifest. @xref{export-manifest, @option{--export-manifest}}, to learn how to obtain a manifest file from an existing profile. @item --roll-back @cindex rolling back @cindex undoing transactions @cindex transactions, undoing Roll back to the previous @dfn{generation} of the profile---i.e., undo the last transaction. When combined with options such as @option{--install}, roll back occurs before any other actions. When rolling back from the first generation that actually contains installed packages, the profile is made to point to the @dfn{zeroth generation}, which contains no files apart from its own metadata. After having rolled back, installing, removing, or upgrading packages overwrites previous future generations. Thus, the history of the generations in a profile is always linear. @item --switch-generation=@var{pattern} @itemx -S @var{pattern} @cindex generations Switch to a particular generation defined by @var{pattern}. @var{pattern} may be either a generation number or a number prefixed with ``+'' or ``-''. The latter means: move forward/backward by a specified number of generations. For example, if you want to return to the latest generation after @option{--roll-back}, use @option{--switch-generation=+1}. The difference between @option{--roll-back} and @option{--switch-generation=-1} is that @option{--switch-generation} will not make a zeroth generation, so if a specified generation does not exist, the current generation will not be changed. @item --search-paths[=@var{kind}] @cindex search paths Report environment variable definitions, in Bash syntax, that may be needed in order to use the set of installed packages. These environment variables are used to specify @dfn{search paths} for files used by some of the installed packages. For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH} environment variables to be defined so it can look for headers and libraries in the user's profile (@pxref{Environment Variables,,, gcc, Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C library are installed in the profile, then @option{--search-paths} will suggest setting these variables to @file{@var{profile}/include} and @file{@var{profile}/lib}, respectively (@pxref{Search Paths}, for info on search path specifications associated with packages.) The typical use case is to define these environment variables in the shell: @example $ eval $(guix package --search-paths) @end example @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix}, meaning that the returned environment variable definitions will either be exact settings, or prefixes or suffixes of the current value of these variables. When omitted, @var{kind} defaults to @code{exact}. This option can also be used to compute the @emph{combined} search paths of several profiles. Consider this example: @example $ guix package -p foo -i guile $ guix package -p bar -i guile-json $ guix package -p foo -p bar --search-paths @end example The last command above reports about the @env{GUILE_LOAD_PATH} variable, even though, taken individually, neither @file{foo} nor @file{bar} would lead to that recommendation. @cindex profile, choosing @item --profile=@var{profile} @itemx -p @var{profile} Use @var{profile} instead of the user's default profile. @var{profile} must be the name of a file that will be created upon completion. Concretely, @var{profile} will be a mere symbolic link (``symlink'') pointing to the actual profile where packages are installed: @example $ guix install hello -p ~/code/my-profile @dots{} $ ~/code/my-profile/bin/hello Hello, world! @end example All it takes to get rid of the profile is to remove this symlink and its siblings that point to specific generations: @example $ rm ~/code/my-profile ~/code/my-profile-*-link @end example @item --list-profiles List all the user's profiles: @example $ guix package --list-profiles /home/charlie/.guix-profile /home/charlie/code/my-profile /home/charlie/code/devel-profile /home/charlie/tmp/test @end example When running as root, list all the profiles of all the users. @cindex collisions, in a profile @cindex colliding packages in profiles @cindex profile collisions @item --allow-collisions Allow colliding packages in the new profile. Use at your own risk! By default, @command{guix package} reports as an error @dfn{collisions} in the profile. Collisions happen when two or more different versions or variants of a given package end up in the profile. @item --bootstrap Use the bootstrap Guile to build the profile. This option is only useful to distribution developers. @end table In addition to these actions, @command{guix package} supports the following options to query the current state of a profile, or the availability of packages: @table @option @item --search=@var{regexp} @itemx -s @var{regexp} @anchor{guix-search} @cindex searching for packages List the available packages whose name, synopsis, or description matches @var{regexp} (in a case-insensitive fashion), sorted by relevance. Print all the metadata of matching packages in @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). This allows specific fields to be extracted using the @command{recsel} command, for instance: @example $ guix package -s malloc | recsel -p name,version,relevance name: jemalloc version: 4.5.0 relevance: 6 name: glibc version: 2.25 relevance: 1 name: libgc version: 7.6.0 relevance: 1 @end example Similarly, to show the name of all the packages available under the terms of the GNU@tie{}LGPL version 3: @example $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' name: elfutils name: gmp @dots{} @end example It is also possible to refine search results using several @code{-s} flags to @command{guix package}, or several arguments to @command{guix search}. For example, the following command returns a list of board games (this time using the @command{guix search} alias): @example $ guix search '\<board\>' game | recsel -p name name: gnubg @dots{} @end example If we were to omit @code{-s game}, we would also get software packages that deal with printed circuit boards; removing the angle brackets around @code{board} would further add packages that have to do with keyboards. And now for a more elaborate example. The following command searches for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby libraries, and prints the name and synopsis of the matching packages: @example $ guix search crypto library | \ recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis @end example @noindent @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more information on @dfn{selection expressions} for @code{recsel -e}. @item --show=@var{package} Show details about @var{package}, taken from the list of available packages, in @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). @example $ guix package --show=guile | recsel -p name,version name: guile version: 3.0.5 name: guile version: 3.0.2 name: guile version: 2.2.7 @dots{} @end example You may also specify the full name of a package to only get details about a specific version of it (this time using the @command{guix show} alias): @example $ guix show guile@@3.0.5 | recsel -p name,version name: guile version: 3.0.5 @end example @item --list-installed[=@var{regexp}] @itemx -I [@var{regexp}] List the currently installed packages in the specified profile, with the most recently installed packages shown last. When @var{regexp} is specified, list only installed packages whose name matches @var{regexp}. For each installed package, print the following items, separated by tabs: the package name, its version string, the part of the package that is installed (for instance, @code{out} for the default output, @code{include} for its headers, etc.), and the path of this package in the store. @item --list-available[=@var{regexp}] @itemx -A [@var{regexp}] List packages currently available in the distribution for this system (@pxref{GNU Distribution}). When @var{regexp} is specified, list only available packages whose name matches @var{regexp}. For each package, print the following items separated by tabs: its name, its version string, the parts of the package (@pxref{Packages with Multiple Outputs}), and the source location of its definition. @item --list-generations[=@var{pattern}] @itemx -l [@var{pattern}] @cindex generations Return a list of generations along with their creation dates; for each generation, show the installed packages, with the most recently installed packages shown last. Note that the zeroth generation is never shown. For each installed package, print the following items, separated by tabs: the name of a package, its version string, the part of the package that is installed (@pxref{Packages with Multiple Outputs}), and the location of this package in the store. When @var{pattern} is used, the command returns only matching generations. Valid patterns include: @itemize @item @emph{Integers and comma-separated integers}. Both patterns denote generation numbers. For instance, @option{--list-generations=1} returns the first one. And @option{--list-generations=1,8,2} outputs three generations in the specified order. Neither spaces nor trailing commas are allowed. @item @emph{Ranges}. @option{--list-generations=2..9} prints the specified generations and everything in between. Note that the start of a range must be smaller than its end. It is also possible to omit the endpoint. For example, @option{--list-generations=2..}, returns all generations starting from the second one. @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks, or months by passing an integer along with the first letter of the duration. For example, @option{--list-generations=20d} lists generations that are up to 20 days old. @end itemize @item --delete-generations[=@var{pattern}] @itemx -d [@var{pattern}] When @var{pattern} is omitted, delete all generations except the current one. This command accepts the same patterns as @option{--list-generations}. When @var{pattern} is specified, delete the matching generations. When @var{pattern} specifies a duration, generations @emph{older} than the specified duration match. For instance, @option{--delete-generations=1m} deletes generations that are more than one month old. If the current generation matches, it is @emph{not} deleted. Also, the zeroth generation is never deleted. Note that deleting generations prevents rolling back to them. Consequently, this command must be used with care. @cindex manifest, exporting @anchor{export-manifest} @item --export-manifest Write to standard output a manifest suitable for @option{--manifest} corresponding to the chosen profile(s). This option is meant to help you migrate from the ``imperative'' operating mode---running @command{guix install}, @command{guix upgrade}, etc.---to the declarative mode that @option{--manifest} offers. Be aware that the resulting manifest @emph{approximates} what your profile actually contains; for instance, depending on how your profile was created, it can refer to packages or package versions that are not exactly what you specified. Keep in mind that a manifest is purely symbolic: it only contains package names and possibly versions, and their meaning varies over time. If you wish to ``pin'' channels to the revisions that were used to build the profile(s), see @option{--export-channels} below. @cindex pinning, channel revisions of a profile @item --export-channels Write to standard output the list of channels used by the chosen profile(s), in a format suitable for @command{guix pull --channels} or @command{guix time-machine --channels} (@pxref{Channels}). Together with @option{--export-manifest}, this option provides information allowing you to replicate the current profile (@pxref{Replicating Guix}). However, note that the output of this command @emph{approximates} what was actually used to build this profile. In particular, a single profile might have been built from several different revisions of the same channel. In that case, @option{--export-manifest} chooses the last one and writes the list of other revisions in a comment. If you really need to pick packages from different channel revisions, you can use inferiors in your manifest to do so (@pxref{Inferiors}). Together with @option{--export-manifest}, this is a good starting point if you are willing to migrate from the ``imperative'' model to the fully declarative model consisting of a manifest file along with a channels file pinning the exact channel revision(s) you want. @end table Finally, since @command{guix package} may actually start build processes, it supports all the common build options (@pxref{Common Build Options}). It also supports package transformation options, such as @option{--with-source}, and preserves them across upgrades (@pxref{Package Transformation Options}). @node Substitutes @section Substitutes @cindex substitutes @cindex pre-built binaries Guix supports transparent source/binary deployment, which means that it can either build things locally, or download pre-built items from a server, or both. We call these pre-built items @dfn{substitutes}---they are substitutes for local build results. In many cases, downloading a substitute is much faster than building things locally. Substitutes can be anything resulting from a derivation build (@pxref{Derivations}). Of course, in the common case, they are pre-built package binaries, but source tarballs, for instance, which also result from derivation builds, can be available as substitutes. @menu * Official Substitute Servers:: One particular source of substitutes. * Substitute Server Authorization:: How to enable or disable substitutes. * Getting Substitutes from Other Servers:: Substitute diversity. * Substitute Authentication:: How Guix verifies substitutes. * Proxy Settings:: How to get substitutes via proxy. * Substitution Failure:: What happens when substitution fails. * On Trusting Binaries:: How can you trust that binary blob? @end menu @node Official Substitute Servers @subsection Official Substitute Servers @cindex build farm @code{@value{SUBSTITUTE-SERVER-1}} and @code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build farms that build packages from Guix continuously for some architectures, and make them available as substitutes. These are the default source of substitutes; which can be overridden by passing the @option{--substitute-urls} option either to @command{guix-daemon} (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) or to client tools such as @command{guix package} (@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). Substitute URLs can be either HTTP or HTTPS. HTTPS is recommended because communications are encrypted; conversely, using HTTP makes all communications visible to an eavesdropper, who could use the information gathered to determine, for instance, whether your system has unpatched security vulnerabilities. Substitutes from the official build farms are enabled by default when using Guix System (@pxref{GNU Distribution}). However, they are disabled by default when using Guix on a foreign distribution, unless you have explicitly enabled them via one of the recommended installation steps (@pxref{Installation}). The following paragraphs describe how to enable or disable substitutes for the official build farm; the same procedure can also be used to enable substitutes for any other substitute server. @node Substitute Server Authorization @subsection Substitute Server Authorization @cindex security @cindex substitutes, authorization thereof @cindex access control list (ACL), for substitutes @cindex ACL (access control list), for substitutes To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you must add the relevant public key to the access control list (ACL) of archive imports, using the @command{guix archive} command (@pxref{Invoking guix archive}). Doing so implies that you trust the substitute server to not be compromised and to serve genuine substitutes. @quotation Note If you are using Guix System, you can skip this section: Guix System authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and @code{@value{SUBSTITUTE-SERVER-2}} by default. @end quotation The public keys for each of the project maintained substitute servers are installed along with Guix, in @code{@var{prefix}/share/guix/}, where @var{prefix} is the installation prefix of Guix. If you installed Guix from source, make sure you checked the GPG signature of @file{guix-@value{VERSION}.tar.gz}, which contains this public key file. Then, you can run something like this: @example # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub @end example Once this is in place, the output of a command like @code{guix build} should change from something like: @example $ guix build emacs --dry-run The following derivations would be built: /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv @dots{} @end example @noindent to something like: @example $ guix build emacs --dry-run 112.3 MB would be downloaded: /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7 @dots{} @end example @noindent The text changed from ``The following derivations would be built'' to ``112.3 MB would be downloaded''. This indicates that substitutes from the configured substitute servers are usable and will be downloaded, when possible, for future builds. @cindex substitutes, how to disable The substitute mechanism can be disabled globally by running @code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking guix-daemon}). It can also be disabled temporarily by passing the @option{--no-substitutes} option to @command{guix package}, @command{guix build}, and other command-line tools. @node Getting Substitutes from Other Servers @subsection Getting Substitutes from Other Servers @c Note: This section name appears in a hint printed by 'guix weather'. @cindex substitute servers, adding more Guix can look up and fetch substitutes from several servers. This is useful when you are using packages from additional channels for which the official server does not have substitutes but another server provides them. Another situation where this is useful is when you would prefer to download from your organization's substitute server, resorting to the official server only as a fallback or dismissing it altogether. You can give Guix a list of substitute server URLs and it will check them in the specified order. You also need to explicitly authorize the public keys of substitute servers to instruct Guix to accept the substitutes they sign. On Guix System, this is achieved by modifying the configuration of the @code{guix} service. Since the @code{guix} service is part of the default lists of services, @code{%base-services} and @code{%desktop-services}, you can use @code{modify-services} to change its configuration and add the URLs and substitute keys that you want (@pxref{Service Reference, @code{modify-services}}). As an example, suppose you want to fetch substitutes from @code{guix.example.org} and to authorize the signing key of that server, in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and @code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system configuration will look something like: @lisp (operating-system ;; @dots{} (services ;; Assume we're starting from '%desktop-services'. Replace it ;; with the list of services you're actually using. (modify-services %desktop-services (guix-service-type config => (guix-configuration (inherit config) (substitute-urls (append (list "https://guix.example.org") %default-substitute-urls)) (authorized-keys (append (list (local-file "./key.pub")) %default-authorized-guix-keys))))))) @end lisp This assumes that the file @file{key.pub} contains the signing key of @code{guix.example.org}. With this change in place in your operating system configuration file (say @file{/etc/config.scm}), you can reconfigure and restart the @code{guix-daemon} service or reboot so the changes take effect: @example $ sudo guix system reconfigure /etc/config.scm $ sudo herd restart guix-daemon @end example If you're running Guix on a ``foreign distro'', you would instead take the following steps to get substitutes from additional servers: @enumerate @item Edit the service configuration file for @code{guix-daemon}; when using systemd, this is normally @file{/etc/systemd/system/guix-daemon.service}. Add the @option{--substitute-urls} option on the @command{guix-daemon} command line and list the URLs of interest (@pxref{daemon-substitute-urls, @code{guix-daemon --substitute-urls}}): @example @dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}' @end example @item Restart the daemon. For systemd, it goes like this: @example systemctl daemon-reload systemctl restart guix-daemon.service @end example @item Authorize the key of the new server (@pxref{Invoking guix archive}): @example guix archive --authorize < key.pub @end example Again this assumes @file{key.pub} contains the public key that @code{guix.example.org} uses to sign substitutes. @end enumerate Now you're all set! Substitutes will be preferably taken from @code{https://guix.example.org}, using @code{@value{SUBSTITUTE-SERVER-1}} then @code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you can list as many substitute servers as you like, with the caveat that substitute lookup can be slowed down if too many servers need to be contacted. @quotation Troubleshooting To diagnose problems, you can run @command{guix weather}. For example, running: @example guix weather coreutils @end example @noindent not only tells you which of the currently-configured servers has substitutes for the @code{coreutils} package, it also reports whether one of these servers is unauthorized. @xref{Invoking guix weather}, for more information. @end quotation Note that there are also situations where one may want to add the URL of a substitute server @emph{without} authorizing its key. @xref{Substitute Authentication}, to understand this fine point. @node Substitute Authentication @subsection Substitute Authentication @cindex digital signatures Guix detects and raises an error when attempting to use a substitute that has been tampered with. Likewise, it ignores substitutes that are not signed, or that are not signed by one of the keys listed in the ACL. There is one exception though: if an unauthorized server provides substitutes that are @emph{bit-for-bit identical} to those provided by an authorized server, then the unauthorized server becomes eligible for downloads. For example, assume we have chosen two substitute servers with this option: @example --substitute-urls="https://a.example.org https://b.example.org" @end example @noindent @cindex reproducible builds If the ACL contains only the key for @samp{b.example.org}, and if @samp{a.example.org} happens to serve the @emph{exact same} substitutes, then Guix will download substitutes from @samp{a.example.org} because it comes first in the list and can be considered a mirror of @samp{b.example.org}. In practice, independent build machines usually produce the same binaries, thanks to bit-reproducible builds (see below). When using HTTPS, the server's X.509 certificate is @emph{not} validated (in other words, the server is not authenticated), contrary to what HTTPS clients such as Web browsers usually do. This is because Guix authenticates substitute information itself, as explained above, which is what we care about (whereas X.509 certificates are about authenticating bindings between domain names and public keys). @node Proxy Settings @subsection Proxy Settings @vindex http_proxy @vindex https_proxy Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and @env{https_proxy} environment variables can be set in the environment of @command{guix-daemon} and are honored for downloads of substitutes. Note that the value of those environment variables in the environment where @command{guix build}, @command{guix package}, and other client commands are run has @emph{absolutely no effect}. @node Substitution Failure @subsection Substitution Failure Even when a substitute for a derivation is available, sometimes the substitution attempt will fail. This can happen for a variety of reasons: the substitute server might be offline, the substitute may recently have been deleted, the connection might have been interrupted, etc. When substitutes are enabled and a substitute for a derivation is available, but the substitution attempt fails, Guix will attempt to build the derivation locally depending on whether or not @option{--fallback} was given (@pxref{fallback-option,, common build option @option{--fallback}}). Specifically, if @option{--fallback} was omitted, then no local build will be performed, and the derivation is considered to have failed. However, if @option{--fallback} was given, then Guix will attempt to build the derivation locally, and the success or failure of the derivation depends on the success or failure of the local build. Note that when substitutes are disabled or no substitute is available for the derivation in question, a local build will @emph{always} be performed, regardless of whether or not @option{--fallback} was given. To get an idea of how many substitutes are available right now, you can try running the @command{guix weather} command (@pxref{Invoking guix weather}). This command provides statistics on the substitutes provided by a server. @node On Trusting Binaries @subsection On Trusting Binaries @cindex trust, of pre-built binaries Today, each individual's control over their own computing is at the mercy of institutions, corporations, and groups with enough power and determination to subvert the computing infrastructure and exploit its weaknesses. While using substitutes can be convenient, we encourage users to also build on their own, or even run their own build farm, such that the project run substitute servers are less of an interesting target. One way to help is by publishing the software you build using @command{guix publish} so that others have one more choice of server to download substitutes from (@pxref{Invoking guix publish}). Guix has the foundations to maximize build reproducibility (@pxref{Features}). In most cases, independent builds of a given package or derivation should yield bit-identical results. Thus, through a diverse set of independent package builds, we can strengthen the integrity of our systems. The @command{guix challenge} command aims to help users assess substitute servers, and to assist developers in finding out about non-deterministic package builds (@pxref{Invoking guix challenge}). Similarly, the @option{--check} option of @command{guix build} allows users to check whether previously-installed substitutes are genuine by rebuilding them locally (@pxref{build-check, @command{guix build --check}}). In the future, we want Guix to have support to publish and retrieve binaries to/from other users, in a peer-to-peer fashion. If you would like to discuss this project, join us on @email{guix-devel@@gnu.org}. @node Packages with Multiple Outputs @section Packages with Multiple Outputs @cindex multiple-output packages @cindex package outputs @cindex outputs Often, packages defined in Guix have a single @dfn{output}---i.e., the source package leads to exactly one directory in the store. When running @command{guix install glibc}, one installs the default output of the GNU libc package; the default output is called @code{out}, but its name can be omitted as shown in this command. In this particular case, the default output of @code{glibc} contains all the C header files, shared libraries, static libraries, Info documentation, and other supporting files. Sometimes it is more appropriate to separate the various types of files produced from a single source package into separate outputs. For instance, the GLib C library (used by GTK+ and related packages) installs more than 20 MiB of reference documentation as HTML pages. To save space for users who do not need it, the documentation goes to a separate output, called @code{doc}. To install the main GLib output, which contains everything but the documentation, one would run: @example guix install glib @end example @cindex documentation The command to install its documentation is: @example guix install glib:doc @end example While the colon syntax works for command-line specification of package outputs, it will not work when using a package @emph{variable} in Scheme code. For example, to add the documentation of @code{glib} to the globally installed packages of an @code{operating-system} (see @ref{operating-system Reference}), a list of two items, the first one being the package @emph{variable} and the second one the name of the output to select (a string), must be used instead: @lisp (use-modules (gnu packages glib)) ;; glib-with-documentation is the Guile symbol for the glib package (operating-system ... (packages (append (list (list glib-with-documentation "doc")) %base-packages))) @end lisp Some packages install programs with different ``dependency footprints''. For instance, the WordNet package installs both command-line tools and graphical user interfaces (GUIs). The former depend solely on the C library, whereas the latter depend on Tcl/Tk and the underlying X libraries. In this case, we leave the command-line tools in the default output, whereas the GUIs are in a separate output. This allows users who do not need the GUIs to save space. The @command{guix size} command can help find out about such situations (@pxref{Invoking guix size}). @command{guix graph} can also be helpful (@pxref{Invoking guix graph}). There are several such multiple-output packages in the GNU distribution. Other conventional output names include @code{lib} for libraries and possibly header files, @code{bin} for stand-alone programs, and @code{debug} for debugging information (@pxref{Installing Debugging Files}). The outputs of a package are listed in the third column of the output of @command{guix package --list-available} (@pxref{Invoking guix package}). @node Invoking guix locate @section Invoking @command{guix locate} @cindex file, searching in packages @cindex file search @cindex searching for packages There's so much free software out there that sooner or later, you will need to search for packages. The @command{guix search} command that we've seen before (@pxref{Invoking guix package}) lets you search by keywords: @example guix search video editor @end example @cindex searching for packages, by file name Sometimes, you instead want to find which package provides a given file, and this is where @command{guix locate} comes in. Here is how you can find which package provides the @command{ls} command: @example $ guix locate ls coreutils@@9.1 /gnu/store/@dots{}-coreutils-9.1/bin/ls @end example Of course the command works for any file, not just commands: @example $ guix locate unistr.h icu4c@@71.1 /gnu/store/@dots{}/include/unicode/unistr.h libunistring@@1.0 /gnu/store/@dots{}/include/unistr.h @end example You may also specify @dfn{glob patterns} with wildcards. For example, here is how you would search for packages providing @file{.service} files: @example $ guix locate -g '*.service' man-db@@2.11.1 @dots{}/lib/systemd/system/man-db.service wpa-supplicant@@2.10 @dots{}/system-services/fi.w1.wpa_supplicant1.service @end example The @command{guix locate} command relies on a database that maps file names to package names. By default, it automatically creates that database if it does not exist yet by traversing packages available @emph{locally}, which can take a few minutes (depending on the size of your store and the speed of your storage device). @quotation Note For now, @command{guix locate} builds its database based on purely local knowledge---meaning that you will not find packages that never reached your store. Eventually it will support downloading a pre-built database so you can potentially find more packages. @end quotation By default, @command{guix locate} first tries to look for a system-wide database, usually under @file{/var/cache/guix/locate}; if it does not exist or is too old, it falls back to the per-user database, by default under @file{~/.cache/guix/locate}. On a multi-user system, administrators may want to periodically update the system-wide database so that all users can benefit from it, for instance by setting up @code{package-database-service-type} (@pxref{File Search Services, @code{package-database-service-type}}). The general syntax is: @example guix locate [@var{options}@dots{}] @var{file}@dots{} @end example @noindent ... where @var{file} is the name of a file to search for (specifically, the ``base name'' of the file: files whose parent directories are called @var{file} are not matched). The available options are as follows: @table @code @item --glob @item -g Interpret @var{file}@dots{} as @dfn{glob patterns}---patterns that may include wildcards, such as @samp{*.scm} to denote all files ending in @samp{.scm}. @item --stats Display database statistics. @item --update @itemx -u Update the file database. By default, the database is automatically updated when it is too old. @item --clear Clear the database and re-populate it. This option lets you start anew, ensuring old data is removed from the database, which also avoids having an endlessly growing database. By default @command{guix locate} automatically does that periodically, though infrequently. @item --database=@var{file} Use @var{file} as the database, creating it if necessary. By default, @command{guix locate} picks the database under @file{~/.cache/guix} or @file{/var/cache/guix}, whichever is the most recent one. @item --method=@var{method} @itemx -m @var{method} Use @var{method} to select the set of packages to index. Possible values are: @table @code @item manifests This is the default method: it works by traversing profiles on the machine and recording packages it encounters---packages you or other users of the machine installed, directly or indirectly. It is fast but it can miss other packages available in the store but not referred to by any profile. @item store This is a slower but more exhaustive method: it checks among all the existing packages those that are available in the store and records them. @end table @end table @node Invoking guix gc @section Invoking @command{guix gc} @cindex garbage collector @cindex disk space @cindex @command{guix gc} Packages that are installed, but not used, may be @dfn{garbage-collected}. The @command{guix gc} command allows users to explicitly run the garbage collector to reclaim space from the @file{/gnu/store} directory. It is the @emph{only} way to remove files from @file{/gnu/store}---removing files or directories manually may break it beyond repair! @cindex GC roots @cindex garbage collector roots The garbage collector has a set of known @dfn{roots}: any file under @file{/gnu/store} reachable from a root is considered @dfn{live} and cannot be deleted; any other file is considered @dfn{dead} and may be deleted. The set of garbage collector roots (``GC roots'' for short) includes default user profiles; by default, the symlinks under @file{/var/guix/gcroots} represent these GC roots. New GC roots can be added with @command{guix build --root}, for example (@pxref{Invoking guix build}). The @command{guix gc --list-roots} command lists them. Prior to running @code{guix gc --collect-garbage} to make space, it is often useful to remove old generations from user profiles; that way, old package builds referenced by those generations can be reclaimed. This is achieved by running @code{guix package --delete-generations} (@pxref{Invoking guix package}). Our recommendation is to run a garbage collection periodically, or when you are short on disk space. For instance, to guarantee that at least 5@tie{}GB are available on your disk, simply run: @example guix gc -F 5G @end example It is perfectly safe to run as a non-interactive periodic job (@pxref{Scheduled Job Execution}, for how to set up such a job). Running @command{guix gc} with no arguments will collect as much garbage as it can, but that is often inconvenient: you may find yourself having to rebuild or re-download software that is ``dead'' from the GC viewpoint but that is necessary to build other pieces of software---e.g., the compiler tool chain. The @command{guix gc} command has three modes of operation: it can be used to garbage-collect any dead files (the default), to delete specific files (the @option{--delete} option), to print garbage-collector information, or for more advanced queries. The garbage collection options are as follows: @table @code @item --collect-garbage[=@var{min}] @itemx -C [@var{min}] Collect garbage---i.e., unreachable @file{/gnu/store} files and sub-directories. This is the default operation when no option is specified. When @var{min} is given, stop once @var{min} bytes have been collected. @var{min} may be a number of bytes, or it may include a unit as a suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}). When @var{min} is omitted, collect all the garbage. @item --free-space=@var{free} @itemx -F @var{free} Collect garbage until @var{free} space is available under @file{/gnu/store}, if possible; @var{free} denotes storage space, such as @code{500MiB}, as described above. When @var{free} or more is already available in @file{/gnu/store}, do nothing and exit immediately. @item --delete-generations[=@var{duration}] @itemx -d [@var{duration}] Before starting the garbage collection process, delete all the generations older than @var{duration}, for all the user profiles and home environment generations; when run as root, this applies to all the profiles @emph{of all the users}. For example, this command deletes all the generations of all your profiles that are older than 2 months (except generations that are current), and then proceeds to free space until at least 10 GiB are available: @example guix gc -d 2m -F 10G @end example @item --delete @itemx -D Attempt to delete all the store files and directories specified as arguments. This fails if some of the files are not in the store, or if they are still live. @item --list-failures List store items corresponding to cached build failures. This prints nothing unless the daemon was started with @option{--cache-failures} (@pxref{Invoking guix-daemon, @option{--cache-failures}}). @item --list-roots List the GC roots owned by the user; when run as root, list @emph{all} the GC roots. @item --list-busy List store items in use by currently running processes. These store items are effectively considered GC roots: they cannot be deleted. @item --clear-failures Remove the specified store items from the failed-build cache. Again, this option only makes sense when the daemon is started with @option{--cache-failures}. Otherwise, it does nothing. @item --list-dead Show the list of dead files and directories still present in the store---i.e., files and directories no longer reachable from any root. @item --list-live Show the list of live store files and directories. @end table In addition, the references among existing store files can be queried: @table @code @item --references @itemx --referrers @cindex package dependencies List the references (respectively, the referrers) of store files given as arguments. @item --requisites @itemx -R @cindex closure List the requisites of the store files passed as arguments. Requisites include the store files themselves, their references, and the references of these, recursively. In other words, the returned list is the @dfn{transitive closure} of the store files. @xref{Invoking guix size}, for a tool to profile the size of the closure of an element. @xref{Invoking guix graph}, for a tool to visualize the graph of references. @item --derivers @cindex derivation Return the derivation(s) leading to the given store items (@pxref{Derivations}). For example, this command: @example guix gc --derivers $(guix package -I ^emacs$ | cut -f4) @end example @noindent returns the @file{.drv} file(s) leading to the @code{emacs} package installed in your profile. Note that there may be zero matching @file{.drv} files, for instance because these files have been garbage-collected. There can also be more than one matching @file{.drv} due to fixed-output derivations. @end table Lastly, the following options allow you to check the integrity of the store and to control disk usage. @table @option @item --verify[=@var{options}] @cindex integrity, of the store @cindex integrity checking Verify the integrity of the store. By default, make sure that all the store items marked as valid in the database of the daemon actually exist in @file{/gnu/store}. When provided, @var{options} must be a comma-separated list containing one or more of @code{contents} and @code{repair}. When passing @option{--verify=contents}, the daemon computes the content hash of each store item and compares it against its hash in the database. Hash mismatches are reported as data corruptions. Because it traverses @emph{all the files in the store}, this command can take a long time, especially on systems with a slow disk drive. @cindex repairing the store @cindex corruption, recovering from Using @option{--verify=repair} or @option{--verify=contents,repair} causes the daemon to try to repair corrupt store items by fetching substitutes for them (@pxref{Substitutes}). Because repairing is not atomic, and thus potentially dangerous, it is available only to the system administrator. A lightweight alternative, when you know exactly which items in the store are corrupt, is @command{guix build --repair} (@pxref{Invoking guix build}). @item --optimize @cindex deduplication Optimize the store by hard-linking identical files---this is @dfn{deduplication}. The daemon performs deduplication after each successful build or archive import, unless it was started with @option{--disable-deduplication} (@pxref{Invoking guix-daemon, @option{--disable-deduplication}}). Thus, this option is primarily useful when the daemon was running with @option{--disable-deduplication}. @item --vacuum-database @cindex vacuum the store database @comment Avoid words like 'repair,' 'compress,' and 'optimize.' Guix uses an sqlite database to keep track of the items in the store (@pxref{The Store}). Over time it is possible that the database may grow to a large size and become fragmented. As a result, one may wish to clear the freed space and join the partially used pages in the database left behind from removed packages or after running the garbage collector. Running @command{sudo guix gc --vacuum-database} will lock the database and @code{VACUUM} the store, defragmenting the database and purging freed pages, unlocking the database when it finishes. @end table @node Invoking guix pull @section Invoking @command{guix pull} @cindex upgrading Guix @cindex updating Guix @cindex @command{guix pull} @cindex pull @cindex security, @command{guix pull} @cindex authenticity, of code obtained with @command{guix pull} Packages are installed or upgraded to the latest version available in the distribution currently available on your local machine. To update that distribution, along with the Guix tools, you must run @command{guix pull}: the command downloads the latest Guix source code and package descriptions, and deploys it. Source code is downloaded from a @uref{https://git-scm.com/book/en/, Git} repository, by default the official GNU@tie{}Guix repository, though this can be customized. @command{guix pull} ensures that the code it downloads is @emph{authentic} by verifying that commits are signed by Guix developers. Specifically, @command{guix pull} downloads code from the @dfn{channels} (@pxref{Channels}) specified by one of the following, in this order: @enumerate @item the @option{--channels} option; @item the user's @file{~/.config/guix/channels.scm} file, unless @option{-q} is passed; @item the system-wide @file{/etc/guix/channels.scm} file, unless @option{-q} is passed (on Guix System, this file can be declared in the operating system configuration, @pxref{guix-configuration-channels, @code{channels} field of @code{guix-configuration}}); @item the built-in default channels specified in the @code{%default-channels} variable. @end enumerate On completion, @command{guix package} will use packages and package versions from this just-retrieved copy of Guix. Not only that, but all the Guix commands and Scheme modules will also be taken from that latest version. New @command{guix} sub-commands added by the update also become available. Any user can update their Guix copy using @command{guix pull}, and the effect is limited to the user who ran @command{guix pull}. For instance, when user @code{root} runs @command{guix pull}, this has no effect on the version of Guix that user @code{alice} sees, and vice versa. The result of running @command{guix pull} is a @dfn{profile} available under @file{~/.config/guix/current} containing the latest Guix. The @option{--list-generations} or @option{-l} option lists past generations produced by @command{guix pull}, along with details about their provenance: @example $ guix pull -l Generation 1 Jun 10 2018 00:18:18 guix 65956ad repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe Generation 2 Jun 11 2018 11:02:49 guix e0cc7f6 repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d Generation 3 Jun 13 2018 23:31:07 (current) guix 844cc1c repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: 844cc1c8f394f03b404c5bb3aee086922373490c @end example @xref{Invoking guix describe, @command{guix describe}}, for other ways to describe the current status of Guix. This @code{~/.config/guix/current} profile works exactly like the profiles created by @command{guix package} (@pxref{Invoking guix package}). That is, you can list generations, roll back to the previous generation---i.e., the previous Guix---and so on: @example $ guix pull --roll-back switched from generation 3 to 2 $ guix pull --delete-generations=1 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link @end example You can also use @command{guix package} (@pxref{Invoking guix package}) to manage the profile by naming it explicitly: @example $ guix package -p ~/.config/guix/current --roll-back switched from generation 3 to 2 $ guix package -p ~/.config/guix/current --delete-generations=1 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link @end example The @command{guix pull} command is usually invoked with no arguments, but it supports the following options: @table @code @item --url=@var{url} @itemx --commit=@var{commit} @itemx --branch=@var{branch} Download code for the @code{guix} channel from the specified @var{url}, at the given @var{commit} (a valid Git commit ID represented as a hexadecimal string or the name of a tag), or @var{branch}. @cindex @file{channels.scm}, configuration file @cindex configuration file for channels These options are provided for convenience, but you can also specify your configuration in the @file{~/.config/guix/channels.scm} file or using the @option{--channels} option (see below). @item --channels=@var{file} @itemx -C @var{file} Read the list of channels from @var{file} instead of @file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}. @var{file} must contain Scheme code that evaluates to a list of channel objects. @xref{Channels}, for more information. @item --no-channel-files @itemx -q Inhibit loading of the user and system channel files, @file{~/.config/guix/channels.scm} and @file{/etc/guix/channels.scm}. @cindex channel news @item --news @itemx -N Display news written by channel authors for their users for changes made since the previous generation (@pxref{Channels, Writing Channel News}). When @option{--details} is passed, additionally display new and upgraded packages. You can view that information for previous generations with @command{guix pull -l}. @item --list-generations[=@var{pattern}] @itemx -l [@var{pattern}] List all the generations of @file{~/.config/guix/current} or, if @var{pattern} is provided, the subset of generations that match @var{pattern}. The syntax of @var{pattern} is the same as with @code{guix package --list-generations} (@pxref{Invoking guix package}). By default, this prints information about the channels used in each revision as well as the corresponding news entries. If you pass @option{--details}, it will also print the list of packages added and upgraded in each generation compared to the previous one. @item --details Instruct @option{--list-generations} or @option{--news} to display more information about the differences between subsequent generations---see above. @item --roll-back @cindex rolling back @cindex undoing transactions @cindex transactions, undoing Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e., undo the last transaction. @item --switch-generation=@var{pattern} @itemx -S @var{pattern} @cindex generations Switch to a particular generation defined by @var{pattern}. @var{pattern} may be either a generation number or a number prefixed with ``+'' or ``-''. The latter means: move forward/backward by a specified number of generations. For example, if you want to return to the latest generation after @option{--roll-back}, use @option{--switch-generation=+1}. @item --delete-generations[=@var{pattern}] @itemx -d [@var{pattern}] When @var{pattern} is omitted, delete all generations except the current one. This command accepts the same patterns as @option{--list-generations}. When @var{pattern} is specified, delete the matching generations. When @var{pattern} specifies a duration, generations @emph{older} than the specified duration match. For instance, @option{--delete-generations=1m} deletes generations that are more than one month old. If the current generation matches, it is @emph{not} deleted. Note that deleting generations prevents rolling back to them. Consequently, this command must be used with care. @xref{Invoking guix describe}, for a way to display information about the current generation only. @item --profile=@var{profile} @itemx -p @var{profile} Use @var{profile} instead of @file{~/.config/guix/current}. @item --dry-run @itemx -n Show which channel commit(s) would be used and what would be built or substituted but do not actually do it. @item --allow-downgrades Allow pulling older or unrelated revisions of channels than those currently in use. @cindex downgrade attacks, protection against By default, @command{guix pull} protects against so-called ``downgrade attacks'' whereby the Git repository of a channel would be reset to an earlier or unrelated revision of itself, potentially leading you to install older, known-vulnerable versions of software packages. @quotation Note Make sure you understand its security implications before using @option{--allow-downgrades}. @end quotation @item --disable-authentication Allow pulling channel code without authenticating it. @cindex authentication, of channel code By default, @command{guix pull} authenticates code downloaded from channels by verifying that its commits are signed by authorized developers, and raises an error if this is not the case. This option instructs it to not perform any such verification. @quotation Note Make sure you understand its security implications before using @option{--disable-authentication}. @end quotation @item --no-check-certificate Do not validate the X.509 certificates of HTTPS servers. When using this option, you have @emph{absolutely no guarantee} that you are communicating with the authentic server responsible for the given URL. Unless the channel is authenticated, this makes you vulnerable to ``man-in-the-middle'' attacks. @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the system type of the build host. @item --bootstrap Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers. @end table The @dfn{channel} mechanism allows you to instruct @command{guix pull} which repository and branch to pull from, as well as @emph{additional} repositories containing package modules that should be deployed. @xref{Channels}, for more information. In addition, @command{guix pull} supports all the common build options (@pxref{Common Build Options}). @node Invoking guix time-machine @section Invoking @command{guix time-machine} @cindex @command{guix time-machine} @cindex pinning, channels @cindex replicating Guix @cindex reproducibility, of Guix The @command{guix time-machine} command provides access to other revisions of Guix, for example to install older versions of packages, or to reproduce a computation in an identical environment. The revision of Guix to be used is defined by a commit or by a channel description file created by @command{guix describe} (@pxref{Invoking guix describe}). Let's assume that you want to travel to those days of November 2020 when version 1.2.0 of Guix was released and, once you're there, run the @command{guile} of that time: @example guix time-machine --commit=v1.2.0 -- \ environment -C --ad-hoc guile -- guile @end example The command above fetches Guix@tie{}1.2.0 (and possibly other channels specified by your @file{channels.scm} configuration files---see below) and runs its @command{guix environment} command to spawn an environment in a container running @command{guile} (@command{guix environment} has since been subsumed by @command{guix shell}; @pxref{Invoking guix shell}). It's like driving a DeLorean@footnote{If you don't know what a DeLorean is, consider traveling back to the 1980's. (@uref{https://www.imdb.com/title/tt0088763/, Back to the Future (1985)})}! The first @command{guix time-machine} invocation can be expensive: it may have to download or even build a large number of packages; the result is cached though and subsequent commands targeting the same commit are almost instantaneous. As for @command{guix pull}, in the absence of any options, @command{time-machine} fetches the latest commits of the channels specified in @file{~/.config/guix/channels.scm}, @file{/etc/guix/channels.scm}, or the default channels; the @option{-q} option lets you ignore these configuration files. The command: @example guix time-machine -q -- build hello @end example will thus build the package @code{hello} as defined in the main branch of Guix, without any additional channel, which is in general a newer revision of Guix than you have installed. Time travel works in both directions! @quotation Note The history of Guix is immutable and @command{guix time-machine} provides the exact same software as they are in a specific Guix revision. Naturally, no security fixes are provided for old versions of Guix or its channels. A careless use of @command{guix time-machine} opens the door to security vulnerabilities. @xref{Invoking guix pull, @option{--allow-downgrades}}. @end quotation @c Keep this paragraph in sync with 'time-machine.scm'. @command{guix time-machine} raises an error when attempting to travel to commits older than ``v0.16.0'' (commit @samp{4a0b87f0}), dated Dec.@: 2018. This is one of the oldest commits supporting the channel mechanism that makes ``time travel'' possible. @quotation Note Although it should technically be possible to travel to such an old commit, the ease to do so will largely depend on the availability of binary substitutes. When traveling to a distant past, some packages may not easily build from source anymore. One such example are old versions of OpenSSL whose tests would fail after a certain date. This particular problem can be worked around by running a @dfn{virtual build machine} with its clock set to the right time (@pxref{build-vm, Virtual Build Machines}). @end quotation The general syntax is: @example guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{} @end example where @var{command} and @var{arg}@dots{} are passed unmodified to the @command{guix} command of the specified revision. The @var{options} that define this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}): @table @code @item --url=@var{url} @itemx --commit=@var{commit} @itemx --branch=@var{branch} Use the @code{guix} channel from the specified @var{url}, at the given @var{commit} (a valid Git commit ID represented as a hexadecimal string or the name of a tag), or @var{branch}. @item --channels=@var{file} @itemx -C @var{file} Read the list of channels from @var{file}. @var{file} must contain Scheme code that evaluates to a list of channel objects. @xref{Channels} for more information. @item --no-channel-files @itemx -q Inhibit loading of the user and system channel files, @file{~/.config/guix/channels.scm} and @file{/etc/guix/channels.scm}. Thus, @command{guix time-machine -q} is equivalent to the following Bash command, using the ``process substitution'' syntax (@pxref{Process Substitution,,, bash, The GNU Bash Reference Manual}): @example guix time-machine -C <(echo %default-channels) @dots{} @end example @end table Note that @command{guix time-machine} can trigger builds of channels and their dependencies, and these are controlled by the standard build options (@pxref{Common Build Options}). If @command{guix time-machine} is executed without any command, it prints the file name of the profile that would be used to execute the command. This is sometimes useful if you need to get store file name of the profile---e.g., when you want to @command{guix copy} it. @node Inferiors @section Inferiors @c TODO: Remove this once we're more confident about API stability. @quotation Note The functionality described here is a ``technology preview'' as of version @value{VERSION}. As such, the interface is subject to change. @end quotation @cindex inferiors @cindex composition of Guix revisions Sometimes you might need to mix packages from the revision of Guix you're currently running with packages available in a different revision of Guix. Guix @dfn{inferiors} allow you to achieve that by composing different Guix revisions in arbitrary ways. @cindex inferior packages Technically, an ``inferior'' is essentially a separate Guix process connected to your main Guix process through a REPL (@pxref{Invoking guix repl}). The @code{(guix inferior)} module allows you to create inferiors and to communicate with them. It also provides a high-level interface to browse and manipulate the packages that an inferior provides---@dfn{inferior packages}. When combined with channels (@pxref{Channels}), inferiors provide a simple way to interact with a separate revision of Guix. For example, let's assume you want to install in your profile the current @code{guile} package, along with the @code{guile-json} as it existed in an older revision of Guix---perhaps because the newer @code{guile-json} has an incompatible API and you want to run your code against the old API@. To do that, you could write a manifest for use by @code{guix package --manifest} (@pxref{Writing Manifests}); in that manifest, you would create an inferior for that old Guix revision you care about, and you would look up the @code{guile-json} package in the inferior: @lisp (use-modules (guix inferior) (guix channels) (srfi srfi-1)) ;for 'first' (define channels ;; This is the old revision from which we want to ;; extract guile-json. (list (channel (name 'guix) (url "https://git.savannah.gnu.org/git/guix.git") (commit "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) (define inferior ;; An inferior representing the above revision. (inferior-for-channels channels)) ;; Now create a manifest with the current "guile" package ;; and the old "guile-json" package. (packages->manifest (list (first (lookup-inferior-packages inferior "guile-json")) (specification->package "guile"))) @end lisp On its first run, @command{guix package --manifest} might have to build the channel you specified before it can create the inferior; subsequent runs will be much faster because the Guix revision will be cached. The @code{(guix inferior)} module provides the following procedures to open an inferior: @deffn {Procedure} inferior-for-channels channels [#:cache-directory] [#:ttl] Return an inferior for @var{channels}, a list of channels. Use the cache at @var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds. This procedure opens a new connection to the build daemon. As a side effect, this procedure may build or substitute binaries for @var{channels}, which can take time. @end deffn @deffn {Procedure} open-inferior directory [#:command "bin/guix"] Open the inferior Guix in @var{directory}, running @code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if the inferior could not be launched. @end deffn @cindex inferior packages The procedures listed below allow you to obtain and manipulate inferior packages. @deffn {Procedure} inferior-packages inferior Return the list of packages known to @var{inferior}. @end deffn @deffn {Procedure} lookup-inferior-packages inferior name [version] Return the sorted list of inferior packages matching @var{name} in @var{inferior}, with highest version numbers first. If @var{version} is true, return only packages with a version number prefixed by @var{version}. @end deffn @deffn {Procedure} inferior-package? obj Return true if @var{obj} is an inferior package. @end deffn @deffn {Procedure} inferior-package-name package @deffnx {Procedure} inferior-package-version package @deffnx {Procedure} inferior-package-synopsis package @deffnx {Procedure} inferior-package-description package @deffnx {Procedure} inferior-package-home-page package @deffnx {Procedure} inferior-package-location package @deffnx {Procedure} inferior-package-inputs package @deffnx {Procedure} inferior-package-native-inputs package @deffnx {Procedure} inferior-package-propagated-inputs package @deffnx {Procedure} inferior-package-transitive-propagated-inputs package @deffnx {Procedure} inferior-package-native-search-paths package @deffnx {Procedure} inferior-package-transitive-native-search-paths package @deffnx {Procedure} inferior-package-search-paths package These procedures are the counterpart of package record accessors (@pxref{package Reference}). Most of them work by querying the inferior @var{package} comes from, so the inferior must still be live when you call these procedures. @end deffn Inferior packages can be used transparently like any other package or file-like object in G-expressions (@pxref{G-Expressions}). They are also transparently handled by the @code{packages->manifest} procedure, which is commonly used in manifests (@pxref{Invoking guix package, the @option{--manifest} option of @command{guix package}}). Thus you can insert an inferior package pretty much anywhere you would insert a regular package: in manifests, in the @code{packages} field of your @code{operating-system} declaration, and so on. @node Invoking guix describe @section Invoking @command{guix describe} @cindex reproducibility @cindex replicating Guix @cindex @command{guix describe} Often you may want to answer questions like: ``Which revision of Guix am I using?'' or ``Which channels am I using?'' This is useful information in many situations: if you want to @emph{replicate} an environment on a different machine or user account, if you want to report a bug or to determine what change in the channels you are using caused it, or if you want to record your system state for reproducibility purposes. The @command{guix describe} command answers these questions. When run from a @command{guix pull}ed @command{guix}, @command{guix describe} displays the channel(s) that it was built from, including their repository URL and commit IDs (@pxref{Channels}): @example $ guix describe Generation 10 Sep 03 2018 17:32:44 (current) guix e0fa68c repository URL: https://git.savannah.gnu.org/git/guix.git branch: master commit: e0fa68c7718fffd33d81af415279d6ddb518f727 @end example If you're familiar with the Git version control system, this is similar in spirit to @command{git describe}; the output is also similar to that of @command{guix pull --list-generations}, but limited to the current generation (@pxref{Invoking guix pull, the @option{--list-generations} option}). Because the Git commit ID shown above unambiguously refers to a snapshot of Guix, this information is all it takes to describe the revision of Guix you're using, and also to replicate it. To make it easier to replicate Guix, @command{guix describe} can also be asked to return a list of channels instead of the human-readable description above: @example $ guix describe -f channels (list (channel (name 'guix) (url "https://git.savannah.gnu.org/git/guix.git") (commit "e0fa68c7718fffd33d81af415279d6ddb518f727") (introduction (make-channel-introduction "9edb3f66fd807b096b48283debdcddccfea34bad" (openpgp-fingerprint "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"))))) @end example @noindent You can save this to a file and feed it to @command{guix pull -C} on some other machine or at a later point in time, which will instantiate @emph{this exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}). From there on, since you're able to deploy the same revision of Guix, you can just as well @emph{replicate a complete software environment}. We humbly think that this is @emph{awesome}, and we hope you'll like it too! The details of the options supported by @command{guix describe} are as follows: @table @code @item --format=@var{format} @itemx -f @var{format} Produce output in the specified @var{format}, one of: @table @code @item human produce human-readable output; @item channels produce a list of channel specifications that can be passed to @command{guix pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking guix pull}); @item channels-sans-intro like @code{channels}, but omit the @code{introduction} field; use it to produce a channel specification suitable for Guix version 1.1.0 or earlier---the @code{introduction} field has to do with channel authentication (@pxref{Channels, Channel Authentication}) and is not supported by these older versions; @item json @cindex JSON produce a list of channel specifications in JSON format; @item recutils produce a list of channel specifications in Recutils format. @end table @item --list-formats Display available formats for @option{--format} option. @item --profile=@var{profile} @itemx -p @var{profile} Display information about @var{profile}. @end table @node Invoking guix archive @section Invoking @command{guix archive} @cindex @command{guix archive} @cindex archive @cindex exporting files from the store @cindex importing files to the store The @command{guix archive} command allows users to @dfn{export} files from the store into a single archive, and to later @dfn{import} them on a machine that runs Guix. In particular, it allows store files to be transferred from one machine to the store on another machine. @quotation Note If you're looking for a way to produce archives in a format suitable for tools other than Guix, @pxref{Invoking guix pack}. @end quotation @cindex exporting store items To export store files as an archive to standard output, run: @example guix archive --export @var{options} @var{specifications}... @end example @var{specifications} may be either store file names or package specifications, as for @command{guix package} (@pxref{Invoking guix package}). For instance, the following command creates an archive containing the @code{gui} output of the @code{git} package and the main output of @code{emacs}: @example guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar @end example If the specified packages are not built yet, @command{guix archive} automatically builds them. The build process may be controlled with the common build options (@pxref{Common Build Options}). To transfer the @code{emacs} package to a machine connected over SSH, one would run: @example guix archive --export -r emacs | ssh the-machine guix archive --import @end example @noindent Similarly, a complete user profile may be transferred from one machine to another like this: @example guix archive --export -r $(readlink -f ~/.guix-profile) | \ ssh the-machine guix archive --import @end example @noindent However, note that, in both examples, all of @code{emacs} and the profile as well as all of their dependencies are transferred (due to @option{-r}), regardless of what is already available in the store on the target machine. The @option{--missing} option can help figure out which items are missing from the target store. The @command{guix copy} command simplifies and optimizes this whole process, so this is probably what you should use in this case (@pxref{Invoking guix copy}). @cindex nar, archive format @cindex normalized archive (nar) @cindex nar bundle, archive format Each store item is written in the @dfn{normalized archive} or @dfn{nar} format (described below), and the output of @command{guix archive --export} (and input of @command{guix archive --import}) is a @dfn{nar bundle}. The nar format is comparable in spirit to `tar', but with differences that make it more appropriate for our purposes. First, rather than recording all Unix metadata for each file, the nar format only mentions the file type (regular, directory, or symbolic link); Unix permissions and owner/group are dismissed. Second, the order in which directory entries are stored always follows the order of file names according to the C locale collation order. This makes archive production fully deterministic. That nar bundle format is essentially the concatenation of zero or more nars along with metadata for each store item it contains: its file name, references, corresponding derivation, and a digital signature. When exporting, the daemon digitally signs the contents of the archive, and that digital signature is appended. When importing, the daemon verifies the signature and rejects the import in case of an invalid signature or if the signing key is not authorized. @c FIXME: Add xref to daemon doc about signatures. The main options are: @table @code @item --export Export the specified store files or packages (see below). Write the resulting archive to the standard output. Dependencies are @emph{not} included in the output, unless @option{--recursive} is passed. @item -r @itemx --recursive When combined with @option{--export}, this instructs @command{guix archive} to include dependencies of the given items in the archive. Thus, the resulting archive is self-contained: it contains the closure of the exported store items. @item --import Read an archive from the standard input, and import the files listed therein into the store. Abort if the archive has an invalid digital signature, or if it is signed by a public key not among the authorized keys (see @option{--authorize} below). @item --missing Read a list of store file names from the standard input, one per line, and write on the standard output the subset of these files missing from the store. @item --generate-key[=@var{parameters}] @cindex signing, archives Generate a new key pair for the daemon. This is a prerequisite before archives can be exported with @option{--export}. This operation is usually instantaneous but it can take time if the system's entropy pool needs to be refilled. On Guix System, @code{guix-service-type} takes care of generating this key pair the first boot. The generated key pair is typically stored under @file{/etc/guix}, in @file{signing-key.pub} (public key) and @file{signing-key.sec} (private key, which must be kept secret). When @var{parameters} is omitted, an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt versions before 1.6.0, it is a 4096-bit RSA key. Alternatively, @var{parameters} can specify @code{genkey} parameters suitable for Libgcrypt (@pxref{General public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The Libgcrypt Reference Manual}). @item --authorize @cindex authorizing, archives Authorize imports signed by the public key passed on standard input. The public key must be in ``s-expression advanced format''---i.e., the same format as the @file{signing-key.pub} file. The list of authorized keys is kept in the human-editable file @file{/etc/guix/acl}. The file contains @url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format s-expressions''} and is structured as an access-control list in the @url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure (SPKI)}. @item --extract=@var{directory} @itemx -x @var{directory} Read a single-item archive as served by substitute servers (@pxref{Substitutes}) and extract it to @var{directory}. This is a low-level operation needed in only very narrow use cases; see below. For example, the following command extracts the substitute for Emacs served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}: @example $ wget -O - \ https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \ | gunzip | guix archive -x /tmp/emacs @end example Single-item archives are different from multiple-item archives produced by @command{guix archive --export}; they contain a single store item, and they do @emph{not} embed a signature. Thus this operation does @emph{no} signature verification and its output should be considered unsafe. The primary purpose of this operation is to facilitate inspection of archive contents coming from possibly untrusted substitute servers (@pxref{Invoking guix challenge}). @item --list @itemx -t Read a single-item archive as served by substitute servers (@pxref{Substitutes}) and print the list of files it contains, as in this example: @example $ wget -O - \ https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \ | lzip -d | guix archive -t @end example @end table @c ********************************************************************* @node Channels @chapter Channels @cindex channels @cindex @file{channels.scm}, configuration file @cindex configuration file for channels @cindex @command{guix pull}, configuration file @cindex configuration of @command{guix pull} Guix and its package collection are updated by running @command{guix pull}. By default @command{guix pull} downloads and deploys Guix itself from the official GNU@tie{}Guix repository. This can be customized by providing a file specifying the set of @dfn{channels} to pull from (@pxref{Invoking guix pull}). A channel specifies the URL and branch of a Git repository to be deployed, and @command{guix pull} can be instructed to pull from one or more channels. In other words, channels can be used to @emph{customize} and to @emph{extend} Guix, as we will see below. Guix is able to take into account security concerns and deal with authenticated updates. @menu * Specifying Additional Channels:: Extending the package collection. * Using a Custom Guix Channel:: Using a customized Guix. * Replicating Guix:: Running the @emph{exact same} Guix. * Customizing the System-Wide Guix:: Default channels on Guix System. * 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. @end menu @node Specifying Additional Channels @section Specifying Additional Channels @cindex extending the package collection (channels) @cindex variant packages (channels) You can specify @emph{additional channels} to pull from. To use a channel, write @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it @emph{in addition} to the default Guix channel(s): @vindex %default-channels @lisp ;; Add variant packages to those Guix provides. (cons (channel (name 'variant-packages) (url "https://example.org/variant-packages.git")) %default-channels) @end lisp @noindent Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to add a channel the list of channels that the variable @code{%default-channels} is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference Manual}). With this file in place, @command{guix pull} builds not only Guix but also the package modules from your own repository. The result in @file{~/.config/guix/current} is the union of Guix with your own package modules: @example $ guix describe Generation 19 Aug 27 2018 16:20:48 guix d894ab8 repository URL: https://git.savannah.gnu.org/git/guix.git branch: master commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300 variant-packages dd3df5e repository URL: https://example.org/variant-packages.git branch: master commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb @end example @noindent The output of @command{guix describe} above shows that we're now running Generation@tie{}19 and that it includes both Guix and packages from the @code{variant-packages} channel (@pxref{Invoking guix describe}). @node Using a Custom Guix Channel @section Using a Custom Guix Channel The channel called @code{guix} specifies where Guix itself---its command-line tools as well as its package collection---should be downloaded. For instance, suppose you want to update from another copy of the Guix repository at @code{example.org}, and specifically the @code{super-hacks} branch, you can write in @code{~/.config/guix/channels.scm} this specification: @lisp ;; Tell 'guix pull' to use another repo. (list (channel (name 'guix) (url "https://example.org/another-guix.git") (branch "super-hacks"))) @end lisp @noindent From there on, @command{guix pull} will fetch code from the @code{super-hacks} branch of the repository at @code{example.org}. The authentication concern is addressed below (@pxref{Channel Authentication}). Note that you can specify a local directory on the @code{url} field above if the channel that you intend to use resides on a local file system. However, in this case @command{guix} checks said directory for ownership before any further processing. This means that if the user is not the directory owner, but wants to use it as their default, they will then need to set it as a safe directory in their global git configuration file. Otherwise, @command{guix} will refuse to even read it. Supposing your system-wide local directory is at @code{/src/guix.git}, you would then create a git configuration file at @code{~/.gitconfig} with the following contents: @example [safe] directory = /src/guix.git @end example @noindent This also applies to the root user unless when called with @command{sudo} by the directory owner. @node Replicating Guix @section Replicating Guix @cindex pinning, channels @cindex replicating Guix @cindex reproducibility, of Guix The @command{guix describe} command shows precisely which commits were used to build the instance of Guix we're using (@pxref{Invoking guix describe}). We can replicate this instance on another machine or at a different point in time by providing a channel specification ``pinned'' to these commits that looks like this: @lisp ;; Deploy specific commits of my channels of interest. (list (channel (name 'guix) (url "https://git.savannah.gnu.org/git/guix.git") (commit "6298c3ffd9654d3231a6f25390b056483e8f407c")) (channel (name 'variant-packages) (url "https://example.org/variant-packages.git") (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) @end lisp To obtain this pinned channel specification, the easiest way is to run @command{guix describe} and to save its output in the @code{channels} format in a file, like so: @example guix describe -f channels > channels.scm @end example The resulting @file{channels.scm} file can be passed to the @option{-C} option of @command{guix pull} (@pxref{Invoking guix pull}) or @command{guix time-machine} (@pxref{Invoking guix time-machine}), as in this example: @example guix time-machine -C channels.scm -- shell python -- python3 @end example Given the @file{channels.scm} file, the command above will always fetch the @emph{exact same Guix instance}, then use that instance to run the exact same Python (@pxref{Invoking guix shell}). On any machine, at any time, it ends up running the exact same binaries, bit for bit. @cindex lock files Pinned channels address a problem similar to ``lock files'' as implemented by some deployment tools---they let you pin and reproduce a set of packages. In the case of Guix though, you are effectively pinning the entire package set as defined at the given channel commits; in fact, you are pinning all of Guix, including its core modules and command-line tools. You're also getting strong guarantees that you are, indeed, obtaining the exact same software. This gives you super powers, allowing you to track the provenance of binary artifacts with very fine grain, and to reproduce software environments at will---some sort of ``meta reproducibility'' capabilities, if you will. @xref{Inferiors}, for another way to take advantage of these super powers. @node Customizing the System-Wide Guix @section Customizing the System-Wide Guix @cindex system-wide Guix, customization @cindex channels, for the default Guix If you're running Guix System or building system images with it, maybe you will want to customize the system-wide @command{guix} it provides---specifically, @file{/run/current-system/profile/bin/guix}. For example, you might want to provide additional channels or to pin its revision. This can be done using the @code{guix-for-channels} procedure, which returns a package for the given channels, and using it as part of your operating system configuration, as in this example: @lisp (use-modules (gnu packages package-management) (guix channels)) (define my-channels ;; Channels that should be available to ;; /run/current-system/profile/bin/guix. (append (list (channel (name 'guix-science) (url "https://github.com/guix-science/guix-science") (branch "master"))) %default-channels)) (operating-system ;; @dots{} (services ;; Change the package used by 'guix-service-type'. (modify-services %base-services (guix-service-type config => (guix-configuration (inherit config) (channels my-channels) (guix (guix-for-channels my-channels))))))) @end lisp The resulting operating system will have both the @code{guix} and the @code{guix-science} channels visible by default. The @code{channels} field of @code{guix-configuration} above further ensures that @file{/etc/guix/channels.scm}, which is used by @command{guix pull}, specifies the same set of channels (@pxref{guix-configuration-channels, @code{channels} field of @code{guix-configuration}}). The @code{(gnu packages package-management)} module exports the @code{guix-for-channels} procedure, described below. @deffn {Procedure} guix-for-channels @var{channels} Return a package corresponding to @var{channels}. The result is a ``regular'' package, which can be used in @code{guix-configuration} as shown above or in any other place that expects a package. @end deffn @node Channel Authentication @section Channel Authentication @anchor{channel-authentication} @cindex authentication, of channel code The @command{guix pull} and @command{guix time-machine} commands @dfn{authenticate} the code retrieved from channels: they make sure each commit that is fetched is signed by an authorized developer. The goal is to protect from unauthorized modifications to the channel that would lead users to run malicious code. As a user, you must provide a @dfn{channel introduction} in your channels file so that Guix knows how to authenticate its first commit. A channel specification, including its introduction, looks something along these lines: @lisp (channel (name 'some-channel) (url "https://example.org/some-channel.git") (introduction (make-channel-introduction "6f0d8cc0d88abb59c324b2990bfee2876016bb86" (openpgp-fingerprint "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5")))) @end lisp The specification above shows the name and URL of the channel. The call to @code{make-channel-introduction} above specifies that authentication of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed by the OpenPGP key with fingerprint @code{CABB A931@dots{}}. For the main channel, called @code{guix}, you automatically get that information from your Guix installation. For other channels, include the channel introduction provided by the channel authors in your @file{channels.scm} file. Make sure you retrieve the channel introduction from a trusted source since that is the root of your trust. If you're curious about the authentication mechanics, read on! @node Channels with Substitutes @section Channels with Substitutes When running @command{guix pull}, Guix will first compile the definitions of every available package. This is an expensive operation for which substitutes (@pxref{Substitutes}) may be available. The following snippet in @file{channels.scm} will ensure that @command{guix pull} uses the latest commit with available substitutes for the package definitions: this is done by querying the continuous integration server at @url{https://ci.guix.gnu.org}. @lisp (use-modules (guix ci)) (list (channel-with-substitutes-available %default-guix-channel "https://ci.guix.gnu.org")) @end lisp Note that this does not mean that all the packages that you will install after running @command{guix pull} will have available substitutes. It only ensures that @command{guix pull} will not try to compile package definitions. This is particularly useful when using machines with limited resources. @node Creating a Channel @section Creating a Channel @cindex personal packages (channels) @cindex channels, for personal packages Let's say you have a bunch of custom package variants or personal packages that you think would make little sense to contribute to the Guix project, but would like to have these packages transparently available to you at the command line. By creating a @dfn{channel}, you can use and publish such a package collection. This involves the following steps: @enumerate @item A channel lives in a Git repository so the first step, when creating a channel, is to create its repository: @example mkdir my-channel cd my-channel git init @end example @item The next step is to create files containing package modules (@pxref{Package Modules}), each of which will contain one or more package definitions (@pxref{Defining Packages}). A channel can provide things other than packages, such as build systems or services; we're using packages as it's the most common use case. For example, Alice might want to provide a module called @code{(alice packages greetings)} that will provide her favorite ``hello world'' implementations. To do that Alice will create a directory corresponding to that module name. @example mkdir -p alice/packages $EDITOR alice/packages/greetings.scm git add alice/packages/greetings.scm @end example You can name your package modules however you like; the main constraint to keep in mind is to avoid name clashes with other package collections, which is why our hypothetical Alice wisely chose the @code{(alice packages @dots{})} name space. Note that you can also place modules in a sub-directory of the repository; @pxref{Package Modules in a Sub-directory}, for more info on that. @item With this first module in place, the next step is to test the packages it provides. This can be done with @command{guix build}, which needs to be told to look for modules in the Git checkout. For example, assuming @code{(alice packages greetings)} provides a package called @code{hi-from-alice}, Alice will run this command from the Git checkout: @example guix build -L. hi-from-alice @end example @noindent ... where @code{-L.} adds the current directory to Guile's load path (@pxref{Load Paths,,, guile, GNU Guile Reference Manual}). @item It might take Alice a few iterations to obtain satisfying package definitions. Eventually Alice will commit this file: @example git commit @end example As a channel author, consider bundling authentication material with your channel so that users can authenticate it. @xref{Channel Authentication}, and @ref{Specifying Channel Authorizations}, for info on how to do it. @item To use Alice's channel, anyone can now add it to their channel file (@pxref{Specifying Additional Channels}) and run @command{guix pull} (@pxref{Invoking guix pull}): @example $EDITOR ~/.config/guix/channels.scm guix pull @end example Guix will now behave as if the root directory of that channel's Git repository had been permanently added to the Guile load path. In this example, @code{(alice packages greetings)} will automatically be found by the @command{guix} command. @end enumerate Voilà! @c What follows stems from discussions at @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as @c earlier discussions on guix-devel@gnu.org. @quotation Warning Before you publish your channel, we would like to share a few words of caution: @itemize @item Before publishing a channel, please consider contributing your package definitions to Guix proper (@pxref{Contributing}). Guix as a project is open to free software of all sorts, and packages in Guix proper are readily available to all Guix users and benefit from the project's quality assurance process. @item Package modules and package definitions are Scheme code that uses various programming interfaces (APIs). We, Guix developers, never change APIs gratuitously, but we do @emph{not} commit to freezing APIs either. When you maintain package definitions outside Guix, we consider that @emph{the compatibility burden is on you}. @item Corollary: if you're using an external channel and that channel breaks, please @emph{report the issue to the channel authors}, not to the Guix project. @end itemize You've been warned! Having said this, we believe external channels are a practical way to exert your freedom to augment Guix' package collection and to share your improvements, which are basic tenets of @uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. @end quotation @node Package Modules in a Sub-directory @section Package Modules in a Sub-directory @cindex subdirectory, channels As a channel author, you may want to keep your channel modules in a sub-directory. If your modules are in the sub-directory @file{guix}, you must add a meta-data file @file{.guix-channel} that contains: @lisp (channel (version 0) (directory "guix")) @end lisp The modules must be @b{underneath} the specified directory, as the @code{directory} changes Guile's @code{load-path}. For example, if @file{.guix-channel} has @code{(directory "base")}, then a module defined as @code{(define-module (gnu packages fun))} must be located at @code{base/gnu/packages/fun.scm}. Doing this allows for only parts of a repository to be used as a channel, as Guix expects valid Guile modules when pulling. For instance, @command{guix deploy} machine configuration files are not valid Guile modules, and treating them as such would make @command{guix pull} fail. @node Declaring Channel Dependencies @section Declaring Channel Dependencies @cindex dependencies, channels @cindex meta-data, channels Channel authors may decide to augment a package collection provided by other channels. They can declare their channel to be dependent on other channels in a meta-data file @file{.guix-channel}, which is to be placed in the root of the channel repository. The meta-data file should contain a simple S-expression like this: @lisp (channel (version 0) (dependencies (channel (name some-collection) (url "https://example.org/first-collection.git") ;; The 'introduction' bit below is optional: you would ;; provide it for dependencies that can be authenticated. (introduction (channel-introduction (version 0) (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd") (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5")))) (channel (name some-other-collection) (url "https://example.org/second-collection.git") (branch "testing")))) @end lisp In the above example this channel is declared to depend on two other channels, which will both be fetched automatically. The modules provided by the channel will be compiled in an environment where the modules of all these declared channels are available. For the sake of reliability and maintainability, you should avoid dependencies on channels that you don't control, and you should aim to keep the number of dependencies to a minimum. @node Specifying Channel Authorizations @section Specifying Channel Authorizations @cindex channel authorizations @anchor{channel-authorizations} As we saw above, Guix ensures the source code it pulls from channels comes from authorized developers. As a channel author, you need to specify the list of authorized developers in the @file{.guix-authorizations} file in the channel's Git repository. The authentication rule is simple: each commit must be signed by a key listed in the @file{.guix-authorizations} file of its parent commit(s)@footnote{Git commits form a @dfn{directed acyclic graph} (DAG). Each commit can have zero or more parents; ``regular'' commits have one parent and merge commits have two parent commits. Read @uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git for Computer Scientists}} for a great overview.} The @file{.guix-authorizations} file looks like this: @lisp ;; Example '.guix-authorizations' file. (authorizations (version 0) ;current file format version (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3" (name "alice")) ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5" (name "bob")) ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5" (name "charlie")))) @end lisp Each fingerprint is followed by optional key/value pairs, as in the example above. Currently these key/value pairs are ignored. This authentication rule creates a chicken-and-egg issue: how do we authenticate the first commit? Related to that: how do we deal with channels whose repository history contains unsigned commits and lack @file{.guix-authorizations}? And how do we fork existing channels? @cindex channel introduction Channel introductions answer these questions by describing the first commit of a channel that should be authenticated. The first time a channel is fetched with @command{guix pull} or @command{guix time-machine}, the command looks up the introductory commit and verifies that it is signed by the specified OpenPGP key. From then on, it authenticates commits according to the rule above. Authentication fails if the target commit is neither a descendant nor an ancestor of the introductory commit. Additionally, your channel must provide all the OpenPGP keys that were ever mentioned in @file{.guix-authorizations}, stored as @file{.key} files, which can be either binary or ``ASCII-armored''. By default, those @file{.key} files are searched for in the branch named @code{keyring} but you can specify a different branch name in @code{.guix-channel} like so: @lisp (channel (version 0) (keyring-reference "my-keyring-branch")) @end lisp To summarize, as the author of a channel, there are three things you have to do to allow users to authenticate your code: @enumerate @item Export the OpenPGP keys of past and present committers with @command{gpg --export} and store them in @file{.key} files, by default in a branch named @code{keyring} (we recommend making it an @dfn{orphan branch}). @item Introduce an initial @file{.guix-authorizations} in the channel's repository. Do that in a signed commit (@pxref{Commit Access}, for information on how to sign Git commits). @item Advertise the channel introduction, for instance on your channel's web page. The channel introduction, as we saw above, is the commit/key pair---i.e., the commit that introduced @file{.guix-authorizations}, and the fingerprint of the OpenPGP used to sign it. @end enumerate Before pushing to your public Git repository, you can run @command{guix git authenticate} to verify that you did sign all the commits you are about to push with an authorized key: @example guix git authenticate @var{commit} @var{signer} @end example @noindent where @var{commit} and @var{signer} are your channel introduction. @xref{Invoking guix git authenticate}, for details. Publishing a signed channel requires discipline: any mistake, such as an unsigned commit or a commit signed by an unauthorized key, will prevent users from pulling from your channel---well, that's the whole point of authentication! Pay attention to merges in particular: merge commits are considered authentic if and only if they are signed by a key present in the @file{.guix-authorizations} file of @emph{both} branches. @node Primary URL @section Primary URL @cindex primary URL, channels Channel authors can indicate the primary URL of their channel's Git repository in the @file{.guix-channel} file, like so: @lisp (channel (version 0) (url "https://example.org/guix.git")) @end lisp This allows @command{guix pull} to determine whether it is pulling code from a mirror of the channel; when that is the case, it warns the user that the mirror might be stale and displays the primary URL@. That way, users cannot be tricked into fetching code from a stale mirror that does not receive security updates. This feature only makes sense for authenticated repositories, such as the official @code{guix} channel, for which @command{guix pull} ensures the code it fetches is authentic. @node Writing Channel News @section Writing Channel News @cindex news, for channels Channel authors may occasionally want to communicate to their users information about important changes in the channel. You'd send them all an email, but that's not convenient. Instead, channels can provide a @dfn{news file}; when the channel users run @command{guix pull}, that news file is automatically read and @command{guix pull --news} can display the announcements that correspond to the new commits that have been pulled, if any. To do that, channel authors must first declare the name of the news file in their @file{.guix-channel} file: @lisp (channel (version 0) (news-file "etc/news.txt")) @end lisp The news file itself, @file{etc/news.txt} in this example, must look something like this: @lisp (channel-news (version 0) (entry (tag "the-bug-fix") (title (en "Fixed terrible bug") (fr "Oh la la")) (body (en "@@emph@{Good news@}! It's fixed!") (eo "Certe ĝi pli bone funkcias nun!"))) (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906") (title (en "Added a great package") (ca "Què vol dir guix?")) (body (en "Don't miss the @@code@{hello@} package!")))) @end lisp While the news file is using the Scheme syntax, avoid naming it with a @file{.scm} extension or else it will get picked up when building the channel and yield an error since it is not a valid module. Alternatively, you can move the channel module to a subdirectory and store the news file in another directory. The file consists of a list of @dfn{news entries}. Each entry is associated with a commit or tag: it describes changes made in this commit, possibly in preceding commits as well. Users see entries only the first time they obtain the commit the entry refers to. The @code{title} field should be a one-line summary while @code{body} can be arbitrarily long, and both can contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are a list of language tag/message tuples, which allows @command{guix pull} to display news in the language that corresponds to the user's locale. If you want to translate news using a gettext-based workflow, you can extract translatable strings with @command{xgettext} (@pxref{xgettext Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming you write news entries in English first, the command below creates a PO file containing the strings to translate: @example xgettext -o news.po -l scheme -ken etc/news.txt @end example To sum up, yes, you could use your channel as a blog. But beware, this is @emph{not quite} what your users might expect. @c ********************************************************************* @node Development @chapter Development @cindex software development If you are a software developer, Guix provides tools that you should find helpful---independently of the language you're developing in. This is what this chapter is about. The @command{guix shell} command provides a convenient way to set up one-off software environments, be it for development purposes or to run a command without installing it in your profile. The @command{guix pack} command allows you to create @dfn{application bundles} that can be easily distributed to users who do not run Guix. @menu * 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. @end menu @node Invoking guix shell @section Invoking @command{guix shell} @cindex reproducible build environments @cindex development environments @cindex @command{guix environment} @cindex @command{guix shell} @cindex environment, package build environment The purpose of @command{guix shell} is to make it easy to create one-off software environments, without changing one's profile. It is typically used to create development environments; it is also a convenient way to run applications without ``polluting'' your profile. @quotation Note The @command{guix shell} command was recently introduced to supersede @command{guix environment} (@pxref{Invoking guix environment}). If you are familiar with @command{guix environment}, you will notice that it is similar but also---we hope!---more convenient. @end quotation The general syntax is: @example guix shell [@var{options}] [@var{package}@dots{}] @end example Sometimes an interactive shell session is not desired. An arbitrary command may be invoked by placing the @code{--} token to separate the command from the rest of the arguments. The following example creates an environment containing Python and NumPy, building or downloading any missing package, and runs the @command{python3} command in that environment: @example guix shell python python-numpy -- python3 @end example Note that it is necessary to include the main @code{python} package in this command even if it is already installed into your environment. This is so that the shell environment knows to set @env{PYTHONPATH} and other related variables. The shell environment cannot check the previously installed environment, because then it would be non-deterministic. This is true for most libraries: their corresponding language package should be included in the shell invocation. @quotation Note @cindex shebang, for @command{guix shell} @command{guix shell} can be also be used as a script interpreter, also known as @dfn{shebang}. Here is an example self-contained Python script making use of this feature: @example #!/usr/bin/env -S guix shell python python-numpy -- python3 import numpy print("This is numpy", numpy.version.version) @end example You may pass any @command{guix shell} option, but there's one caveat: the Linux kernel has a limit of 127 bytes on shebang length. @end quotation Development environments can be created as in the example below, which spawns an interactive shell containing all the dependencies and environment variables needed to work on Inkscape: @example guix shell --development inkscape @end example Exiting the shell places the user back in the original environment before @command{guix shell} was invoked. The next garbage collection (@pxref{Invoking guix gc}) may clean up packages that were installed in the environment and that are no longer used outside of it. As an added convenience, @command{guix shell} will try to do what you mean when it is invoked interactively without any other arguments as in: @example guix shell @end example If it finds a @file{manifest.scm} in the current working directory or any of its parents, it uses this manifest as though it was given via @code{--manifest}. Likewise, if it finds a @file{guix.scm} in the same directories, it uses it to build a development profile as though both @code{--development} and @code{--file} were present. In either case, the file will only be loaded if the directory it resides in is listed in @file{~/.config/guix/shell-authorized-directories}. This provides an easy way to define, share, and enter development environments. By default, the shell session or command runs in an @emph{augmented} environment, where the new packages are added to search path environment variables such as @code{PATH}. You can, instead, choose to create an @emph{isolated} environment containing nothing but the packages you asked for. Passing the @option{--pure} option clears environment variable definitions found in the parent environment@footnote{Be sure to use the @option{--check} option the first time you use @command{guix shell} interactively to make sure the shell does not undo the effect of @option{--pure}.}; passing @option{--container} goes one step further by spawning a @dfn{container} isolated from the rest of the system: @example guix shell --container emacs gcc-toolchain @end example The command above spawns an interactive shell in a container where nothing but @code{emacs}, @code{gcc-toolchain}, and their dependencies is available. The container lacks network access and shares no files other than the current working directory with the surrounding environment. This is useful to prevent access to system-wide resources such as @file{/usr/bin} on foreign distros. This @option{--container} option can also prove useful if you wish to run a security-sensitive application, such as a web browser, in an isolated environment. For example, the command below launches Ungoogled-Chromium in an isolated environment, which: @itemize @item shares network access with the host @item inherits host's environment variables @code{DISPLAY} and @code{XAUTHORITY} @item has access to host's authentication records from the @code{XAUTHORITY} file @item has no information about host's current directory @end itemize @example guix shell --container --network --no-cwd ungoogled-chromium \ --preserve='^XAUTHORITY$' --expose="$@{XAUTHORITY@}" \ --preserve='^DISPLAY$' -- chromium @end example @vindex GUIX_ENVIRONMENT @command{guix shell} defines the @env{GUIX_ENVIRONMENT} variable in the shell it spawns; its value is the file name of the profile of this environment. This allows users to, say, define a specific prompt for development environments in their @file{.bashrc} (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}): @example if [ -n "$GUIX_ENVIRONMENT" ] then export PS1="\u@@\h \w [dev]\$ " fi @end example @noindent ...@: or to browse the profile: @example $ ls "$GUIX_ENVIRONMENT/bin" @end example The available options are summarized below. @table @code @item --check Set up the environment and check whether the shell would clobber environment variables. It's a good idea to use this option the first time you run @command{guix shell} for an interactive session to make sure your setup is correct. For example, if the shell modifies the @env{PATH} environment variable, report it since you would get a different environment than what you asked for. Such problems usually indicate that the shell startup files are unexpectedly modifying those environment variables. For example, if you are using Bash, make sure that environment variables are set or modified in @file{~/.bash_profile} and @emph{not} in @file{~/.bashrc}---the former is sourced only by log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for details on Bash start-up files. @anchor{shell-development-option} @item --development @itemx -D Cause @command{guix shell} to include in the environment the dependencies of the following package rather than the package itself. This can be combined with other packages. For instance, the command below starts an interactive shell containing the build-time dependencies of GNU@tie{}Guile, plus Autoconf, Automake, and Libtool: @example guix shell -D guile autoconf automake libtool @end example @item --expression=@var{expr} @itemx -e @var{expr} Create an environment for the package or list of packages that @var{expr} evaluates to. For example, running: @example guix shell -D -e '(@@ (gnu packages maths) petsc-openmpi)' @end example starts a shell with the environment for this specific variant of the PETSc package. Running: @example guix shell -e '(@@ (gnu) %base-packages)' @end example starts a shell with all the base system packages available. The above commands only use the default output of the given packages. To select other outputs, two element tuples can be specified: @example guix shell -e '(list (@@ (gnu packages bash) bash) "include")' @end example @xref{package-development-manifest, @code{package->development-manifest}}, for information on how to write a manifest for the development environment of a package. @item --file=@var{file} @itemx -f @var{file} Create an environment containing the package or list of packages that the code within @var{file} evaluates to. As an example, @var{file} might contain a definition like this (@pxref{Defining Packages}): @lisp @verbatiminclude environment-gdb.scm @end lisp With the file above, you can enter a development environment for GDB by running: @example guix shell -D -f gdb-devel.scm @end example @anchor{shell-manifest} @item --manifest=@var{file} @itemx -m @var{file} Create an environment for the packages contained in 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 is similar to the same-named option in @command{guix package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest files. @xref{Writing Manifests}, for information on how to write a manifest. See @option{--export-manifest} below on how to obtain a first manifest. @cindex manifest, exporting @anchor{shell-export-manifest} @item --export-manifest Write to standard output a manifest suitable for @option{--manifest} corresponding to given command-line options. This is a way to ``convert'' command-line arguments into a manifest. For example, imagine you are tired of typing long lines and would like to get a manifest equivalent to this command line: @example guix shell -D guile git emacs emacs-geiser emacs-geiser-guile @end example Just add @option{--export-manifest} to the command line above: @example guix shell --export-manifest \ -D guile git emacs emacs-geiser emacs-geiser-guile @end example @noindent ... and you get a manifest along these lines: @lisp (concatenate-manifests (list (specifications->manifest (list "git" "emacs" "emacs-geiser" "emacs-geiser-guile")) (package->development-manifest (specification->package "guile")))) @end lisp You can store it into a file, say @file{manifest.scm}, and from there pass it to @command{guix shell} or indeed pretty much any @command{guix} command: @example guix shell -m manifest.scm @end example Voilà, you've converted a long command line into a manifest! That conversion process honors package transformation options (@pxref{Package Transformation Options}) so it should be lossless. @item --profile=@var{profile} @itemx -p @var{profile} Create an environment containing the packages installed in @var{profile}. Use @command{guix package} (@pxref{Invoking guix package}) to create and manage profiles. @item --pure Unset existing environment variables when building the new environment, except those specified with @option{--preserve} (see below). This has the effect of creating an environment in which search paths only contain package inputs. @item --preserve=@var{regexp} @itemx -E @var{regexp} When used alongside @option{--pure}, preserve the environment variables matching @var{regexp}---in other words, put them on a ``white list'' of environment variables that must be preserved. This option can be repeated several times. @example guix shell --pure --preserve=^SLURM openmpi @dots{} \ -- mpirun @dots{} @end example This example runs @command{mpirun} in a context where the only environment variables defined are @env{PATH}, environment variables whose name starts with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME}, @env{USER}, etc.). @item --search-paths Display the environment variable definitions that make up the environment. @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}. @item --container @itemx -C @cindex container Run @var{command} within an isolated container. The current working directory outside the container is mapped inside the container. Additionally, unless overridden with @option{--user}, a dummy home directory is created that matches the current user's home directory, and @file{/etc/passwd} is configured accordingly. The spawned process runs as the current user outside the container. Inside the container, it has the same UID and GID as the current user, unless @option{--user} is passed (see below). @item --network @itemx -N For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device. @item --link-profile @itemx -P For containers, link the environment profile to @file{~/.guix-profile} within the container and set @code{GUIX_ENVIRONMENT} to that. This is equivalent to making @file{~/.guix-profile} a symlink to the actual profile within the container. Linking will fail and abort the environment if the directory already exists, which will certainly be the case if @command{guix shell} was invoked in the user's home directory. Certain packages are configured to look in @file{~/.guix-profile} for configuration files and data;@footnote{For example, the @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts} for additional fonts.} @option{--link-profile} allows these programs to behave as expected within the environment. @item --user=@var{user} @itemx -u @var{user} For containers, use the username @var{user} in place of the current user. The generated @file{/etc/passwd} entry within the container will contain the name @var{user}, the home directory will be @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore, the UID and GID inside the container are 1000. @var{user} need not exist on the system. Additionally, any shared or exposed path (see @option{--share} and @option{--expose} respectively) whose target is within the current user's home directory will be remapped relative to @file{/home/USER}; this includes the automatic mapping of the current working directory. @example # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target cd $HOME/wd guix shell --container --user=foo \ --expose=$HOME/test \ --expose=/tmp/target=$HOME/target @end example While this will limit the leaking of user identity through home paths and each of the user fields, this is only one useful component of a broader privacy/anonymity solution---not one in and of itself. @item --no-cwd For containers, the default behavior is to share the current working directory with the isolated container and immediately change to that directory within the container. If this is undesirable, @option{--no-cwd} will cause the current working directory to @emph{not} be automatically shared and will change to the user's home directory within the container instead. See also @option{--user}. @item --expose=@var{source}[=@var{target}] @itemx --share=@var{source}[=@var{target}] For containers, @option{--expose} (resp. @option{--share}) exposes the file system @var{source} from the host system as the read-only (resp. writable) file system @var{target} within the container. If @var{target} is not specified, @var{source} is used as the target mount point in the container. The example below spawns a Guile REPL in a container in which the user's home directory is accessible read-only via the @file{/exchange} directory: @example guix shell --container --expose=$HOME=/exchange guile -- guile @end example @cindex symbolic links, guix shell @item --symlink=@var{spec} @itemx -S @var{spec} For containers, create the symbolic links specified by @var{spec}, as documented in @ref{pack-symlink-option}. @cindex file system hierarchy standard (FHS) @cindex FHS (file system hierarchy standard) @item --emulate-fhs @itemx -F When used with @option{--container}, emulate a @uref{https://refspecs.linuxfoundation.org/fhs.shtml, Filesystem Hierarchy Standard (FHS)} configuration within the container, providing @file{/bin}, @file{/lib}, and other directories and files specified by the FHS. As Guix deviates from the FHS specification, this option sets up the container to more closely mimic that of other GNU/Linux distributions. This is useful for reproducing other development environments, testing, and using programs which expect the FHS specification to be followed. With this option, the container will include a version of glibc that will read @file{/etc/ld.so.cache} within the container for the shared library cache (contrary to glibc in regular Guix usage) and set up the expected FHS directories: @file{/bin}, @file{/etc}, @file{/lib}, and @file{/usr} from the container's profile. @cindex nested containers, for @command{guix shell} @cindex container nesting, for @command{guix shell} @item --nesting @itemx -W When used with @option{--container}, provide Guix @emph{inside} the container and arrange so that it can interact with the build daemon that runs outside the container. This is useful if you want, within your isolated container, to create other containers, as in this sample session: @example $ guix shell -CW coreutils [env]$ guix shell -C guile -- guile -c '(display "hello!\n")' hello! [env]$ exit @end example The session above starts a container with @code{coreutils} programs available in @env{PATH}. From there, we spawn @command{guix shell} to create a @emph{nested} container that provides nothing but Guile. Another example is evaluating a @file{guix.scm} file that is untrusted, as shown here: @example guix shell -CW -- guix build -f guix.scm @end example The @command{guix build} command as executed above can only access the current directory. Under the hood, the @option{-W} option does several things: @itemize @item map the daemon's socket (by default @file{/var/guix/daemon-socket/socket}) inside the container; @item map the whole store (by default @file{/gnu/store}) inside the container such that store items made available by nested @command{guix} invocations are visible; @item add the currently-used @command{guix} command to the profile in the container, such that @command{guix describe} returns the same state inside and outside the container; @item share the cache (by default @file{~/.cache/guix}) with the host, to speed up operations such as @command{guix time-machine} and @command{guix shell}. @end itemize @item --rebuild-cache @cindex caching, of profiles @cindex caching, in @command{guix shell} In most cases, @command{guix shell} caches the environment so that subsequent uses are instantaneous. Least-recently used cache entries are periodically removed. The cache is also invalidated, when using @option{--file} or @option{--manifest}, anytime the corresponding file is modified. The @option{--rebuild-cache} forces the cached environment to be refreshed. This is useful when using @option{--file} or @option{--manifest} and the @command{guix.scm} or @command{manifest.scm} file has external dependencies, or if its behavior depends, say, on environment variables. @item --root=@var{file} @itemx -r @var{file} @cindex persistent environment @cindex garbage collector root, for environments Make @var{file} a symlink to the profile for this environment, and register it as a garbage collector root. This is useful if you want to protect your environment from garbage collection, to make it ``persistent''. When this option is omitted, @command{guix shell} caches profiles so that subsequent uses of the same environment are instantaneous---this is comparable to using @option{--root} except that @command{guix shell} takes care of periodically removing the least-recently used garbage collector roots. In some cases, @command{guix shell} does not cache profiles---e.g., if transformation options such as @option{--with-latest} are used. In those cases, the environment is protected from garbage collection only for the duration of the @command{guix shell} session. This means that next time you recreate the same environment, you could have to rebuild or re-download packages. @xref{Invoking guix gc}, for more on GC roots. @end table @command{guix shell} also supports all of the common build options that @command{guix build} supports (@pxref{Common Build Options}) as well as package transformation options (@pxref{Package Transformation Options}). @node Invoking guix environment @section Invoking @command{guix environment} @cindex @command{guix environment} The purpose of @command{guix environment} is to assist in creating development environments. @quotation Deprecation warning The @command{guix environment} command is deprecated in favor of @command{guix shell}, which performs similar functions but is more convenient to use. @xref{Invoking guix shell}. Being deprecated, @command{guix environment} is slated for eventual removal, but the Guix project is committed to keeping it until May 1st, 2023. Please get in touch with us at @email{guix-devel@@gnu.org} if you would like to discuss it. @end quotation The general syntax is: @example guix environment @var{options} @var{package}@dots{} @end example The following example spawns a new shell set up for the development of GNU@tie{}Guile: @example guix environment guile @end example If the needed dependencies are not built yet, @command{guix environment} automatically builds them. The environment of the new shell is an augmented version of the environment that @command{guix environment} was run in. It contains the necessary search paths for building the given package added to the existing environment variables. To create a ``pure'' environment, in which the original environment variables have been unset, use the @option{--pure} option@footnote{Users sometimes wrongfully augment environment variables such as @env{PATH} in their @file{~/.bashrc} file. As a consequence, when @command{guix environment} launches it, Bash may read @file{~/.bashrc}, thereby introducing ``impurities'' in these environment variables. It is an error to define such environment variables in @file{.bashrc}; instead, they should be defined in @file{.bash_profile}, which is sourced only by log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for details on Bash start-up files.}. Exiting from a Guix environment is the same as exiting from the shell, and will place the user back in the old environment before @command{guix environment} was invoked. The next garbage collection (@pxref{Invoking guix gc}) will clean up packages that were installed from within the environment and are no longer used outside of it. @vindex GUIX_ENVIRONMENT @command{guix environment} defines the @env{GUIX_ENVIRONMENT} variable in the shell it spawns; its value is the file name of the profile of this environment. This allows users to, say, define a specific prompt for development environments in their @file{.bashrc} (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}): @example if [ -n "$GUIX_ENVIRONMENT" ] then export PS1="\u@@\h \w [dev]\$ " fi @end example @noindent ...@: or to browse the profile: @example $ ls "$GUIX_ENVIRONMENT/bin" @end example Additionally, more than one package may be specified, in which case the union of the inputs for the given packages are used. For example, the command below spawns a shell where all of the dependencies of both Guile and Emacs are available: @example guix environment guile emacs @end example Sometimes an interactive shell session is not desired. An arbitrary command may be invoked by placing the @code{--} token to separate the command from the rest of the arguments: @example guix environment guile -- make -j4 @end example In other situations, it is more convenient to specify the list of packages needed in the environment. For example, the following command runs @command{python} from an environment containing Python@tie{}3 and NumPy: @example guix environment --ad-hoc python-numpy python -- python3 @end example Furthermore, one might want the dependencies of a package and also some additional packages that are not build-time or runtime dependencies, but are useful when developing nonetheless. Because of this, the @option{--ad-hoc} flag is positional. Packages appearing before @option{--ad-hoc} are interpreted as packages whose dependencies will be added to the environment. Packages appearing after are interpreted as packages that will be added to the environment directly. For example, the following command creates a Guix development environment that additionally includes Git and strace: @example guix environment --pure guix --ad-hoc git strace @end example @cindex container Sometimes it is desirable to isolate the environment as much as possible, for maximal purity and reproducibility. In particular, when using Guix on a host distro that is not Guix System, it is desirable to prevent access to @file{/usr/bin} and other system-wide resources from the development environment. For example, the following command spawns a Guile REPL in a ``container'' where only the store and the current working directory are mounted: @example guix environment --ad-hoc --container guile -- guile @end example @quotation Note The @option{--container} option requires Linux-libre 3.19 or newer. @end quotation @cindex certificates Another typical use case for containers is to run security-sensitive applications such as a web browser. To run Eolie, we must expose and share some files and directories; we include @code{nss-certs} and expose @file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the @env{DISPLAY} environment variable since containerized graphical applications won't display without it. @example guix environment --preserve='^DISPLAY$' --container --network \ --expose=/etc/machine-id \ --expose=/etc/ssl/certs/ \ --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \ --ad-hoc eolie nss-certs dbus -- eolie @end example The available options are summarized below. @table @code @item --check Set up the environment and check whether the shell would clobber environment variables. @xref{Invoking guix shell, @option{--check}}, for more info. @item --root=@var{file} @itemx -r @var{file} @cindex persistent environment @cindex garbage collector root, for environments Make @var{file} a symlink to the profile for this environment, and register it as a garbage collector root. This is useful if you want to protect your environment from garbage collection, to make it ``persistent''. When this option is omitted, the environment is protected from garbage collection only for the duration of the @command{guix environment} session. This means that next time you recreate the same environment, you could have to rebuild or re-download packages. @xref{Invoking guix gc}, for more on GC roots. @item --expression=@var{expr} @itemx -e @var{expr} Create an environment for the package or list of packages that @var{expr} evaluates to. For example, running: @example guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' @end example starts a shell with the environment for this specific variant of the PETSc package. Running: @example guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' @end example starts a shell with all the base system packages available. The above commands only use the default output of the given packages. To select other outputs, two element tuples can be specified: @example guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' @end example @item --load=@var{file} @itemx -l @var{file} Create an environment for the package or list of packages that the code within @var{file} evaluates to. As an example, @var{file} might contain a definition like this (@pxref{Defining Packages}): @lisp @verbatiminclude environment-gdb.scm @end lisp @item --manifest=@var{file} @itemx -m @var{file} Create an environment for the packages contained in 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 is similar to the same-named option in @command{guix package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest files. @xref{shell-export-manifest, @command{guix shell --export-manifest}}, for information on how to ``convert'' command-line options into a manifest. @item --ad-hoc Include all specified packages in the resulting environment, as if an @i{ad hoc} package were defined with them as inputs. This option is useful for quickly creating an environment without having to write a package expression to contain the desired inputs. For instance, the command: @example guix environment --ad-hoc guile guile-sdl -- guile @end example runs @command{guile} in an environment where Guile and Guile-SDL are available. Note that this example implicitly asks for the default output of @code{guile} and @code{guile-sdl}, but it is possible to ask for a specific output---e.g., @code{glib:bin} asks for the @code{bin} output of @code{glib} (@pxref{Packages with Multiple Outputs}). This option may be composed with the default behavior of @command{guix environment}. Packages appearing before @option{--ad-hoc} are interpreted as packages whose dependencies will be added to the environment, the default behavior. Packages appearing after are interpreted as packages that will be added to the environment directly. @item --profile=@var{profile} @itemx -p @var{profile} Create an environment containing the packages installed in @var{profile}. Use @command{guix package} (@pxref{Invoking guix package}) to create and manage profiles. @item --pure Unset existing environment variables when building the new environment, except those specified with @option{--preserve} (see below). This has the effect of creating an environment in which search paths only contain package inputs. @item --preserve=@var{regexp} @itemx -E @var{regexp} When used alongside @option{--pure}, preserve the environment variables matching @var{regexp}---in other words, put them on a ``white list'' of environment variables that must be preserved. This option can be repeated several times. @example guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ -- mpirun @dots{} @end example This example runs @command{mpirun} in a context where the only environment variables defined are @env{PATH}, environment variables whose name starts with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME}, @env{USER}, etc.). @item --search-paths Display the environment variable definitions that make up the environment. @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}. @item --container @itemx -C @cindex container Run @var{command} within an isolated container. The current working directory outside the container is mapped inside the container. Additionally, unless overridden with @option{--user}, a dummy home directory is created that matches the current user's home directory, and @file{/etc/passwd} is configured accordingly. The spawned process runs as the current user outside the container. Inside the container, it has the same UID and GID as the current user, unless @option{--user} is passed (see below). @item --network @itemx -N For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device. @item --link-profile @itemx -P For containers, link the environment profile to @file{~/.guix-profile} within the container and set @code{GUIX_ENVIRONMENT} to that. This is equivalent to making @file{~/.guix-profile} a symlink to the actual profile within the container. Linking will fail and abort the environment if the directory already exists, which will certainly be the case if @command{guix environment} was invoked in the user's home directory. Certain packages are configured to look in @file{~/.guix-profile} for configuration files and data;@footnote{For example, the @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts} for additional fonts.} @option{--link-profile} allows these programs to behave as expected within the environment. @item --user=@var{user} @itemx -u @var{user} For containers, use the username @var{user} in place of the current user. The generated @file{/etc/passwd} entry within the container will contain the name @var{user}, the home directory will be @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore, the UID and GID inside the container are 1000. @var{user} need not exist on the system. Additionally, any shared or exposed path (see @option{--share} and @option{--expose} respectively) whose target is within the current user's home directory will be remapped relative to @file{/home/USER}; this includes the automatic mapping of the current working directory. @example # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target cd $HOME/wd guix environment --container --user=foo \ --expose=$HOME/test \ --expose=/tmp/target=$HOME/target @end example While this will limit the leaking of user identity through home paths and each of the user fields, this is only one useful component of a broader privacy/anonymity solution---not one in and of itself. @item --no-cwd For containers, the default behavior is to share the current working directory with the isolated container and immediately change to that directory within the container. If this is undesirable, @option{--no-cwd} will cause the current working directory to @emph{not} be automatically shared and will change to the user's home directory within the container instead. See also @option{--user}. @item --expose=@var{source}[=@var{target}] @itemx --share=@var{source}[=@var{target}] For containers, @option{--expose} (resp. @option{--share}) exposes the file system @var{source} from the host system as the read-only (resp. writable) file system @var{target} within the container. If @var{target} is not specified, @var{source} is used as the target mount point in the container. The example below spawns a Guile REPL in a container in which the user's home directory is accessible read-only via the @file{/exchange} directory: @example guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile @end example @item --emulate-fhs @item -F For containers, emulate a Filesystem Hierarchy Standard (FHS) configuration within the container, see @uref{https://refspecs.linuxfoundation.org/fhs.shtml, the official specification}. As Guix deviates from the FHS specification, this option sets up the container to more closely mimic that of other GNU/Linux distributions. This is useful for reproducing other development environments, testing, and using programs which expect the FHS specification to be followed. With this option, the container will include a version of @code{glibc} which will read @code{/etc/ld.so.cache} within the container for the shared library cache (contrary to @code{glibc} in regular Guix usage) and set up the expected FHS directories: @code{/bin}, @code{/etc}, @code{/lib}, and @code{/usr} from the container's profile. @end table @command{guix environment} also supports all of the common build options that @command{guix build} supports (@pxref{Common Build Options}) as well as package transformation options (@pxref{Package Transformation Options}). @node Invoking guix pack @section Invoking @command{guix pack} @cindex @command{guix pack} Occasionally you want to pass software to people who are not (yet!) lucky enough to be using Guix. You'd tell them to run @command{guix package -i @var{something}}, but that's not possible in this case. This is where @command{guix pack} comes in. @quotation Note If you are looking for ways to exchange binaries among machines that already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix publish}, and @ref{Invoking guix archive}. @end quotation @cindex pack @cindex bundle @cindex application bundle @cindex software bundle The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or @dfn{software bundle}: it creates a tarball or some other archive containing the binaries of the software you're interested in, and all its dependencies. The resulting archive can be used on any machine that does not have Guix, and people can run the exact same binaries as those you have with Guix. The pack itself is created in a bit-reproducible fashion, so anyone can verify that it really contains the build results that you pretend to be shipping. For example, to create a bundle containing Guile, Emacs, Geiser, and all their dependencies, you can run: @example $ guix pack guile emacs emacs-geiser @dots{} /gnu/store/@dots{}-pack.tar.gz @end example The result here is a tarball containing a @file{/gnu/store} directory with all the relevant packages. The resulting tarball contains a @dfn{profile} with the three packages of interest; the profile is the same as would be created by @command{guix package -i}. It is this mechanism that is used to create Guix's own standalone binary tarball (@pxref{Binary Installation}). Users of this pack would have to run @file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may find inconvenient. To work around it, you can create, say, a @file{/opt/gnu/bin} symlink to the profile: @example guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser @end example @noindent That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy. @cindex relocatable binaries, with @command{guix pack} What if the recipient of your pack does not have root privileges on their machine, and thus cannot unpack it in the root file system? In that case, you will want to use the @option{--relocatable} option (see below). This option produces @dfn{relocatable binaries}, meaning they can be placed anywhere in the file system hierarchy: in the example above, users can unpack your tarball in their home directory and directly run @file{./opt/gnu/bin/guile}. @cindex Docker, build an image with guix pack Alternatively, you can produce a pack in the Docker image format using the following command: @example guix pack -f docker -S /bin=bin guile guile-readline @end example @noindent The result is a tarball that can be passed to the @command{docker load} command, followed by @code{docker run}: @example docker load < @var{file} docker run -ti guile-guile-readline /bin/guile @end example @noindent where @var{file} is the image returned by @command{guix pack}, and @code{guile-guile-readline} is its ``image tag''. See the @uref{https://docs.docker.com/engine/reference/commandline/load/, Docker documentation} for more information. @cindex Singularity, build an image with guix pack @cindex SquashFS, build an image with guix pack Yet another option is to produce a SquashFS image with the following command: @example guix pack -f squashfs bash guile emacs emacs-geiser @end example @noindent The result is a SquashFS file system image that can either be mounted or directly be used as a file system container image with the @uref{https://www.sylabs.io/docs/, Singularity container execution environment}, using commands like @command{singularity shell} or @command{singularity exec}. @cindex AppImage, create an AppImage file with @command{guix pack} Another format internally based on SquashFS is @uref{https://appimage.org/, AppImage}. An AppImage file can be created and executed without any special privileges: @example file=$(guix pack -f appimage --entry-point=bin/guile guile) $file --help @end example Several command-line options allow you to customize your pack: @table @code @item --format=@var{format} @itemx -f @var{format} Produce a pack in the given @var{format}. The available formats are: @table @code @item tarball This is the default format. It produces a tarball containing all the specified binaries and symlinks. @item docker This produces a tarball that follows the @uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, Docker Image Specification}. By default, the ``repository name'' as it appears in the output of the @command{docker images} command is computed from package names passed on the command line or in the manifest file. Alternatively, the ``repository name'' can also be configured via the @option{--image-tag} option. Refer to @option{--help-docker-format} for more information on such advanced options. @item squashfs This produces a SquashFS image containing all the specified binaries and symlinks, as well as empty mount points for virtual file systems like procfs. @quotation Note Singularity @emph{requires} you to provide @file{/bin/sh} in the image. For that reason, @command{guix pack -f squashfs} always implies @code{-S /bin=bin}. Thus, your @command{guix pack} invocation must always start with something like: @example guix pack -f squashfs bash @dots{} @end example If you forget the @code{bash} (or similar) package, @command{singularity run} and @command{singularity exec} will fail with an unhelpful ``no such file or directory'' message. @end quotation @item deb @cindex Debian, build a .deb package with guix pack This produces a Debian archive (a package with the @samp{.deb} file extension) containing all the specified binaries and symbolic links, that can be installed on top of any dpkg-based GNU(/Linux) distribution. Advanced options can be revealed via the @option{--help-deb-format} option. They allow embedding control files for more fine-grained control, such as activating specific triggers or providing a maintainer configure script to run arbitrary setup code upon installation. @example guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello @end example @quotation Note Because archives produced with @command{guix pack} contain a collection of store items and because each @command{dpkg} package must not have conflicting files, in practice that means you likely won't be able to install more than one such archive on a given system. You can nonetheless pack as many Guix packages as you want in one such archive. @end quotation @quotation Warning @command{dpkg} will assume ownership of any files contained in the pack that it does @emph{not} know about. It is unwise to install Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is shared by other software, such as a Guix installation or other, non-deb packs. @end quotation @item rpm @cindex RPM, build an RPM archive with guix pack This produces an RPM archive (a package with the @samp{.rpm} file extension) containing all the specified binaries and symbolic links, that can be installed on top of any RPM-based GNU/Linux distribution. The RPM format embeds checksums for every file it contains, which the @command{rpm} command uses to validate the integrity of the archive. Advanced RPM-related options are revealed via the @option{--help-rpm-format} option. These options allow embedding maintainer scripts that can run before or after the installation of the RPM archive, for example. The RPM format supports relocatable packages via the @option{--prefix} option of the @command{rpm} command, which can be handy to install an RPM package to a specific prefix. @example guix pack -f rpm -R -C xz -S /usr/bin/hello=bin/hello hello @end example @example sudo rpm --install --prefix=/opt /gnu/store/...-hello.rpm @end example @quotation Note Contrary to Debian packages, conflicting but @emph{identical} files in RPM packages can be installed simultaneously, which means multiple @command{guix pack}-produced RPM packages can usually be installed side by side without any problem. @end quotation @quotation Warning @command{rpm} assumes ownership of any files contained in the pack, which means it will remove @file{/gnu/store} upon uninstalling a Guix-generated RPM package, unless the RPM package was installed with the @option{--prefix} option of the @command{rpm} command. It is unwise to install Guix-produced @samp{.rpm} packages on a system where @file{/gnu/store} is shared by other software, such as a Guix installation or other, non-rpm packs. @end quotation @item appimage @cindex AppImage, create an AppImage file with @command{guix pack} This produces an @uref{https://appimage.org/, AppImage file} with the @samp{.AppImage} extension. AppImage is a SquashFS volume prefixed with a runtime that mounts the SquashFS file system and executes the binary provided with @option{--entry-point}. This results in a self-contained archive that bundles the software and all its requirements into a single file. When the file is made executable it runs the packaged software. @example guix pack -f appimage --entry-point=bin/vlc vlc @end example The runtime used by AppImages invokes the @command{fusermount3} command to mount the image quickly. If that command is unavailable, the AppImage fails to run, but it can still be started by passing the @option{--appimage-extract-and-run} flag. @quotation Warning When building an AppImage, always @emph{pass} the @option{--relocatable} option (or @option{-R}, or @option{-RR}) to make sure the image can be used on systems where Guix is not installed. A warning is printed when this option is not used. @end quotation @example guix pack -f appimage --entry-point=bin/hello --relocatable hello @end example @quotation Note The resulting AppImage does not conform to the complete standard as it currently does not contain a @file{.DirIcon} file. This does not impact functionality of the AppImage itself, but possibly that of software used to manage AppImages. @end quotation @quotation Note As the generated AppImage packages the complete dependency graph, it will be larger than comparable AppImage files found online, which depend on host system libraries. @end quotation @end table @cindex relocatable binaries @item --relocatable @itemx -R Produce @dfn{relocatable binaries}---i.e., binaries that can be placed anywhere in the file system hierarchy and run from there. When this option is passed once, the resulting binaries require support for @dfn{user namespaces} in the kernel Linux; when passed @emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds PRoot support, can be thought of as the abbreviation of ``Really Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to other techniques if user namespaces are unavailable, and essentially work anywhere---see below for the implications. For example, if you create a pack containing Bash with: @example guix pack -RR -S /mybin=bin bash @end example @noindent ...@: you can copy that pack to a machine that lacks Guix, and from your home directory as a normal user, run: @example tar xf pack.tar.gz ./mybin/sh @end example @noindent In that shell, if you type @code{ls /gnu/store}, you'll notice that @file{/gnu/store} shows up and contains all the dependencies of @code{bash}, even though the machine actually lacks @file{/gnu/store} altogether! That is probably the simplest way to deploy Guix-built software on a non-Guix machine. @quotation Note By default, relocatable binaries rely on the @dfn{user namespace} feature of the kernel Linux, which allows unprivileged users to mount or change root. Old versions of Linux did not support it, and some GNU/Linux distributions turn it off. To produce relocatable binaries that work even in the absence of user namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In that case, binaries will try user namespace support and fall back to another @dfn{execution engine} if user namespaces are not supported. The following execution engines are supported: @table @code @item default Try user namespaces and fall back to PRoot if user namespaces are not supported (see below). @item performance Try user namespaces and fall back to Fakechroot if user namespaces are not supported (see below). @item userns Run the program through user namespaces and abort if they are not supported. @item proot Run through PRoot. The @uref{https://proot-me.github.io/, PRoot} program provides the necessary support for file system virtualization. It achieves that by using the @code{ptrace} system call on the running program. This approach has the advantage to work without requiring special kernel support, but it incurs run-time overhead every time a system call is made. @item fakechroot Run through Fakechroot. @uref{https://github.com/dex4er/fakechroot/, Fakechroot} virtualizes file system accesses by intercepting calls to C library functions such as @code{open}, @code{stat}, @code{exec}, and so on. Unlike PRoot, it incurs very little overhead. However, it does not always work: for example, some file system accesses made from within the C library are not intercepted, and file system accesses made @i{via} direct syscalls are not intercepted either, leading to erratic behavior. @end table @vindex GUIX_EXECUTION_ENGINE When running a wrapped program, you can explicitly request one of the execution engines listed above by setting the @env{GUIX_EXECUTION_ENGINE} environment variable accordingly. @end quotation @cindex entry point, for Docker and Singularity images @item --entry-point=@var{command} Use @var{command} as the @dfn{entry point} of the resulting pack, if the pack format supports it---currently @code{docker}, @code{appimage}, and @code{squashfs} (Singularity) support it. @var{command} must be relative to the profile contained in the pack. The entry point specifies the command that tools like @code{docker run} or @code{singularity run} automatically start by default. For example, you can do: @example guix pack -f docker --entry-point=bin/guile guile @end example The resulting pack can easily be loaded and @code{docker run} with no extra arguments will spawn @code{bin/guile}: @example docker load -i pack.tar.gz docker run @var{image-id} @end example @cindex entry point arguments, for docker images @item --entry-point-argument=@var{command} @itemx -A @var{command} Use @var{command} as an argument to @dfn{entry point} of the resulting pack. This option is only valid in conjunction with @code{--entry-point} and can appear multiple times on the command line. @example guix pack -f docker --entry-point=bin/guile --entry-point-argument="--help" guile @end example @cindex maximum layers argument, for docker images @item --max-layers=@code{n} Specifies the maximum number of Docker image layers allowed when building an image. @example guix pack -f docker --max-layers=100 guile @end example This option allows you to limit the number of layers in a Docker image. Docker images are comprised of multiple layers, and each layer adds to the overall size and complexity of the image. By setting a maximum number of layers, you can control the following effects: @itemize @item Disk Usage: Increasing the number of layers can help optimize the disk space required to store multiple images built with a similar package graph. @item Pulling: When transferring images between different nodes or systems, having more layers can reduce the time required to pull the image. @end itemize @item --expression=@var{expr} @itemx -e @var{expr} Consider the package @var{expr} evaluates to. This has the same purpose as the same-named option in @command{guix build} (@pxref{Additional Build Options, @option{--expression} in @command{guix build}}). @item --file=@var{file} Build a pack containing the package or other object the code within @var{file} evaluates to. This has the same purpose as the same-named option in @command{guix build} (@pxref{Additional Build Options, @option{--file} in @command{guix build}}), but it has no shorthand, because @option{-f} already means @option{--format}. @anchor{pack-manifest} @item --manifest=@var{file} @itemx -m @var{file} Use the packages contained in 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 has a similar purpose as the same-named option in @command{guix package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest files. It allows you to define a collection of packages once and use it both for creating profiles and for creating archives for use on machines that do not have Guix installed. Note that you can specify @emph{either} a manifest file @emph{or} a list of packages, but not both. @xref{Writing Manifests}, for information on how to write a manifest. @xref{shell-export-manifest, @command{guix shell --export-manifest}}, for information on how to ``convert'' command-line options into a manifest. @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the system type of the build host. @item --target=@var{triplet} @cindex cross-compilation Cross-build for @var{triplet}, which must be a valid GNU triplet, such as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU configuration triplets,, autoconf, Autoconf}). @item --compression=@var{tool} @itemx -C @var{tool} Compress the resulting tarball using @var{tool}---one of @code{gzip}, @code{zstd}, @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression. @anchor{pack-symlink-option} @item --symlink=@var{spec} @itemx -S @var{spec} Add the symlinks specified by @var{spec} to the pack. This option can appear several times. @var{spec} has the form @code{@var{source}=@var{target}}, where @var{source} is the symlink that will be created and @var{target} is the symlink target. For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin} symlink pointing to the @file{bin} sub-directory of the profile. @item --save-provenance Save provenance information for the packages passed on the command line. Provenance information includes the URL and commit of the channels in use (@pxref{Channels}). Provenance information is saved in the @file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the usual package metadata---the name and version of each package, their propagated inputs, and so on. It is useful information to the recipient of the pack, who then knows how the pack was (supposedly) obtained. This option is not enabled by default because, like timestamps, provenance information contributes nothing to the build process. In other words, there is an infinity of channel URLs and commit IDs that can lead to the same pack. Recording such ``silent'' metadata in the output thus potentially breaks the source-to-binary bitwise reproducibility property. @item --root=@var{file} @itemx -r @var{file} @cindex garbage collector root, for packs Make @var{file} a symlink to the resulting pack, and register it as a garbage collector root. @item --localstatedir @itemx --profile-name=@var{name} Include the ``local state directory'', @file{/var/guix}, in the resulting pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}} profile---by default @var{name} is @code{guix-profile}, which corresponds to @file{~root/.guix-profile}. @file{/var/guix} contains the store database (@pxref{The Store}) as well as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in the pack means that the store is ``complete'' and manageable by Guix; not providing it in the pack means that the store is ``dead'': items cannot be added to it or removed from it after extraction of the pack. One use case for this is the Guix self-contained binary tarball (@pxref{Binary Installation}). @item --derivation @itemx -d Print the name of the derivation that builds the pack. @item --bootstrap Use the bootstrap binaries to build the pack. This option is only useful to Guix developers. @end table In addition, @command{guix pack} supports all the common build options (@pxref{Common Build Options}) and all the package transformation options (@pxref{Package Transformation Options}). @node The GCC toolchain @section The GCC toolchain @cindex GCC @cindex ld-wrapper @cindex linker wrapper @cindex toolchain, for C development @cindex toolchain, for Fortran development If you need a complete toolchain for compiling and linking C or C++ source code, use the @code{gcc-toolchain} package. This package provides a complete GCC toolchain for C/C++ development, including GCC itself, the GNU C Library (headers and binaries, plus debugging symbols in the @code{debug} output), Binutils, and a linker wrapper. The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches passed to the linker, add corresponding @code{-rpath} arguments, and invoke the actual linker with this new set of arguments. You can instruct the wrapper to refuse to link against libraries not in the store by setting the @env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. The package @code{gfortran-toolchain} provides a complete GCC toolchain for Fortran development. For other languages, please use @samp{guix search gcc toolchain} (@pxref{guix-search,, Invoking guix package}). @node Invoking guix git authenticate @section Invoking @command{guix git authenticate} @cindex @command{guix git authenticate} @cindex authentication, of Git checkouts @cindex Git checkout authentication The @command{guix git authenticate} command authenticates a Git checkout following the same rule as for channels (@pxref{channel-authentication, channel authentication}). That is, starting from a given commit, it ensures that all subsequent commits are signed by an OpenPGP key whose fingerprint appears in the @file{.guix-authorizations} file of its parent commit(s). You will find this command useful if you maintain a channel. But in fact, this authentication mechanism is useful in a broader context, so you might want to use it for Git repositories that have nothing to do with Guix. The general syntax is: @example guix git authenticate @var{commit} @var{signer} [@var{options}@dots{}] @end example @cindex introduction, for Git authentication By default, this command authenticates the Git checkout in the current directory; it outputs nothing and exits with exit code zero on success and non-zero on failure. @var{commit} above denotes the first commit where authentication takes place, and @var{signer} is the OpenPGP fingerprint of public key used to sign @var{commit}. Together, they form a @dfn{channel introduction} (@pxref{channel-authentication, channel introduction}). On your first successful run, the introduction is recorded in the @file{.git/config} file of your checkout, allowing you to omit them from subsequent invocations: @example guix git authenticate [@var{options}@dots{}] @end example Should you have branches that require different introductions, you can specify them directly in @file{.git/config}. For example, if the branch called @code{personal-fork} has a different introduction than other branches, you can extend @file{.git/config} along these lines: @smallexample [guix "authentication-personal-fork"] introduction-commit = cabba936fd807b096b48283debdcddccfea3900d introduction-signer = C0FF EECA BBA9 E6A8 0D1D E643 A2A0 6DF2 A33A 54FA keyring = keyring @end smallexample The first run also attempts to install pre-push and post-merge hooks, such that @command{guix git authenticate} is invoked as soon as you run @command{git push}, @command{git pull}, and related commands; it does not overwrite preexisting hooks though. The command-line options described below allow you to fine-tune the process. @table @code @item --repository=@var{directory} @itemx -r @var{directory} Open the Git repository in @var{directory} instead of the current directory. @item --keyring=@var{reference} @itemx -k @var{reference} Load OpenPGP keyring from @var{reference}, the reference of a branch such as @code{origin/keyring} or @code{my-keyring}. The branch must contain OpenPGP public keys in @file{.key} files, either in binary form or ``ASCII-armored''. By default the keyring is loaded from the branch named @code{keyring}. @item --end=@var{commit} Authenticate revisions up to @var{commit}. @item --stats Display commit signing statistics upon completion. @item --cache-key=@var{key} Previously-authenticated commits are cached in a file under @file{~/.cache/guix/authentication}. This option forces the cache to be stored in file @var{key} in that directory. @item --historical-authorizations=@var{file} By default, any commit whose parent commit(s) lack the @file{.guix-authorizations} file is considered inauthentic. In contrast, this option considers the authorizations in @var{file} for any commit that lacks @file{.guix-authorizations}. The format of @var{file} is the same as that of @file{.guix-authorizations} (@pxref{channel-authorizations, @file{.guix-authorizations} format}). @end table @c ********************************************************************* @node Programming Interface @chapter Programming Interface GNU Guix provides several Scheme programming interfaces (APIs) to define, build, and query packages. The first interface allows users to write high-level package definitions. These definitions refer to familiar packaging concepts, such as the name and version of a package, its build system, and its dependencies. These definitions can then be turned into concrete build actions. Build actions are performed by the Guix daemon, on behalf of users. In a standard setup, the daemon has write access to the store---the @file{/gnu/store} directory---whereas users do not. The recommended setup also has the daemon perform builds in chroots, under specific build users, to minimize interference with the rest of the system. @cindex derivation Lower-level APIs are available to interact with the daemon and the store. To instruct the daemon to perform a build action, users actually provide it with a @dfn{derivation}. A derivation is a low-level representation of the build actions to be taken, and the environment in which they should occur---derivations are to package definitions what assembly is to C programs. The term ``derivation'' comes from the fact that build results @emph{derive} from them. This chapter describes all these APIs in turn, starting from high-level package definitions. @xref{Source Tree Structure}, for a more general overview of the source code. @menu * 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. @end menu @node Package Modules @section Package Modules From a programming viewpoint, the package definitions of the GNU distribution are provided by Guile modules in the @code{(gnu packages @dots{})} name space@footnote{Note that packages under the @code{(gnu packages @dots{})} module name space are not necessarily ``GNU packages''. This module naming scheme follows the usual Guile module naming convention: @code{gnu} means that these modules are distributed as part of the GNU system, and @code{packages} identifies modules that define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile Reference Manual}). For instance, the @code{(gnu packages emacs)} module exports a variable named @code{emacs}, which is bound to a @code{<package>} object (@pxref{Defining Packages}). The @code{(gnu packages @dots{})} module name space is automatically scanned for packages by the command-line tools. For instance, when running @code{guix install emacs}, all the @code{(gnu packages @dots{})} modules are scanned until one that exports a package object whose name is @code{emacs} is found. This package search facility is implemented in the @code{(gnu packages)} module. @cindex customization, of packages @cindex package module search path Users can store package definitions in modules with different names---e.g., @code{(my-packages emacs)}@footnote{Note that the file name and module name must match. For instance, the @code{(my-packages emacs)} module must be stored in a @file{my-packages/emacs.scm} file relative to the load path specified with @option{--load-path} or @env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, guile, GNU Guile Reference Manual}, for details.}. There are two ways to make these package definitions visible to the user interfaces: @enumerate @item By adding the directory containing your package modules to the search path with the @code{-L} flag of @command{guix package} and other commands (@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH} environment variable described below. @item By defining a @dfn{channel} and configuring @command{guix pull} so that it pulls from it. A channel is essentially a Git repository containing package modules. @xref{Channels}, for more information on how to define and use channels. @end enumerate @env{GUIX_PACKAGE_PATH} works similarly to other search path variables: @defvr {Environment Variable} GUIX_PACKAGE_PATH This is a colon-separated list of directories to search for additional package modules. Directories listed in this variable take precedence over the own modules of the distribution. @end defvr The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: each package is built based solely on other packages in the distribution. The root of this dependency graph is a small set of @dfn{bootstrap binaries}, provided by the @code{(gnu packages bootstrap)} module. For more information on bootstrapping, @pxref{Bootstrapping}. @node Defining Packages @section Defining Packages The high-level interface to package definitions is implemented in the @code{(guix packages)} and @code{(guix build-system)} modules. As an example, the package definition, or @dfn{recipe}, for the GNU Hello package looks like this: @lisp (define-module (gnu packages hello) #:use-module (guix packages) #:use-module (guix download) #:use-module (guix build-system gnu) #:use-module (guix licenses) #:use-module (gnu packages gawk)) (define-public hello (package (name "hello") (version "2.10") (source (origin (method url-fetch) (uri (string-append "mirror://gnu/hello/hello-" version ".tar.gz")) (sha256 (base32 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) (build-system gnu-build-system) (arguments '(#:configure-flags '("--enable-silent-rules"))) (inputs (list gawk)) (synopsis "Hello, GNU world: An example GNU package") (description "Guess what GNU Hello prints!") (home-page "https://www.gnu.org/software/hello/") (license gpl3+))) @end lisp @noindent Without being a Scheme expert, the reader may have guessed the meaning of the various fields here. This expression binds the variable @code{hello} to a @code{<package>} object, which is essentially a record (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}). This package object can be inspected using procedures found in the @code{(guix packages)} module; for instance, @code{(package-name hello)} returns---surprise!---@code{"hello"}. With luck, you may be able to import part or all of the definition of the package you are interested in from another repository, using the @code{guix import} command (@pxref{Invoking guix import}). In the example above, @code{hello} is defined in a module of its own, @code{(gnu packages hello)}. Technically, this is not strictly necessary, but it is convenient to do so: all the packages defined in modules under @code{(gnu packages @dots{})} are automatically known to the command-line tools (@pxref{Package Modules}). There are a few points worth noting in the above package definition: @itemize @item The @code{source} field of the package is an @code{<origin>} object (@pxref{origin Reference}, for the complete reference). Here, the @code{url-fetch} method from @code{(guix download)} is used, meaning that the source is a file to be downloaded over FTP or HTTP. The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of the GNU mirrors defined in @code{(guix download)}. The @code{sha256} field specifies the expected SHA256 hash of the file being downloaded. It is mandatory, and allows Guix to check the integrity of the file. The @code{(base32 @dots{})} form introduces the base32 representation of the hash. You can obtain this information with @code{guix download} (@pxref{Invoking guix download}) and @code{guix hash} (@pxref{Invoking guix hash}). @cindex patches When needed, the @code{origin} form can also have a @code{patches} field listing patches to be applied, and a @code{snippet} field giving a Scheme expression to modify the source code. @item @cindex GNU Build System The @code{build-system} field specifies the procedure to build the package (@pxref{Build Systems}). Here, @code{gnu-build-system} represents the familiar GNU Build System, where packages may be configured, built, and installed with the usual @code{./configure && make && make check && make install} command sequence. When you start packaging non-trivial software, you may need tools to manipulate those build phases, manipulate files, and so on. @xref{Build Utilities}, for more on this. @item The @code{arguments} field specifies options for the build system (@pxref{Build Systems}). Here it is interpreted by @code{gnu-build-system} as a request run @file{configure} with the @option{--enable-silent-rules} flag. @cindex quote @cindex quoting @findex ' @findex quote @cindex backquote (quasiquote) @findex ` @findex quasiquote @cindex comma (unquote) @findex , @findex unquote What about these quote (@code{'}) characters? They are Scheme syntax to introduce a literal list; @code{'} is synonymous with @code{quote}. Sometimes you'll also see @code{`} (a backquote, synonymous with @code{quasiquote}) and @code{,} (a comma, synonymous with @code{unquote}). @xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual}, for details. Here the value of the @code{arguments} field is a list of arguments passed to the build system down the road, as with @code{apply} (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword} (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and @code{#:configure-flags} is a keyword used to pass a keyword argument to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile Reference Manual}). @item The @code{inputs} field specifies inputs to the build process---i.e., build-time or run-time dependencies of the package. Here, we add an input, a reference to the @code{gawk} variable; @code{gawk} is itself bound to a @code{<package>} object. Note that GCC, Coreutils, Bash, and other essential tools do not need to be specified as inputs here. Instead, @code{gnu-build-system} takes care of ensuring that they are present (@pxref{Build Systems}). However, any other dependencies need to be specified in the @code{inputs} field. Any dependency not specified here will simply be unavailable to the build process, possibly leading to a build failure. @end itemize @xref{package Reference}, for a full description of possible fields. @quotation Going further @cindex Scheme programming language, getting started Intimidated by the Scheme language or curious about it? The Cookbook has a short section to get started that recaps some of the things shown above and explains the fundamentals. @xref{A Scheme Crash Course,,, guix-cookbook, GNU Guix Cookbook}, for more information. @end quotation Once a package definition is in place, the package may actually be built using the @code{guix build} command-line tool (@pxref{Invoking guix build}), troubleshooting any build failures you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the package definition using the @command{guix edit} command (@pxref{Invoking guix edit}). @xref{Packaging Guidelines}, for more information on how to test package definitions, and @ref{Invoking guix lint}, for information on how to check a definition for style conformance. @vindex GUIX_PACKAGE_PATH Lastly, @pxref{Channels}, for information on how to extend the distribution by adding your own package definitions in a ``channel''. Finally, updating the package definition to a new upstream version can be partly automated by the @command{guix refresh} command (@pxref{Invoking guix refresh}). Behind the scenes, a derivation corresponding to the @code{<package>} object is first computed by the @code{package-derivation} procedure. That derivation is stored in a @file{.drv} file under @file{/gnu/store}. The build actions it prescribes may then be realized by using the @code{build-derivations} procedure (@pxref{The Store}). @deffn {Procedure} package-derivation store package [system] Return the @code{<derivation>} object of @var{package} for @var{system} (@pxref{Derivations}). @var{package} must be a valid @code{<package>} object, and @var{system} must be a string denoting the target system type---e.g., @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store} must be a connection to the daemon, which operates on the store (@pxref{The Store}). @end deffn @noindent @cindex cross-compilation Similarly, it is possible to compute a derivation that cross-builds a package for some other system: @deffn {Procedure} package-cross-derivation store package target [system] Return the @code{<derivation>} object of @var{package} cross-built from @var{system} to @var{target}. @var{target} must be a valid GNU triplet denoting the target hardware and operating system, such as @code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets,,, autoconf, Autoconf}). @end deffn Once you have package definitions, you can easily define @emph{variants} of those packages. @xref{Defining Package Variants}, for more on that. @menu * package Reference:: The package data type. * origin Reference:: The origin data type. @end menu @node package Reference @subsection @code{package} Reference This section summarizes all the options available in @code{package} declarations (@pxref{Defining Packages}). @deftp {Data Type} package This is the data type representing a package recipe. @table @asis @item @code{name} The name of the package, as a string. @item @code{version} The version of the package, as a string. @xref{Version Numbers}, for guidelines. @item @code{source} An object telling how the source code for the package should be acquired. Most of the time, this is an @code{origin} object, which denotes a file fetched from the Internet (@pxref{origin Reference}). It can also be any other ``file-like'' object such as a @code{local-file}, which denotes a file from the local file system (@pxref{G-Expressions, @code{local-file}}). @item @code{build-system} The build system that should be used to build the package (@pxref{Build Systems}). @item @code{arguments} (default: @code{'()}) The arguments that should be passed to the build system (@pxref{Build Systems}). This is a list, typically containing sequential keyword-value pairs, as in this example: @lisp (package (name "example") ;; several fields omitted (arguments (list #:tests? #f ;skip tests #:make-flags #~'("VERBOSE=1") ;pass flags to 'make' #:configure-flags #~'("--enable-frobbing")))) @end lisp The exact set of supported keywords depends on the build system (@pxref{Build Systems}), but you will find that almost all of them honor @code{#:configure-flags}, @code{#:make-flags}, @code{#:tests?}, and @code{#:phases}. The @code{#:phases} keyword in particular lets you modify the set of build phases for your package (@pxref{Build Phases}). The REPL has dedicated commands to interactively inspect values of some of these arguments, as a convenient debugging aid (@pxref{Using Guix Interactively}). @quotation Compatibility Note Until version 1.3.0, the @code{arguments} field would typically use @code{quote} (@code{'}) or @code{quasiquote} (@code{`}) and no G-expressions, like so: @lisp (package ;; several fields omitted (arguments ;old-style quoted arguments '(#:tests? #f #:configure-flags '("--enable-frobbing")))) @end lisp To convert from that style to the one shown above, you can run @code{guix style -S arguments @var{package}} (@pxref{Invoking guix style}). @end quotation @item @code{inputs} (default: @code{'()}) @itemx @code{native-inputs} (default: @code{'()}) @itemx @code{propagated-inputs} (default: @code{'()}) @cindex inputs, of packages These fields list dependencies of the package. Each element of these lists is either a package, origin, or other ``file-like object'' (@pxref{G-Expressions}); to specify the output of that file-like object that should be used, pass a two-element list where the second element is the output (@pxref{Packages with Multiple Outputs}, for more on package outputs). For example, the list below specifies three inputs: @lisp (list libffi libunistring `(,glib "bin")) ;the "bin" output of GLib @end lisp In the example above, the @code{"out"} output of @code{libffi} and @code{libunistring} is used. @quotation Compatibility Note Until version 1.3.0, input lists were a list of tuples, where each tuple has a label for the input (a string) as its first element, a package, origin, or derivation as its second element, and optionally the name of the output thereof that should be used, which defaults to @code{"out"}. For example, the list below is equivalent to the one above, but using the @dfn{old input style}: @lisp ;; Old input style (deprecated). `(("libffi" ,libffi) ("libunistring" ,libunistring) ("glib:bin" ,glib "bin")) ;the "bin" output of GLib @end lisp This style is now deprecated; it is still supported but support will be removed in a future version. It should not be used for new package definitions. @xref{Invoking guix style}, on how to migrate to the new style. @end quotation @cindex cross compilation, package dependencies The distinction between @code{native-inputs} and @code{inputs} is necessary when considering cross-compilation. When cross-compiling, dependencies listed in @code{inputs} are built for the @emph{target} architecture; conversely, dependencies listed in @code{native-inputs} are built for the architecture of the @emph{build} machine. @code{native-inputs} is typically used to list tools needed at build time, but not at run time, such as Autoconf, Automake, pkg-config, Gettext, or Bison. @command{guix lint} can report likely mistakes in this area (@pxref{Invoking guix lint}). @anchor{package-propagated-inputs} Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the specified packages will be automatically installed to profiles (@pxref{Features, the role of profiles in Guix}) alongside the package they belong to (@pxref{package-cmd-propagated-inputs, @command{guix package}}, for information on how @command{guix package} deals with propagated inputs). For example this is necessary when packaging a C/C++ library that needs headers of another library to compile, or when a pkg-config file refers to another one @i{via} its @code{Requires} field. Another example where @code{propagated-inputs} is useful is for languages that lack a facility to record the run-time search path akin to the @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and more. When packaging libraries written in those languages, ensure they can find library code they depend on at run time by listing run-time dependencies in @code{propagated-inputs} rather than @code{inputs}. @item @code{outputs} (default: @code{'("out")}) The list of output names of the package. @xref{Packages with Multiple Outputs}, for typical uses of additional outputs. @item @code{native-search-paths} (default: @code{'()}) @itemx @code{search-paths} (default: @code{'()}) A list of @code{search-path-specification} objects describing search-path environment variables honored by the package. @xref{Search Paths}, for more on search path specifications. As for inputs, the distinction between @code{native-search-paths} and @code{search-paths} only matters when cross-compiling. In a cross-compilation context, @code{native-search-paths} applies exclusively to native inputs whereas @code{search-paths} applies only to host inputs. Packages such as cross-compilers care about target inputs---for instance, our (modified) GCC cross-compiler has @env{CROSS_C_INCLUDE_PATH} in @code{search-paths}, which allows it to pick @file{.h} files for the target system and @emph{not} those of native inputs. For the majority of packages though, only @code{native-search-paths} makes sense. @item @code{replacement} (default: @code{#f}) This must be either @code{#f} or a package object that will be used as a @dfn{replacement} for this package. @xref{Security Updates, grafts}, for details. @item @code{synopsis} A one-line description of the package. @item @code{description} A more elaborate description of the package, as a string in Texinfo syntax. @item @code{license} @cindex license, of packages The license of the package; a value from @code{(guix licenses)}, or a list of such values. @item @code{home-page} The URL to the home-page of the package, as a string. @item @code{supported-systems} (default: @code{%supported-systems}) The list of systems supported by the package, as strings of the form @code{architecture-kernel}, for example @code{"x86_64-linux"}. @item @code{location} (default: source location of the @code{package} form) The source location of the package. It is useful to override this when inheriting from another package, in which case this field is not automatically corrected. @end table @end deftp @defmac this-package When used in the @emph{lexical scope} of a package field definition, this identifier resolves to the package being defined. The example below shows how to add a package as a native input of itself when cross-compiling: @lisp (package (name "guile") ;; ... ;; When cross-compiled, Guile, for example, depends on ;; a native version of itself. Add it here. (native-inputs (if (%current-target-system) (list this-package) '()))) @end lisp It is an error to refer to @code{this-package} outside a package definition. @end defmac The following helper procedures are provided to help deal with package inputs. @deffn {Procedure} lookup-package-input package name @deffnx {Procedure} lookup-package-native-input package name @deffnx {Procedure} lookup-package-propagated-input package name @deffnx {Procedure} lookup-package-direct-input package name Look up @var{name} among @var{package}'s inputs (or native, propagated, or direct inputs). Return it if found, @code{#f} otherwise. @var{name} is the name of a package or the file name of an origin depended on. Here's how you might use it: @lisp (use-modules (guix packages) (gnu packages base)) (lookup-package-direct-input coreutils "gmp") @result{} #<package gmp@@6.2.1 @dots{}> @end lisp In this example we obtain the @code{gmp} package that is among the direct inputs of @code{coreutils}. When looking up an origin, use the name that appears in the origin's @code{file-name} field or its default file name---e.g., @code{"foo-1.2.tar.gz"}. @end deffn @cindex development inputs, of a package @cindex implicit inputs, of a package Sometimes you will want to obtain the list of inputs needed to @emph{develop} a package---all the inputs that are visible when the package is compiled. This is what the @code{package-development-inputs} procedure returns. @deffn {Procedure} package-development-inputs package [system] [#:target #f] Return the list of inputs required by @var{package} for development purposes on @var{system}. When @var{target} is true, return the inputs needed to cross-compile @var{package} from @var{system} to @var{target}, where @var{target} is a triplet such as @code{"aarch64-linux-gnu"}. Note that the result includes both explicit inputs and implicit inputs---inputs automatically added by the build system (@pxref{Build Systems}). Let us take the @code{hello} package to illustrate that: @lisp (use-modules (gnu packages base) (guix packages)) hello @result{} #<package hello@@2.10 gnu/packages/base.scm:79 7f585d4f6790> (package-direct-inputs hello) @result{} () (package-development-inputs hello) @result{} (("source" @dots{}) ("tar" #<package tar@@1.32 @dots{}>) @dots{}) @end lisp In this example, @code{package-direct-inputs} returns the empty list, because @code{hello} has zero explicit dependencies. Conversely, @code{package-development-inputs} includes inputs implicitly added by @code{gnu-build-system} that are required to build @code{hello}: tar, gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph hello} would show you explicit inputs, whereas @command{guix graph -t bag hello} would include implicit inputs (@pxref{Invoking guix graph}). @end deffn Because packages are regular Scheme objects that capture a complete dependency graph and associated build procedures, it is often useful to write procedures that take a package and return a modified version thereof according to some parameters. Below are a few examples. @cindex tool chain, choosing a package's tool chain @deffn {Procedure} package-with-c-toolchain package toolchain Return a variant of @var{package} that uses @var{toolchain} instead of the default GNU C/C++ toolchain. @var{toolchain} must be a list of inputs (label/package tuples) providing equivalent functionality, such as the @code{gcc-toolchain} package. The example below returns a variant of the @code{hello} package built with GCC@tie{}10.x and the rest of the GNU tool chain (Binutils and the GNU C Library) instead of the default tool chain: @lisp (let ((toolchain (specification->package "gcc-toolchain@@10"))) (package-with-c-toolchain hello `(("toolchain" ,toolchain)))) @end lisp The build tool chain is part of the @dfn{implicit inputs} of packages---it's usually not listed as part of the various ``inputs'' fields and is instead pulled in by the build system. Consequently, this procedure works by changing the build system of @var{package} so that it pulls in @var{toolchain} instead of the defaults. @xref{Build Systems}, for more on build systems. @end deffn @node origin Reference @subsection @code{origin} Reference This section documents @dfn{origins}. An @code{origin} declaration specifies data that must be ``produced''---downloaded, usually---and whose content hash is known in advance. Origins are primarily used to represent the source code of packages (@pxref{Defining Packages}). For that reason, the @code{origin} form allows you to declare patches to apply to the original source code as well as code snippets to modify it. @deftp {Data Type} origin This is the data type representing a source code origin. @table @asis @item @code{uri} An object containing the URI of the source. The object type depends on the @code{method} (see below). For example, when using the @var{url-fetch} method of @code{(guix download)}, the valid @code{uri} values are: a URL represented as a string, or a list thereof. @cindex fixed-output derivations, for download @item @code{method} A monadic procedure that handles the given URI@. The procedure must accept at least three arguments: the value of the @code{uri} field and the hash algorithm and hash value specified by the @code{hash} field. It must return a store item or a derivation in the store monad (@pxref{The Store Monad}); most methods return a fixed-output derivation (@pxref{Derivations}). Commonly used methods include @code{url-fetch}, which fetches data from a URL, and @code{git-fetch}, which fetches data from a Git repository (see below). @item @code{sha256} A bytevector containing the SHA-256 hash of the source. This is equivalent to providing a @code{content-hash} SHA256 object in the @code{hash} field described below. @item @code{hash} The @code{content-hash} object of the source---see below for how to use @code{content-hash}. You can obtain this information using @code{guix download} (@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking guix hash}). @item @code{file-name} (default: @code{#f}) The file name under which the source code should be saved. When this is @code{#f}, a sensible default value will be used in most cases. In case the source is fetched from a URL, the file name from the URL will be used. For version control checkouts, it is