mirror of
https://github.com/NixOS/nixpkgs.git
synced 2025-06-21 08:59:20 +03:00
07cb3bf3cc
Update the pinned channel in `md-to-db`, which bumps the Pandoc version, which fixes https://github.com/NixOS/nixpkgs/issues/125511 maybe.
95 lines
3.7 KiB
XML
95 lines
3.7 KiB
XML
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-meta-attributes">
|
||
<title>Meta Attributes</title>
|
||
<para>
|
||
Like Nix packages, NixOS modules can declare meta-attributes to
|
||
provide extra information. Module meta attributes are defined in the
|
||
<literal>meta.nix</literal> special module.
|
||
</para>
|
||
<para>
|
||
<literal>meta</literal> is a top level attribute like
|
||
<literal>options</literal> and <literal>config</literal>. Available
|
||
meta-attributes are <literal>maintainers</literal>,
|
||
<literal>doc</literal>, and <literal>buildDocsInSandbox</literal>.
|
||
</para>
|
||
<para>
|
||
Each of the meta-attributes must be defined at most once per module
|
||
file.
|
||
</para>
|
||
<programlisting language="nix">
|
||
{ config, lib, pkgs, ... }:
|
||
{
|
||
options = {
|
||
...
|
||
};
|
||
|
||
config = {
|
||
...
|
||
};
|
||
|
||
meta = {
|
||
maintainers = with lib.maintainers; [ ericsagnes ];
|
||
doc = ./default.xml;
|
||
buildDocsInSandbox = true;
|
||
};
|
||
}
|
||
</programlisting>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<literal>maintainers</literal> contains a list of the module
|
||
maintainers.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>doc</literal> points to a valid DocBook file containing
|
||
the module documentation. Its contents is automatically added to
|
||
<xref linkend="ch-configuration" />. Changes to a module
|
||
documentation have to be checked to not break building the NixOS
|
||
manual:
|
||
</para>
|
||
<programlisting>
|
||
$ nix-build nixos/release.nix -A manual.x86_64-linux
|
||
</programlisting>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<literal>buildDocsInSandbox</literal> 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
|
||
<literal>NIXOS_EXTRA_MODULE_PATH</literal> are always built
|
||
outside of the sandbox, as has been the case in previous
|
||
releases.
|
||
</para>
|
||
<para>
|
||
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 <literal>options</literal> and
|
||
<literal>lib</literal> module arguments and the
|
||
<literal>pkgs.formats</literal> attribute of the
|
||
<literal>pkgs</literal> argument, <literal>config</literal> and
|
||
the rest of <literal>pkgs</literal> 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 <literal>options</literal>
|
||
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.
|
||
</para>
|
||
<para>
|
||
The default is <literal>true</literal> and should usually not be
|
||
changed; set it to <literal>false</literal> only if the module
|
||
requires access to <literal>pkgs</literal> 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).
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|