nixpkgs-suyu/nixos/doc/manual/development/option-declarations.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-option-declarations">

<title>Option Declarations</title>

<para>An option declaration specifies the name, type and description
of a NixOS configuration option.  It is invalid to define an option
that hasn’t been declared in any module.  An option declaration
generally looks like this:

<programlisting>
options = {
  <replaceable>name</replaceable> = mkOption {
    type = <replaceable>type specification</replaceable>;
    default = <replaceable>default value</replaceable>;
    example = <replaceable>example value</replaceable>;
    description = "<replaceable>Description for use in the NixOS manual.</replaceable>";
  };
};
</programlisting>

</para>

<para>The function <varname>mkOption</varname> accepts the following arguments.

<variablelist>

  <varlistentry>
    <term><varname>type</varname></term>
    <listitem>
      <para>The type of the option (see below).  It may be omitted,
      but that’s not advisable since it may lead to errors that are
      hard to diagnose.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>default</varname></term>
    <listitem>
      <para>The default value used if no value is defined by any
      module.  A default is not required; in that case, if the option
      value is never used, an error will be thrown.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>example</varname></term>
    <listitem>
      <para>An example value that will be shown in the NixOS manual.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>description</varname></term>
    <listitem>
      <para>A textual description of the option, in DocBook format,
      that will be included in the NixOS manual.</para>
    </listitem>
  </varlistentry>

</variablelist>

</para>

<para>Here is a non-exhaustive list of option types:

<variablelist>

  <varlistentry>
    <term><varname>types.bool</varname></term>
    <listitem>
      <para>A Boolean.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.int</varname></term>
    <listitem>
      <para>An integer.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.str</varname></term>
    <listitem>
      <para>A string.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.lines</varname></term>
    <listitem>
      <para>A string.  If there are multiple definitions, they are
      concatenated, with newline characters in between.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.path</varname></term>
    <listitem>
      <para>A path, defined as anything that, when coerced to a
      string, starts with a slash.  This includes derivations.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.package</varname></term>
    <listitem>
      <para>A derivation (such as <literal>pkgs.hello</literal>) or a
      store path (such as
      <filename>/nix/store/1ifi1cfbfs5iajmvwgrbmrnrw3a147h9-hello-2.10</filename>).</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.listOf</varname> <replaceable>t</replaceable></term>
    <listitem>
      <para>A list of elements of type <replaceable>t</replaceable>
      (e.g., <literal>types.listOf types.str</literal> is a list of
      strings).  Multiple definitions are concatenated together.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.attrsOf</varname> <replaceable>t</replaceable></term>
    <listitem>
      <para>A set of elements of type <replaceable>t</replaceable>
      (e.g., <literal>types.attrsOf types.int</literal> is a set of
      name/value pairs, the values being integers).</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><varname>types.nullOr</varname> <replaceable>t</replaceable></term>
    <listitem>
      <para>Either the value <literal>null</literal> or something of
      type <replaceable>t</replaceable>.</para>
    </listitem>
  </varlistentry>

</variablelist>

You can also create new types using the function
<varname>mkOptionType</varname>.  See
<filename>lib/types.nix</filename> in Nixpkgs for details.</para>

</section>