pyrox.dev
1# Option Declarations {#sec-option-declarations}
2
3An option declaration specifies the name, type and description of a
4NixOS configuration option. It is invalid to define an option that
5hasn't been declared in any module. An option declaration generally
6looks like this:
7
8```nix
9options = {
10 name = mkOption {
11 type = type specification;
12 default = default value;
13 example = example value;
14 description = "Description for use in the NixOS manual.";
15 };
16};
17```
18
19The attribute names within the `name` attribute path must be camel
20cased in general but should, as an exception, match the [ package
21attribute name](https://nixos.org/nixpkgs/manual/#sec-package-naming)
22when referencing a Nixpkgs package. For example, the option
23`services.nix-serve.bindAddress` references the `nix-serve` Nixpkgs
24package.
25
26The function `mkOption` accepts the following arguments.
27
28`type`
29
30: The type of the option (see [](#sec-option-types)). It may be
31 omitted, but that's not advisable since it may lead to errors that
32 are hard to diagnose.
33
34`default`
35
36: The default value used if no value is defined by any module. A
37 default is not required; but if a default is not given, then users
38 of the module will have to define the value of the option, otherwise
39 an error will be thrown.
40
41`defaultText`
42
43: A textual representation of the default value to be rendered verbatim in
44 the manual. Useful if the default value is a complex expression or depends
45 on other values or packages.
46 Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for
47 a plain English description in DocBook format.
48
49`example`
50
51: An example value that will be shown in the NixOS manual.
52 You can use `lib.literalExpression` and `lib.literalDocBook` in the same way
53 as in `defaultText`.
54
55`description`
56
57: A textual description of the option, in DocBook format, that will be
58 included in the NixOS manual.
59
60## Extensible Option Types {#sec-option-declarations-eot}
61
62Extensible option types is a feature that allow to extend certain types
63declaration through multiple module files. This feature only work with a
64restricted set of types, namely `enum` and `submodules` and any composed
65forms of them.
66
67Extensible option types can be used for `enum` options that affects
68multiple modules, or as an alternative to related `enable` options.
69
70As an example, we will take the case of display managers. There is a
71central display manager module for generic display manager options and a
72module file per display manager backend (sddm, gdm \...).
73
74There are two approach to this module structure:
75
76- Managing the display managers independently by adding an enable
77 option to every display manager module backend. (NixOS)
78
79- Managing the display managers in the central module by adding an
80 option to select which display manager backend to use.
81
82Both approaches have problems.
83
84Making backends independent can quickly become hard to manage. For
85display managers, there can be only one enabled at a time, but the type
86system can not enforce this restriction as there is no relation between
87each backend `enable` option. As a result, this restriction has to be
88done explicitely by adding assertions in each display manager backend
89module.
90
91On the other hand, managing the display managers backends in the central
92module will require to change the central module option every time a new
93backend is added or removed.
94
95By using extensible option types, it is possible to create a placeholder
96option in the central module
97([Example: Extensible type placeholder in the service module](#ex-option-declaration-eot-service)),
98and to extend it in each backend module
99([Example: Extending `services.xserver.displayManager.enable` in the `gdm` module](#ex-option-declaration-eot-backend-gdm),
100[Example: Extending `services.xserver.displayManager.enable` in the `sddm` module](#ex-option-declaration-eot-backend-sddm)).
101
102As a result, `displayManager.enable` option values can be added without
103changing the main service module file and the type system automatically
104enforce that there can only be a single display manager enabled.
105
106::: {#ex-option-declaration-eot-service .example}
107::: {.title}
108**Example: Extensible type placeholder in the service module**
109:::
110```nix
111services.xserver.displayManager.enable = mkOption {
112 description = "Display manager to use";
113 type = with types; nullOr (enum [ ]);
114};
115```
116:::
117
118::: {#ex-option-declaration-eot-backend-gdm .example}
119::: {.title}
120**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module**
121:::
122```nix
123services.xserver.displayManager.enable = mkOption {
124 type = with types; nullOr (enum [ "gdm" ]);
125};
126```
127:::
128
129::: {#ex-option-declaration-eot-backend-sddm .example}
130::: {.title}
131**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module**
132:::
133```nix
134services.xserver.displayManager.enable = mkOption {
135 type = with types; nullOr (enum [ "sddm" ]);
136};
137```
138:::
139
140The placeholder declaration is a standard `mkOption` declaration, but it
141is important that extensible option declarations only use the `type`
142argument.
143
144Extensible option types work with any of the composed variants of `enum`
145such as `with types; nullOr (enum [ "foo" "bar" ])` or `with types;
146listOf (enum [ "foo" "bar" ])`.