GNU Guix 烹饪书：函数式包管理的实用指南

Introduction

The GNU Guix Cookbook serves as a comprehensive collection of tutorials and practical examples for GNU Guix, a functional package manager designed for the GNU system. This document is intended for users who wish to move beyond basic commands and explore the powerful, programmable features that Guix offers. It complements the official GNU Guix reference manual, which provides exhaustive details on the system's architecture, API, and core concepts.

《GNU Guix 烹饪书》是针对 GNU 系统设计的函数式包管理工具 GNU Guix 的教程与详细示例合集。本文档面向希望超越基础命令、探索 Guix 强大可编程功能的用户。它是对官方 GNU Guix 参考手册的补充，后者提供了关于系统架构、API 和核心概念的详尽说明。

This manual is a testament to the global free software community, available in multiple languages including Simplified Chinese, French, German, Korean, Spanish, Italian, Brazilian Portuguese, Russian, Slovak, Swedish, and Tamil. Contributions to translate this document into more languages are welcomed through Weblate.

本手册是全球自由软件社区的成果，提供简体中文、法语、德语、韩语、西班牙语、意大利语、巴西葡萄牙语、俄语、斯洛伐克语、瑞典语和泰米尔语等多种语言版本。欢迎通过 Weblate 为本文档贡献更多语言的翻译。

Core Concepts and Structure

The cookbook is structured to guide users from foundational knowledge to advanced system operations. Its chapters are logically organized to build competence progressively.

本书的结构旨在引导用户从基础知识进阶到高级系统操作。其章节按逻辑组织，以循序渐进地构建用户能力。

1. Scheme Tutorials

GNU Guix is implemented in Scheme, and proficiency in this language is key to unlocking its advanced capabilities. Users can programmatically generate package definitions, modify them, build software, and deploy entire operating systems. This section provides the necessary Scheme foundation, demonstrating that one does not need to be an expert programmer to leverage Guix's power effectively.

GNU Guix 使用 Scheme 语言一种 Lisp 方言，是 GNU Guix 的实现语言，用于编写包定义和系统配置。实现，掌握该语言是解锁其高级功能的关键。用户可以编程式地生成包定义、修改它们、构建软件以及部署整个操作系统。本节提供了必要的 Scheme 基础，表明用户无需成为专家级程序员即可有效利用 Guix 的功能。

1.1 A Scheme Crash Course

This tutorial introduces the Guile implementation of Scheme used by Guix. It begins with instructions on launching a Read-Eval-Print Loop (REPL) using either guile or guix shell guile -- guile.

本教程介绍了 Guix 所使用的 Guile Scheme 实现。开头说明了如何使用 guile 或 guix shell guile -- guile 启动一个读取-求值-输出循环（REPL）。

Key Syntax Elements:

Expressions and S-Expressions: Scheme syntax is based on a tree of expressions (S-expressions). These can be literals (numbers, strings) or parenthesized lists of compounds and literals. The Booleans are represented by #true (#t) and #false (#f).

表达式与 S-表达式：Scheme 语法基于表达式树（S-表达式）。它们可以是字面量（数字、字符串）或由复合元素和字面量组成的带括号列表。布尔值由 #true (#t) 和 #false (#f) 表示。
Function Calls: Evaluation of a parenthesized expression treats the first term as the function and the rest as arguments. Functions return the last evaluated expression.

函数调用：对带括号表达式的求值将第一项视为函数，其余项视为参数。函数返回最后一个被求值的表达式。
Procedures (Anonymous Functions): Created with the lambda term. They are first-class values, just like numbers or strings.

过程（匿名函数）：使用 lambda 项创建。它们是一等值，与数字或字符串地位相同。
Variable Definition: The define keyword binds a value to a global name.

变量定义：define 关键字将值与一个全局名称绑定。
Procedure Definition Shorthand: A concise syntax exists for defining named functions.

过程定义简写：存在一种用于定义命名函数的简洁语法。
Lists: Created using the list procedure.

列表：使用 list 过程创建。

The tutorial provides concrete REPL examples to illustrate each concept, such as evaluating literals, nesting function calls, defining and applying procedures, and creating lists.

教程提供了具体的 REPL 示例来说明每个概念，例如求值字面量、嵌套函数调用、定义和应用过程以及创建列表。

2. Packaging

This is a central chapter for contributors, detailing how to create and manage packages for the Guix ecosystem. It starts with a complete tutorial and expands into specific workflows and advanced techniques.

本章节是贡献者的核心指南，详细说明了如何为 Guix 生态系统创建和管理软件包。它从一个完整的教程开始，并扩展到具体的工作流程和高级技巧。

2.1 Packaging Tutorial

A "Hello World" package: The simplest possible package definition.

一个 "Hello World" 软件包：最简单的包定义示例。
Setup: Covers different development environments: using a local file, working with channels, and direct checkout hacking.

设置：涵盖不同的开发环境：使用本地文件、通过渠道工作以及直接检出代码进行开发。
Extended Example: A deep dive into a real package definition, covering:

扩展示例：深入探讨一个真实的包定义，涵盖：
- The git-fetch method for source code.
  
  用于获取源代码的 git-fetch 方法。
- Using code snippets for patching.
  
  使用代码片段进行补丁。
- Specifying build inputs and outputs.
  
  指定构建输入和输出。
- Build system arguments and code staging.
  
  构建系统参数和代码暂存。
- Utility functions and module organization.
  
  实用函数和模块组织。
Other Build Systems: Guidance beyond the standard GNU Build System.

其他构建系统：超越标准 GNU 构建系统的指南。
Programmable and Automated Package Definition: Techniques for generating packages programmatically, using recursive importers, automatic updates, and inheritance.

可编程和自动化的包定义：以编程方式生成包的技术，包括使用递归导入器、自动更新和继承。
Getting Help and References: Points to community resources for support.

获取帮助与参考资料：指向社区支持资源。

2.2 Packaging Workflows

Packaging Rust Crates: A specialized guide for handling Rust packages, including common workflows, Cargo workspaces, and integrating Rust libraries into other build systems.

打包 Rust Crate：处理 Rust 软件包的专门指南，包括常见工作流程、Cargo 工作空间以及将 Rust 库集成到其他构建系统中。

(The following sections provide a high-level overview of the remaining cookbook chapters.)

（以下部分对烹饪书的其余章节进行高层概述。）

3. System Configuration

This chapter explores configuring Guix System, the operating system distribution built on Guix. It includes practical recipes for:

本章探讨如何配置基于 Guix 构建的操作系统发行版——Guix System。它包含以下实用方案：

Auto-login, kernel customization, and the System Image API.

自动登录、内核定制和系统镜像 API。
Integrating security keys (Yubikey) for 2FA and KeePassXC.

集成安全密钥（Yubikey）用于双因素认证和 KeePassXC。
Setting up services: Dynamic DNS, WireGuard VPN, custom window managers (StumpWM), session locks.

设置服务：动态 DNS、WireGuard VPN、自定义窗口管理器（StumpWM）、会话锁。
Deployment on cloud servers (Linode, Kimsufi).

在云服务器（Linode, Kimsufi）上部署。
Advanced setups: bind mounts, fetching substitutes over Tor, NGINX with Lua, music servers with Bluetooth audio.

高级设置：绑定挂载、通过 Tor 获取替代品、带 Lua 的 NGINX、支持蓝牙音频的音乐服务器。

4. Containers

Guix provides lightweight, reproducible containers. This section covers:

Guix 提供轻量级、可复现的容器。本节涵盖：

Guix Containers: For isolating user-space environments.

Guix 容器：用于隔离用户空间环境。
Guix System Containers: For running full system services in isolation (e.g., a database container), including networking configuration.

Guix 系统容器基于 GNU Guix 的轻量级容器技术，提供隔离的运行环境。：用于隔离运行完整的系统服务（例如数据库容器），包括网络配置。

5. Virtual Machines

Recipes for creating and networking VMs with Guix, focusing on:

使用 Guix 创建虚拟机和配置网络的方案，重点包括：

QEMU: Setting up network bridges and troubleshooting Docker conflicts.

QEMU：设置网络桥接并排查 Docker 引起的冲突。
libvirt: Configuring routed networks and custom NAT-based networks.

libvirt：配置路由网络和基于 NAT 的自定义网络。

6. Advanced Package Management

Focuses on the powerful concept of profiles, which are separate collections of packages. It explains:

重点介绍 profile（配置文件） 这一强大概念，即独立的软件包集合。它解释了：

Using manifests to declare profile contents.

使用清单用于声明一组软件包集合的配置文件，支持可复现的软件环境管理。（manifest）声明配置文件内容。
Benefits for reproducibility and managing multiple environments (development, default, specific projects).

对于实现可复现性和管理多个环境（开发、默认、特定项目）的好处。

7. Software Development

A guide to integrating Guix into a software development workflow, progressing from simple builds to continuous integration:

将 Guix 集成到软件开发工作流程的指南，从简单构建逐步推进到持续集成：

Building software with Guix.

使用 Guix 构建软件。
Treating your repository as a Guix channel for dependency management.

将你的代码仓库视为 Guix 渠道以进行依赖管理。
Creating package variants.

创建软件包变体。
Setting up CI for builds.

为构建设置持续集成。

8. Environment Management

Integrating Guix with direnv for automatic environment setup per project directory.

将 Guix 与 direnv 集成，实现按项目目录自动设置环境。

9. Using Guix for Reproducible Research

A methodology for leveraging Guix's reproducibility to ensure scientific research can be replicated:

利用 Guix 的可复现性确保科学研究能够被复现的方法：

Setting up and recording the exact software environment.

设置并记录精确的软件环境。
Archiving source code and referencing the environment in publications.

归档源代码并在出版物中引用该环境。

10. Installing Guix on a Cluster

Guidance for deploying Guix in high-performance computing environments, covering head node setup, compute node configuration, network access, disk usage, and security.

在高性能计算环境中部署 Guix 的指南，涵盖主节点设置、计算节点配置、网络访问、磁盘使用和安全考量。

11. Guix System Management

Specific administrative tasks, such as upgrading PostgreSQL for the Cuirass continuous integration service.

特定的管理任务，例如为 Cuirass 持续集成服务升级 PostgreSQL。

Conclusion and Further Resources

The GNU Guix Cookbook is a living document, continuously enriched by its community. It bridges the gap between theoretical understanding and practical application, empowering users to fully harness the declarative and reproducible nature of functional system management. For authoritative and detailed specifications, readers are always encouraged to consult the primary GNU Guix reference manual.

《GNU Guix 烹饪书》是一份活文档，由其社区不断丰富。它弥合了理论理解与实际应用之间的差距，使用户能够充分利用函数式系统管理的声明性和可复现特性。对于权威和详细的规范，始终鼓励读者查阅主要的 GNU Guix 参考手册。

[The cookbook also includes Acknowledgments, the GNU Free Documentation License, and a Concept Index.]

[本书还包括致谢、GNU 自由文档许可证和一个概念索引。]