forked from mirrors/nixpkgs
f3d94cfc23
This reverts commit cad8957eab. It
breaks NixOps, but more importantly, such major changes to the module
system really need to be reviewed.
151 lines
4.3 KiB
XML
151 lines
4.3 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.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>
|