NixOS RFC42-style module as library [nix-0001]

不知道叫做 RFC42-style module 这个名字合适不合适，因为 RFC42 实际上并不是定义 module 的。但是既然 flake.parts 这么叫了，那就继续沿用了。

1. NixOS RFC42-style module [nix-0002]

RFC42 提出了两个稳定的部分。

  1. Structural settings instead of stringly extraConfig

    NixOS RFC42 structural settings [nix-0003]

    简单概括，就是将原本 module config 中硬编码的程序配置，改为使用结构化的 nix 数据，使其对应程序 config。

    例如 wakapi 使用 yaml 来作为配置文件，在 RFC42 之前，一个做法是写 str type 的 option 为 services.wakapi.extraConfig，直接将 yaml 内容写入此处，传递给 wakapi。 

    options.services.wakapi.extraConfig = lib.mkOption {
    type = lib.types.str;
    description = lib.mdDoc ''
      The wakapi config content.
    '';
  };
    这么做显然有很多缺点，比如语法无法检查、选项合并困难等。

    在 RFC42 之后，不再推荐这种写法，而是提供了一种统一的结构化（structural）的 settings option。还是 wakapi： 

    let
    format = pkgs.formats.yaml { };
  in
    options.services.wakapi.settings = lib.mkOption {
      type = lib.types.submodule {
        freeformType = format.type;
        options = { };
        default = { };
        description = lib.mdDoc ''
          The wakapi config settings.
        '';
      };
    };
    这里的重点在于 freeformType = format.type;，它允许 config 中写下 option 中未直接定义的选项。这些任意写下的选项，最后都可以通过 format.generate 以设定的文件格式写入。 
    confFile = format.generate "wakapi.yaml" cfg.settings
    另外，options = { }; 中仍然可以写明确的 option，如果这么写的话，选项可以被类型检查和生成文档。

  2. Balancing module option count

    NixOS RFC42 balancing module option count [nix-0004]

    只是推荐 module 编写者平衡 option 的数量。适当地写 option，帮助生成合适数量的文档选项，但是不用把所有的选项都写出来，使后续维护困难。

另外，尽管 NixOS module 没有明确的 RFC 或 spec，但在 RFC42 中隐含地使用了 module 的部分结构。可以相信这部分的 module 结构是稳定，不轻易改变的。

NixOS RFC42-style module options x config [nix-0005]

一个典型的 RFC42 module 一般由 options 和 config 组成。 

options = {};
  config = {};
TODO

在 ❄️ Nix 程序的组织中，经常需要，但是并没有默认提供定义方式的是 library 的写法。即有一系列常用或相关的函数，想要在程序的全局中方便地调用。

最直觉想到的解决方式是一个 mylib.nix，其接收一些必要的参数，返回一个含所有函数的 attrset。 

{ lib, inputs, nixpkgs }:
  {
    mkSystem = nixpkgs.lib.nixosSystem { ... };

    mkEmptyFreeformOption = description: lib.mkOption {
      type = lib.types.submodule {
        freeformType = format.type;
      };
      default = { };
      inherit description;
    };
  }
社区中的例子🌰：
  1. Ryan4yin 的 NixOS config
  2. Mitchell Hashimoto 的 NixOS config

另外一个方式是从 srid 在 flake-parts 中提的 issue 中学到的，利用 module 实现的全局共享函数。借助 module 的自动合并和自动应用，可以比较优雅地共享 library。不过不确定的一点是，这么做是否构成了对 options 的滥用，或者说违反了 options 的语义。

尽管该 issue 还处于 open 状态，flake-parts 对于这个问题还没有共识。但在自己的配置中这么做还是没有问题。

2. Use NixOS RFC42-style module options to expose function [nix-0007]

origin: https://github.com/hercules-ci/flake-parts/issues/51

通过 options 和 options 的 default 值来导出和共享一个全局的 function。 

{ self, ... }:
  {
    options = {
      mkCheck = lib.mkOption {
        type = lib.types.functionTo lib.types.unspecified;
        default = { package, ... }:
        abort "TODO: return a derivation that runs the tests for $package";
      };
    };
  }
这是一个 RFC42-style 的 module，options 会被自动合并，并赋予一个默认值。

因此，在其他 RFC42-style module 中，可以通过 config 来访问该函数。 

{ self, ... }: {
    perSystem = { config, ... }: {
      checks.foo = config.mkCheck { ... };
    };
  }