From 6877012179ebfbbf47451d2bc8d61212981c7940 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 22:14:03 +0800 Subject: nixos: nixos/doc/manual/development/option-declarations.xml to CommonMark --- .../development/option-declarations.section.md | 136 ++++++++++++++ .../doc/manual/development/option-declarations.xml | 199 -------------------- nixos/doc/manual/development/writing-modules.xml | 2 +- .../development/option-declarations.section.xml | 203 +++++++++++++++++++++ 4 files changed, 340 insertions(+), 200 deletions(-) create mode 100644 nixos/doc/manual/development/option-declarations.section.md delete mode 100644 nixos/doc/manual/development/option-declarations.xml create mode 100644 nixos/doc/manual/from_md/development/option-declarations.section.xml diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md new file mode 100644 index 00000000000..819c23684cd --- /dev/null +++ b/nixos/doc/manual/development/option-declarations.section.md @@ -0,0 +1,136 @@ +# Option Declarations {#sec-option-declarations} + +An option declaration specifies the name, type and description of a +NixOS configuration option. It is invalid to define an option that +hasn't been declared in any module. An option declaration generally +looks like this: + +```nix +options = { + name = mkOption { + type = type specification; + default = default value; + example = example value; + description = "Description for use in the NixOS manual."; + }; +}; +``` + +The attribute names within the `name` attribute path must be camel +cased in general but should, as an exception, match the [ package +attribute name](https://nixos.org/nixpkgs/manual/#sec-package-naming) +when referencing a Nixpkgs package. For example, the option +`services.nix-serve.bindAddress` references the `nix-serve` Nixpkgs +package. + +The function `mkOption` accepts the following arguments. + +`type` + +: The type of the option (see [](#sec-option-types)). It may be + omitted, but that's not advisable since it may lead to errors that + are hard to diagnose. + +`default` + +: The default value used if no value is defined by any module. A + default is not required; but if a default is not given, then users + of the module will have to define the value of the option, otherwise + an error will be thrown. + +`example` + +: An example value that will be shown in the NixOS manual. + +`description` + +: A textual description of the option, in DocBook format, that will be + included in the NixOS manual. + +## Extensible Option Types {#sec-option-declarations-eot} + +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 approach to this module structure: + +- Managing the display managers independently by adding an enable + option to every display manager module backend. (NixOS) + +- Managing 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 be only one enabled at a time, but the type +system can not enforce this restriction as there is no relation between +each backend `enable` option. As a result, this restriction has to be +done explicitely by adding assertions in each display manager backend +module. + +On the other hand, managing the display managers backends in the central +module will require to change 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](#ex-option-declaration-eot-service)), +and to extend it in each backend module +([Example: Extending `services.xserver.displayManager.enable` in the `gdm` module](#ex-option-declaration-eot-backend-gdm), +[Example: Extending `services.xserver.displayManager.enable` in the `sddm` module](#ex-option-declaration-eot-backend-sddm)). + +As a result, `displayManager.enable` option values can be added without +changing the main service module file and the type system automatically +enforce that there can only be a single display manager enabled. + +::: {#ex-option-declaration-eot-service .example} +::: {.title} +**Example: Extensible type placeholder in the service module** +::: +```nix +services.xserver.displayManager.enable = mkOption { + description = "Display manager to use"; + type = with types; nullOr (enum [ ]); +}; +``` +::: + +::: {#ex-option-declaration-eot-backend-gdm .example} +::: {.title} +**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module** +::: +```nix +services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "gdm" ]); +}; +``` +::: + +::: {#ex-option-declaration-eot-backend-sddm .example} +::: {.title} +**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module** +::: +```nix +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" ])`. diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml deleted file mode 100644 index 56ebf481630..00000000000 --- a/nixos/doc/manual/development/option-declarations.xml +++ /dev/null @@ -1,199 +0,0 @@ -
- Option Declarations - - - An option declaration specifies the name, type and description of a NixOS - configuration option. It is invalid to define an option that hasn’t been - declared in any module. An option declaration generally looks like this: - -options = { - name = mkOption { - type = type specification; - default = default value; - example = example value; - description = "Description for use in the NixOS manual."; - }; -}; - - The attribute names within the name attribute path - must be camel cased in general but should, as an exception, match the - - package attribute name when referencing a Nixpkgs package. For - example, the option services.nix-serve.bindAddress - references the nix-serve Nixpkgs package. - - - - The function mkOption accepts the following arguments. - - - - type - - - - The type of the option (see ). It may - be omitted, but that’s not advisable since it may lead to errors that - are hard to diagnose. - - - - - - default - - - - The default value used if no value is defined by any module. A default is - not required; but if a default is not given, then users of the module - will have to define the value of the option, otherwise an error will be - thrown. - - - - - - example - - - - An example value that will be shown in the NixOS manual. - - - - - - description - - - - A textual description of the option, in DocBook format, that will be - included in the NixOS manual. - - - - - - -
- 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 approach to this module structure: - - - - Managing the display managers independently by adding an enable option to - every display manager module backend. (NixOS) - - - - - Managing 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 be only one enabled at a time, but the type system can - not enforce this restriction as there is no relation between each backend - enable option. As a result, this restriction has to be - done explicitely by adding assertions in each display manager backend - module. - - - - On the other hand, managing the display managers backends in the central - module will require to change 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 - (), and to extend - it in each backend module - (, - ). - - - - As a result, displayManager.enable option values can be - added without changing the main service module file and the type system - automatically enforce that there can only be a single display manager - enabled. - - - - Extensible type placeholder in the service module - -services.xserver.displayManager.enable = mkOption { - description = "Display manager to use"; - type = with types; nullOr (enum [ ]); -}; - - - - Extending <literal>services.xserver.displayManager.enable</literal> in the <literal>gdm</literal> module - -services.xserver.displayManager.enable = mkOption { - type = with types; nullOr (enum [ "gdm" ]); -}; - - - - Extending <literal>services.xserver.displayManager.enable</literal> in the <literal>sddm</literal> 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" - ]). - -
-
diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml index 04497db77b8..a1efbeac723 100644 --- a/nixos/doc/manual/development/writing-modules.xml +++ b/nixos/doc/manual/development/writing-modules.xml @@ -179,7 +179,7 @@ in { } - + diff --git a/nixos/doc/manual/from_md/development/option-declarations.section.xml b/nixos/doc/manual/from_md/development/option-declarations.section.xml new file mode 100644 index 00000000000..85a59a543d1 --- /dev/null +++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml @@ -0,0 +1,203 @@ +
+ Option Declarations + + An option declaration specifies the name, type and description of a + NixOS configuration option. It is invalid to define an option that + hasn’t been declared in any module. An option declaration generally + looks like this: + + +options = { + name = mkOption { + type = type specification; + default = default value; + example = example value; + description = "Description for use in the NixOS manual."; + }; +}; + + + The attribute names within the name attribute + path must be camel cased in general but should, as an exception, + match the + + package attribute name when referencing a Nixpkgs package. + For example, the option + services.nix-serve.bindAddress references the + nix-serve Nixpkgs package. + + + The function mkOption accepts the following + arguments. + + + + + type + + + + The type of the option (see + ). It may be omitted, but + that’s not advisable since it may lead to errors that are hard + to diagnose. + + + + + + default + + + + The default value used if no value is defined by any module. A + default is not required; but if a default is not given, then + users of the module will have to define the value of the + option, otherwise an error will be thrown. + + + + + + example + + + + An example value that will be shown in the NixOS manual. + + + + + + description + + + + A textual description of the option, in DocBook format, that + will be included in the NixOS manual. + + + + +
+ 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 approach to this module structure: + + + + + Managing the display managers independently by adding an + enable option to every display manager module backend. (NixOS) + + + + + Managing 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 be only one enabled at a time, but the + type system can not enforce this restriction as there is no + relation between each backend enable option. As + a result, this restriction has to be done explicitely by adding + assertions in each display manager backend module. + + + On the other hand, managing the display managers backends in the + central module will require to change 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 enforce 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 + + +services.xserver.displayManager.enable = mkOption { + type = with types; nullOr (enum [ "gdm" ]); +}; + + + + 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" ]). + +
+
-- cgit 1.4.1