GNU Guix 参考手册

Table of Contents

GNU Guix

这份文档介绍GNU Guix版本1.3.0，一个为GNU系统编写的函数式包管理器。

This manual is also available in Simplified Chinese (see GNU Guix参考手册), French (see Manuel de référence de GNU Guix), German (see Referenzhandbuch zu GNU Guix), Spanish (see Manual de referencia de GNU Guix), and Russian (see Руководство GNU Guix). If you would like to translate it in your native language, consider joining Weblate.

 －－－详细的章节列表－－－



介绍

安装

设置后台进程

系统安装

手动安装

软件包管理

substitutes

通道

开发

编程接口

定义软件包

工具

调用guix build

系统配置

服务

定义服务

安装调试文件

引导

1 介绍

GNU Guix¹是GNU系统的包管理器和发行版。Guix让无特权的用户可以轻松地安装，升级，或删除软件包，回滚到前一个软件包集合，从源代码构建软件包，及辅助软件环境的创建和维护。

你可以在现有的GNU/Linux发行版上安装GNU Guix（see 安装），Guix可以补充已有的工具，并且不会和它们产生冲突。或者你可以把它当作独立的操作系统发行版（Guix 系统²）。See GNU发行版.

1.1 以Guix的方式管理软件

Guix provides a command-line package management interface (see 软件包管理), tools to help with software development (see 开发), command-line utilities for more advanced usage (see 工具), as well as Scheme programming interfaces (see 编程接口). 构建后台进程为用户构建软件包（see 设置后台进程），及从授权的源（see substitutes）下载预构建的二进制文件。

Guix包含很多GNU和非GNU的软件包定义，所有的这些软件包都尊重用户的自由。它是可扩展的：用户可以编写自己的软件包定义（see 定义软件包），并且把它们作为独立的软件包模块see 软件包模块。它也是可定制的：用户可以从现有的软件包定义衍生出特殊的软件包，包括从命令行（see 软件包变换选项。）。

在底层，Guix实现了由Nix（see 致谢）开创的函数式包管理器。在Guix里，软件包构建和安装过程被视为数学意义上的函数。函数获取输入，如构建脚本、编译器和库，并且返回一个安装好的软件包。作为一个纯函数，它的结果只取决于它的输入－－例如，它不能引用没有作为显式输入传入的软件和脚本。当传入特定的输入时，一个构建函数总是得到相同的结果。它不能以任何方式修改运行系统的环境，例如，它不能创建，修改，或删除构建和安装环境之外的文件夹。这是通过在隔离的环境（容器）里运行构建进程实现的，在这个环境里只能访问到显式的输入。

软件包构建函数的结果被缓存在文件系统里的一个叫做仓库（see 仓库）的特殊文件夹内。每个软件包都被安装在仓库（默认在/gnu/store）里的一个独立的文件夹内。这个文件夹的名字含有用于构建这个软件包的所有输入的hash，所以，修改输入会得到一个不同的文件夹名。

这种手段是实现Guix的突出功能的基础：对事务型软件包升级和回滚的支持，每个用户独立的安装，软件包垃圾回收see 功能。

1.2 GNU发行版

Guix提供了一个GNU系统发行版，这个发新版只包含自由软件³。这个发行版可以独立安装（see 系统安装），但是把Guix安装为一个已经安装好的GNU/Linux系统的包管理器也是可行的（see 安装）。当我们需要区分这两者时，我们把独立的发行版称为“Guix系统”。

这个发行版提供了GNU核心软件包，如libc、gcc和Binutils，以及很多GNU和非GNU应用程序。可用的软件包的完整列表可以在on-line浏览，或者通过运行guix package（see 调用guix package）获得：

guix package --list-available

我们的目标是提供一个基于Linux和其它GNU变体的可用的100%自由的软件发行版，我们的重点是推广和紧密集成GNU组件，以及强调帮助用户行使那些自由的程序和工具。

目前这些平台提供软件包：

x86_64-linux

Intel/AMD x86_64 架构，Linux-Libre 内核。

i686-linux

Intel 32 位架构（IA32)，Linux-Libre 内核。

armhf-linux

ARMv7-A架构，带硬件浮点数、Thumb-2和NEON扩展，EABI硬件浮点数应用二进制接口（ABI），和Linux-Libre内核。

aarch64-linux

little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.

i586-gnu

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 hurd-vm-service-type on your GNU/Linux machine (see hurd-vm-service-type). See 贡献, on how to help!

mips64el-linux (deprecated)

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.

powerpc64le-linux

little-endian 64-bit Power ISA processors, Linux-Libre kernel. This includes POWER9 systems such as the 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 (see substitutes), and some packages may fail to build (see Tracking Bugs and Patches). That said, the Guix community is actively working on improving this support, and now is a great time to try it and get involved!

在Guix系统里，你声明操作系统所有方面的配置，然后Guix以事务型的，可重复的，和无状态的方式解决实例化配置的问题（see 系统配置）。Guix系统使用Linux-Libre内核，Shepherd初始化系统see 介绍 in GNU Shepherd用户手册，知名的GNU工具和工具链，以及你可选的图形界面环境和系统服务。

Guix System is available on all the above platforms except mips64el-linux and powerpc64le-linux.

关于移植到其它架构或内核的信息，see 移植。

构建这个发行版需要努力合作，欢迎你加入！关于你可以怎样提供帮助的信息，See 贡献。

2 安装

注: 我们推荐使用shell安装脚本在已有的GNU/Linux系统（即foreign distro）上安装Guix。⁴这个脚本自动下载、安装并且初始化Guix，它需要以root用户身份运行。

在foreign distro上安装时，GNU Guix可以在不引起冲突的前提下补充现有的工具。它的数据只存放在两个文件夹里，通常是/gnu/store和/var/guix；系统上的其它文件，如/etc，不会被修改。

一旦安装好了，可以通过运行guix pull升级Guix（see 调用guix pull）。

如果你希望手动执行安装步骤，或者想改变安装步骤，接下来这些小节会很有用。它们介绍Guix的软件依赖，以及如何手动安装和使用Guix。

2.1 二进制文件安装

这个小节介绍如何在任意的系统上用独立的Guix二进制文件包安装Guix和它的依赖。这通常比从源代码安装更快，下一小节会介绍如何从源代码安装。唯一的需求是有GNU tar和Xz。

注: We recommend the use of this shell installer script. The script automates the download, installation, and initial configuration steps described below. It should be run as the root user. As root, you can thus run this:

cd /tmp
wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
chmod +x guix-install.sh
./guix-install.sh

When you’re done, see 设置应用程序 for extra configuration you might need, and 入门 for your first steps!

安装步骤如下：

1. Download the binary tarball from ‘https://ftp.gnu.org/gnu/guix/guix-binary-1.3.0.x86_64-linux.tar.xz’, where x86_64-linux can be replaced with i686-linux for an i686 (32-bits) machine already running the kernel Linux, and so on (see GNU发行版).

   请确保下载相关的.sig文件，并且用它验证文件包的可靠性，方法如下：

   $ wget https://ftp.gnu.org/gnu/guix/guix-binary-1.3.0.x86_64-linux.tar.xz.sig
   $ gpg --verify guix-binary-1.3.0.x86_64-linux.tar.xz.sig
   

   如果那个命令因为缺少所需的公钥而失败了，那么用这个命令导入它：

   $ wget 'https://sv.gnu.org/people/viewgpg.php?user_id=127547' \
         -qO - | gpg --import -
   

   再次运行gpg --verify命令。

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

2. 现在你需要成为root用户。基于你的发行版，你可能需要执行su -或sudo -i。以root用户身份，执行：

   # cd /tmp
   # tar --warning=no-timestamp -xf \
        /path/to/guix-binary-1.3.0.x86_64-linux.tar.xz
   # mv var/guix /var/ && mv gnu /
   

   This creates /gnu/store (see 仓库) and /var/guix. The latter contains a ready-to-use profile for root (see next step).

   不要在一个正常的Guix系统上解压这个文件包，因为那会把现有的重要的文件覆盖。

   The --warning=no-timestamp option makes sure GNU tar does not emit warnings about “implausibly old time stamps” (such warnings were triggered by GNU tar 1.26 and older; recent versions are fine). They stem from the fact that all the files in the archive have their modification time set to 1 (which means January 1st, 1970). This is done on purpose to make sure the archive content is independent of its creation time, thus making it reproducible.

3. 使profile出现在~root/.config/guix/current，这是guix pull安装更新的位置（see 调用guix pull）：

   # mkdir -p ~root/.config/guix
   # ln -sf /var/guix/profiles/per-user/root/current-guix \
            ~root/.config/guix/current
   

   Source etc/profile to augment PATH and other relevant environment variables:

   # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
     source $GUIX_PROFILE/etc/profile
   

4. 像下面解释的那样为“构建用户”创建用户组和用户（see 设置构建环境）。
5. 运行后台进程，并设置为开机自启动。

   如果你的主机的发行版使用systemd init系统，可以用这些命令：

   # cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
        ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
        /etc/systemd/system/
   # systemctl enable --now gnu-store.mount guix-daemon
   

   如果你的主机的发行版使用Upstart init系统：

   # initctl reload-configuration
   # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
        /etc/init/
   # start guix-daemon
   

   此外，你可以手动启动后台进程：

   # ~root/.config/guix/current/bin/guix-daemon \
          --build-users-group=guixbuild
   

6. 使机器上的其他用户也可以使用guix命令：

   # mkdir -p /usr/local/bin
   # cd /usr/local/bin
   # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
   

   最好让这个用户手册的Info版也可以被访问：

   # mkdir -p /usr/local/share/info
   # cd /usr/local/share/info
   # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
     do ln -s $i ; done
   

   That way, assuming /usr/local/share/info is in the search path, running info guix will open this manual (see Other Info Directories in GNU Texinfo, for more details on changing the Info search path).

7. 为了使用ci.guix.gnu.org或其镜像的substitute（see substitutes），对其授权：

   # guix archive --authorize < \
        ~root/.config/guix/current/share/guix/ci.guix.gnu.org.pub
   

8. 每个用户可能需要执行一些额外的步骤以使各自的Guix环境可用，see 设置应用程序。

瞧，安装完成了！

你可以通过给root profile安装一个软件包来确认Guix可以正常工作。

# guix install hello

二进制安装包可以通过在Guix源代码树里运行下面这些命令来重现和验证：

make guix-binary.系统.tar.xz

... 这个命令会执行：

guix pack -s 系统 --localstatedir \
  --profile-name=current-guix guix

See 调用guix pack，了解这个方便的工具。

2.2 需求

这个小节列举了从源代码构建Guix的需求。构建Guix的步骤和其它GNU软件相同，这里不介绍。请阅读Guix源代码树里的README和INSTALL文件以了解更多的信息。

GNU Guix可以从它的网站下载https://www.gnu.org/software/guix/。

GNU Guix依赖这些软件包：

• GNU Guile, version 3.0.x or 2.2.x;
• Guile-Gcrypt，版本 0.1.0或更新；
• GnuTLS，特别是它的Guile接口（see 怎样为Guile安装GnuTLS接口 in GnuTLS-Guile）；
• Guile-SQLite3，版本0.1.0或更新；
• Guile-zlib, version 0.1.0 or later;
• Guile-lzlib;
• Guile-Avahi;
• Guile-Git, version 0.3.0 or later;
• Guile-JSON 4.3.0 or later;
• GNU Make。

这些依赖是可选的：

• Support for build offloading (see 下发工作给后台进程的设置) and guix copy (see 调用guix copy) depends on Guile-SSH, version 0.13.0 or later.
• Guile-zstd, for zstd compression and decompression in guix publish and for substitutes (see 调用guix publish).
• Guile-Semver for the crate importer (see 调用guix import).
• Guile-Lib for the go importer (see 调用guix import) and for some of the “updaters” (see 调用guix refresh).
• 当libbz2存在时，guix-daemon可以用它压缩构建日志。

Unless --disable-daemon was passed to configure, the following packages are also needed:

• GNU libgcrypt；
• SQLite 3；
• GCC’s g++，支持 C++11标准。

When configuring Guix on a system that already has a Guix installation, be sure to specify the same state directory as the existing installation using the --localstatedir option of the configure script (see localstatedir in GNU Coding Standards). Usually, this localstatedir option is set to the value /var. The configure script protects against unintended misconfiguration of localstatedir so you do not inadvertently corrupt your store (see 仓库).

2.3 运行测试套件

成功执行configure和make之后，最好运行测试套件。它可以帮助查找设置和环境的错误，或者是Guix自身的bug－－并且，报告测试错误是帮助改进软件的好方法。输入下面的命令以执行测试套件。

make check

测试用例可以并行运行：你可以用GNU make的-j参数来加速运行。才一台较新的机器上第一次运行可能会花几分钟，后续的运行会更快，因为为测试创建的仓库已经包含了各种缓存。

你还可以通过定义makefile的TESTS变量只运行测试的一个子集：

make check TESTS="tests/store.scm tests/cpio.scm"

默认情况下，测试结果只展示到文件层级。为了看每个独立的测试用例的详情，可以像这样定义SCM_LOG_DRIVER_FLAGS makefile变量：

make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"

The underlying SRFI 64 custom Automake test driver used for the ’check’ test suite (located at build-aux/test-driver.scm) also allows selecting which test cases to run at a finer level, via its --select and --exclude options. Here’s an example, to run all the test cases from the tests/packages.scm test file whose names start with “transaction-upgrade-entry”:

export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
make check TESTS="tests/packages.scm"

Those wishing to inspect the results of failed tests directly from the command line can add the --errors-only=yes option to the SCM_LOG_DRIVER_FLAGS makefile variable and set the VERBOSE Automake makefile variable, as in:

make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1

The --show-duration=yes option can be used to print the duration of the individual test cases, when used in combination with --brief=no:

make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"

See Parallel Test Harness in GNU Automake for more information about the Automake Parallel Test Harness.

遇到错误时，请给bug-guix@gnu.org发邮件，并附带test-suite.log文件。请在消息里说明使用的Guix的版本信息和依赖（see 需求）的版本信息。

Guix还附带了一个可以测试整个Guix系统实例的全系统测试套件。它只能在已经安装Guix的系统上运行：

make check-system

或者，同样的，通过定义TESTS只运行测试的一个子集：

make check-system TESTS="basic mcron"

这些系统测试是在(gnu tests …)模块里定义的。它们在虚拟机（VM）里运行轻量的指令。它们的计算量可能很多也可能很少，这取决于它们依赖的substitute（see substitutes）是否已经存在。它们之中有些需要很多存储空间以保存虚拟机硬盘。

再重复一遍，如果遇到测试错误，请给bug-guix@gnu.org发邮件，并附带详细的说明。

2.4 设置后台进程

构建软件包或运行垃圾回收器之类的操作都是由一个特殊的进程代替客户执行的，即构建后台进程。只有这个进程可以访问仓库和相关的数据库。因此，所有修改仓库的操作都通过这个后台进程执行。例如，guix package和guix build之类的命令行工具通过和这个后台进程通信（通过远程过程调用）来指示它该做什么。

接下来的几个小节介绍如何准备“构建后台进程”的环境。参考substitutes，了解怎样允许这个后台进程下载预构建好的二进制文件。

2.4.1 设置构建环境

在一个标准的多用户设置里，Guix和它的后台进程–guix-daemon程序–是由root用户安装的，并且guix-daemon以root用户身份运行。无特权的用户可以用Guix的工具构建软件包或访问仓库，这个后台进程会代替用户进行这些操作，以确保仓库保持一致的状态，并且允许构建好的软件包可以在不同用户间共享。

当guix-daemon以root用户身份运行时，由于安全方面的考虑，你可能不希望软件包构建进程也以root用户身份运行。为了避免那样，我们需要创建一个构建用户池，以供后台进程启动的构建进程使用。这些构建用户不需要拥有shell和家目录：他们只会在后台进程为构建进程剥夺root特权时使用。拥有多个这类用户使后台进程可以以不同的UID启动不同的构建进程，这保证它们不会互相干扰–这是一个重要的功能，因为构建被视为纯函数（see 介绍）。

在一个GNU/Linux系统上，可以这样创建一个构建用户池（用bash语法和shadow命令）：

# 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

构建用户的数量决定了有多少个构建任务可以并行执行，即--max-jobs参数(see --max-jobs)。为了使用guix system vm和相关的命令，你需要把构建用户添加到kvm用户组，以使它们访问/dev/kvm。为此，把-G guixbuild替换成-G guixbuild,kvm（see 调用guix system）。

之后以root身份用下面的命令运行guix-daemon程序command⁵：

# guix-daemon --build-users-group=guixbuild

这样，后台进程在一个chroot环境里，以一个guixbuilder用户组成员的身份启动构建进程。在GNU/Linux上，默认的，这个chroot环境仅包含这些东西：

• 一个和主机/dev独立的⁶，最小的/dev文件夹；
• /proc文件夹；它只含有当前容器的进程，因为用了一个独立的进程PID命名空间；
• /etc/passwd，仅包含当前用户和nobody；
• /etc/group，包含用户的组；
• /etc/hosts，包含localhost映射到127.0.0.1的条目；
• 一个可写的/tmp文件夹。

You can influence the directory where the daemon stores build trees via the TMPDIR environment variable. However, the build tree within the chroot is always called /tmp/guix-build-name.drv-0, where name is the derivation name—e.g., coreutils-8.24. This way, the value of TMPDIR does not leak inside build environments, which avoids discrepancies in cases where build processes capture the name of their build tree.

The daemon also honors the http_proxy and https_proxy environment variables for HTTP and HTTPS downloads it performs, be it for fixed-output derivations (see Derivations) or for substitutes (see substitutes).

If you are installing Guix as an unprivileged user, it is still possible to run guix-daemon provided you pass --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 pure functions.

2.4.2 使用任务下发设施

When desired, the build daemon can offload derivation builds to other machines running Guix, using the offload build hook⁷. When that feature is enabled, a list of user-specified build machines is read from /etc/guix/machines.scm; every time a build is requested, for instance via 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., x86_64-linux. A single machine can have multiple system types, either because its architecture natively supports it, via emulation (see 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:

1. The availability of a build slot. A build machine can have as many build slots (connections) as the value of the parallel-builds field of its build-machine object.
2. Its relative speed, as defined via the speed field of its build-machine object.
3. Its load. The normalized machine load must be lower than a threshold value, configurable via the overload-threshold field of its build-machine object.
4. Disk space availability. More than a 100 MiB must be available.

/etc/guix/machines.scm文件通常是这样的：

(list (build-machine
        (name "eightysix.example.org")
        (systems (list "x86_64-linux" "i686-linux"))
        (host-key "ssh-ed25519 AAAAC3Nza…")
        (user "bob")
        (speed 2.))     ;incredibly fast!

      (build-machine
        (name "armeight.example.org")
        (systems (list "aarch64-linux"))
        (host-key "ssh-rsa AAAAB3Nza…")
        (user "alice")
        (private-key
         (string-append (getenv "HOME")
                        "/.ssh/identity-for-guix"))))

In the example above we specify a list of two build machines, one for the x86_64 and i686 architectures and one for the aarch64 architecture.

事实上，这个文件–并不意外地–是一个Scheme文件，当下发钩子被启动时执行。它的返回值必须是一个包含build-machine对象的列表。虽然这个例子展示的是一个固定的列表，你可以想象，使用DNS-SD来返回一个包含从局域网内发现的构建机器的列表，see Guile-Avahi in 在Guile Scheme程序里使用Avahi。build-machine数据类型的详细信息如下。

数据类型: build-machine

这个数据类型表示后台进程可以下发构建任务的构建机器。重要的项有：

名字

远程机器的主机名。

systems

The system types the remote machine supports—e.g., (list "x86_64-linux" "i686-linux").

用户

通过SSH连接远程机器时使用的用户帐号。注意，SSH密钥不能被密码保护，以支持无交互的登录。

主机公钥

这必须是机器的OpenSSH格式的SSH公钥。这是用来在连接机器时认证身份的。它是一个像这样的长字符串：

ssh-ed25519 AAAAC3NzaC…mde+UhL hint@example.org

如果这个机器正在运行OpenSSH后台进程，sshd，那么主机公钥可以在/etc/ssh/ssh_host_ed25519_key.pub找到。

如果这个机器正在运行GNU lsh，lshd，那么主机公钥可以在/etc/lsh/host-key.pub或类似的位置找到。它可以通过lsh-export-key命令转换成OpenSSH格式（see Converting keys in LSH用户手册）：

$ lsh-export-key --openssh < /etc/lsh/host-key.pub
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV…

一些可选的项：

port（默认值：22）

机器上的SSH服务器的端口号。

private-key（默认值：~root/.ssh/id_rsa）

连接机器时使用的SSH私钥，OpenSSH格式。这个私钥不能被密码保护。

注意，默认值是root帐号的私钥。使用默认值时请确保它存在。

compression（默认值："zlib@openssh.com,zlib"）

compression-level（默认值：3）

SSH压缩算法和压缩级别。

下发任务依赖SSH压缩来减少传输文件到构建机器时使用的带宽。

daemon-socket（默认值："/var/guix/daemon-socket/socket"）

那台机器上的guix-daemon监听的Unix套接字文件名。

overload-threshold (default: 0.6)

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 overload-threshold to #f.

parallel-builds（默认值：1）

那台机器上可以并行运行的构建任务数量。

speed（默认值：1.0）

一个相对的速度值。下发调度器会偏好速度更快的机器。

features （'()）

一个表示机器支持的功能的字符串列表。例如，"kvm"表示机器有KVM Linux模块和相关的硬件支持。Derivation可以通过名字请求需要的功能，然后被分发到匹配的机器的任务队列里。

guix命令必须在构建机器的搜素路径里。你可以通过这个命令检查：

ssh build-machine guix repl --version

machines.scm到位后，还有一件要做的事。如上所述，下发任务时会在机器的仓库之间传输文件。为此，你需要在每台机器上生成一个密钥对，以使后台进程可以从仓库导出签名后的文件包（see 调用guix archive）：

# guix archive --generate-key

每台构建机器都必须认证主机器的公钥，从而接收从主机器接收的仓库文件：

# guix archive --authorize < master-public-key.txt

类似的，主机器必须认证每台构建机器的公钥：

所有这些有关公钥的繁琐事宜都是为了表达主服务器和构建服务器之间成对的互相信任关系。具体地，当主机器从构建机器接收文件时（反之亦然），它的构建后台进程可以确保文件是原样的，没有被篡改，并且被认证的公钥签名过。

为了测试你的设置是否能正常工作，在主节点上运行这个命令：

# guix offload test

This will attempt to connect to each of the build machines specified in /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.

如果你希望用别的文件测试，只需要在命令行指定它：

# guix offload test machines-qualif.scm

最后，你可以像这样只测试机器列表里名字匹配某个正则表达式的子集：

# guix offload test machines.scm '\.gnu\.org$'

若想展示所有构建主机的当前负载，在主节点上运行这个命令：

# guix offload status

2.4.3 SELinux的支持

Guix附带一个SELinux策略文件，位置在etc/guix-daemon.cil，它可以在启用SELinux的系统上安装，为Guix的文件添加标签及指定后台进程的期望行为。由于Guix系统不提供SELinux基础策略，这个后台进程策略不能在Guix系统上使用。

2.4.3.1 安装SELinux策略

用root用户执行这个命令以安装策略：

semodule -i etc/guix-daemon.cil

用restorecon或者你的系统提供的其它机制重新给文件系统打标签。

一旦安装好策略，为文件系统重新打好标签，并且重启了后台进程，它应该在guix_daemon_t环境里运行。你可以用下面这个命令确认：

ps -Zax | grep guix-daemon

运行guix build hello之类的命令并监控SELinux日志以说服你自己SELinux允许所有的操作。

2.4.3.2 限制

这个策略不是完美的。这里有一个关于限制和缺陷的列表，当为Guix后台进程部署提供的SELinux策略时该认真考虑。

1. guix_daemon_socket_t isn’t actually used. None of the socket operations involve contexts that have anything to do with 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.
2. guix gc不可以任意访问指向profile的链接。由于设计的原因，符号链接的目标的文件标签和符号链接本身的文件标签是不同的。尽管$localstatedir里的所有profile都被打上了标签，指向这些profile的符号链接继承它们所在的文件夹的标签。对于普通用户的家目录里的链接，标签是user_home_t。但是对于root用户的家目录，或/tmp，或HTTP服务器的工作目录等文件夹里的链接不是这样。guix gc会被阻止读取和跟随这些链接。
3. 后台进程监听TCP连接的功能不再可用。这可能需要额外的规则，因为SELinux区别对待网络套接字和文件。
4. 目前，所有匹配正则表达式/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon的文件都被赋予guix_daemon_exec_t标签；这意味着任何profile里的任何有这样名字的的文件都会被允许在guix_daemon_t域里执行。这不够理想。一个攻击者可以构建提供这个可执行程序的软件包，并说服一个用户安装、运行它，以此进入guix_daemon_t域。那时，SELinux无法阻止它访问所在域的进程可以访问的文件。

   You will need to relabel the store directory after all upgrades to guix-daemon, such as after running guix pull. Assuming the store is in /gnu, you can do this with restorecon -vR /gnu, or by other means provided by your operating system.

   我们可以在安装时生成一个更严格的策略，仅当前安装的guix-daemon的精确的的文件名会被打上guix_daemon_exec_t标签，而不是用一个宽泛的正则表达式。这样的缺点是root必须在每次安装提供guix-daemon的Guix软件包时安装或升级策略。

2.5 调用guix-daemon

guix-daemon程序实现了所有访问仓库的功能。包括启动构建进程，运行垃圾回收器，查询构建结果，等。它通常以root身份运行：

# guix-daemon --build-users-group=guixbuild

关于如何设置它，see 设置后台进程。

By default, guix-daemon launches build processes under different UIDs, taken from the build group specified with --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 (see derivation), plus a set of specific system directories. By default, the latter contains /dev and /dev/pts. Furthermore, on GNU/Linux, the build environment is a 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 (see 功能).

When the daemon performs a build on behalf of the user, it creates a build directory under /tmp or under the directory specified by its 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 /tmp/guix-build-name.drv-0.

The build directory is automatically deleted upon completion, unless the build failed and the client specified --keep-failed (see --keep-failed).

The daemon listens for connections and spawns one sub-process for each session started by a client (one of the guix sub-commands). The guix processes command allows you to get an overview of the activity on your system by viewing each of the active sessions and clients. See 调用guix processes, for more information.

下面这些命令行选项受支持：

--build-users-group=用户组

这会从用户组里选取用户，以运行构建进程（see 构建用户）。

--no-substitutes

不要为构建商品使用substitute。即，总是在本地构建，而不是下载预构建的二进制文件（see substitutes）。

When the daemon runs with --no-substitutes, clients can still explicitly enable substitution via the set-build-options remote procedure call (see 仓库).

--substitute-urls=urls

urls是用空格分隔的substitute源URL列表。当这个选项被省略时，默认使用‘https://ci.guix.gnu.org’。

这意味着可以从urls下载substitute，只要它们的签名可信（see substitutes）。

See Getting Substitutes from Other Servers, for more information on how to configure the daemon to get substitutes from other servers.

--no-offload

Do not use offload builds to other machines (see 下发工作给后台进程的设置). That is, always build things locally instead of offloading builds to remote machines.

--cache-failures

缓存失败的构建。默认地，只缓存成功的构建。

当这个选项被使用时，可以用guix gc --list-failures查询被标记为失败的仓库文件；guix gc --clear-failures从仓库里删除失败的缓存。See 调用guix gc。

--cores=n

-c n

用n个CPU核来构建每个derivation；0表示有多少就用多少。

The default value is 0, but it may be overridden by clients, such as the --cores option of guix build (see 调用guix build).

The effect is to define the NIX_BUILD_CORES environment variable in the build process, which can then use it to exploit internal parallelism—for instance, by running make -j$NIX_BUILD_CORES.

--max-jobs=n

-M n

最多允许n个并行的构建任务。默认值是1。设置为0表示不在本地执行构建；而是下发构建任务（see 下发工作给后台进程的设置），或者直接失败。

--max-silent-time=seconds

当构建或substitution进程超过seconds秒仍然保持静默，就把它结束掉并报告构建失败。

默认值是0，表示关闭超时。

The value specified here can be overridden by clients (see --max-silent-time).

--timeout=seconds

类似地，当构建或substitution进程执行超过seconds秒，就把它结束掉并报告构建失败。

默认值是0，表示关闭超时。

The value specified here can be overridden by clients (see --timeout).

--rounds=N

为每个derivation构建n次，如果连续的构建结果不是每个比特都相同就报告错误。这个设置可以被guix build之类的客户端覆盖（see 调用guix build）。

当和--keep-failed一起使用时，不同的输出保存在/gnu/store/…-check。这让检查两个结果的区别更容易。

--debug

生成调试输出。

This is useful to debug daemon start-up issues, but then it may be overridden by clients, for example the --verbosity option of guix build (see 调用guix build).

--chroot-directory=dir

把dir添加到构建的chroot。

这么做可能会改变构建进程的结果–例如，如果它们使用了在dir里发现的可选依赖。因此，建议不要这么做，而是确保每个derivation声明所需的全部输入。

--disable-chroot

关闭chroot构建。

不建议使用这个选项，因为它会允许构建进程访问到没被声明的依赖。但是，当guix-daemon以没有特权的用户身份运行时，这个选项是必须的。

--log-compression=type

以type方式压缩构建日志，可选的值：gzip，bzip2，none。

Unless --lose-logs is used, all the build logs are kept in the localstatedir. To save space, the daemon automatically compresses them with Bzip2 by default.

--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.

1. It might be faster/less expensive than fetching from remote servers;
2. There are no security risks, only genuine substitutes will be used (see 验证substitute);
3. An attacker advertising guix publish on your LAN cannot serve you malicious binaries, but they can learn what software you’re installing;
4. Servers may serve substitute over HTTP, unencrypted, so anyone on the LAN can see what software you’re installing.

It is also possible to enable or disable substitute server discovery at run-time by running:

herd discover guix-daemon on
herd discover guix-daemon off

--disable-deduplication

关闭自动对仓库文件“去重”。

默认地，添加到仓库的文件会被自动“去重”：如果新添加的文件和仓库里找到的某个文件完全相同，后台进程把这个新文件变成另一个文件的硬链接。这可以明显地减少硬盘使用，代价是构建结束后轻微地增加输入／输出负载。这个选项关闭这个优化。

--gc-keep-outputs[=yes|no]

垃圾收集器（GC）是否必须保留存活的derivation的输出。

When set to yes, the GC will keep the outputs of any live derivation available in the store—the .drv files. The default is no, meaning that derivation outputs are kept only if they are reachable from a GC root. See 调用guix gc, for more on GC roots.

--gc-keep-derivations[=yes|no]

垃圾收集器（GC）是否必须保留和存活的输出相关的derivation。

When set to yes, as is the case by default, the GC keeps derivations—i.e., .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 no saves a bit of disk space.

In this way, setting --gc-keep-derivations to yes causes liveness to flow from outputs to derivations, and setting --gc-keep-outputs to yes causes liveness to flow from derivations to outputs. When both are set to 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.

--impersonate-linux-2.6

On Linux-based systems, impersonate Linux 2.6. This means that the kernel’s uname system call will report 2.6 as the release number.

这可能会有助于构建那些（通常是错误地）依赖内核版本号的程序。

--lose-logs

Do not keep build logs. By default they are kept under localstatedir/guix/log.

--system=system

假设system是当前的系统类型。默认值是configure时发现的架构／内核元组，如x86_64-linux。

--listen=endpoint

Listen for connections on endpoint. endpoint is interpreted as the file name of a Unix-domain socket if it starts with / (slash sign). Otherwise, endpoint is interpreted as a host name or host name and port to listen to. Here are a few examples:

--listen=/gnu/var/daemon

Listen for connections on the /gnu/var/daemon Unix-domain socket, creating it if needed.

--listen=localhost

Listen for TCP connections on the network interface corresponding to localhost, on port 44146.

--listen=128.0.0.42:1234

Listen for TCP connections on the network interface corresponding to 128.0.0.42, on port 1234.

This option can be repeated multiple times, in which case guix-daemon accepts connections on all the specified endpoints. Users can tell client commands what endpoint to connect to by setting the GUIX_DAEMON_SOCKET environment variable (see GUIX_DAEMON_SOCKET).

注: The daemon protocol is unauthenticated and unencrypted. Using --listen=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.

When --listen is omitted, guix-daemon listens for connections on the Unix-domain socket located at localstatedir/guix/daemon-socket/socket.

2.6 设置应用程序

When using Guix on top of GNU/Linux distribution other than Guix System—a so-called foreign distro—a few additional steps are needed to get everything in place. Here are some of them.

2.6.1 区域

Packages installed 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 GUIX_LOCPATH environment variable:

$ guix install glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale

Note that the glibc-locales package contains data for all the locales supported by the GNU libc and weighs in at around 917 MiB. Alternatively, the glibc-utf8-locales is smaller but limited to a few UTF-8 locales.

The GUIX_LOCPATH variable plays a role similar to LOCPATH (see LOCPATH in The GNU C Library Reference Manual). There are two important differences though:

1. GUIX_LOCPATH is honored only by the libc in Guix, and not by the libc provided by foreign distros. Thus, using GUIX_LOCPATH allows you to make sure the programs of the foreign distro will not end up loading incompatible locale data.
2. libc suffixes each entry of GUIX_LOCPATH with /X.Y, where X.Y is the libc version—e.g., 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.

This is important because the locale data format used by different libc versions may be incompatible.

2.6.2 Name Service Switch

When using Guix on a foreign distro, we strongly recommend that the system run the GNU C library’s name service cache daemon, nscd, which should be listening on the /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.

The GNU C library implements a name service switch (NSS), which is an extensible mechanism for “name lookups” in general: host name resolution, user accounts, and more (see Name Service Switch in The GNU C Library Reference Manual).

Being extensible, the NSS supports plugins, which provide new name lookup implementations: for example, the nss-mdns plugin allow resolution of .local host names, the nis plugin allows user account lookup using the Network information service (NIS), and so on. These extra “lookup services” are configured system-wide in /etc/nsswitch.conf, and all the programs running on the system honor those settings (see NSS Configuration File in The GNU C Reference Manual).

When they perform a name lookup—for instance by calling the 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 libnss_*.so files—are 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, libnss_mdns.so for glibc 2.22), it will likely crash or have its name lookups fail unexpectedly.

Running nscd on the system, among other advantages, eliminates this binary incompatibility problem because those libnss_*.so files are loaded in the nscd process, not in applications themselves.

2.6.3 X11 Fonts

The majority of graphical applications use Fontconfig to locate and load fonts and perform X11-client-side rendering. The fontconfig package in Guix looks for fonts in $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 gs-fonts, font-dejavu, and font-gnu-freefont.

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:

guix install fontconfig
fc-cache -rv

To display text written in Chinese languages, Japanese, or Korean in graphical applications, consider installing font-adobe-source-han-sans or font-wqy-zenhei. The former has multiple outputs, one per language family (see 有多个输出的软件包). For instance, the following command installs fonts for Chinese languages:

guix install font-adobe-source-han-sans:cn

Older programs such as 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:

-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1

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:

xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))

After that, you can run xlsfonts (from xlsfonts package) to make sure your TrueType fonts are listed there.

2.6.4 X.509证书

The 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. See X.509证书, for detailed information.

2.6.5 Emacs Packages

When you install Emacs packages with Guix, the Elisp files are placed under the share/emacs/site-lisp/ directory of the profile in which they are installed. The Elisp libraries are made available to Emacs through the EMACSLOADPATH environment variable, which is set when installing Emacs itself.

Additionally, autoload definitions are automatically evaluated at the initialization of Emacs, by the Guix-specific guix-emacs-autoload-packages procedure. 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 --no-site-file option (see Init File in The GNU Emacs Manual).

2.7 Upgrading Guix

To upgrade Guix, run:

guix pull

See 调用guix pull, for more information.

On a foreign distro, you can upgrade the build daemon by running:

sudo -i guix pull

followed by (assuming your distro uses the systemd service management tool):

systemctl restart guix-daemon.service

On Guix System, upgrading the daemon is achieved by reconfiguring the system (see guix system reconfigure).

3 系统安装

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, see 安装.

3.1 限制

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

Nevertheless, before you proceed with the installation, be aware of the following noteworthy limitations applicable to version 1.3.0:

• More and more system services are provided (see 服务), but some may be missing.
• GNOME, Xfce, LXDE, and Enlightenment are available (see 桌面服务), as well as a number of X11 window managers. However, KDE is currently missing.

More than a disclaimer, this is an invitation to report issues (and success stories!), and to join us in improving it. See 贡献, for more info.

3.2 硬件的考虑

GNU 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.

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 ath9k Linux-libre driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core Revision 5), which corresponds to the b43-open Linux-libre driver. Free firmware exists for both and is available out-of-the-box on Guix System, as part of %base-firmware (see firmware).

The Free Software Foundation runs 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 H-Node web site. It contains a catalog of hardware devices with information about their support in GNU/Linux.

3.3 U盘和DVD安装

An ISO-9660 installation image that can be written to a USB stick or burnt to a DVD can be downloaded from ‘https://ftp.gnu.org/gnu/guix/guix-system-install-1.3.0.x86_64-linux.iso’, where you can replace x86_64-linux with one of:

x86_64-linux

for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;

i686-linux

for a 32-bit GNU/Linux system on Intel-compatible CPUs.

Make sure to download the associated .sig file and to verify the authenticity of the image against it, along these lines:

$ wget https://ftp.gnu.org/gnu/guix/guix-system-install-1.3.0.系统.iso.sig
$ gpg --verify guix-system-install-1.3.0.系统.iso.sig

如果那个命令因为缺少所需的公钥而失败了，那么用这个命令导入它：

$ wget https://sv.gnu.org/people/viewgpg.php?user_id=127547 \
      -qO - | gpg --import -

再次运行gpg --verify命令。

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

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

Copying to a USB Stick

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

dd if=guix-system-install-1.3.0.x86_64-linux.iso of=/dev/sdX status=progress
sync

Access to /dev/sdX usually requires root privileges.

Burning on a DVD

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

growisofs -dvd-compat -Z /dev/srX=guix-system-install-1.3.0.x86_64-linux.iso

Access to /dev/srX usually requires root privileges.

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 c key and type search_grub usb.

See 在虚拟机里安装 Guix, if, instead, you would like to install Guix System in a virtual machine (VM).

3.4 准备安装

Once you have booted, you can use the guided graphical installer, which makes it easy to get started (see 指导的图形安装). 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 (see 手动安装).

The graphical installer is available on TTY1. You can obtain root shells on TTYs 3 to 6 by hitting ctrl-alt-f3, ctrl-alt-f4, etc. TTY2 shows this documentation and you can reach it with ctrl-alt-f2. Documentation is browsable using the Info reader commands (see 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.

注: Installation requires access to the Internet so that any missing dependencies of your system configuration can be downloaded. See the “Networking” section below.

3.5 指导的图形安装

The graphical installer is a text-based user interface. It will guide you, with dialog boxes, through the steps needed to install GNU 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.

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.

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.

Once you’re done, the installer produces an operating system configuration and displays it (see 使用配置系统). At that point you can hit “OK” and installation will proceed. On success, you can reboot into the new system and enjoy. See 系统安装之后, for what’s next!

3.6 手动安装

This section describes how you would “manually” install GNU 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 (see 指导的图形安装).

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

3.6.1 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.

3.6.1.1 键盘布局

安装镜像使用的是美国的 qwerty 键盘布局，如果想更改，可以使用 loadkeys 命令。 例如，用以下命令选择 Dvorak 键盘布局：

loadkeys dvorak

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

3.6.1.2 Networking

运行以下命令查看你的网络接口的名称：

ifconfig -a

… 或者，使用 GNU/Linux 特有的 ip 命令：

ip address

Wired interfaces have a name starting with ‘e’; for example, the interface corresponding to the first on-board Ethernet controller is called ‘eno1’. Wireless interfaces have a name starting with ‘w’, like ‘w1p2s0’.

有线连接

To configure a wired network run the following command, substituting interface with the name of the wired interface you want to use.

ifconfig interface up

… 或者，使用 GNU/Linux 特有的 ip 命令：

ip link set interface up

无线连接

To configure wireless networking, you can create a configuration file for the wpa_supplicant configuration tool (its location is not important) using one of the available text editors such as nano:

nano wpa_supplicant.conf

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:

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

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

wpa_supplicant -c wpa_supplicant.conf -i interface -B

Run man wpa_supplicant for more information.

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

dhclient -v interface

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

ping -c 3 gnu.org

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

If you need HTTP and HTTPS access to go through a proxy, run the following command:

herd set-http-proxy guix-daemon URL

where URL is the proxy URL, for example http://example.org:8118.

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

herd start ssh-daemon

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

3.6.1.3 磁盘分区

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 (see Overview in GNU Parted User Manual), fdisk, and cfdisk. Run it and set up your disk with the partition layout you want:

cfdisk

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 (see BIOS installation in GNU GRUB manual).

If you instead wish to use EFI-based GRUB, a FAT32 EFI System Partition (ESP) is required. This partition can be mounted at /boot/efi for instance and must have the esp flag set. E.g., for parted:

parted /dev/sda set 1 esp on

注: Unsure whether to use EFI- or BIOS-based GRUB? If the directory /sys/firmware/efi exists in the installation image, then you should probably perform an EFI installation, using grub-efi-bootloader. Otherwise you should use the BIOS-based GRUB, known as grub-bootloader. See 引导设置, for more info on bootloaders.

Once you are done partitioning the target hard disk drive, you have to create a file system on the relevant partition(s)⁸. For the ESP, if you have one and assuming it is /dev/sda1, run:

mkfs.fat -F32 /dev/sda1

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 (see deduplication).

Preferably, assign file systems a label so that you can easily and reliably refer to them in file-system declarations (see 文件系统). This is typically done using the -L option of mkfs.ext4 and related commands. So, assuming the target root partition lives at /dev/sda2, a file system with the label my-root can be created with:

mkfs.ext4 -L my-root /dev/sda2

If you are instead planning to encrypt the root partition, you can use the Cryptsetup/LUKS utilities to do that (see man cryptsetup for more information). Assuming you want to store the root partition on /dev/sda2, the command sequence would be along these lines:

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

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

mount LABEL=my-root /mnt

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

Finally, if you plan to use one or more swap partitions (see swap space in The GNU C Library Reference Manual), make sure to initialize them with mkswap. Assuming you have one swap partition on /dev/sda3, you would run:

mkswap /dev/sda3
swapon /dev/sda3

Alternatively, you may use a swap file. For example, assuming that in the new system you want to use the file /swapfile as a swap file, you would run⁹:

# 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

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.

3.6.2 继续安装步骤

With the target partitions ready and the target root mounted on /mnt, we’re ready to go. First, run:

herd start cow-store /mnt

This makes /gnu/store copy-on-write, such that packages added to it during the installation phase are written to the target disk on /mnt rather than kept in memory. This is necessary because the first phase of the guix system init command (see below) entails downloads or builds to /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 (see GNU nano Manual), which supports syntax highlighting and parentheses matching; other editors include GNU Zile (an Emacs clone), and nvi (a clone of the original BSD vi editor). We strongly recommend storing that file on the target root file system, say, as /mnt/etc/config.scm. Failing to do that, you will have lost your configuration file once you have rebooted into the newly-installed system.

See 使用配置系统, for an overview of the configuration file. The example configurations discussed in that section are available under /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:

# mkdir /mnt/etc
# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
# nano /mnt/etc/config.scm

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

• Make sure the bootloader-configuration form refers to the target you want to install GRUB on. It should mention grub-bootloader if you are installing GRUB in the legacy way, or grub-efi-bootloader for newer UEFI systems. For legacy systems, the target field names a device, like /dev/sda; for UEFI systems it names a path to a mounted EFI partition, like /boot/efi; do make sure the path is currently mounted and a file-system entry is specified in your configuration.
• Be sure that your file system labels match the value of their respective device fields in your file-system configuration, assuming your file-system configuration uses the file-system-label procedure in its device field.
• If there are encrypted or RAID partitions, make sure to add a mapped-devices field to describe them (see 映射的设备).

Once you are done preparing the configuration file, the new system must be initialized (remember that the target root file system is mounted under /mnt):

guix system init /mnt/etc/config.scm /mnt

This copies all the necessary files and installs GRUB on /dev/sdX, unless you pass the --no-bootloader option. For more information, see 调用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 reboot and boot into the new system. The root password in the new system is initially empty; other users’ passwords need to be initialized by running the passwd command as root, unless your configuration specifies otherwise (see user account passwords). See 系统安装之后, for what’s next!

3.7 系统安装之后

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

guix pull
sudo guix system reconfigure /etc/config.scm

This builds a new system generation with the latest packages and services (see 调用guix system). We recommend doing that regularly so that your system includes the latest security updates (see 安全更新).

注: Note that sudo guix runs your user’s guix command and not root’s, because sudo leaves PATH unchanged. To explicitly run root’s guix, type sudo -i guix ….

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

Now, see 入门, and join us on #guix on the Libera Chat IRC network or on guix-devel@gnu.org to share your experience!

3.8 Installing Guix in a Virtual Machine

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 QEMU VM for installing Guix System in a disk image, follow these steps:

1. First, retrieve and decompress the Guix system installation image as described previously (see U盘和DVD安装).
2. Create a disk image that will hold the installed system. To make a qcow2-formatted disk image, use the qemu-img command:

   qemu-img create -f qcow2 guix-system.img 50G
   

   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.

3. Boot the USB installation image in an VM:

   qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
     -nic user,model=virtio-net-pci -boot menu=on,order=d \
     -drive file=guix-system.img \
     -drive media=cdrom,file=guix-system-install-1.3.0.system.iso
   

   -enable-kvm is optional, but significantly improves performance, see 在虚拟机里运行Guix.

4. You’re now root in the VM, proceed with the installation process. See 准备安装, and follow the instructions.

Once installation is complete, you can boot the system that’s on your guix-system.img image. See 在虚拟机里运行Guix, for how to do that.

3.9 构建安装镜像

The installation image described above was built using the guix system command, specifically:

guix system image -t iso9660 gnu/system/install.scm

Have a look at gnu/system/install.scm in the source tree, and see also 调用guix system for more information about the installation image.

3.10 Building the Installation Image for ARM Boards

Many ARM boards require a specific variant of the 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:

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

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

4 入门

Presumably, you’ve reached this section because either you have installed Guix on top of another distribution (see 安装), or you’ve installed the standalone Guix System (see 系统安装). 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:

guix search text editor

This command shows you a number of matching 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, no need for root privileges!):

guix install emacs

You’ve installed your first package, congrats! The package is now visible in your default profile, $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 not use pre-built binaries, then probably Guix is still building software (see substitutes, for more info).

Unless you’re using Guix System, the guix install command must have printed this hint:

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"'.

Indeed, you must now tell your shell where emacs and other programs installed with Guix are to be found. Pasting the two lines above will do just that: it will add $HOME/.guix-profile/bin—which is where the installed package is—to the 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 ~/.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 python and Python libraries, PYTHONPATH will be defined.

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

guix package --list-installed

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

guix package --roll-back

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

guix package --list-generations

现在你知道包管理的基本知识了吧！

Going further: See 软件包管理, for more about package management. You may like declarative package management with guix package --manifest, managing separate profiles with --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, see 开发 for additional tools. And if you’re curious, see 功能, to peek under the hood.

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

guix pull

The end result is a new guix command, under ~/.config/guix/current/bin. Unless you’re on Guix System, the first time you run 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 .bash_profile:

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

You must also instruct your shell to point to this new guix:

hash guix

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

guix upgrade

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:

guix describe

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

Going further: See 调用guix pull, for more information. See 通道, on how to specify additional channels to pull packages from, how to replicate Guix, and more. You may also find time-machine handy (see Invoking guix time-machine).

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

sudo guix system reconfigure /etc/config.scm

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

sudo guix system roll-back

There are many things you’ll probably want to tweak on your system: adding new user accounts, adding new system services, fiddling with the configuration of those services, etc. The system configuration is entirely described in the /etc/config.scm file. See 使用配置系统, to learn how to change it.

Now you know enough to get started!

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

• See The GNU Guix Cookbook, for a list of “how-to” style of recipes for a variety of applications.
• The GNU Guix Reference Card lists in two pages most of the commands and options you’ll ever need.
• The web site contains instructional videos covering topics such as everyday use of Guix, how to get help, and how to become a contributor.
• See 文档, to learn how to access documentation on your computer.

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

5 软件包管理

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 (see guix package), you may also use the Emacs-Guix interface (see The Emacs-Guix Reference Manual), after installing emacs-guix package (run M-x guix-help command to start with it):

guix install emacs-guix

5.1 功能

Here we assume you’ve already made your first steps with Guix (see 入门) and would like to get an overview about what’s going on under the hood.

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

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

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

The guix package command is the central tool to manage packages (see 调用guix package). It operates on the per-user profiles, and can be used with normal user privileges.

The command provides the obvious install, remove, and upgrade operations. Each invocation is actually a transaction: either the specified operation succeeds, or nothing happens. Thus, if the 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 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 (see 使用配置系统).

All packages in the package store may be garbage-collected. Guix can determine which packages are still referenced by user profiles, and remove those that are provably no longer referenced (see 调用guix gc). Users may also explicitly remove old generations of their profile so that the packages they refer to can be collected.

Guix takes a purely functional approach to package management, as described in the introduction (see 介绍). Each /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 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 (see container).

This foundation allows Guix to support transparent binary/source deployment. When a pre-built binary for a /gnu/store item is available from an external source—a substitute, Guix just downloads it and unpacks it; otherwise, it builds the package from source, locally (see 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 challenge providers (see 调用guix challenge).

Control over the build environment is a feature that is also useful for developers. The guix environment 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 (see 调用guix environment).

All of Guix and its package definitions is version-controlled, and guix pull allows you to “travel in time” on the history of Guix itself (see 调用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 replicate complete software environments, while retaining precise provenance tracking of the software.

5.2 Invoking guix package

The 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 profile—a directory of installed packages. Each user has a default profile in $HOME/.guix-profile. The command operates only on the user’s own profile, and works with normal user privileges (see 功能). Its syntax is:

guix package options

Primarily, options specifies the operations to be performed during the transaction. Upon completion, a new profile is created, but previous generations of the profile remain available, should the user want to roll back.

For example, to remove lua and install guile and guile-cairo in a single transaction:

guix package -r lua -i guile guile-cairo

For your convenience, we also provide the following aliases:

• guix search is an alias for guix package -s,
• guix install is an alias for guix package -i,
• guix remove is an alias for guix package -r,
• guix upgrade is an alias for guix package -u,
• and guix show is an alias for guix package --show=.

These aliases are less expressive than guix package and provide fewer options, so in some cases you’ll probably want to use guix package directly.

guix package also supports a declarative approach whereby the user specifies the exact set of packages to be available and passes it via the --manifest option (see --manifest).

For each user, a symlink to the user’s default profile is automatically created in $HOME/.guix-profile. This symlink always points to the current generation of the user’s default profile. Thus, users can add $HOME/.guix-profile/bin to their PATH environment variable, and so on. If you are not using Guix System, consider adding the following lines to your ~/.bash_profile (see Bash Startup Files in The GNU Bash Reference Manual) so that newly-spawned shells get all the right environment variable definitions:

GUIX_PROFILE="$HOME/.guix-profile" ; \
source "$GUIX_PROFILE/etc/profile"

In a multi-user setup, user profiles are stored in a place registered as a garbage-collector root, which $HOME/.guix-profile points to (see 调用guix gc). That directory is normally localstatedir/guix/profiles/per-user/user, where localstatedir is the value passed to configure as --localstatedir, and user is the user name. The per-user directory is created when guix-daemon is started, and the user sub-directory is created by guix package.

The options can be among the following:

--install=package …

-i package …

Install the specified packages.

Each package may specify either a simple package name, such as guile, or a package name followed by an at-sign and version number, such as guile@1.8.8 or simply guile@1.8 (in the latter case, the newest version prefixed by 1.8 is selected).

If no version number is specified, the newest available version will be selected. In addition, package may contain a colon, followed by the name of one of the outputs of the package, as in gcc:doc or binutils@2.22:lib (see 有多个输出的软件包). Packages with a corresponding name (and optionally version) are searched for among the GNU distribution modules (see 软件包模块).

Sometimes packages have propagated inputs: these are dependencies that automatically get installed along with the required package (see propagated-inputs in package objects, for information about propagated inputs in package definitions).

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 --search-paths below). Any missing or possibly incorrect environment variable definitions are reported here.

--install-from-expression=exp

-e exp

Install the package exp evaluates to.

exp must be a Scheme expression that evaluates to a <package> object. This option is notably useful to disambiguate between same-named variants of a package, with expressions such as (@ (gnu packages base) 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.

--install-from-file=file

-f file

Install the package that the code within file evaluates to.

As an example, file might contain a definition like this (see 定义软件包):

(use-modules (guix)
             (guix build-system gnu)
             (guix licenses))

(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)
  (synopsis "Hello, GNU world: An example GNU package")
  (description "Guess what GNU Hello prints!")
  (home-page "http://www.gnu.org/software/hello/")
  (license gpl3+))

Developers may find it useful to include such a guix.scm file in the root of their project source tree that can be used to test development snapshots and create reproducible development environments (see 调用guix environment).

The file may also contain a JSON representation of one or more package definitions. Running guix package -f on hello.json with the following contents would result in installing the package greeter after building myhello:

[
  {
    "name": "myhello",
    "version": "2.10",
    "source": "mirror://gnu/hello/hello-2.10.tar.gz",
    "build-system": "gnu",
    "arguments": {
      "tests?": false
    }
    "home-page": "https://www.gnu.org/software/hello/",
    "synopsis": "Hello, GNU world: An example GNU package",
    "description": "GNU Hello prints a greeting.",
    "license": "GPL-3.0+",
    "native-inputs": ["gettext"]
  },
  {
    "name": "greeter",
    "version": "1.0",
    "source": "https://example.com/greeter-1.0.tar.gz",
    "build-system": "gnu",
    "arguments": {
      "test-target": "foo",
      "parallel-build?": false,
    },
    "home-page": "https://example.com/",
    "synopsis": "Greeter using GNU Hello",
    "description": "This is a wrapper around GNU Hello.",
    "license": "GPL-3.0+",
    "inputs": ["myhello", "hello"]
  }
]

--remove=package …

-r package …

Remove the specified packages.

As for --install, each package may specify a version number and/or output name in addition to the package name. For instance, ‘-r glibc:debug’ would remove the debug output of glibc.

--upgrade[=regexp …]

-u [regexp …]

Upgrade all the installed packages. If one or more regexps are specified, upgrade only installed packages whose name matches a regexp. Also see the --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 guix pull (see 调用guix pull).

When upgrading, package transformations that were originally applied when creating the profile are automatically re-applied (see 软件包变换选项。). For example, assume you first installed Emacs from the tip of its development branch with:

guix install emacs-next --with-branch=emacs-next=master

Next time you run guix upgrade, Guix will again pull the tip of the Emacs development branch and build emacs-next from that checkout.

Note that transformation options such as --with-branch and --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:

guix install package

--do-not-upgrade[=regexp …]

When used together with the --upgrade option, do not upgrade any packages whose name matches a regexp. For example, to upgrade all packages in the current profile except those containing the substring “emacs”:

$ guix package --upgrade . --do-not-upgrade emacs

--manifest=file

-m file

Create a new generation of the profile from the manifest object returned by the Scheme code in file. This option can be repeated several times, in which case the manifests are concatenated.

This allows you to declare the profile’s contents rather than constructing it through a sequence of --install and similar commands. The advantage is that file can be put under version control, copied to different machines to reproduce the same profile, and so on.

file must return a manifest object, which is roughly a list of packages:

(use-package-modules guile emacs)

(packages->manifest
 (list emacs
       guile-2.0
       ;; Use a specific package output.
       (list guile-2.0 "debug")))

In this example we have to know which modules define the emacs and guile-2.0 variables to provide the right use-package-modules line, which can be cumbersome. We can instead provide regular package specifications and let specifications->manifest look up the corresponding package objects, like this:

(specifications->manifest
 '("emacs" "guile@2.2" "guile@2.2:debug"))

See --export-manifest, to learn how to obtain a manifest file from an existing profile.

--roll-back

Roll back to the previous generation of the profile—i.e., undo the last transaction.

When combined with options such as --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 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.

--switch-generation=pattern

-S pattern

Switch to a particular generation defined by pattern.

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 --roll-back, use --switch-generation=+1.

The difference between --roll-back and --switch-generation=-1 is that --switch-generation will not make a zeroth generation, so if a specified generation does not exist, the current generation will not be changed.

--search-paths[=kind]

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 search paths for files used by some of the installed packages.

For example, GCC needs the CPATH and LIBRARY_PATH environment variables to be defined so it can look for headers and libraries in the user’s profile (see Environment Variables in Using the GNU Compiler Collection (GCC)). If GCC and, say, the C library are installed in the profile, then --search-paths will suggest setting these variables to profile/include and profile/lib, respectively.

The typical use case is to define these environment variables in the shell:

$ eval `guix package --search-paths`

kind may be one of exact, prefix, or 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, kind defaults to exact.

This option can also be used to compute the combined search paths of several profiles. Consider this example:

$ guix package -p foo -i guile
$ guix package -p bar -i guile-json
$ guix package -p foo -p bar --search-paths

The last command above reports about the GUILE_LOAD_PATH variable, even though, taken individually, neither foo nor bar would lead to that recommendation.

--profile=profile

-p profile

Use profile instead of the user’s default profile.

profile must be the name of a file that will be created upon completion. Concretely, profile will be a mere symbolic link (“symlink”) pointing to the actual profile where packages are installed:

$ guix install hello -p ~/code/my-profile
…
$ ~/code/my-profile/bin/hello
Hello, world!

All it takes to get rid of the profile is to remove this symlink and its siblings that point to specific generations:

$ rm ~/code/my-profile ~/code/my-profile-*-link

--list-profiles

List all the user’s profiles:

$ guix package --list-profiles
/home/charlie/.guix-profile
/home/charlie/code/my-profile
/home/charlie/code/devel-profile
/home/charlie/tmp/test

When running as root, list all the profiles of all the users.

--allow-collisions

Allow colliding packages in the new profile. Use at your own risk!

By default, guix package reports as an error collisions in the profile. Collisions happen when two or more different versions or variants of a given package end up in the profile.

--bootstrap

Use the bootstrap Guile to build the profile. This option is only useful to distribution developers.

In addition to these actions, guix package supports the following options to query the current state of a profile, or the availability of packages:

--search=regexp

-s regexp

List the available packages whose name, synopsis, or description matches regexp (in a case-insensitive fashion), sorted by relevance. Print all the metadata of matching packages in recutils format (see GNU recutils databases in GNU recutils manual).

This allows specific fields to be extracted using the recsel command, for instance:

$ 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

Similarly, to show the name of all the packages available under the terms of the GNU LGPL version 3:

$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
name: elfutils

name: gmp
…

It is also possible to refine search results using several -s flags to guix package, or several arguments to guix search. For example, the following command returns a list of board games (this time using the guix search alias):

$ guix search '\<board\>' game | recsel -p name
name: gnubg
…

If we were to omit -s game, we would also get software packages that deal with printed circuit boards; removing the angle brackets around 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:

$ guix search crypto library | \
    recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis

See Selection Expressions in GNU recutils manual, for more information on selection expressions for recsel -e.

--show=package

Show details about package, taken from the list of available packages, in recutils format (see GNU recutils databases in GNU recutils manual).

$ guix package --show=python | recsel -p name,version
name: python
version: 2.7.6

name: python
version: 3.3.5

You may also specify the full name of a package to only get details about a specific version of it (this time using the guix show alias):

$ guix show python@3.4 | recsel -p name,version
name: python
version: 3.4.3

--list-installed[=regexp]

-I [regexp]

List the currently installed packages in the specified profile, with the most recently installed packages shown last. When regexp is specified, list only installed packages whose name matches 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, out for the default output, include for its headers, etc.), and the path of this package in the store.

--list-available[=regexp]

-A [regexp]

List packages currently available in the distribution for this system (see GNU发行版). When regexp is specified, list only available packages whose name matches regexp.

For each package, print the following items separated by tabs: its name, its version string, the parts of the package (see 有多个输出的软件包), and the source location of its definition.

--list-generations[=pattern]

-l [pattern]

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 (see 有多个输出的软件包), and the location of this package in the store.

When pattern is used, the command returns only matching generations. Valid patterns include:

• Integers and comma-separated integers. Both patterns denote generation numbers. For instance, --list-generations=1 returns the first one.

  And --list-generations=1,8,2 outputs three generations in the specified order. Neither spaces nor trailing commas are allowed.

• Ranges. --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, --list-generations=2.., returns all generations starting from the second one.

• Durations. You can also get the last N days, weeks, or months by passing an integer along with the first letter of the duration. For example, --list-generations=20d lists generations that are up to 20 days old.

--delete-generations[=pattern]

-d [pattern]

When pattern is omitted, delete all generations except the current one.

This command accepts the same patterns as --list-generations. When pattern is specified, delete the matching generations. When pattern specifies a duration, generations older than the specified duration match. For instance, --delete-generations=1m deletes generations that are more than one month old.

If the current generation matches, it is 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.

--export-manifest

Write to standard output a manifest suitable for --manifest corresponding to the chosen profile(s).

This option is meant to help you migrate from the “imperative” operating mode—running guix install, guix upgrade, etc.—to the declarative mode that --manifest offers.

Be aware that the resulting manifest 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 --export-channels below.

--export-channels

Write to standard output the list of channels used by the chosen profile(s), in a format suitable for guix pull --channels or guix time-machine --channels (see 通道).

Together with --export-manifest, this option provides information allowing you to replicate the current profile (see Replicating Guix).

However, note that the output of this command 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, --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 (see Inferiors).

Together with --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.

Finally, since guix package may actually start build processes, it supports all the common build options (see 普通的构建选项). It also supports package transformation options, such as --with-source, and preserves them across upgrades (see 软件包变换选项。).

5.3 substitutes

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 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 (see 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.

5.3.1 官方的substitute服务器

The ci.guix.gnu.org server is a front-end to an official build farm that builds packages from Guix continuously for some architectures, and makes them available as substitutes. This is the default source of substitutes; it can be overridden by passing the --substitute-urls option either to guix-daemon (see guix-daemon --substitute-urls) or to client tools such as guix package (see client --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 farm are enabled by default when using Guix System (see GNU发行版). 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 (see 安装). 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.

5.3.2 授权substitute服务器。

To allow Guix to download substitutes from ci.guix.gnu.org or a mirror thereof, you must add its public key to the access control list (ACL) of archive imports, using the guix archive command (see 调用guix archive). Doing so implies that you trust ci.guix.gnu.org to not be compromised and to serve genuine substitutes.

注: If you are using Guix System, you can skip this section: Guix System authorizes substitutes from ci.guix.gnu.org by default.

The public key for ci.guix.gnu.org is installed along with Guix, in prefix/share/guix/ci.guix.gnu.org.pub, where prefix is the installation prefix of Guix. If you installed Guix from source, make sure you checked the GPG signature of guix-1.3.0.tar.gz, which contains this public key file. Then, you can run something like this:

# guix archive --authorize < prefix/share/guix/ci.guix.gnu.org.pub

Once this is in place, the output of a command like guix build should change from something like:

$ 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
…

to something like:

$ 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
…

The text changed from “The following derivations would be built” to “112.3 MB would be downloaded”. This indicates that substitutes from ci.guix.gnu.org are usable and will be downloaded, when possible, for future builds.

The substitute mechanism can be disabled globally by running guix-daemon with --no-substitutes (see 调用guix-daemon). It can also be disabled temporarily by passing the --no-substitutes option to guix package, guix build, and other command-line tools.

5.3.3 Getting Substitutes from Other Servers

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 guix service. Since the guix service is part of the default lists of services, %base-services and %desktop-services, you can use modify-services to change its configuration and add the URLs and substitute keys that you want (see modify-services).

As an example, suppose you want to fetch substitutes from guix.example.org and to authorize the signing key of that server, in addition to the default ci.guix.gnu.org. The resulting operating system configuration will look something like:

(operating-system
  ;; …
  (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)))))))

This assumes that the file key.pub contains the signing key of guix.example.org. With this change in place in your operating system configuration file (say /etc/config.scm), you can reconfigure and restart the guix-daemon service or reboot so the changes take effect:

$ sudo guix system reconfigure /etc/config.scm
$ sudo herd restart guix-daemon

If you’re running Guix on a “foreign distro”, you would instead take the following steps to get substitutes from additional servers:

1. Edit the service configuration file for guix-daemon; when using systemd, this is normally /etc/systemd/system/guix-daemon.service. Add the --substitute-urls option on the guix-daemon command line and list the URLs of interest (see guix-daemon --substitute-urls):

   … --substitute-urls='https://guix.example.org https://ci.guix.gnu.org'
   

2. Restart the daemon. For systemd, it goes like this:

   systemctl daemon-reload
   systemctl restart guix-daemon.service
   

3. Authorize the key of the new server (see 调用guix archive):

   guix archive --authorize < key.pub
   

   Again this assumes key.pub contains the public key that guix.example.org uses to sign substitutes.

Now you’re all set! Substitutes will be preferably taken from https://guix.example.org, using ci.guix.gnu.org as a fallback. 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.

Note that there are also situations where one may want to add the URL of a substitute server without authorizing its key. See 验证substitute, to understand this fine point.

5.3.4 验证substitute

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 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:

--substitute-urls="https://a.example.org https://b.example.org"

If the ACL contains only the key for ‘b.example.org’, and if ‘a.example.org’ happens to serve the exact same substitutes, then Guix will download substitutes from ‘a.example.org’ because it comes first in the list and can be considered a mirror of ‘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 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).

5.3.5 代理设置

Substitutes are downloaded over HTTP or HTTPS. The http_proxy and https_proxy environment variables can be set in the environment of guix-daemon and are honored for downloads of substitutes. Note that the value of those environment variables in the environment where guix build, guix package, and other client commands are run has absolutely no effect.

5.3.6 substitute失败

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 --fallback was given (see common build option --fallback). Specifically, if --fallback was omitted, then no local build will be performed, and the derivation is considered to have failed. However, if --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 always be performed, regardless of whether or not --fallback was given.

To get an idea of how many substitutes are available right now, you can try running the guix weather command (see 调用guix weather). This command provides statistics on the substitutes provided by a server.

5.3.7 关于信任二进制文件

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 ci.guix.gnu.org substitutes can be convenient, we encourage users to also build on their own, or even run their own build farm, such that ci.guix.gnu.org is less of an interesting target. One way to help is by publishing the software you build using guix publish so that others have one more choice of server to download substitutes from (see 调用guix publish).

Guix has the foundations to maximize build reproducibility (see 功能). 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 guix challenge command aims to help users assess substitute servers, and to assist developers in finding out about non-deterministic package builds (see 调用guix challenge). Similarly, the --check option of guix build allows users to check whether previously-installed substitutes are genuine by rebuilding them locally (see 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 guix-devel@gnu.org.

5.4 有多个输出的软件包

Often, packages defined in Guix have a single output—i.e., the source package leads to exactly one directory in the store. When running guix install glibc, one installs the default output of the GNU libc package; the default output is called out, but its name can be omitted as shown in this command. In this particular case, the default output of 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 doc. To install the main GLib output, which contains everything but the documentation, one would run:

guix install glib

The command to install its documentation is:

guix install glib:doc

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 guix size command can help find out about such situations (see 调用guix size). guix graph can also be helpful (see 调用guix graph).

There are several such multiple-output packages in the GNU distribution. Other conventional output names include lib for libraries and possibly header files, bin for stand-alone programs, and debug for debugging information (see 安装调试文件). The outputs of a packages are listed in the third column of the output of guix package --list-available (see 调用guix package).

5.5 Invoking guix gc

Packages that are installed, but not used, may be garbage-collected. The guix gc command allows users to explicitly run the garbage collector to reclaim space from the /gnu/store directory. It is the only way to remove files from /gnu/store—removing files or directories manually may break it beyond repair!

The garbage collector has a set of known roots: any file under /gnu/store reachable from a root is considered live and cannot be deleted; any other file is considered dead and may be deleted. The set of garbage collector roots (“GC roots” for short) includes default user profiles; by default, the symlinks under /var/guix/gcroots represent these GC roots. New GC roots can be added with guix build --root, for example (see 调用guix build). The guix gc --list-roots command lists them.

Prior to running 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 guix package --delete-generations (see 调用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 GB are available on your disk, simply run:

guix gc -F 5G

It is perfectly safe to run as a non-interactive periodic job (see 执行计划任务, for how to set up such a job). Running 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 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 --delete option), to print garbage-collector information, or for more advanced queries. The garbage collection options are as follows:

--collect-garbage[=min]

-C [min]

Collect garbage—i.e., unreachable /gnu/store files and sub-directories. This is the default operation when no option is specified.

When min is given, stop once min bytes have been collected. min may be a number of bytes, or it may include a unit as a suffix, such as MiB for mebibytes and GB for gigabytes (see size specifications in GNU Coreutils).

When min is omitted, collect all the garbage.

--free-space=free

-F free

Collect garbage until free space is available under /gnu/store, if possible; free denotes storage space, such as 500MiB, as described above.

When free or more is already available in /gnu/store, do nothing and exit immediately.

--delete-generations[=duration]

-d [duration]

Before starting the garbage collection process, delete all the generations older than duration, for all the user profiles; when run as root, this applies to all the profiles 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:

guix gc -d 2m -F 10G

--delete

-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.

--list-failures

List store items corresponding to cached build failures.

This prints nothing unless the daemon was started with --cache-failures (see --cache-failures).

--list-roots

List the GC roots owned by the user; when run as root, list all the GC roots.

--list-busy

List store items in use by currently running processes. These store items are effectively considered GC roots: they cannot be deleted.

--clear-failures

Remove the specified store items from the failed-build cache.

Again, this option only makes sense when the daemon is started with --cache-failures. Otherwise, it does nothing.

--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.

--list-live

Show the list of live store files and directories.

In addition, the references among existing store files can be queried:

--references

--referrers

List the references (respectively, the referrers) of store files given as arguments.

--requisites

-R

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 transitive closure of the store files.

See 调用guix size, for a tool to profile the size of the closure of an element. See 调用guix graph, for a tool to visualize the graph of references.

--derivers

Return the derivation(s) leading to the given store items (see Derivations).

For example, this command:

guix gc --derivers $(guix package -I ^emacs$ | cut -f4)

returns the .drv file(s) leading to the emacs package installed in your profile.

Note that there may be zero matching .drv files, for instance because these files have been garbage-collected. There can also be more than one matching .drv due to fixed-output derivations.

Lastly, the following options allow you to check the integrity of the store and to control disk usage.

--verify[=options]

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 /gnu/store.

When provided, options must be a comma-separated list containing one or more of contents and repair.

When passing --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 all the files in the store, this command can take a long time, especially on systems with a slow disk drive.

Using --verify=repair or --verify=contents,repair causes the daemon to try to repair corrupt store items by fetching substitutes for them (see 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 guix build --repair (see 调用guix build).

--optimize

Optimize the store by hard-linking identical files—this is deduplication.

The daemon performs deduplication after each successful build or archive import, unless it was started with --disable-deduplication (see --disable-deduplication). Thus, this option is primarily useful when the daemon was running with --disable-deduplication.

5.6 Invoking 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 guix pull: the command downloads the latest Guix source code and package descriptions, and deploys it. Source code is downloaded from a Git repository, by default the official GNU Guix repository, though this can be customized. guix pull ensures that the code it downloads is authentic by verifying that commits are signed by Guix developers.

Specifically, guix pull downloads code from the channels (see 通道) specified by one of the followings, in this order:

1. the --channels option;
2. the user’s ~/.config/guix/channels.scm file;
3. the system-wide /etc/guix/channels.scm file;
4. the built-in default channels specified in the %default-channels variable.

On completion, 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 guix sub-commands added by the update also become available.

Any user can update their Guix copy using guix pull, and the effect is limited to the user who ran guix pull. For instance, when user root runs guix pull, this has no effect on the version of Guix that user alice sees, and vice versa.

The result of running guix pull is a profile available under ~/.config/guix/current containing the latest Guix. Thus, make sure to add it to the beginning of your search path so that you use the latest version, and similarly for the Info manual (see 文档):

export PATH="$HOME/.config/guix/current/bin:$PATH"
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"

The --list-generations or -l option lists past generations produced by guix pull, along with details about their provenance:

$ 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
  2 new packages: keepalived, libnfnetlink
  6 packages upgraded: emacs-nix-mode@2.0.4,
    guile2.0-guix@0.14.0-12.77a1aac, guix@0.14.0-12.77a1aac,
    heimdal@7.5.0, milkytracker@1.02.00, nix@2.0.4

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
  28 new packages: emacs-helm-ls-git, emacs-helm-mu, …
  69 packages upgraded: borg@1.1.6, cheese@3.28.0, …

See guix describe, for other ways to describe the current status of Guix.

This ~/.config/guix/current profile works exactly like the profiles created by guix package (see 调用guix package). That is, you can list generations, roll back to the previous generation—i.e., the previous Guix—and so on:

$ 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

You can also use guix package (see 调用guix package) to manage the profile by naming it explicitly:

$ 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

The guix pull command is usually invoked with no arguments, but it supports the following options:

--url=url

--commit=commit

--branch=branch

Download code for the guix channel from the specified url, at the given commit (a valid Git commit ID represented as a hexadecimal string), or branch.

These options are provided for convenience, but you can also specify your configuration in the ~/.config/guix/channels.scm file or using the --channels option (see below).

--channels=file

-C file

Read the list of channels from file instead of ~/.config/guix/channels.scm or /etc/guix/channels.scm. file must contain Scheme code that evaluates to a list of channel objects. See 通道, for more information.

--news

-N

Display the list of packages added or upgraded since the previous generation, as well as, occasionally, news written by channel authors for their users (see Writing Channel News).

The package information is the same as displayed upon guix pull completion, but without ellipses; it is also similar to the output of guix pull -l for the last generation (see below).

--list-generations[=pattern]

-l [pattern]

List all the generations of ~/.config/guix/current or, if pattern is provided, the subset of generations that match pattern. The syntax of pattern is the same as with guix package --list-generations (see 调用guix package).

--roll-back

Roll back to the previous generation of ~/.config/guix/current—i.e., undo the last transaction.

--switch-generation=pattern

-S pattern

Switch to a particular generation defined by pattern.

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 --roll-back, use --switch-generation=+1.

--delete-generations[=pattern]

-d [pattern]

When pattern is omitted, delete all generations except the current one.

This command accepts the same patterns as --list-generations. When pattern is specified, delete the matching generations. When pattern specifies a duration, generations older than the specified duration match. For instance, --delete-generations=1m deletes generations that are more than one month old.

If the current generation matches, it is not deleted.

Note that deleting generations prevents rolling back to them. Consequently, this command must be used with care.

See 调用guix describe, for a way to display information about the current generation only.

--profile=profile

-p profile

Use profile instead of ~/.config/guix/current.

--dry-run

-n

Show which channel commit(s) would be used and what would be built or substituted but do not actually do it.

--allow-downgrades

Allow pulling older or unrelated revisions of channels than those currently in use.

By default, 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.

注: Make sure you understand its security implications before using --allow-downgrades.

--disable-authentication

Allow pulling channel code without authenticating it.

By default, 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.

注: Make sure you understand its security implications before using --disable-authentication.

--system=system

-s system

Attempt to build for system—e.g., i686-linux—instead of the system type of the build host.

--bootstrap

Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers.

The channel mechanism allows you to instruct guix pull which repository and branch to pull from, as well as additional repositories containing package modules that should be deployed. See 通道, for more information.

In addition, guix pull supports all the common build options (see 普通的构建选项).

5.7 Invoking guix time-machine

The 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 guix describe (see 调用guix describe).

The general syntax is:

guix time-machine options… -- command arg…

where command and arg… are passed unmodified to the guix command of the specified revision. The options that define this revision are the same as for guix pull (see 调用guix pull):

--url=url

--commit=commit

--branch=branch

Use the guix channel from the specified url, at the given commit (a valid Git commit ID represented as a hexadecimal string), or branch.

--channels=file

-C file

Read the list of channels from file. file must contain Scheme code that evaluates to a list of channel objects. See 通道 for more information.

As for guix pull, the absence of any options means that the latest commit on the master branch will be used. The command

guix time-machine -- build hello

will thus build the package hello as defined in the master branch, which is in general a newer revision of Guix than you have installed. Time travel works in both directions!

Note that guix time-machine can trigger builds of channels and their dependencies, and these are controlled by the standard build options (see 普通的构建选项).

5.8 Inferiors

注: The functionality described here is a “technology preview” as of version 1.3.0. As such, the interface is subject to change.

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 inferiors allow you to achieve that by composing different Guix revisions in arbitrary ways.

Technically, an “inferior” is essentially a separate Guix process connected to your main Guix process through a REPL (see 调用guix repl). The (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—inferior packages.

When combined with channels (see 通道), 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 guile package, along with the guile-json as it existed in an older revision of Guix—perhaps because the newer 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 guix package --manifest (see 调用guix package); in that manifest, you would create an inferior for that old Guix revision you care about, and you would look up the guile-json package in the inferior:

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

On its first run, 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 (guix inferior) module provides the following procedures to open an inferior:

Scheme Procedure: inferior-for-channels channels [#:cache-directory] [#:ttl] Return an inferior for channels, a list of

channels. Use the cache at cache-directory, where entries can be reclaimed after ttl seconds. This procedure opens a new connection to the build daemon.

As a side effect, this procedure may build or substitute binaries for channels, which can take time.

Scheme Procedure: open-inferior directory [#:command "bin/guix"] Open the inferior Guix in directory, running

directory/command repl or equivalent. Return #f if the inferior could not be launched.

The procedures listed below allow you to obtain and manipulate inferior packages.

Scheme Procedure: inferior-packages inferior

Return the list of packages known to inferior.

Scheme Procedure: lookup-inferior-packages inferior name [version] Return the sorted list of inferior packages matching

name in inferior, with highest version numbers first. If version is true, return only packages with a version number prefixed by version.

Scheme Procedure: inferior-package? obj

Return true if obj is an inferior package.

Scheme Procedure: inferior-package-name package

Scheme Procedure: inferior-package-version package

Scheme Procedure: inferior-package-synopsis package

Scheme Procedure: inferior-package-description package

Scheme Procedure: inferior-package-home-page package

Scheme Procedure: inferior-package-location package

Scheme Procedure: inferior-package-inputs package

Scheme Procedure: inferior-package-native-inputs package

Scheme Procedure: inferior-package-propagated-inputs package

Scheme Procedure: inferior-package-transitive-propagated-inputs package

Scheme Procedure: inferior-package-native-search-paths package

Scheme Procedure: inferior-package-transitive-native-search-paths package

Scheme Procedure: inferior-package-search-paths package

These procedures are the counterpart of package record accessors (see 软件包引用). Most of them work by querying the inferior package comes from, so the inferior must still be live when you call these procedures.

Inferior packages can be used transparently like any other package or file-like object in G-expressions (see G-表达式). They are also transparently handled by the packages->manifest procedure, which is commonly used in manifests (see the --manifest option of guix package). Thus you can insert an inferior package pretty much anywhere you would insert a regular package: in manifests, in the packages field of your operating-system declaration, and so on.

5.9 Invoking 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 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 guix describe command answers these questions.

When run from a guix pulled guix, guix describe displays the channel(s) that it was built from, including their repository URL and commit IDs (see 通道):

$ 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

If you’re familiar with the Git version control system, this is similar in spirit to git describe; the output is also similar to that of guix pull --list-generations, but limited to the current generation (see the --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, guix describe can also be asked to return a list of channels instead of the human-readable description above:

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

You can save this to a file and feed it to guix pull -C on some other machine or at a later point in time, which will instantiate this exact Guix revision (see the -C option). From there on, since you’re able to deploy the same revision of Guix, you can just as well replicate a complete software environment. We humbly think that this is awesome, and we hope you’ll like it too!

The details of the options supported by guix describe are as follows:

--format=format

-f format

Produce output in the specified format, one of:

human

produce human-readable output;

channels

produce a list of channel specifications that can be passed to guix pull -C or installed as ~/.config/guix/channels.scm (see 调用guix pull);

channels-sans-intro

like channels, but omit the introduction field; use it to produce a channel specification suitable for Guix version 1.1.0 or earlier—the introduction field has to do with channel authentication (see Channel Authentication) and is not supported by these older versions;

json

produce a list of channel specifications in JSON format;

recutils

produce a list of channel specifications in Recutils format.

--list-formats

Display available formats for --format option.

--profile=profile

-p profile

Display information about profile.

5.10 Invoking guix archive

The guix archive command allows users to export files from the store into a single archive, and to later 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.

注: If you’re looking for a way to produce archives in a format suitable for tools other than Guix, see 调用guix pack.

To export store files as an archive to standard output, run:

guix archive --export options specifications...

specifications may be either store file names or package specifications, as for guix package (see 调用guix package). For instance, the following command creates an archive containing the gui output of the git package and the main output of emacs:

guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar

If the specified packages are not built yet, guix archive automatically builds them. The build process may be controlled with the common build options (see 普通的构建选项).

To transfer the emacs package to a machine connected over SSH, one would run:

guix archive --export -r emacs | ssh the-machine guix archive --import

Similarly, a complete user profile may be transferred from one machine to another like this:

guix archive --export -r $(readlink -f ~/.guix-profile) | \
  ssh the-machine guix archive --import

However, note that, in both examples, all of emacs and the profile as well as all of their dependencies are transferred (due to -r), regardless of what is already available in the store on the target machine. The --missing option can help figure out which items are missing from the target store. The guix copy command simplifies and optimizes this whole process, so this is probably what you should use in this case (see 调用guix copy).

Each store item is written in the normalized archive or nar format (described below), and the output of guix archive --export (and input of guix archive --import) is a 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.

The main options are:

--export

Export the specified store files or packages (see below). Write the resulting archive to the standard output.

Dependencies are not included in the output, unless --recursive is passed.

-r

--recursive

When combined with --export, this instructs 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.

--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 --authorize below).

--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.

--generate-key[=parameters]

Generate a new key pair for the daemon. This is a prerequisite before archives can be exported with --export. This operation is usually instantaneous but it can take time if the system’s entropy pool needs to be refilled. On Guix System, guix-service-type takes care of generating this key pair the first boot.

The generated key pair is typically stored under /etc/guix, in signing-key.pub (public key) and signing-key.sec (private key, which must be kept secret). When 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, parameters can specify genkey parameters suitable for Libgcrypt (see gcry_pk_genkey in The Libgcrypt Reference Manual).

--authorize

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 signing-key.pub file.

The list of authorized keys is kept in the human-editable file /etc/guix/acl. The file contains “advanced-format s-expressions” and is structured as an access-control list in the Simple Public-Key Infrastructure (SPKI).

--extract=directory

-x directory

Read a single-item archive as served by substitute servers (see substitutes) and extract it to 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 ci.guix.gnu.org to /tmp/emacs:

$ wget -O - \
  https://ci.guix.gnu.org/nar/gzip/…-emacs-24.5 \
  | gunzip | guix archive -x /tmp/emacs

Single-item archives are different from multiple-item archives produced by guix archive --export; they contain a single store item, and they do not embed a signature. Thus this operation does 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 (see 调用guix challenge).

--list

-t

Read a single-item archive as served by substitute servers (see substitutes) and print the list of files it contains, as in this example:

$ wget -O - \
  https://ci.guix.gnu.org/nar/lzip/…-emacs-26.3 \
  | lzip -d | guix archive -t

6 通道

Guix and its package collection are updated by running guix pull (see 调用guix pull). By default guix pull downloads and deploys Guix itself from the official GNU Guix repository. This can be customized by defining channels in the ~/.config/guix/channels.scm file. A channel specifies a URL and branch of a Git repository to be deployed, and guix pull can be instructed to pull from one or more channels. In other words, channels can be used to customize and to extend Guix, as we will see below. Guix is able to take into account security concerns and deal with authenticated updates.

6.1 Specifying Additional Channels

You can specify additional channels to pull from. To use a channel, write ~/.config/guix/channels.scm to instruct guix pull to pull from it in addition to the default Guix channel(s):

;; Add variant packages to those Guix provides.
(cons (channel
        (name 'variant-packages)
        (url "https://example.org/variant-packages.git"))
      %default-channels)

Note that the snippet above is (as always!) Scheme code; we use cons to add a channel the list of channels that the variable %default-channels is bound to (see cons and lists in GNU Guile Reference Manual). With this file in place, guix pull builds not only Guix but also the package modules from your own repository. The result in ~/.config/guix/current is the union of Guix with your own package modules:

$ guix pull --list-generations
…
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
  11 new packages: variant-gimp, variant-emacs-with-cool-features, …
  4 packages upgraded: emacs-racket-mode@0.0.2-2.1b78827, …

The output of guix pull above shows that Generation 19 includes both Guix and packages from the variant-personal-packages channel. Among the new and upgraded packages that are listed, some like variant-gimp and variant-emacs-with-cool-features might come from variant-packages, while others come from the Guix default channel.

6.2 Using a Custom Guix Channel

The channel called 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 example.org, and specifically the super-hacks branch, you can write in ~/.config/guix/channels.scm this specification:

;; Tell 'guix pull' to use another repo.
(list (channel
        (name 'guix)
        (url "https://example.org/another-guix.git")
        (branch "super-hacks")))

From there on, guix pull will fetch code from the super-hacks branch of the repository at example.org. The authentication concern is addressed below ((see Channel Authentication).

6.3 Replicating Guix

The guix pull --list-generations output above shows precisely which commits were used to build this instance of Guix. We can thus replicate it, say, on another machine, by providing a channel specification in ~/.config/guix/channels.scm that is “pinned” to these commits:

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

The guix describe --format=channels command can even generate this list of channels directly (see 调用guix describe). The resulting file can be used with the -C options of guix pull (see 调用guix pull) or guix time-machine (see Invoking guix time-machine).

At this point the two machines run the exact same Guix, with access to the exact same packages. The output of guix build gimp on one machine will be exactly the same, bit for bit, as the output of the same command on the other machine. It also means both machines have access to all the source code of Guix and, transitively, to all the source code of every package it defines.

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. See Inferiors, for another way to take advantage of these super powers.

6.4 Channel Authentication

The guix pull and guix time-machine commands 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 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:

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

The specification above shows the name and URL of the channel. The call to make-channel-introduction above specifies that authentication of this channel starts at commit 6f0d8cc…, which is signed by the OpenPGP key with fingerprint CABB A931….

For the main channel, called guix, you automatically get that information from your Guix installation. For other channels, include the channel introduction provided by the channel authors in your 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!

6.5 Channels with Substitutes

When running guix pull, Guix will first compile the definitions of every available package. This is an expensive operation for which substitutes (see substitutes) may be available. The following snippet in channels.scm will ensure that guix pull uses the latest commit with available substitutes for the package definitions: this is done by querying the continuous integration server at https://ci.guix.gnu.org.

(use-modules (guix ci))

(list (channel-with-substitutes-available
       %default-guix-channel
       "https://ci.guix.gnu.org"))

Note that this does not mean that all the packages that you will install after running guix pull will have available substitutes. It only ensures that guix pull will not try to compile package definitions. This is particularly useful when using machines with limited resources.

6.6 创建一个频道

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. You would first write modules containing those package definitions (see 软件包模块), maintain them in a Git repository, and then you and anyone else can use it as an additional channel to get packages from. Neat, no?

Warning: Before you, dear user, shout—“woow this is soooo coool!”—and publish your personal channel to the world, we would like to share a few words of caution:

• Before publishing a channel, please consider contributing your package definitions to Guix proper (see 贡献). 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.
• When you maintain package definitions outside Guix, we, Guix developers, consider that the compatibility burden is on you. Remember that package modules and package definitions are just Scheme code that uses various programming interfaces (APIs). We want to remain free to change these APIs to keep improving Guix, possibly in ways that break your channel. We never change APIs gratuitously, but we will not commit to freezing APIs either.
• Corollary: if you’re using an external channel and that channel breaks, please report the issue to the channel authors, not to the Guix project.

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 free software. Please email us at guix-devel@gnu.org if you’d like to discuss this.

To create a channel, create a Git repository containing your own package modules and make it available. The repository can contain anything, but a useful channel will contain Guile modules that export packages. Once you start using a channel, Guix will behave as if the root directory of that channel’s Git repository has been added to the Guile load path (see Load Paths in GNU Guile Reference Manual). For example, if your channel contains a file at my-packages/my-tools.scm that defines a Guile module, then the module will be available under the name (my-packages my-tools), and you will be able to use it like any other module (see 模块 in GNU Guile Reference Manual).

As a channel author, consider bundling authentication material with your channel so that users can authenticate it. See Channel Authentication, and Specifying Channel Authorizations, for info on how to do it.

6.7 Package Modules in a Sub-directory

As a channel author, you may want to keep your channel modules in a sub-directory. If your modules are in the sub-directory guix, you must add a meta-data file .guix-channel that contains:

(channel
  (version 0)
  (directory "guix"))

6.8 Declaring Channel Dependencies

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 .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:

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

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.

6.9 Specifying 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 .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 .guix-authorizations file of its parent commit(s)¹⁰ The .guix-authorizations file looks like this:

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

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 .guix-authorizations? And how do we fork existing channels?

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 guix pull or 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.

Additionally, your channel must provide all the OpenPGP keys that were ever mentioned in .guix-authorizations, stored as .key files, which can be either binary or “ASCII-armored”. By default, those .key files are searched for in the branch named keyring but you can specify a different branch name in .guix-channel like so:

(channel
  (version 0)
  (keyring-reference "my-keyring-branch"))

To summarize, as the author of a channel, there are three things you have to do to allow users to authenticate your code:

1. Export the OpenPGP keys of past and present committers with gpg --export and store them in .key files, by default in a branch named keyring (we recommend making it an orphan branch).
2. Introduce an initial .guix-authorizations in the channel’s repository. Do that in a signed commit (see 提交权利, for information on how to sign Git commits.)
3. 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 .guix-authorizations, and the fingerprint of the OpenPGP used to sign it.

Before pushing to your public Git repository, you can run guix git-authenticate to verify that you did sign all the commits you are about to push with an authorized key:

guix git authenticate commit signer

where commit and signer are your channel introduction. See 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 .guix-authorizations file of both branches.

6.10 Primary URL

Channel authors can indicate the primary URL of their channel’s Git repository in the .guix-channel file, like so:

(channel
  (version 0)
  (url "https://example.org/guix.git"))

This allows 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 guix channel, for which guix pull ensures the code it fetches is authentic.

6.11 Writing Channel News

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 news file; when the channel users run guix pull, that news file is automatically read and 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 .guix-channel file:

(channel
  (version 0)
  (news-file "etc/news.txt"))

The news file itself, etc/news.txt in this example, must look something like this:

(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!"))))

While the news file is using the Scheme syntax, avoid naming it with a .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 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 title field should be a one-line summary while body can be arbitrarily long, and both can contain Texinfo markup (see Overview in GNU Texinfo). Both the title and body are a list of language tag/message tuples, which allows 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 xgettext (see xgettext Invocation in 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:

xgettext -o news.po -l scheme -ken etc/news.txt

To sum up, yes, you could use your channel as a blog. But beware, this is not quite what your users might expect.

7 开发

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 guix environment command provides a convenient way to set up development environments containing all the dependencies and tools necessary to work on the software package of your choice. The guix pack command allows you to create application bundles that can be easily distributed to users who do not run Guix.

7.1 Invoking guix environment

The purpose of guix environment is to assist hackers in creating reproducible development environments without polluting their package profile. The guix environment tool takes one or more packages, builds all of their inputs, and creates a shell environment to use them.

The general syntax is:

guix environment options package…

The following example spawns a new shell set up for the development of GNU Guile:

guix environment guile

If the needed dependencies are not built yet, guix environment automatically builds them. The environment of the new shell is an augmented version of the environment that 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 --pure option¹¹.

Exiting from a Guix environment is the same as exiting from the shell, and will place the user back in the old environment before guix environment was invoked. The next garbage collection (see 调用guix gc) will clean up packages that were installed from within the environment and are no longer used outside of it.

guix environment defines the 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 .bashrc (see Bash Startup Files in The GNU Bash Reference Manual):

if [ -n "$GUIX_ENVIRONMENT" ]
then
    export PS1="\u@\h \w [dev]\$ "
fi

... or to browse the profile:

$ ls "$GUIX_ENVIRONMENT/bin"

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:

guix environment guile emacs

Sometimes an interactive shell session is not desired. An arbitrary command may be invoked by placing the -- token to separate the command from the rest of the arguments:

guix environment guile -- make -j4

In other situations, it is more convenient to specify the list of packages needed in the environment. For example, the following command runs python from an environment containing Python 2.7 and NumPy:

guix environment --ad-hoc python2-numpy python-2.7 -- python

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 --ad-hoc flag is positional. Packages appearing before --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:

guix environment --pure guix --ad-hoc git strace

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 /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:

guix environment --ad-hoc --container guile -- guile

注: The --container option requires Linux-libre 3.19 or newer.

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 nss-certs and expose /etc/ssl/certs/ for HTTPS authentication; finally we preserve the DISPLAY environment variable since containerized graphical applications won’t display without it.

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

The available options are summarized below.

--root=file

-r file

Make 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 guix environment session. This means that next time you recreate the same environment, you could have to rebuild or re-download packages. See 调用guix gc, for more on GC roots.

--expression=expr

-e expr

Create an environment for the package or list of packages that expr evaluates to.

For example, running:

guix environment -e '(@ (gnu packages maths) petsc-openmpi)'

starts a shell with the environment for this specific variant of the PETSc package.

Running:

guix environment --ad-hoc -e '(@ (gnu) %base-packages)'

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:

guix environment --ad-hoc -e '(list (@ (gnu packages bash) bash) "include")'

--load=file

-l file

Create an environment for the package or list of packages that the code within file evaluates to.

As an example, file might contain a definition like this (see 定义软件包):

(use-modules (guix)
             (gnu packages gdb)
             (gnu packages autotools)
             (gnu packages texinfo))

;; Augment the package definition of GDB with the build tools
;; needed when developing GDB (and which are not needed when
;; simply installing it.)
(package (inherit gdb)
  (native-inputs `(("autoconf" ,autoconf-2.64)
                   ("automake" ,automake)
                   ("texinfo" ,texinfo)
                   ,@(package-native-inputs gdb))))

--manifest=file

-m file

Create an environment for the packages contained in the manifest object returned by the Scheme code in file. This option can be repeated several times, in which case the manifests are concatenated.

This is similar to the same-named option in guix package (see --manifest) and uses the same manifest files.

--ad-hoc

Include all specified packages in the resulting environment, as if an 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:

guix environment --ad-hoc guile guile-sdl -- guile

runs guile in an environment where Guile and Guile-SDL are available.

Note that this example implicitly asks for the default output of guile and guile-sdl, but it is possible to ask for a specific output—e.g., glib:bin asks for the bin output of glib (see 有多个输出的软件包).

This option may be composed with the default behavior of guix environment. Packages appearing before --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.

--pure

Unset existing environment variables when building the new environment, except those specified with --preserve (see below). This has the effect of creating an environment in which search paths only contain package inputs.

--preserve=regexp

-E regexp

When used alongside --pure, preserve the environment variables matching regexp—in other words, put them on a “white list” of environment variables that must be preserved. This option can be repeated several times.

guix environment --pure --preserve=^SLURM --ad-hoc openmpi … \
  -- mpirun …

This example runs mpirun in a context where the only environment variables defined are PATH, environment variables whose name starts with ‘SLURM’, as well as the usual “precious” variables (HOME, USER, etc.).

--search-paths

Display the environment variable definitions that make up the environment.

--system=system

-s system

Attempt to build for system—e.g., i686-linux.

--container

-C

Run command within an isolated container. The current working directory outside the container is mapped inside the container. Additionally, unless overridden with --user, a dummy home directory is created that matches the current user’s home directory, and /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 --user is passed (see below).

--network

-N

For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device.

--link-profile

-P

For containers, link the environment profile to ~/.guix-profile within the container and set GUIX_ENVIRONMENT to that. This is equivalent to making ~/.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 guix environment was invoked in the user’s home directory.

Certain packages are configured to look in ~/.guix-profile for configuration files and data;¹² --link-profile allows these programs to behave as expected within the environment.

--user=user

-u user

For containers, use the username user in place of the current user. The generated /etc/passwd entry within the container will contain the name user, the home directory will be /home/user, and no user GECOS data will be copied. Furthermore, the UID and GID inside the container are 1000. user need not exist on the system.

Additionally, any shared or exposed path (see --share and --expose respectively) whose target is within the current user’s home directory will be remapped relative to /home/USER; this includes the automatic mapping of the current working directory.

# 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

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.

--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, --no-cwd will cause the current working directory to not be automatically shared and will change to the user’s home directory within the container instead. See also --user.

--expose=source[=target]

--share=source[=target]

For containers, --expose (resp. --share) exposes the file system source from the host system as the read-only (resp. writable) file system target within the container. If target is not specified, 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 /exchange directory:

guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile

guix environment also supports all of the common build options that guix build supports (see 普通的构建选项) as well as package transformation options (see 软件包变换选项。).

7.2 Invoking 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 guix package -i something, but that’s not possible in this case. This is where guix pack comes in.

注: If you are looking for ways to exchange binaries among machines that already run Guix, see 调用guix copy, 调用guix publish, and 调用guix archive.

The guix pack command creates a shrink-wrapped pack or 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:

$ guix pack guile emacs geiser
…
/gnu/store/…-pack.tar.gz

The result here is a tarball containing a /gnu/store directory with all the relevant packages. The resulting tarball contains a profile with the three packages of interest; the profile is the same as would be created by guix package -i. It is this mechanism that is used to create Guix’s own standalone binary tarball (see 二进制文件安装).

Users of this pack would have to run /gnu/store/…-profile/bin/guile to run Guile, which you may find inconvenient. To work around it, you can create, say, a /opt/gnu/bin symlink to the profile:

guix pack -S /opt/gnu/bin=bin guile emacs geiser

That way, users can happily type /opt/gnu/bin/guile and enjoy.

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 --relocatable option (see below). This option produces relocatable binaries, meaning they 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 ./opt/gnu/bin/guile.

Alternatively, you can produce a pack in the Docker image format using the following command:

guix pack -f docker -S /bin=bin guile guile-readline

The result is a tarball that can be passed to the docker load command, followed by docker run:

docker load < file
docker run -ti guile-guile-readline /bin/guile

where file is the image returned by guix pack, and guile-guile-readline is its “image tag”. See the Docker documentation for more information.

Yet another option is to produce a SquashFS image with the following command:

guix pack -f squashfs bash guile emacs geiser

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 Singularity container execution environment, using commands like singularity shell or singularity exec.

Several command-line options allow you to customize your pack:

--format=format

-f format

Produce a pack in the given format.

The available formats are:

tarball

This is the default format. It produces a tarball containing all the specified binaries and symlinks.

docker

This produces a tarball that follows the Docker Image Specification. The “repository name” as it appears in the output of the docker images command is computed from package names passed on the command line or in the manifest file.

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.

注: Singularity requires you to provide /bin/sh in the image. For that reason, guix pack -f squashfs always implies -S /bin=bin. Thus, your guix pack invocation must always start with something like:

guix pack -f squashfs bash …

If you forget the bash (or similar) package, singularity run and singularity exec will fail with an unhelpful “no such file or directory” message.

--relocatable

-R

Produce 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 user namespaces in the kernel Linux; when passed twice¹³, 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:

guix pack -RR -S /mybin=bin bash

... you can copy that pack to a machine that lacks Guix, and from your home directory as a normal user, run:

tar xf pack.tar.gz
./mybin/sh

In that shell, if you type ls /gnu/store, you’ll notice that /gnu/store shows up and contains all the dependencies of bash, even though the machine actually lacks /gnu/store altogether! That is probably the simplest way to deploy Guix-built software on a non-Guix machine.

注: By default, relocatable binaries rely on the 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 --relocatable or -R twice. In that case, binaries will try user namespace support and fall back to another execution engine if user namespaces are not supported. The following execution engines are supported:

default

Try user namespaces and fall back to PRoot if user namespaces are not supported (see below).

performance

Try user namespaces and fall back to Fakechroot if user namespaces are not supported (see below).

userns

Run the program through user namespaces and abort if they are not supported.

proot

Run through PRoot. The PRoot program provides the necessary support for file system virtualization. It achieves that by using the 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.

fakechroot

Run through Fakechroot. Fakechroot virtualizes file system accesses by intercepting calls to C library functions such as open, stat, 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 via direct syscalls are not intercepted either, leading to erratic behavior.

When running a wrapped program, you can explicitly request one of the execution engines listed above by setting the GUIX_EXECUTION_ENGINE environment variable accordingly.

--entry-point=command

Use command as the entry point of the resulting pack, if the pack format supports it—currently docker and squashfs (Singularity) support it. command must be relative to the profile contained in the pack.

The entry point specifies the command that tools like docker run or singularity run automatically start by default. For example, you can do:

guix pack -f docker --entry-point=bin/guile guile

The resulting pack can easily be loaded and docker run with no extra arguments will spawn bin/guile:

docker load -i pack.tar.gz
docker run image-id

--expression=expr

-e expr

Consider the package expr evaluates to.

This has the same purpose as the same-named option in guix build (see --expression in guix build).

--manifest=file

-m file

Use the packages contained in the manifest object returned by the Scheme code in 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 guix package (see --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 either a manifest file or a list of packages, but not both.

--system=system

-s system

Attempt to build for system—e.g., i686-linux—instead of the system type of the build host.

--target=triplet

Cross-build for triplet, which must be a valid GNU triplet, such as "aarch64-linux-gnu" (see GNU configuration triplets in Autoconf).

--compression=tool

-C tool

Compress the resulting tarball using tool—one of gzip, zstd, bzip2, xz, lzip, or none for no compression.

--symlink=spec

-S spec

Add the symlinks specified by spec to the pack. This option can appear several times.

spec has the form source=target, where source is the symlink that will be created and target is the symlink target.

For instance, -S /opt/gnu/bin=bin creates a /opt/gnu/bin symlink pointing to the bin sub-directory of the profile.

--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 (see 通道).

Provenance information is saved in the /gnu/store/…-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.

--root=file

-r file

Make file a symlink to the resulting pack, and register it as a garbage collector root.

--localstatedir

--profile-name=name

Include the “local state directory”, /var/guix, in the resulting pack, and notably the /var/guix/profiles/per-user/root/name profile—by default name is guix-profile, which corresponds to ~root/.guix-profile.

/var/guix contains the store database (see 仓库) as well as garbage-collector roots (see 调用guix gc). Providing it in the pack means that the store is “complete” and manageable by Guix; not providing it 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 (see 二进制文件安装).

--derivation

-d

Print the name of the derivation that builds the pack.

--bootstrap

Use the bootstrap binaries to build the pack. This option is only useful to Guix developers.

In addition, guix pack supports all the common build options (see 普通的构建选项) and all the package transformation options (see 软件包变换选项。).

7.3 The GCC toolchain

If you need a complete toolchain for compiling and linking C or C++ source code, use the 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 debug output), Binutils, and a linker wrapper.

The wrapper’s purpose is to inspect the -L and -l switches passed to the linker, add corresponding -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 GUIX_LD_WRAPPER_ALLOW_IMPURITIES environment variable to no.

The package gfortran-toolchain provides a complete GCC toolchain for Fortran development. For other languages, please use ‘guix search gcc toolchain’ (see Invoking guix package).

7.4 Invoking guix git authenticate

The guix git authenticate command authenticates a Git checkout following the same rule as for channels (see 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 .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:

guix git authenticate commit signer [options…]

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. commit above denotes the first commit where authentication takes place, and signer is the OpenPGP fingerprint of public key used to sign commit. Together, they form a “channel introduction” (see channel introduction). The options below allow you to fine-tune the process.

--repository=directory

-r directory

Open the Git repository in directory instead of the current directory.

--keyring=reference

-k reference

Load OpenPGP keyring from reference, the reference of a branch such as origin/keyring or my-keyring. The branch must contain OpenPGP public keys in .key files, either in binary form or “ASCII-armored”. By default the keyring is loaded from the branch named keyring.

--stats

Display commit signing statistics upon completion.

--cache-key=key

Previously-authenticated commits are cached in a file under ~/.cache/guix/authentication. This option forces the cache to be stored in file key in that directory.

--historical-authorizations=file

By default, any commit whose parent commit(s) lack the .guix-authorizations file is considered inauthentic. In contrast, this option considers the authorizations in file for any commit that lacks .guix-authorizations. The format of file is the same as that of .guix-authorizations (see .guix-authorizations format).

8 编程接口

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 /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.

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 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 derive from them.

This chapter describes all these APIs in turn, starting from high-level package definitions.

8.1 软件包模块

From a programming viewpoint, the package definitions of the GNU distribution are provided by Guile modules in the (gnu packages …) name space¹⁴ (see Guile modules in GNU Guile Reference Manual). For instance, the (gnu packages emacs) module exports a variable named emacs, which is bound to a <package> object (see 定义软件包).

The (gnu packages …) module name space is automatically scanned for packages by the command-line tools. For instance, when running guix install emacs, all the (gnu packages …) modules are scanned until one that exports a package object whose name is emacs is found. This package search facility is implemented in the (gnu packages) module.

Users can store package definitions in modules with different names—e.g., (my-packages emacs)¹⁵. There are two ways to make these package definitions visible to the user interfaces:

1. By adding the directory containing your package modules to the search path with the -L flag of guix package and other commands (see 普通的构建选项), or by setting the GUIX_PACKAGE_PATH environment variable described below.
2. By defining a channel and configuring guix pull so that it pulls from it. A channel is essentially a Git repository containing package modules. See 通道, for more information on how to define and use channels.

GUIX_PACKAGE_PATH works similarly to other search path variables:

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.

The distribution is fully bootstrapped and 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 bootstrap binaries, provided by the (gnu packages bootstrap) module. For more information on bootstrapping, see 引导.

8.2 定义软件包

The high-level interface to package definitions is implemented in the (guix packages) and (guix build-system) modules. As an example, the package definition, or recipe, for the GNU Hello package looks like this:

(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 `(("gawk" ,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+)))

Without being a Scheme expert, the reader may have guessed the meaning of the various fields here. This expression binds the variable hello to a <package> object, which is essentially a record (see Scheme records in GNU Guile Reference Manual). This package object can be inspected using procedures found in the (guix packages) module; for instance, (package-name hello) returns—surprise!—"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 guix import command (see 调用guix import).

In the example above, hello is defined in a module of its own, (gnu packages hello). Technically, this is not strictly necessary, but it is convenient to do so: all the packages defined in modules under (gnu packages …) are automatically known to the command-line tools (see 软件包模块).

There are a few points worth noting in the above package definition:

• The source field of the package is an <origin> object (see origin参考手册, for the complete reference). Here, the url-fetch method from (guix download) is used, meaning that the source is a file to be downloaded over FTP or HTTP.

  The mirror://gnu prefix instructs url-fetch to use one of the GNU mirrors defined in (guix download).

  The 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 (base32 …) form introduces the base32 representation of the hash. You can obtain this information with guix download (see 调用guix download) and guix hash (see 调用guix hash).

  When needed, the origin form can also have a patches field listing patches to be applied, and a snippet field giving a Scheme expression to modify the source code.

• The build-system field specifies the procedure to build the package (see 构建系统). Here, gnu-build-system represents the familiar GNU Build System, where packages may be configured, built, and installed with the usual ./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. See Build Utilities, for more on this.

• The arguments field specifies options for the build system (see 构建系统). Here it is interpreted by gnu-build-system as a request run configure with the --enable-silent-rules flag.

  What about these quote (') characters? They are Scheme syntax to introduce a literal list; ' is synonymous with quote. See quoting in GNU Guile Reference Manual, for details. Here the value of the arguments field is a list of arguments passed to the build system down the road, as with apply (see apply in GNU Guile Reference Manual).

  The hash-colon (#:) sequence defines a Scheme keyword (see Keywords in GNU Guile Reference Manual), and #:configure-flags is a keyword used to pass a keyword argument to the build system (see Coding With Keywords in GNU Guile Reference Manual).

• The inputs field specifies inputs to the build process—i.e., build-time or run-time dependencies of the package. Here, we define an input called "gawk" whose value is that of the gawk variable; gawk is itself bound to a <package> object.

  Again, ` (a backquote, synonymous with quasiquote) allows us to introduce a literal list in the inputs field, while , (a comma, synonymous with unquote) allows us to insert a value in that list (see unquote in GNU Guile Reference Manual).

  Note that GCC, Coreutils, Bash, and other essential tools do not need to be specified as inputs here. Instead, gnu-build-system takes care of ensuring that they are present (see 构建系统).

  However, any other dependencies need to be specified in the inputs field. Any dependency not specified here will simply be unavailable to the build process, possibly leading to a build failure.

See 软件包引用, for a full description of possible fields.

Once a package definition is in place, the package may actually be built using the guix build command-line tool (see 调用guix build), troubleshooting any build failures you encounter (see 调试构建错误). You can easily jump back to the package definition using the guix edit command (see 调用guix edit。). See 打包指导, for more information on how to test package definitions, and 调用guix lint, for information on how to check a definition for style conformance. Lastly, see 通道, 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 guix refresh command (see 调用guix refresh).

Behind the scenes, a derivation corresponding to the <package> object is first computed by the package-derivation procedure. That derivation is stored in a .drv file under /gnu/store. The build actions it prescribes may then be realized by using the build-derivations procedure (see 仓库).

Scheme Procedure: package-derivation store package [system]

Return the <derivation> object of package for system (see Derivations).

package must be a valid <package> object, and system must be a string denoting the target system type—e.g., "x86_64-linux" for an x86_64 Linux-based GNU system. store must be a connection to the daemon, which operates on the store (see 仓库).

Similarly, it is possible to compute a derivation that cross-builds a package for some other system:

Scheme Procedure: package-cross-derivation store package target [system] Return the <derivation>

object of package cross-built from system to target.

target must be a valid GNU triplet denoting the target hardware and operating system, such as "aarch64-linux-gnu" (see Specifying Target Triplets in Autoconf).

Once you have package definitions, you can easily define variants of those packages. See Defining Package Variants, for more on that.

8.2.1 package Reference

This section summarizes all the options available in package declarations (see 定义软件包).

Data Type: package

This is the data type representing a package recipe.

名字

The name of the package, as a string.

version

The version of the package, as a string.

source

An object telling how the source code for the package should be acquired. Most of the time, this is an origin object, which denotes a file fetched from the Internet (see origin参考手册). It can also be any other “file-like” object such as a local-file, which denotes a file from the local file system (see local-file).

build-system

The build system that should be used to build the package (see 构建系统).

arguments (default: '())

The arguments that should be passed to the build system. This is a list, typically containing sequential keyword-value pairs.

inputs (default: '())

native-inputs (default: '())

propagated-inputs (default: '())

These fields list dependencies of the package. Each one is 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 "out" (see 有多个输出的软件包, for more on package outputs). For example, the list below specifies three inputs:

`(("libffi" ,libffi)
  ("libunistring" ,libunistring)
  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib

The distinction between native-inputs and inputs is necessary when considering cross-compilation. When cross-compiling, dependencies listed in inputs are built for the target architecture; conversely, dependencies listed in native-inputs are built for the architecture of the build machine.

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. guix lint can report likely mistakes in this area (see 调用guix lint).

Lastly, propagated-inputs is similar to inputs, but the specified packages will be automatically installed to profiles (see the role of profiles in Guix) alongside the package they belong to (see guix package, for information on how 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 via its Requires field.

Another example where propagated-inputs is useful is for languages that lack a facility to record the run-time search path akin to the 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 propagated-inputs rather than inputs.

outputs (default: '("out"))

The list of output names of the package. See 有多个输出的软件包, for typical uses of additional outputs.

native-search-paths (default: '())

search-paths (default: '())

A list of search-path-specification objects describing search-path environment variables honored by the package.

replacement (default: #f)

This must be either #f or a package object that will be used as a replacement for this package. See grafts, for details.

synopsis

A one-line description of the package.

description

A more elaborate description of the package.

license

The license of the package; a value from (guix licenses), or a list of such values.

home-page

The URL to the home-page of the package, as a string.

supported-systems (default: %supported-systems)

The list of systems supported by the package, as strings of the form architecture-kernel, for example "x86_64-linux".

location (default: source location of the 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.

Scheme Syntax: this-package

When used in the 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:

(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)
                     `(("self" ,this-package))
                     '())))

It is an error to refer to this-package outside a package definition.

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.

Scheme Procedure: package-with-c-toolchain package toolchain

Return a variant of package that uses toolchain instead of the default GNU C/C++ toolchain. toolchain must be a list of inputs (label/package tuples) providing equivalent functionality, such as the gcc-toolchain package.

The example below returns a variant of the hello package built with GCC 10.x and the rest of the GNU tool chain (Binutils and the GNU C Library) instead of the default tool chain:

(let ((toolchain (specification->package "gcc-toolchain@10")))
  (package-with-c-toolchain hello `(("toolchain" ,toolchain))))

The build tool chain is part of the 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 package so that it pulls in toolchain instead of the defaults. 构建系统, for more on build systems.

8.2.2 origin Reference

This section documents origins. An 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 (see 定义软件包). For that reason, the origin form allows you to declare patches to apply to the original source code as well as code snippets to modify it.

Data Type: origin

This is the data type representing a source code origin.

uri

An object containing the URI of the source. The object type depends on the method (see below). For example, when using the url-fetch method of (guix download), the valid uri values are: a URL represented as a string, or a list thereof.

method

A monadic procedure that handles the given URI. The procedure must accept at least three arguments: the value of the uri field and the hash algorithm and hash value specified by the hash field. It must return a store item or a derivation in the store monad (see 仓库monad); most methods return a fixed-output derivation (see Derivations).

Commonly used methods include url-fetch, which fetches data from a URL, and git-fetch, which fetches data from a Git repository (see below).

sha256

A bytevector containing the SHA-256 hash of the source. This is equivalent to providing a content-hash SHA256 object in the hash field described below.

hash

The content-hash object of the source—see below for how to use content-hash.

You can obtain this information using guix download (see 调用guix download) or guix hash (see 调用guix hash).

file-name (default: #f)

The file name under which the source code should be saved. When this is #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 recommended to provide the file name explicitly because the default is not very descriptive.

patches (default: '())

A list of file names, origins, or file-like objects (see file-like objects) pointing to patches to be applied to the source.

This list of patches must be unconditional. In particular, it cannot depend on the value of %current-system or %current-target-system.

snippet (default: #f)

A G-expression (see G-表达式) or S-expression that will be run in the source directory. This is a convenient way to modify the source, sometimes more convenient than a patch.

patch-flags (default: '("-p1"))

A list of command-line flags that should be passed to the patch command.

patch-inputs (default: #f)

Input packages or derivations to the patching process. When this is #f, the usual set of inputs necessary for patching are provided, such as GNU Patch.

modules (default: '())

A list of Guile modules that should be loaded during the patching process and while running the code in the snippet field.

patch-guile (default: #f)

The Guile package that should be used in the patching process. When this is #f, a sensible default is used.

Data Type: content-hash value [algorithm]

Construct a content hash object for the given algorithm, and with value as its hash value. When algorithm is omitted, assume it is sha256.

value can be a literal string, in which case it is base32-decoded, or it can be a bytevector.

The following forms are all equivalent:

(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
              sha256)
(content-hash (base32
               "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
(content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
              sha256)

Technically, content-hash is currently implemented as a macro. It performs sanity checks at macro-expansion time, when possible, such as ensuring that value has the right size for algorithm.

As we have seen above, how exactly the data an origin refers to is retrieved is determined by its method field. The (guix download) module provides the most common method, url-fetch, described below.

Scheme Procedure: url-fetch url hash-algo hash [name] [#:executable? #f] Return a fixed-output derivation that fetches data

from url (a string, or a list of strings denoting alternate URLs), which is expected to have hash hash of type hash-algo (a symbol). By default, the file name is the base name of URL; optionally, name can specify a different file name. When executable? is true, make the downloaded file executable.

When one of the URL starts with mirror://, then its host part is interpreted as the name of a mirror scheme, taken from %mirror-file.

Alternatively, when URL starts with file://, return the corresponding file name in the store.

Likewise, the (guix git-download) module defines the git-fetch origin method, which fetches data from a Git version control repository, and the git-reference data type to describe the repository and revision to fetch.

Scheme Procedure: git-fetch ref hash-algo hash

Return a fixed-output derivation that fetches ref, a <git-reference> object. The output is expected to have recursive hash hash of type hash-algo (a symbol). Use name as the file name, or a generic name if #f.

Data Type: git-reference

This data type represents a Git reference for git-fetch to retrieve.

url

The URL of the Git repository to clone.

commit

This string denotes either the commit to fetch (a hexadecimal string, either the full SHA1 commit or a “short” commit string; the latter is not recommended) or the tag to fetch.

recursive? (default: #f)

This Boolean indicates whether to recursively fetch Git sub-modules.

The example below denotes the v2.10 tag of the GNU Hello repository:

(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "v2.10"))

This is equivalent to the reference below, which explicitly names the commit:

(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))