pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-meta-attributes">
2 <title>Meta Attributes</title>
3 <para>
4 Like Nix packages, NixOS modules can declare meta-attributes to
5 provide extra information. Module meta attributes are defined in the
6 <literal>meta.nix</literal> special module.
7 </para>
8 <para>
9 <literal>meta</literal> is a top level attribute like
10 <literal>options</literal> and <literal>config</literal>. Available
11 meta-attributes are <literal>maintainers</literal>,
12 <literal>doc</literal>, and <literal>buildDocsInSandbox</literal>.
13 </para>
14 <para>
15 Each of the meta-attributes must be defined at most once per module
16 file.
17 </para>
18 <programlisting language="bash">
19{ config, lib, pkgs, ... }:
20{
21 options = {
22 ...
23 };
24
25 config = {
26 ...
27 };
28
29 meta = {
30 maintainers = with lib.maintainers; [ ericsagnes ];
31 doc = ./default.xml;
32 buildDocsInSandbox = true;
33 };
34}
35</programlisting>
36 <itemizedlist>
37 <listitem>
38 <para>
39 <literal>maintainers</literal> contains a list of the module
40 maintainers.
41 </para>
42 </listitem>
43 <listitem>
44 <para>
45 <literal>doc</literal> points to a valid DocBook file containing
46 the module documentation. Its contents is automatically added to
47 <xref linkend="ch-configuration" />. Changes to a module
48 documentation have to be checked to not break building the NixOS
49 manual:
50 </para>
51 <programlisting>
52$ nix-build nixos/release.nix -A manual.x86_64-linux
53</programlisting>
54 </listitem>
55 <listitem>
56 <para>
57 <literal>buildDocsInSandbox</literal> indicates whether the
58 option documentation for the module can be built in a derivation
59 sandbox. This option is currently only honored for modules
60 shipped by nixpkgs. User modules and modules taken from
61 <literal>NIXOS_EXTRA_MODULE_PATH</literal> are always built
62 outside of the sandbox, as has been the case in previous
63 releases.
64 </para>
65 <para>
66 Building NixOS option documentation in a sandbox allows caching
67 of the built documentation, which greatly decreases the amount
68 of time needed to evaluate a system configuration that has NixOS
69 documentation enabled. The sandbox also restricts which
70 attributes may be referenced by documentation attributes (such
71 as option descriptions) to the <literal>options</literal> and
72 <literal>lib</literal> module arguments and the
73 <literal>pkgs.formats</literal> attribute of the
74 <literal>pkgs</literal> argument, <literal>config</literal> and
75 the rest of <literal>pkgs</literal> are disallowed and will
76 cause doc build failures when used. This restriction is
77 necessary because we cannot reproduce the full nixpkgs
78 instantiation with configuration and overlays from a system
79 configuration inside the sandbox. The <literal>options</literal>
80 argument only includes options of modules that are also built
81 inside the sandbox, referencing an option of a module that isn’t
82 built in the sandbox is also forbidden.
83 </para>
84 <para>
85 The default is <literal>true</literal> and should usually not be
86 changed; set it to <literal>false</literal> only if the module
87 requires access to <literal>pkgs</literal> in its documentation
88 (e.g. because it loads information from a linked package to
89 build an option type) or if its documentation depends on other
90 modules that also aren’t sandboxed (e.g. by using types defined
91 in the other module).
92 </para>
93 </listitem>
94 </itemizedlist>
95</section>