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
9{
10 options = {
11 name = mkOption {
12 type = type specification;
13 default = default value;
14 example = example value;
15 description = "Description for use in the NixOS manual.";
16 };
17 };
18}
19```
20
21The attribute names within the `name` attribute path must be camel
22cased in general but should, as an exception, match the [ package
23attribute name](https://nixos.org/nixpkgs/manual/#sec-package-naming)
24when referencing a Nixpkgs package. For example, the option
25`services.nix-serve.bindAddress` references the `nix-serve` Nixpkgs
26package.
27
28The function `mkOption` accepts the following arguments.
29
30`type`
31
32: The type of the option (see [](#sec-option-types)). This
33 argument is mandatory for nixpkgs modules. Setting this is highly
34 recommended for the sake of documentation and type checking. In case it is
35 not set, a fallback type with unspecified behavior is used.
36
37`default`
38
39: The default value used if no value is defined by any module. A
40 default is not required; but if a default is not given, then users
41 of the module will have to define the value of the option, otherwise
42 an error will be thrown.
43
44`defaultText`
45
46: A textual representation of the default value to be rendered verbatim in
47 the manual. Useful if the default value is a complex expression or depends
48 on other values or packages.
49 Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for
50 a plain English description in [Nixpkgs-flavored Markdown](
51 https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format.
52
53`example`
54
55: An example value that will be shown in the NixOS manual.
56 You can use `lib.literalExpression` and `lib.literalMD` in the same way
57 as in `defaultText`.
58
59`description`
60
61: A textual description of the option in [Nixpkgs-flavored Markdown](
62 https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format that will be
63 included in the NixOS manual.
64
65## Utility functions for common option patterns {#sec-option-declarations-util}
66
67### `mkEnableOption` {#sec-option-declarations-util-mkEnableOption}
68
69Creates an Option attribute set for a boolean value option i.e an
70option to be toggled on or off.
71
72This function takes a single string argument, the name of the thing to be toggled.
73
74The option's description is "Whether to enable \<name\>.".
75
76For example:
77
78::: {#ex-options-declarations-util-mkEnableOption-magic .example}
79### `mkEnableOption` usage
80```nix
81lib.mkEnableOption "magic"
82# is like
83lib.mkOption {
84 type = lib.types.bool;
85 default = false;
86 example = true;
87 description = "Whether to enable magic.";
88}
89```
90:::
91
92### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption}
93
94Usage:
95
96```nix
97mkPackageOption pkgs "name" { default = [ "path" "in" "pkgs" ]; example = "literal example"; }
98```
99
100Creates an Option attribute set for an option that specifies the package a module should use for some purpose.
101
102**Note**: You should make package options for your modules, where applicable. While one can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays), they slow down nixpkgs evaluation significantly and are harder to debug when issues arise.
103
104The package is specified in the third argument under `default` as a list of strings
105representing its attribute path in nixpkgs (or another package set).
106Because of this, you need to pass nixpkgs itself (or a subset) as the first argument.
107
108The second argument may be either a string or a list of strings.
109It provides the display name of the package in the description of the generated option
110(using only the last element if the passed value is a list)
111and serves as the fallback value for the `default` argument.
112
113To include extra information in the description, pass `extraDescription` to
114append arbitrary text to the generated description.
115You can also pass an `example` value, either a literal string or an attribute path.
116
117The default argument can be omitted if the provided name is
118an attribute of pkgs (if name is a string) or a
119valid attribute path in pkgs (if name is a list).
120
121If you wish to explicitly provide no default, pass `null` as `default`.
122
123[]{#ex-options-declarations-util-mkPackageOption}
124Examples:
125
126::: {#ex-options-declarations-util-mkPackageOption-hello .example}
127### Simple `mkPackageOption` usage
128```nix
129lib.mkPackageOption pkgs "hello" { }
130# is like
131lib.mkOption {
132 type = lib.types.package;
133 default = pkgs.hello;
134 defaultText = lib.literalExpression "pkgs.hello";
135 description = "The hello package to use.";
136}
137```
138:::
139
140::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
141### `mkPackageOption` with explicit default and example
142```nix
143lib.mkPackageOption pkgs "GHC" {
144 default = [ "ghc" ];
145 example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
146}
147# is like
148lib.mkOption {
149 type = lib.types.package;
150 default = pkgs.ghc;
151 defaultText = lib.literalExpression "pkgs.ghc";
152 example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
153 description = "The GHC package to use.";
154}
155```
156:::
157
158::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}
159### `mkPackageOption` with additional description text
160```nix
161mkPackageOption pkgs [ "python312Packages" "torch" ] {
162 extraDescription = "This is an example and doesn't actually do anything.";
163}
164# is like
165lib.mkOption {
166 type = lib.types.package;
167 default = pkgs.python312Packages.torch;
168 defaultText = lib.literalExpression "pkgs.python312Packages.torch";
169 description = "The pytorch package to use. This is an example and doesn't actually do anything.";
170}
171```
172:::
173
174## Extensible Option Types {#sec-option-declarations-eot}
175
176Extensible option types is a feature that allows to extend certain types
177declaration through multiple module files. This feature only work with a
178restricted set of types, namely `enum` and `submodules` and any composed
179forms of them.
180
181Extensible option types can be used for `enum` options that affects
182multiple modules, or as an alternative to related `enable` options.
183
184As an example, we will take the case of display managers. There is a
185central display manager module for generic display manager options and a
186module file per display manager backend (sddm, gdm ...).
187
188There are two approaches we could take with this module structure:
189
190- Configuring the display managers independently by adding an enable
191 option to every display manager module backend. (NixOS)
192
193- Configuring the display managers in the central module by adding
194 an option to select which display manager backend to use.
195
196Both approaches have problems.
197
198Making backends independent can quickly become hard to manage. For
199display managers, there can only be one enabled at a time, but the
200type system cannot enforce this restriction as there is no relation
201between each backend's `enable` option. As a result, this restriction
202has to be done explicitly by adding assertions in each display manager
203backend module.
204
205On the other hand, managing the display manager backends in the
206central module will require changing the central module option every
207time a new backend is added or removed.
208
209By using extensible option types, it is possible to create a placeholder
210option in the central module
211([Example: Extensible type placeholder in the service module](#ex-option-declaration-eot-service)),
212and to extend it in each backend module
213([Example: Extending `services.xserver.displayManager.enable` in the `gdm` module](#ex-option-declaration-eot-backend-gdm),
214[Example: Extending `services.xserver.displayManager.enable` in the `sddm` module](#ex-option-declaration-eot-backend-sddm)).
215
216As a result, `displayManager.enable` option values can be added without
217changing the main service module file and the type system automatically
218enforces that there can only be a single display manager enabled.
219
220::: {#ex-option-declaration-eot-service .example}
221### Extensible type placeholder in the service module
222```nix
223{
224 services.xserver.displayManager.enable = mkOption {
225 description = "Display manager to use";
226 type = with types; nullOr (enum [ ]);
227 };
228}
229```
230:::
231
232::: {#ex-option-declaration-eot-backend-gdm .example}
233### Extending `services.xserver.displayManager.enable` in the `gdm` module
234```nix
235{
236 services.xserver.displayManager.enable = mkOption {
237 type = with types; nullOr (enum [ "gdm" ]);
238 };
239}
240```
241:::
242
243::: {#ex-option-declaration-eot-backend-sddm .example}
244### Extending `services.xserver.displayManager.enable` in the `sddm` module
245```nix
246{
247 services.xserver.displayManager.enable = mkOption {
248 type = with types; nullOr (enum [ "sddm" ]);
249 };
250}
251```
252:::
253
254The placeholder declaration is a standard `mkOption` declaration, but it
255is important that extensible option declarations only use the `type`
256argument.
257
258Extensible option types work with any of the composed variants of `enum`
259such as `with types; nullOr (enum [ "foo" "bar" ])` or `with types;
260listOf (enum [ "foo" "bar" ])`.