path: root/nixos/doc/manual/development/meta-attributes.xml

<section xmlns="http://docbook.org/ns/docbook"
        xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:xi="http://www.w3.org/2001/XInclude"
        version="5.0"
        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
  <filename
    xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/misc/meta.nix">meta.nix</filename>
  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> and
  <literal>doc</literal>.
 </para>

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

<programlisting>
{ config, lib, pkgs, ... }:
{
  options = {
    ...
  };

  config = {
    ...
  };

  meta = {
    maintainers = with lib.maintainers; [ ericsagnes ]; <co
      xml:id='modules-meta-1' />
    doc = ./default.xml; <co xml:id='modules-meta-2' />
  };
}
</programlisting>

 <calloutlist>
  <callout arearefs='modules-meta-1'>
   <para>
    <varname>maintainers</varname> contains a list of the module maintainers.
   </para>
  </callout>
  <callout arearefs='modules-meta-2'>
   <para>
    <varname>doc</varname> 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>
<screen><prompt>$ </prompt>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
  </callout>
 </calloutlist>
</section>