mirror of
https://github.com/ryan4yin/nixos-and-flakes-book.git
synced 2024-11-29 11:33:12 +01:00
270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# 模块系统与自定义 options
|
||
|
||
我们在前面的 NixOS 配置中通过设置各种 `options` 的值来配置 NixOS 或者 Home Manager，这些 `options` 实际都在这两个位置定义：
|
||
|
||
> 如果你还使用 nix-darwin，那么它的配置也是类似的，其模块系统的实现位于 [nix-darwin/modules](https://github.com/LnL7/nix-darwin/tree/master/modules)
|
||
|
||
- NixOS: [nixpkgs/nixos/modules](https://github.com/NixOS/nixpkgs/tree/23.11/nixos/modules), 我们在 <https://search.nixos.org/options> 中能看到的所有 NixOS options 都是在这里定义的。
|
||
- Home Manager: [home-manager/modules](https://github.com/nix-community/home-manager/blob/release-23.11/modules): 可在 <https://nix-community.github.io/home-manager/options.xhtml> 中找到其所有的 options.
|
||
|
||
而上述 NixOS Modules 跟 Home Manager Modules 的基础，是 Nixpkgs 中实现的一套通用模块系统 [lib/modules.nix][lib/modules.nix]，这套模块系统的官方文档如下（即使是对熟练使用 NixOS 的用户而言，要看懂这玩意儿也不是件容易的事...）：
|
||
|
||
- [Module System - Nixpkgs][Module System - Nixpkgs]
|
||
|
||
因为 Nixpkgs 的模块系统文档没人写，文档中直接建议读另一份专门针对 NixOS 模块系统的编写指南，确实写得清晰一些，但也很难说它对新手有多友好：
|
||
|
||
- [Writing NixOS Modules - Nixpkgs][Writing NixOS Modules - Nixpkgs]
|
||
|
||
总之，模块系统是由 Nixpkgs 实现的，并不是 Nix 包管理器的一部分，因此它的文档也不在 Nix 包管理器的文档中。
|
||
另外 NixOS 与 Home Manager 都是基于 Nixpkgs 的模块系统实现的。
|
||
|
||
## 模块系统有什么用？
|
||
|
||
我们作为一个普通用户，使用 NixOS 与 Home Manager 基于模块系统实现的各种 options 就已经能满足我们大部分的需求了。
|
||
那么深入学习模块系统对于我们来说，还有什么好处呢？
|
||
|
||
我们在前面介绍配置的模块化时，提到了核心点是将配置拆分为多个模块，再通过 `imports = [ ... ];` 来导入这些模块。这其实就是模块系统最基础的用法。
|
||
但仅仅使用 `imports = [ ... ];`，我们只能将模块中定义的配置原封不动地导入到当前模块中，无法对其做任何定制，灵活性很差。
|
||
在配置简单的情况下，这种方式已经足够了，但如果我们的配置比较复杂，那么这种方式就显得力不从心了。
|
||
|
||
这里举个例子来说明其弊端，
|
||
譬如说我通过一份配置管理了 A、B、C 跟 D 共 4 台 NixOS 主机，我希望能在尽量减少配置重复的前提下实现如下功能：
|
||
|
||
- A、B、C 跟 D 都需要启用 docker 服务，设置开机自启
|
||
- A 需要将 docker 的存储驱动改为 `btrfs`，其他不变
|
||
- B、C 是位于中国的服务器，需要在 docker 配置中设置国内镜像源
|
||
- C 是位于美国的服务器，无特殊要求
|
||
- D 是桌面主机，需要为 docker 设置 HTTP 代理加速下载
|
||
|
||
如果单纯使用 `imports`，那么我们可能得将配置拆分成如下几个模块，然后在每台主机上导入不同的模块：
|
||
|
||
```bash
|
||
› tree
|
||
.
|
||
├── docker-default.nix # 基础的 docker 配置，包含开机自启
|
||
├── docker-btrfs.nix # 导入了 docker-default.nix，将存储驱动改为 btrfs
|
||
├── docker-china.nix # 导入了 docker-default.nix，设置国内镜像源
|
||
└── docker-proxy.nix # 导入了 docker-default.nix，设置 HTTP 代理
|
||
```
|
||
|
||
是否感觉到这样的配置很冗余？这还是一个简单的例子，如果我们的机器更多，不同机器的配置差异更大，那么这种配置的冗余性就会更加明显。
|
||
|
||
显然，我们需要借助其他的手段来解决这个配置冗余的问题，自定义一些我们自己的 `options` 就是一个很不错的选择。
|
||
|
||
在深入学习模块系统之前，我再强调一下，如下内容不是必须学习与使用的，有很多 NixOS 用户并未自定义任何 `options`，只是简单地使用 `imports` 就能满足他们的需求了。
|
||
如果你是新手，可以考虑在遇到类似上面这种，`imports` 解决不了的问题时再来学习这部分内容，这是完全 OK 的。
|
||
|
||
## 基本结构与用法
|
||
|
||
Nixpkgs 中定义的模块，其基本结构如下：
|
||
|
||
```nix
|
||
{ config, pkgs, ... }:
|
||
|
||
{
|
||
imports =
|
||
[ # import other modules here
|
||
];
|
||
|
||
options = {
|
||
# ...
|
||
};
|
||
|
||
config = {
|
||
# ...
|
||
};
|
||
}
|
||
```
|
||
|
||
其中的 `imports = [ ... ];` 我们已经很熟悉了，但另外两个部分，我们还没有接触过，这里简单介绍下：
|
||
|
||
- `options = { ... };`: 它类似编程语言中的变量声明，用于声明一些可配置的选项。
|
||
- `config = { ... };`: 它类似编程语言中的变量赋值，用于为 `options` 中声明的选项赋值。
|
||
|
||
最典型的用法是：在同一 Nixpkgs 模块中，依据 `options = { ... };` 中声明的 `options` 当前的值，在 `config = { .. };` 设置为其他 `options` 赋值，这样就实现了参数化配置的功能。
|
||
|
||
直接看个例子更容易理解：
|
||
|
||
```nix
|
||
{ config, lib, pkgs, ... }:
|
||
|
||
with lib;
|
||
|
||
let
|
||
cfg = config.programs.foo;
|
||
in {
|
||
options.programs.foo = {
|
||
enable = mkEnableOption "the foo program";
|
||
|
||
package = mkOption {
|
||
type = types.package;
|
||
default = pkgs.jq;
|
||
defaultText = literalExpression "pkgs.foo";
|
||
description = "foo package to use.";
|
||
};
|
||
|
||
extraConfig = mkOption {
|
||
default = "";
|
||
example = ''
|
||
foo bar
|
||
'';
|
||
type = types.lines;
|
||
description = ''
|
||
Extra settings for foo.
|
||
'';
|
||
};
|
||
};
|
||
|
||
config = mkIf cfg.enable {
|
||
home.packages = [ cfg.package ];
|
||
xdg.configFile."foo/foorc" = mkIf (cfg.extraConfig != "") {
|
||
text = ''
|
||
# Generated by Home Manager.
|
||
|
||
${cfg.extraConfig}
|
||
'';
|
||
};
|
||
};
|
||
}
|
||
```
|
||
|
||
上面这个模块定义了三个 `options`：
|
||
|
||
- `programs.foo.enable`: 用于控制是否启用此模块
|
||
- `programs.foo.package`: 用于自定义 foo 这个包，比如说使用不同版本、设置不同编译参数等等。
|
||
- `programs.foo.extraConfig`: 用于自定义 foo 的配置文件。
|
||
|
||
然后在 `config` 中，根据 `options` 中声明的这三个变量的值，做了不同的设置：
|
||
|
||
- 如果 `programs.foo.enable` 为 `false` 或者未定义，则不做任何设置。
|
||
- 这是借助 `lib.mkIf` 实现的。
|
||
- 否则
|
||
- 将 `programs.foo.package` 添加到 `home.packages` 中，以将其安装到用户环境中。
|
||
- 将 `programs.foo.extraConfig` 的值写入到 `~/.config/foo/foorc` 中。
|
||
|
||
这样，我们就可以在另一个 nix 文件中导入这个模块，并通过设置这里定义的 `options` 来实现对 foo 的自定义配置了，示例：
|
||
|
||
```nix
|
||
{ config, lib, pkgs, ... }:
|
||
|
||
{
|
||
imports = [
|
||
./foo.nix
|
||
];
|
||
|
||
programs.foo ={
|
||
enable = true;
|
||
package = pkgs.foo;
|
||
extraConfig = ''
|
||
foo baz
|
||
'';
|
||
};
|
||
}
|
||
```
|
||
|
||
上面这个例子中我们为 `options` 赋值的方式实际上是一种**缩写**，当一个模块中只声明了 `options`，而没有声明 `config` （以及其他模块系统的特殊参数）时，我们可以省略掉 `config` 前缀，直接使用 `options` 的名称进行赋值。
|
||
|
||
## 模块系统的赋值与延迟求值
|
||
|
||
模块系统充分利用了 Nix 的延迟求值特性，这也是它能实现参数化配置的关键。
|
||
|
||
先看个简单的例子：
|
||
|
||
```nix
|
||
{
|
||
description = "NixOS Flake for Test";
|
||
|
||
inputs = {
|
||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
|
||
home-manager = {
|
||
url = "github:nix-community/home-manager/release-23.11";
|
||
inputs.nixpkgs.follows = "nixpkgs";
|
||
};
|
||
};
|
||
|
||
outputs = {nixpkgs, ...}: {
|
||
nixosConfigurations = {
|
||
"test" = nixpkgs.lib.nixosSystem {
|
||
system = "x86_64-linux";
|
||
modules = [
|
||
({
|
||
config,
|
||
lib,
|
||
...
|
||
}: {
|
||
options = {
|
||
foo = lib.mkOption {
|
||
default = false;
|
||
type = lib.types.bool;
|
||
};
|
||
};
|
||
|
||
# 示例 1（正常）
|
||
config.warnings = if config.foo then ["foo"] else [];
|
||
|
||
# 示例 2（无限递归）
|
||
# error: infinite recursion encountered
|
||
# config = if config.foo then { warnings = ["foo"];} else {};
|
||
|
||
# 示例 3（正常）
|
||
# config = lib.mkIf config.foo {warnings = ["foo"];};
|
||
})
|
||
];
|
||
};
|
||
};
|
||
};
|
||
}
|
||
```
|
||
|
||
上述配置中的示例 1、2、3 中，`config.warnings` 的值都依赖于 `config.foo` 的值，但它们的实现方式却不同。
|
||
将上述配置保存为 `flake.nix`，然后使用命令 `nix eval .#nixosConfigurations.test.config.warnings` 分别测试示例 1、2、3，
|
||
可以发现示例 1、3 都能正常工作，而示例 2 则会报错 `error: infinite recursion encountered`。
|
||
|
||
下面分别解释说明下：
|
||
|
||
1. 示例一计算流程：`config.warnings` => `config.foo` => `config`
|
||
1. 首先，Nix 尝试计算 `config.warnings` 的值，但发现它依赖于 `config.foo`.
|
||
2. 接着，Nix 尝试计算 `config.foo` 的值，它依赖于其外层的 `config`.
|
||
3. Nix 尝试计算 `config` 的值，`config` 中未被 `config.foo` 真正使用的内容都会被 Nix 延迟求值，因此这里不会递归依赖 `config.warnings`。
|
||
4. `config.foo` 求值结束，接着 `config.warnings` 被赋值，计算结束。
|
||
2. 示例二：`config` => `config.foo` => `config`
|
||
1. 首先，Nix 尝试计算 `config` 的值，但发现它依赖于 `config.foo`.
|
||
2. 接着，Nix 尝试计算 `config.foo` 的值，它依赖于其外层的 `config`.
|
||
3. Nix 尝试计算 `config` 的值，这又跳转到步骤 1，于是进入无限递归，最终报错。
|
||
3. 示例三：跟示例二唯一的区别是改用了 `lib.mkIf` 解决了无限递归问题。
|
||
|
||
其关键就在于 `lib.mkIf` 这个函数，使用它定义的 `config` 会被 Nix 延迟求值，也就是说会在 `config.foo` 求值结束后，才会真正计算 `config = lib.mkIf ...` 的值。
|
||
|
||
Nixpkgs 中的模块系统提供了一系列类似 `lib.mkIf` 的函数，用于实现参数化配置与智能的模块合并：
|
||
|
||
1. `lib.mkIf`: 上面已经介绍过了。
|
||
1. `lib.mkOverride` / `lib.mkdDefault` / `lib.mkForce`: 在前面 [模块化 NixOS 配置](../nixos-with-flakes/modularize-the-configuration.md) 中已经介绍过了。
|
||
1. `lib.mkOrder`, `lib.mkBefore` 与 `lib.mkAfter`: 同上
|
||
1. 查看 [Option Definitions - NixOS][Option Definitions - NixOS] 了解更多与 options 赋值（definition）相关的函数。
|
||
|
||
|
||
## Options 声明与类型检查
|
||
|
||
模块系统的赋值是我们最常用的功能，而如果我们需要自定义一些 `options`，还需要深入了解下 options 的声明与类型检查。
|
||
|
||
这个我觉得就还挺简单的，比赋值要简单挺多了，直接看官方文档就能懂个大概，这里就不再赘述了：
|
||
|
||
- [Option Declarations - NixOS][Option Declarations - NixOS]
|
||
- [Options Types - NixOS][Options Types - NixOS]
|
||
|
||
## References
|
||
|
||
- [Best resources for learning about the NixOS module system? - Discourse](https://discourse.nixos.org/t/best-resources-for-learning-about-the-nixos-module-system/1177/4)
|
||
- [NixOS modules - NixOS Wiki](https://nixos.wiki/wiki/NixOS_modules)
|
||
- [NixOS: config argument - NixOS Wiki](https://nixos.wiki/wiki/NixOS:config_argument)
|
||
- [Module System - Nixpkgs][Module System - Nixpkgs]
|
||
- [Writing NixOS Modules - Nixpkgs][Writing NixOS Modules - Nixpkgs]
|
||
|
||
|
||
[lib/modules.nix]: https://github.com/NixOS/nixpkgs/blob/23.11/lib/modules.nix#L995
|
||
[Module System - Nixpkgs]: https://github.com/NixOS/nixpkgs/blob/23.11/doc/module-system/module-system.chapter.md
|
||
[Writing NixOS Modules - Nixpkgs]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/writing-modules.chapter.md
|
||
[Option Definitions - NixOS]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/option-def.section.md
|
||
[Option Declarations - NixOS]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/option-declarations.section.md
|
||
[Options Types - NixOS]: https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/doc/manual/development/option-types.section.md
|