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 = lib.mdDoc "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)). This
31 argument is mandatory for nixpkgs modules. Setting this is highly
32 recommended for the sake of documentation and type checking. In case it is
33 not set, a fallback type with unspecified behavior is used.
34
35`default`
36
37: The default value used if no value is defined by any module. A
38 default is not required; but if a default is not given, then users
39 of the module will have to define the value of the option, otherwise
40 an error will be thrown.
41
42`defaultText`
43
44: A textual representation of the default value to be rendered verbatim in
45 the manual. Useful if the default value is a complex expression or depends
46 on other values or packages.
47 Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for
48 a plain English description in [Nixpkgs-flavored Markdown](
49 https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format.
50
51`example`
52
53: An example value that will be shown in the NixOS manual.
54 You can use `lib.literalExpression` and `lib.literalMD` in the same way
55 as in `defaultText`.
56
57`description`
58
59: A textual description of the option, in [Nixpkgs-flavored Markdown](
60 https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be
61 included in the NixOS manual. During the migration process from DocBook
62 it is necessary to mark descriptions written in CommonMark with `lib.mdDoc`.
63 The description may still be written in DocBook (without any marker), but this
64 is discouraged and will be deprecated in the future.
65
66## Utility functions for common option patterns {#sec-option-declarations-util}
67
68### `mkEnableOption` {#sec-option-declarations-util-mkEnableOption}
69
70Creates an Option attribute set for a boolean value option i.e an
71option to be toggled on or off.
72
73This function takes a single string argument, the name of the thing to be toggled.
74
75The option's description is "Whether to enable \<name\>.".
76
77For example:
78
79::: {#ex-options-declarations-util-mkEnableOption-magic .example}
80```nix
81lib.mkEnableOption "magic"
82# is like
83lib.mkOption {
84 type = lib.types.bool;
85 default = false;
86 example = true;
87 description = lib.mdDoc "Whether to enable magic.";
88}
89```
90
91### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption}
92
93Usage:
94
95```nix
96mkPackageOption pkgs "name" { default = [ "path" "in" "pkgs" ]; example = "literal example"; }
97```
98
99Creates an Option attribute set for an option that specifies the package a module should use for some purpose.
100
101**Note**: You shouldn’t necessarily make package options for all of your modules. You can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).
102
103The default package is specified as a list of strings representing its attribute path in nixpkgs. Because of this, you need to pass nixpkgs itself as the first argument.
104
105The second argument is the name of the option, used in the description "The \<name\> package to use.". You can also pass an example value, either a literal string or a package's attribute path.
106
107You can omit the default path if the name of the option is also attribute path in nixpkgs.
108
109::: {#ex-options-declarations-util-mkPackageOption .title}
110Examples:
111
112::: {#ex-options-declarations-util-mkPackageOption-hello .example}
113```nix
114lib.mkPackageOption pkgs "hello" { }
115# is like
116lib.mkOption {
117 type = lib.types.package;
118 default = pkgs.hello;
119 defaultText = lib.literalExpression "pkgs.hello";
120 description = lib.mdDoc "The hello package to use.";
121}
122```
123
124::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
125```nix
126lib.mkPackageOption pkgs "GHC" {
127 default = [ "ghc" ];
128 example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
129}
130# is like
131lib.mkOption {
132 type = lib.types.package;
133 default = pkgs.ghc;
134 defaultText = lib.literalExpression "pkgs.ghc";
135 example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
136 description = lib.mdDoc "The GHC package to use.";
137}
138```
139
140## Extensible Option Types {#sec-option-declarations-eot}
141
142Extensible option types is a feature that allow to extend certain types
143declaration through multiple module files. This feature only work with a
144restricted set of types, namely `enum` and `submodules` and any composed
145forms of them.
146
147Extensible option types can be used for `enum` options that affects
148multiple modules, or as an alternative to related `enable` options.
149
150As an example, we will take the case of display managers. There is a
151central display manager module for generic display manager options and a
152module file per display manager backend (sddm, gdm \...).
153
154There are two approaches we could take with this module structure:
155
156- Configuring the display managers independently by adding an enable
157 option to every display manager module backend. (NixOS)
158
159- Configuring the display managers in the central module by adding
160 an option to select which display manager backend to use.
161
162Both approaches have problems.
163
164Making backends independent can quickly become hard to manage. For
165display managers, there can only be one enabled at a time, but the
166type system cannot enforce this restriction as there is no relation
167between each backend's `enable` option. As a result, this restriction
168has to be done explicitly by adding assertions in each display manager
169backend module.
170
171On the other hand, managing the display manager backends in the
172central module will require changing the central module option every
173time a new backend is added or removed.
174
175By using extensible option types, it is possible to create a placeholder
176option in the central module
177([Example: Extensible type placeholder in the service module](#ex-option-declaration-eot-service)),
178and to extend it in each backend module
179([Example: Extending `services.xserver.displayManager.enable` in the `gdm` module](#ex-option-declaration-eot-backend-gdm),
180[Example: Extending `services.xserver.displayManager.enable` in the `sddm` module](#ex-option-declaration-eot-backend-sddm)).
181
182As a result, `displayManager.enable` option values can be added without
183changing the main service module file and the type system automatically
184enforces that there can only be a single display manager enabled.
185
186::: {#ex-option-declaration-eot-service .example}
187::: {.title}
188**Example: Extensible type placeholder in the service module**
189:::
190```nix
191services.xserver.displayManager.enable = mkOption {
192 description = "Display manager to use";
193 type = with types; nullOr (enum [ ]);
194};
195```
196:::
197
198::: {#ex-option-declaration-eot-backend-gdm .example}
199::: {.title}
200**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module**
201:::
202```nix
203services.xserver.displayManager.enable = mkOption {
204 type = with types; nullOr (enum [ "gdm" ]);
205};
206```
207:::
208
209::: {#ex-option-declaration-eot-backend-sddm .example}
210::: {.title}
211**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module**
212:::
213```nix
214services.xserver.displayManager.enable = mkOption {
215 type = with types; nullOr (enum [ "sddm" ]);
216};
217```
218:::
219
220The placeholder declaration is a standard `mkOption` declaration, but it
221is important that extensible option declarations only use the `type`
222argument.
223
224Extensible option types work with any of the composed variants of `enum`
225such as `with types; nullOr (enum [ "foo" "bar" ])` or `with types;
226listOf (enum [ "foo" "bar" ])`.