diff options
Diffstat (limited to 'nixos/doc/manual/development/option-declarations.xml')
| -rw-r--r-- | nixos/doc/manual/development/option-declarations.xml | 80 |
1 files changed, 19 insertions, 61 deletions
diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml index eee81bf64263..d6fb3f8f687d 100644 --- a/nixos/doc/manual/development/option-declarations.xml +++ b/nixos/doc/manual/development/option-declarations.xml @@ -6,9 +6,7 @@ <title>Option Declarations</title> <para> - 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: + 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: <programlisting> options = { <replaceable>name</replaceable> = mkOption { @@ -19,13 +17,8 @@ options = { }; }; </programlisting> - The attribute names within the <replaceable>name</replaceable> attribute path - must be camel cased in general but should, as an exception, match the - <link -xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> - package attribute name</link> when referencing a Nixpkgs package. For - example, the option <varname>services.nix-serve.bindAddress</varname> - references the <varname>nix-serve</varname> Nixpkgs package. + The attribute names within the <replaceable>name</replaceable> attribute path must be camel cased in general but should, as an exception, match the <link +xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attribute name</link> when referencing a Nixpkgs package. For example, the option <varname>services.nix-serve.bindAddress</varname> references the <varname>nix-serve</varname> Nixpkgs package. </para> <para> @@ -37,9 +30,7 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> </term> <listitem> <para> - The type of the option (see <xref linkend='sec-option-types' />). It may - be omitted, but that’s not advisable since it may lead to errors that - are hard to diagnose. + The type of the option (see <xref linkend='sec-option-types' />). It may be omitted, but that’s not advisable since it may lead to errors that are hard to diagnose. </para> </listitem> </varlistentry> @@ -49,10 +40,7 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> </term> <listitem> <para> - 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. + 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. </para> </listitem> </varlistentry> @@ -72,8 +60,7 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> </term> <listitem> <para> - A textual description of the option, in DocBook format, that will be - included in the NixOS manual. + A textual description of the option, in DocBook format, that will be included in the NixOS manual. </para> </listitem> </varlistentry> @@ -84,22 +71,15 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> <title>Extensible Option Types</title> <para> - 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 <literal>enum</literal> and - <literal>submodules</literal> and any composed forms of them. + 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 <literal>enum</literal> and <literal>submodules</literal> and any composed forms of them. </para> <para> - Extensible option types can be used for <literal>enum</literal> options that - affects multiple modules, or as an alternative to related - <literal>enable</literal> options. + Extensible option types can be used for <literal>enum</literal> options that affects multiple modules, or as an alternative to related <literal>enable</literal> options. </para> <para> - 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 (slim, sddm, gdm ...). + 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 (slim, sddm, gdm ...). </para> <para> @@ -107,14 +87,12 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> <itemizedlist> <listitem> <para> - Managing the display managers independently by adding an enable option to - every display manager module backend. (NixOS) + Managing the display managers independently by adding an enable option to every display manager module backend. (NixOS) </para> </listitem> <listitem> <para> - Managing the display managers in the central module by adding an option - to select which display manager backend to use. + Managing the display managers in the central module by adding an option to select which display manager backend to use. </para> </listitem> </itemizedlist> @@ -125,37 +103,22 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> </para> <para> - 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 - <literal>enable</literal> option. As a result, this restriction has to be - done explicitely by adding assertions in each display manager backend - module. + 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 <literal>enable</literal> option. As a result, this restriction has to be done explicitely by adding assertions in each display manager backend module. </para> <para> - 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. + 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. </para> <para> - By using extensible option types, it is possible to create a placeholder - option in the central module - (<xref linkend='ex-option-declaration-eot-service' - />), and to extend - it in each backend module - (<xref - linkend='ex-option-declaration-eot-backend-slim' />, - <xref + By using extensible option types, it is possible to create a placeholder option in the central module (<xref linkend='ex-option-declaration-eot-service' + />), and to extend it in each backend module (<xref + linkend='ex-option-declaration-eot-backend-slim' />, <xref linkend='ex-option-declaration-eot-backend-sddm' />). </para> <para> - As a result, <literal>displayManager.enable</literal> 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. + As a result, <literal>displayManager.enable</literal> 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. </para> <example xml:id='ex-option-declaration-eot-service'> @@ -184,16 +147,11 @@ services.xserver.displayManager.enable = mkOption { </example> <para> - The placeholder declaration is a standard <literal>mkOption</literal> - declaration, but it is important that extensible option declarations only - use the <literal>type</literal> argument. + The placeholder declaration is a standard <literal>mkOption</literal> declaration, but it is important that extensible option declarations only use the <literal>type</literal> argument. </para> <para> - Extensible option types work with any of the composed variants of - <literal>enum</literal> such as <literal>with types; nullOr (enum [ "foo" - "bar" ])</literal> or <literal>with types; listOf (enum [ "foo" "bar" - ])</literal>. + Extensible option types work with any of the composed variants of <literal>enum</literal> such as <literal>with types; nullOr (enum [ "foo" "bar" ])</literal> or <literal>with types; listOf (enum [ "foo" "bar" ])</literal>. </para> </section> </section> |