141 lines
4 KiB
XML
141 lines
4 KiB
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 illegal to define an option
|
|||
|
|
that hasn’t been declared in any module. A 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 ever 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.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>
|