pennae fc614c37c6 nixos/documentation: split options doc build

most modules can be evaluated for their documentation in a very
restricted environment that doesn't include all of nixpkgs. this
evaluation can then be cached and reused for subsequent builds, merging
only documentation that has changed into the cached set. since nixos
ships with a large number of modules of which only a few are used in any
given config this can save evaluation a huge percentage of nixos
options available in any given config.

in tests of this caching, despite having to copy most of nixos/, saves
about 80% of the time needed to build the system manual, or about two
second on the machine used for testing. build time for a full system
config shrank from 9.4s to 7.4s, while turning documentation off
entirely shortened the build to 7.1s.

2022-01-02 19:46:13 +01:00

2.6 KiB

Raw Blame History

Meta Attributes

Like Nix packages, NixOS modules can declare meta-attributes to provide extra information. Module meta attributes are defined in the meta.nix special module.

meta is a top level attribute like options and config. Available meta-attributes are maintainers, doc, and buildDocsInSandbox.

Each of the meta-attributes must be defined at most once per module file.

{ config, lib, pkgs, ... }:
{
  options = {
    ...
  };

  config = {
    ...
  };

  meta = {
    maintainers = with lib.maintainers; [ ericsagnes ];
    doc = ./default.xml;
    buildDocsInSandbox = true;
  };
}

maintainers contains a list of the module maintainers.
doc points to a valid DocBook file containing the module documentation. Its contents is automatically added to . Changes to a module documentation have to be checked to not break building the NixOS manual:
```
$ nix-build nixos/release.nix -A manual.x86_64-linux
```
buildDocsInSandbox indicates whether the option documentation for the module can be built in a derivation sandbox. This option is currently only honored for modules shipped by nixpkgs. User modules and modules taken from NIXOS_EXTRA_MODULE_PATH are always built outside of the sandbox, as has been the case in previous releases.

Building NixOS option documentation in a sandbox allows caching of the built documentation, which greatly decreases the amount of time needed to evaluate a system configuration that has NixOS documentation enabled. The sandbox also restricts which attributes may be referenced by documentation attributes (such as option descriptions) to the options and lib module arguments and the pkgs.formats attribute of the pkgs argument, config and the rest of pkgs are disallowed and will cause doc build failures when used. This restriction is necessary because we cannot reproduce the full nixpkgs instantiation with configuration and overlays from a system configuration inside the sandbox. The options argument only includes options of modules that are also built inside the sandbox, referencing an option of a module that isn't built in the sandbox is also forbidden.

The default is true and should usually not be changed; set it to false only if the module requires access to pkgs in its documentation (e.g. because it loads information from a linked package to build an option type) or if its documentation depends on other modules that also aren't sandboxed (e.g. by using types defined in the other module).

2.6 KiB Raw Blame History

Meta Attributes

2.6 KiB

Raw Blame History