pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="sec-option-declarations">
6
7<title>Option Declarations</title>
8
9<para>An option declaration specifies the name, type and description
10of a NixOS configuration option. It is invalid to define an option
11that hasn’t been declared in any module. An option declaration
12generally looks like this:
13
14<programlisting>
15options = {
16 <replaceable>name</replaceable> = mkOption {
17 type = <replaceable>type specification</replaceable>;
18 default = <replaceable>default value</replaceable>;
19 example = <replaceable>example value</replaceable>;
20 description = "<replaceable>Description for use in the NixOS manual.</replaceable>";
21 };
22};
23</programlisting>
24
25</para>
26
27<para>The function <varname>mkOption</varname> accepts the following arguments.
28
29<variablelist>
30
31 <varlistentry>
32 <term><varname>type</varname></term>
33 <listitem>
34 <para>The type of the option (see below). It may be omitted,
35 but that’s not advisable since it may lead to errors that are
36 hard to diagnose.</para>
37 </listitem>
38 </varlistentry>
39
40 <varlistentry>
41 <term><varname>default</varname></term>
42 <listitem>
43 <para>The default value used if no value is defined by any
44 module. A default is not required; in that case, if the option
45 value is never used, an error will be thrown.</para>
46 </listitem>
47 </varlistentry>
48
49 <varlistentry>
50 <term><varname>example</varname></term>
51 <listitem>
52 <para>An example value that will be shown in the NixOS manual.</para>
53 </listitem>
54 </varlistentry>
55
56 <varlistentry>
57 <term><varname>description</varname></term>
58 <listitem>
59 <para>A textual description of the option, in DocBook format,
60 that will be included in the NixOS manual.</para>
61 </listitem>
62 </varlistentry>
63
64</variablelist>
65
66</para>
67
68<para>Here is a non-exhaustive list of option types:
69
70<variablelist>
71
72 <varlistentry>
73 <term><varname>types.bool</varname></term>
74 <listitem>
75 <para>A Boolean.</para>
76 </listitem>
77 </varlistentry>
78
79 <varlistentry>
80 <term><varname>types.int</varname></term>
81 <listitem>
82 <para>An integer.</para>
83 </listitem>
84 </varlistentry>
85
86 <varlistentry>
87 <term><varname>types.str</varname></term>
88 <listitem>
89 <para>A string.</para>
90 </listitem>
91 </varlistentry>
92
93 <varlistentry>
94 <term><varname>types.lines</varname></term>
95 <listitem>
96 <para>A string. If there are multiple definitions, they are
97 concatenated, with newline characters in between.</para>
98 </listitem>
99 </varlistentry>
100
101 <varlistentry>
102 <term><varname>types.path</varname></term>
103 <listitem>
104 <para>A path, defined as anything that, when coerced to a
105 string, starts with a slash. This includes derivations.</para>
106 </listitem>
107 </varlistentry>
108
109 <varlistentry>
110 <term><varname>types.package</varname></term>
111 <listitem>
112 <para>A derivation (such as <literal>pkgs.hello</literal>) or a
113 store path (such as
114 <filename>/nix/store/1ifi1cfbfs5iajmvwgrbmrnrw3a147h9-hello-2.10</filename>).</para>
115 </listitem>
116 </varlistentry>
117
118 <varlistentry>
119 <term><varname>types.listOf</varname> <replaceable>t</replaceable></term>
120 <listitem>
121 <para>A list of elements of type <replaceable>t</replaceable>
122 (e.g., <literal>types.listOf types.str</literal> is a list of
123 strings). Multiple definitions are concatenated together.</para>
124 </listitem>
125 </varlistentry>
126
127 <varlistentry>
128 <term><varname>types.attrsOf</varname> <replaceable>t</replaceable></term>
129 <listitem>
130 <para>A set of elements of type <replaceable>t</replaceable>
131 (e.g., <literal>types.attrsOf types.int</literal> is a set of
132 name/value pairs, the values being integers).</para>
133 </listitem>
134 </varlistentry>
135
136 <varlistentry>
137 <term><varname>types.nullOr</varname> <replaceable>t</replaceable></term>
138 <listitem>
139 <para>Either the value <literal>null</literal> or something of
140 type <replaceable>t</replaceable>.</para>
141 </listitem>
142 </varlistentry>
143
144</variablelist>
145
146You can also create new types using the function
147<varname>mkOptionType</varname>. See
148<filename>lib/types.nix</filename> in Nixpkgs for details.</para>
149
150</section>