git-subtree-dir: third_party/nixpkgs git-subtree-split: 76612b17c0ce71689921ca12d9ffdc9c23ce40b2
2.7 KiB
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.md;
buildDocsInSandbox = true;
};
}
-
maintainers
contains a list of the module maintainers. -
doc
points to a valid Nixpkgs-flavored CommonMark 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 fromNIXOS_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
andlib
module arguments and thepkgs.formats
attribute of thepkgs
argument,config
and the rest ofpkgs
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. Theoptions
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 tofalse
only if the module requires access topkgs
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).