↓ 跳过正文

NixOS(六):理解模块与选项——配置怎样合并与覆盖

·4584 字·10 分钟
锦李本鲤
作者
锦李本鲤
光锥之内,皆为命运。
NixOS系列 - 这篇文章属于一个选集。
§ 6: 本文

缘起
#

把配置拆成公共模块和每台电脑的文件之后(见第三篇),同一个选项可能会在多个文件中设置。不同定义能否合并、哪些定义会被覆盖,取决于选项的类型和优先级。

例如,假设公共配置把时区设置为UTC,而笔记本配置又设置了另一个本地时区,这两个普通定义就会在评估时发生冲突。使用mkDefault或mkForce可以调整定义的优先级,但要先了解它们的区别,才能根据配置用途选择。

这里介绍NixOS模块的使用方法、选项的合并与覆盖规则,最后写一个带开关的小模块。下面的文件名和主机名都是演示用的,可以在自己的测试配置中尝试。

NixOS模块简介
#

NixOS模块不一定很复杂。平时编辑的configuration.nix就是模块,把一组相关设置放到另外一个文件里,也可以成为模块。

例如,建立modules/common.nix:

1
2
3
4
5
{ pkgs, ... }:
{
  time.timeZone = "UTC";
  environment.systemPackages = [ pkgs.tree pkgs.jq ];
}

这里设置时区,并安装tree和jq。第一行表示这个文件是一个函数,接收包含pkgs的参数集合,返回下面的配置。pkgs.tree和pkgs.jq就是从软件包集合中取出这两个包;...表示还可以接收其他参数,不需要全部列出来。

经常看到的参数还有lib和config。lib提供mkDefault等辅助函数,config则可以读取各个模块合并后的配置。它们由模块系统传入,通常不用自己调用这个函数。

如果文件中没有用到这些参数,也可以直接写一个属性集,例如{ time.timeZone = "UTC"; }。这里说的模块是NixOS配置模块,和内核驱动模块不是同一个概念。

使用imports导入模块
#

假设主机配置位于hosts/laptop/configuration.nix,可以这样导入公共文件:

1
2
3
4
5
6
7
8
9
{ pkgs, ... }:
{
  imports = [
    ./hardware-configuration.nix
    ../../modules/common.nix
  ];

  environment.systemPackages = [ pkgs.ripgrep ];
}

这是主机模块的节选,原有的启动、用户等配置仍要保留。路径相对于写着imports的这个文件,所以这里需要向上两层才能找到modules目录。

如果沿用第三篇的mkHost函数,已经在flake的modules列表里加入了公共模块,就不用再在这里导入它。这是两种组织方法,选一种容易看懂的就好。

文件放进目录并不会自动生效,需要从当前主机的模块列表或imports一路连接到它。对于Git管理的本地flake,新文件还要先用git add加入索引,Nix才看得到。

模块系统会收集这些文件中的定义,再根据选项的类型和优先级合并。imports并不是按顺序执行配置的Shell脚本,因此把某个文件移到列表末尾,不等于让它覆盖前面的设置。

Nix语言另外还有一个import函数,用来读取并求值Nix文件。它与模块里的imports列表名字相似,但不会单独替我们完成NixOS选项的合并。

选项定义的合并
#

列表定义合并
#

上面的两个文件分别设置了environment.systemPackages。这个选项是列表类型,两边的定义会合并,所以公共配置里的tree、jq和主机配置里的ripgrep都会加入系统软件包列表。完整列表还可能包含其他模块提供的包。

这里不需要在主机配置中写成:

1
environment.systemPackages = config.environment.systemPackages ++ [ pkgs.ripgrep ];

这个写法是一个反例:config.environment.systemPackages已经是合并后的最终值,而我们正在定义这个值,再引用它来拼接就会造成递归。直接定义本模块需要添加的列表就可以了。

字符串定义冲突
#

现在假设公共配置仍然写着"UTC",又在主机模块中加入:

1
time.timeZone = "Europe/Paris";

两个普通定义的优先级相同,而时区不能同时是两个不同的字符串,评估时就会报冲突。调整imports顺序不能解决这个问题。

这里需要区分选项声明和选项定义:声明规定选项叫什么、接受什么类型、默认值是什么;定义则是我们平时写的time.timeZone = "UTC";,为它提供一个值。许多常用选项已经由NixOS声明好了,使用时只需要定义它们。

具体怎样合并由选项类型决定。列表通常拼接,普通字符串通常要求同一优先级的值一致,也有专门用于拼接文本行的字符串类型。遇到冲突时,可以先查选项说明,确认它的类型和合并规则。

使用mkDefault设置默认值
#

如果想表达"通常使用UTC,但每台电脑可以自己选择",就把modules/common.nix改成:

1
2
3
4
5
{ lib, pkgs, ... }:
{
  time.timeZone = lib.mkDefault "UTC";
  environment.systemPackages = [ pkgs.tree pkgs.jq ];
}

这里比原来多接收了lib参数,并给时区的值加上lib.mkDefault。主机里的time.timeZone = "Europe/Paris";不用改,它的普通定义会胜出。没有另外设置时区的主机,则继续使用公共配置中的UTC。

常见的定义优先级可以放在一起看:

写法优先级数值用途
mkOption中的default1500声明选项时提供的默认值
lib.mkDefault value1000在配置中提供容易覆盖的设置
普通的option = value;100一般配置
lib.mkForce value50覆盖上面几类定义

数值越小,优先级越高。模块系统先留下优先级最高的定义,再按选项类型合并它们。官方手册的优先级说明介绍了这些规则。

两个文件都用mkDefault给时区设置不同的值,仍然会冲突。mkDefault本身也有优先级,只是比普通定义低,并不表示无条件接受其他定义。

使用mkForce覆盖定义
#

如果需要覆盖别的模块里的普通定义,可以写成time.timeZone = lib.mkForce "Europe/Paris";。不过在这个例子里,把公共配置改成mkDefault就可以表达主机设置优先,不需要再使用mkForce。

检查AI修改的配置时,我会注意mkForce是否有必要。遇到冲突,建议先找出两个定义的来源:公共设置是否应该作为默认值,或者某个模块是否不应被导入。如果是导入关系有误,应先调整模块结构,再考虑是否需要覆盖。

列表也要小心。普通定义和mkDefault列表同时存在时,默认列表会被整个舍弃,不是先拼接再覆盖;给整个environment.systemPackages加mkForce,也会把这个选项里优先级更低的其他定义一起丢掉,不是只替换某一个包。两个不同的mkForce定义碰到一起,同样不会自动分出胜负。

使用mkBefore和mkAfter调整顺序
#

对于列表选项,还可以设置不同定义的合并顺序。例如,将本机增加的软件放在普通列表定义之后,可以把主机中的包列表改为:

1
2
3
4
{ lib, pkgs, ... }:
{
  environment.systemPackages = lib.mkAfter [ pkgs.ripgrep ];
}

这里同样只是相关部分的节选。mkBefore和mkAfter调整留下来的列表定义怎样排序,不改变前面说的覆盖优先级。其他普通列表定义仍然可以参与合并。

包列表这个例子方便观察顺序,但软件包通常不需要特意排序;对于按顺序执行的脚本片段,mkBefore和mkAfter会更有用。它们也不能解决软件包之间的文件冲突。

自定义模块与选项
#

普通配置拆成文件已经能解决很多问题,不需要每个文件都设计一套新选项。不过,如果一组设置经常一起启用,又有几个参数需要在不同电脑上调整,就可以给它做一个自己的开关。

这里沿用上一篇创建/etc文件的思路:启用后生成一个演示文件,内容由选项指定。新建modules/demo-notice.nix:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{ config, lib, ... }:
let
  cfg = config.demo.notice;
in
{
  options.demo.notice = {
    enable = lib.mkEnableOption "the demonstration notice file";

    message = lib.mkOption {
      type = lib.types.str;
      default = "Hello from NixOS";
      description = "Text written to the demonstration notice file.";
    };
  };

  config = lib.mkIf cfg.enable {
    environment.etc."nixos-module-demo".text = cfg.message + "\n";
  };
}

demo.notice是这里自己起的名字,不是NixOS内置功能。options声明了两个选项:enable是默认关闭的布尔开关,message是带默认值的字符串。cfg只是一个局部简写,省得每次都写config.demo.notice。

下面的config描述启用后要做的事情:用已有的environment.etc选项生成文件。也就是说,自定义模块把我们新声明的选项转换成了NixOS已经认识的设置。

这里用了完整的options和config结构,就要把系统设置放进config中,不能再把environment.etc混写在最外层。前面那些只有设置的简短模块,则可以省略这层config。

然后在主机模块已有的imports列表中加入../../modules/demo-notice.nix,并在主机设置中添加:

1
2
3
4
demo.notice = {
  enable = true;
  message = "Hello from this computer";
};

不要再写第二个同名的imports = ...;。同一个Nix属性集中重复定义一个属性,本身就是错误;前面说的合并,指的是不同模块提供的定义。

只导入模块但不开启时,它不会生成这个演示文件。启用后不写message,则使用Hello from NixOS。如果把message写成数字,评估这个选项时会遇到类型错误,这也是声明类型的用处。

使用mkIf控制配置
#

cfg.enable来自最终配置,而这个模块也参与生成最终配置。如果直接写成config = if cfg.enable then { ... } else { };,模块系统在判断有哪些定义时,就可能需要先知道尚未确定的配置,造成无限递归。

lib.mkIf让模块系统把条件带到具体的选项定义上,再处理这些条件。同样,不要根据config.demo.notice.enable决定是否把这个模块放入imports,应先导入模块,再用开关控制它提供的设置。mkIf不能解决循环依赖,例如让开关取决于它自己的相反值,仍然不会得到合理结果。

配置检查与问题解决
#

这些合并规则可以先通过评估观察,不必每次都运行switch。假设当前仓库已经提供laptop主机输出,先把新模块加入Git索引:

1
2
git add modules/demo-notice.nix
nix eval --raw .#nixosConfigurations.laptop.config.demo.notice.message --no-update-lock-file

按上面的设置,结果应为Hello from this computer。--raw直接输出字符串,不附加JSON引号,也不会自动补一个换行。

还可以查看将要生成的文件内容:

1
nix eval --raw '.#nixosConfigurations.laptop.config.environment.etc."nixos-module-demo".text' --no-update-lock-file

它会输出同样的文字并带一个换行。不过这只是评估配置,当前电脑的/etc/nixos-module-demo还没有因此被创建。

时区也可以这样查:

1
nix eval --raw .#nixosConfigurations.laptop.config.time.timeZone --no-update-lock-file

如果公共模块使用mkDefault "UTC",主机使用普通定义"Europe/Paris",这里应该得到Europe/Paris。

遇到意外结果时,先搜索自己的定义,再看错误信息指出的文件:

1
rg -n 'timeZone|demo\.notice|mk(Default|Force|Before|After)' . --glob '*.nix'

想查看参与最终时区合并的定义,还可以运行:

1
2
3
nix eval --json .#nixosConfigurations.laptop.options.time.timeZone.definitionsWithLocations \
  --apply 'defs: map (d: { inherit (d) file value; }) defs' \
  --no-update-lock-file

这里查询的是options里的信息,会列出定义来源和对应值。它不是所有被覆盖设置的完整历史,优先级较低而被舍弃的定义不一定出现在这里,所以还需要结合源码搜索。输出可能带本地路径,分享报错时可以先整理一下。

如果某个选项根本不存在,要检查拼写、模块是否导入,以及示例适用的Nixpkgs版本。NixOS选项搜索可以查看类型、默认值和声明位置,但网页选择的版本也要与自己的锁定输入相对应。

最后再按上一篇的流程检查并构建目标系统:

1
2
3
git diff --check
nix flake check --no-build --show-trace --no-update-lock-file
nixos-rebuild build --flake .#laptop --no-update-lock-file

单独查询一个选项,只会求值所需的部分,不能代替整个系统的检查。确认构建结果后,再决定是否应用;应用之后才用cat /etc/nixos-module-demo查看实际文件。

检查AI生成的配置时,可以根据本篇介绍的方法确认设置的位置、默认值和覆盖是否合理。下一篇将介绍软件安装与环境管理方式,包括系统配置、Home Manager、临时Shell和项目开发环境。

NixOS系列 - 这篇文章属于一个选集。
§ 6: 本文