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
83 lib.mkOption
84 {
85 type = lib.types.bool;
86 default = false;
87 example = true;
88 description = "Whether to enable magic.";
89 }
90```
91:::
92
93### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption}
94
95Usage:
96
97```nix
98mkPackageOption pkgs "name" {
99 default = [
100 "path"
101 "in"
102 "pkgs"
103 ];
104 example = "literal example";
105}
106```
107
108Creates an Option attribute set for an option that specifies the package a module should use for some purpose.
109
110**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.
111
112The package is specified in the third argument under `default` as a list of strings
113representing its attribute path in nixpkgs (or another package set).
114Because of this, you need to pass nixpkgs itself (or a subset) as the first argument.
115
116The second argument may be either a string or a list of strings.
117It provides the display name of the package in the description of the generated option
118(using only the last element if the passed value is a list)
119and serves as the fallback value for the `default` argument.
120
121To include extra information in the description, pass `extraDescription` to
122append arbitrary text to the generated description.
123You can also pass an `example` value, either a literal string or an attribute path.
124
125The default argument can be omitted if the provided name is
126an attribute of pkgs (if name is a string) or a
127valid attribute path in pkgs (if name is a list).
128
129If you wish to explicitly provide no default, pass `null` as `default`.
130
131[]{#ex-options-declarations-util-mkPackageOption}
132Examples:
133
134::: {#ex-options-declarations-util-mkPackageOption-hello .example}
135### Simple `mkPackageOption` usage
136```nix
137lib.mkPackageOption pkgs "hello" { }
138 # is like
139 lib.mkOption
140 {
141 type = lib.types.package;
142 default = pkgs.hello;
143 defaultText = lib.literalExpression "pkgs.hello";
144 description = "The hello package to use.";
145 }
146```
147:::
148
149::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
150### `mkPackageOption` with explicit default and example
151```nix
152lib.mkPackageOption pkgs "GHC"
153 {
154 default = [ "ghc" ];
155 example = "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])";
156 }
157 # is like
158 lib.mkOption
159 {
160 type = lib.types.package;
161 default = pkgs.ghc;
162 defaultText = lib.literalExpression "pkgs.ghc";
163 example = lib.literalExpression "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])";
164 description = "The GHC package to use.";
165 }
166```
167:::
168
169::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}
170### `mkPackageOption` with additional description text
171```nix
172mkPackageOption pkgs [ "python312Packages" "torch" ]
173 {
174 extraDescription = "This is an example and doesn't actually do anything.";
175 }
176 # is like
177 lib.mkOption
178 {
179 type = lib.types.package;
180 default = pkgs.python312Packages.torch;
181 defaultText = lib.literalExpression "pkgs.python312Packages.torch";
182 description = "The pytorch package to use. This is an example and doesn't actually do anything.";
183 }
184```
185:::
186
187## Extensible Option Types {#sec-option-declarations-eot}
188
189Extensible option types is a feature that allows to extend certain types
190declaration through multiple module files. This feature only work with a
191restricted set of types, namely `enum` and `submodules` and any composed
192forms of them.
193
194Extensible option types can be used for `enum` options that affects
195multiple modules, or as an alternative to related `enable` options.
196
197As an example, we will take the case of display managers. There is a
198central display manager module for generic display manager options and a
199module file per display manager backend (sddm, gdm ...).
200
201There are two approaches we could take with this module structure:
202
203- Configuring the display managers independently by adding an enable
204 option to every display manager module backend. (NixOS)
205
206- Configuring the display managers in the central module by adding
207 an option to select which display manager backend to use.
208
209Both approaches have problems.
210
211Making backends independent can quickly become hard to manage. For
212display managers, there can only be one enabled at a time, but the
213type system cannot enforce this restriction as there is no relation
214between each backend's `enable` option. As a result, this restriction
215has to be done explicitly by adding assertions in each display manager
216backend module.
217
218On the other hand, managing the display manager backends in the
219central module will require changing the central module option every
220time a new backend is added or removed.
221
222By using extensible option types, it is possible to create a placeholder
223option in the central module
224([Example: Extensible type placeholder in the service module](#ex-option-declaration-eot-service)),
225and to extend it in each backend module
226([Example: Extending `services.xserver.displayManager.enable` in the `gdm` module](#ex-option-declaration-eot-backend-gdm),
227[Example: Extending `services.xserver.displayManager.enable` in the `sddm` module](#ex-option-declaration-eot-backend-sddm)).
228
229As a result, `displayManager.enable` option values can be added without
230changing the main service module file and the type system automatically
231enforces that there can only be a single display manager enabled.
232
233::: {#ex-option-declaration-eot-service .example}
234### Extensible type placeholder in the service module
235```nix
236{
237 services.xserver.displayManager.enable = mkOption {
238 description = "Display manager to use";
239 type = with types; nullOr (enum [ ]);
240 };
241}
242```
243:::
244
245::: {#ex-option-declaration-eot-backend-gdm .example}
246### Extending `services.xserver.displayManager.enable` in the `gdm` module
247```nix
248{
249 services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "gdm" ]); };
250}
251```
252:::
253
254::: {#ex-option-declaration-eot-backend-sddm .example}
255### Extending `services.xserver.displayManager.enable` in the `sddm` module
256```nix
257{
258 services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "sddm" ]); };
259}
260```
261:::
262
263The placeholder declaration is a standard `mkOption` declaration, but it
264is important that extensible option declarations only use the `type`
265argument.
266
267Extensible option types work with any of the composed variants of `enum`
268such as `with types; nullOr (enum [ "foo" "bar" ])` or `with types;
269listOf (enum [ "foo" "bar" ])`.