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