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> point to a valid docbook file containing the module 
    documentation, its contents are automatically added to the <xref 
      linkend="ch-configuration"/>.
    Changes to a module documentation must be checked to be non-breaking by 
    building the NixOS manual.
  </para>
  <programlisting>$ nix-build nixos/release.nix -A manual</programlisting>
 </callout>

</calloutlist>

</section>