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`, `mkPackageOptionMD` {#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
124During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed.
125
126[]{#ex-options-declarations-util-mkPackageOption}
127Examples:
128
129::: {#ex-options-declarations-util-mkPackageOption-hello .example}
130### Simple `mkPackageOption` usage
131```nix
132lib.mkPackageOptionMD pkgs "hello" { }
133# is like
134lib.mkOption {
135 type = lib.types.package;
136 default = pkgs.hello;
137 defaultText = lib.literalExpression "pkgs.hello";
138 description = lib.mdDoc "The hello package to use.";
139}
140```
141:::
142
143::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
144### `mkPackageOption` with explicit default and example
145```nix
146lib.mkPackageOptionMD pkgs "GHC" {
147 default = [ "ghc" ];
148 example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
149}
150# is like
151lib.mkOption {
152 type = lib.types.package;
153 default = pkgs.ghc;
154 defaultText = lib.literalExpression "pkgs.ghc";
155 example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
156 description = lib.mdDoc "The GHC package to use.";
157}
158```
159:::
160
161::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}
162### `mkPackageOption` with additional description text
163```nix
164mkPackageOption pkgs [ "python39Packages" "pytorch" ] {
165 extraDescription = "This is an example and doesn't actually do anything.";
166}
167# is like
168lib.mkOption {
169 type = lib.types.package;
170 default = pkgs.python39Packages.pytorch;
171 defaultText = lib.literalExpression "pkgs.python39Packages.pytorch";
172 description = "The pytorch package to use. This is an example and doesn't actually do anything.";
173}
174```
175:::
176
177## Extensible Option Types {#sec-option-declarations-eot}
178
179Extensible option types is a feature that allow to extend certain types
180declaration through multiple module files. This feature only work with a
181restricted set of types, namely `enum` and `submodules` and any composed
182forms of them.
183
184Extensible option types can be used for `enum` options that affects
185multiple modules, or as an alternative to related `enable` options.
186
187As an example, we will take the case of display managers. There is a
188central display manager module for generic display manager options and a
189module file per display manager backend (sddm, gdm ...).
190
191There are two approaches we could take with this module structure:
192
193- Configuring the display managers independently by adding an enable
194 option to every display manager module backend. (NixOS)
195
196- Configuring the display managers in the central module by adding
197 an option to select which display manager backend to use.
198
199Both approaches have problems.
200
201Making backends independent can quickly become hard to manage. For
202display managers, there can only be one enabled at a time, but the
203type system cannot enforce this restriction as there is no relation
204between each backend's `enable` option. As a result, this restriction
205has to be done explicitly by adding assertions in each display manager
206backend module.
207
208On the other hand, managing the display manager backends in the
209central module will require changing the central module option every
210time a new backend is added or removed.
211
212By using extensible option types, it is possible to create a placeholder
213option in the central module
214([Example: Extensible type placeholder in the service module](#ex-option-declaration-eot-service)),
215and to extend it in each backend module
216([Example: Extending `services.xserver.displayManager.enable` in the `gdm` module](#ex-option-declaration-eot-backend-gdm),
217[Example: Extending `services.xserver.displayManager.enable` in the `sddm` module](#ex-option-declaration-eot-backend-sddm)).
218
219As a result, `displayManager.enable` option values can be added without
220changing the main service module file and the type system automatically
221enforces that there can only be a single display manager enabled.
222
223::: {#ex-option-declaration-eot-service .example}
224### Extensible type placeholder in the service module
225```nix
226services.xserver.displayManager.enable = mkOption {
227 description = "Display manager to use";
228 type = with types; nullOr (enum [ ]);
229};
230```
231:::
232
233::: {#ex-option-declaration-eot-backend-gdm .example}
234### Extending `services.xserver.displayManager.enable` in the `gdm` module
235```nix
236services.xserver.displayManager.enable = mkOption {
237 type = with types; nullOr (enum [ "gdm" ]);
238};
239```
240:::
241
242::: {#ex-option-declaration-eot-backend-sddm .example}
243### Extending `services.xserver.displayManager.enable` in the `sddm` module
244```nix
245services.xserver.displayManager.enable = mkOption {
246 type = with types; nullOr (enum [ "sddm" ]);
247};
248```
249:::
250
251The placeholder declaration is a standard `mkOption` declaration, but it
252is important that extensible option declarations only use the `type`
253argument.
254
255Extensible option types work with any of the composed variants of `enum`
256such as `with types; nullOr (enum [ "foo" "bar" ])` or `with types;
257listOf (enum [ "foo" "bar" ])`.