diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md
index 18ec7ba903a9..0b965647bab7 100644
--- a/nixos/doc/manual/development/option-declarations.section.md
+++ b/nixos/doc/manual/development/option-declarations.section.md
@@ -87,6 +87,7 @@ lib.mkOption {
description = lib.mdDoc "Whether to enable magic.";
}
```
+:::
### `mkPackageOption`, `mkPackageOptionMD` {#sec-option-declarations-util-mkPackageOption}
@@ -108,7 +109,7 @@ You can omit the default path if the name of the option is also attribute path i
During 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.
-::: {#ex-options-declarations-util-mkPackageOption .title}
+[]{#ex-options-declarations-util-mkPackageOption}
Examples:
::: {#ex-options-declarations-util-mkPackageOption-hello .example}
@@ -122,6 +123,7 @@ lib.mkOption {
description = lib.mdDoc "The hello package to use.";
}
```
+:::
::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
```nix
@@ -138,6 +140,7 @@ lib.mkOption {
description = lib.mdDoc "The GHC package to use.";
}
```
+:::
## Extensible Option Types {#sec-option-declarations-eot}
diff --git a/nixos/doc/manual/from_md/development/option-declarations.section.xml b/nixos/doc/manual/from_md/development/option-declarations.section.xml
index af05e61363e4..882c35b9d88a 100644
--- a/nixos/doc/manual/from_md/development/option-declarations.section.xml
+++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml
@@ -137,57 +137,58 @@ lib.mkOption {
description = lib.mdDoc "Whether to enable magic.";
}
-
- <literal>mkPackageOption</literal>,
- <literal>mkPackageOptionMD</literal>
-
- Usage:
-
-
+
+
+ <literal>mkPackageOption</literal>,
+ <literal>mkPackageOptionMD</literal>
+
+ Usage:
+
+
mkPackageOption pkgs "name" { default = [ "path" "in" "pkgs" ]; example = "literal example"; }
-
- Creates an Option attribute set for an option that specifies
- the package a module should use for some purpose.
-
-
- 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.
-
-
- The 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.
-
-
- The 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.
-
-
- You can omit the default path if the name of the option is
- also attribute path in nixpkgs.
-
-
- During 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.
-
+
+ Creates an Option attribute set for an option that specifies the
+ package a module should use for some purpose.
+
+
+ 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.
+
+
+ The 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.
+
+
+ The 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.
+
+
+ You can omit the default path if the name of the option is also
+ attribute path in nixpkgs.
+
+
+ During 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.
+
+
-
- Examples:
-
-
-
+ Examples:
+
+
+
lib.mkPackageOptionMD pkgs "hello" { }
# is like
lib.mkOption {
@@ -197,8 +198,8 @@ lib.mkOption {
description = lib.mdDoc "The hello package to use.";
}
-
-
+
+
lib.mkPackageOptionMD pkgs "GHC" {
default = [ "ghc" ];
example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
@@ -212,134 +213,128 @@ lib.mkOption {
description = lib.mdDoc "The GHC package to use.";
}
-
- Extensible Option Types
-
- Extensible option types is a feature that allow to extend
- certain types declaration through multiple module files.
- This feature only work with a restricted set of types,
- namely enum and
- submodules and any composed forms of
- them.
-
-
- Extensible option types can be used for
- enum options that affects multiple
- modules, or as an alternative to related
- enable options.
-
-
- As an example, we will take the case of display managers.
- There is a central display manager module for generic
- display manager options and a module file per display
- manager backend (sddm, gdm …).
-
-
- There are two approaches we could take with this module
- structure:
-
-
-
-
- Configuring the display managers independently by adding
- an enable option to every display manager module
- backend. (NixOS)
-
-
-
-
- Configuring the display managers in the central module
- by adding an option to select which display manager
- backend to use.
-
-
-
-
- Both approaches have problems.
-
-
- Making backends independent can quickly become hard to
- manage. For display managers, there can only be one enabled
- at a time, but the type system cannot enforce this
- restriction as there is no relation between each backend’s
- enable option. As a result, this
- restriction has to be done explicitly by adding assertions
- in each display manager backend module.
-
-
- On the other hand, managing the display manager backends in
- the central module will require changing the central module
- option every time a new backend is added or removed.
-
-
- By using extensible option types, it is possible to create a
- placeholder option in the central module
- (Example:
- Extensible type placeholder in the service module),
- and to extend it in each backend module
- (Example:
- Extending
- services.xserver.displayManager.enable in
- the gdm module,
- Example:
- Extending
- services.xserver.displayManager.enable in
- the sddm module).
-
-
- As a result, displayManager.enable option
- values can be added without changing the main service module
- file and the type system automatically enforces that there
- can only be a single display manager enabled.
-
-
-
- Example: Extensible type placeholder
- in the service module
-
-
+
+
+
+ Extensible Option Types
+
+ Extensible option types is a feature that allow to extend certain
+ types declaration through multiple module files. This feature only
+ work with a restricted set of types, namely
+ enum and submodules and any
+ composed forms of them.
+
+
+ Extensible option types can be used for enum
+ options that affects multiple modules, or as an alternative to
+ related enable options.
+
+
+ As an example, we will take the case of display managers. There is
+ a central display manager module for generic display manager
+ options and a module file per display manager backend (sddm, gdm
+ …).
+
+
+ There are two approaches we could take with this module structure:
+
+
+
+
+ Configuring the display managers independently by adding an
+ enable option to every display manager module backend. (NixOS)
+
+
+
+
+ Configuring the display managers in the central module by
+ adding an option to select which display manager backend to
+ use.
+
+
+
+
+ Both approaches have problems.
+
+
+ Making backends independent can quickly become hard to manage. For
+ display managers, there can only be one enabled at a time, but the
+ type system cannot enforce this restriction as there is no
+ relation between each backend’s enable option.
+ As a result, this restriction has to be done explicitly by adding
+ assertions in each display manager backend module.
+
+
+ On the other hand, managing the display manager backends in the
+ central module will require changing the central module option
+ every time a new backend is added or removed.
+
+
+ By using extensible option types, it is possible to create a
+ placeholder option in the central module
+ (Example:
+ Extensible type placeholder in the service module), and to
+ extend it in each backend module
+ (Example:
+ Extending
+ services.xserver.displayManager.enable in the
+ gdm module,
+ Example:
+ Extending
+ services.xserver.displayManager.enable in the
+ sddm module).
+
+
+ As a result, displayManager.enable option
+ values can be added without changing the main service module file
+ and the type system automatically enforces that there can only be
+ a single display manager enabled.
+
+
+
+ Example: Extensible type placeholder in
+ the service module
+
+
services.xserver.displayManager.enable = mkOption {
description = "Display manager to use";
type = with types; nullOr (enum [ ]);
};
-
-
- Example: Extending
- services.xserver.displayManager.enable in
- the gdm module
-
-
+
+
+ Example: Extending
+ services.xserver.displayManager.enable in the
+ gdm module
+
+
services.xserver.displayManager.enable = mkOption {
type = with types; nullOr (enum [ "gdm" ]);
};
-
-
- Example: Extending
- services.xserver.displayManager.enable in
- the sddm module
-
-
+
+
+ Example: Extending
+ services.xserver.displayManager.enable in the
+ sddm module
+
+
services.xserver.displayManager.enable = mkOption {
type = with types; nullOr (enum [ "sddm" ]);
};
-
- The placeholder declaration is a standard
- mkOption declaration, but it is important
- that extensible option declarations only use the
- type argument.
-
-
- Extensible option types work with any of the composed
- variants of enum such as
- with types; nullOr (enum [ "foo" "bar" ])
- or
- with types; listOf (enum [ "foo" "bar" ]).
-
-
-
-
+
+ The placeholder declaration is a standard
+ mkOption declaration, but it is important that
+ extensible option declarations only use the
+ type argument.
+
+
+ Extensible option types work with any of the composed variants of
+ enum such as
+ with types; nullOr (enum [ "foo" "bar" ])
+ or
+ with types; listOf (enum [ "foo" "bar" ]).
+