nixos/manual: fix option-declarations sections
the examples for mkPackageOption weren't terminated, leading to pretty odd nesting of docbook (and thus html) elements. close them properly. also turn the (likewise unclosed) fenced div containing just an anchor id and a class that will be silently dropped to an inline anchor while we're here. we'd have to convert it anyway later.
This commit is contained in:
pennae
parent
ba4bcdc5e4
commit
8163651338
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
|
|
@ -137,57 +137,58 @@ lib.mkOption {
|
|||
description = lib.mdDoc "Whether to enable magic.";
|
||||
}
|
||||
</programlisting>
|
||||
<section xml:id="sec-option-declarations-util-mkPackageOption">
|
||||
<title><literal>mkPackageOption</literal>,
|
||||
<literal>mkPackageOptionMD</literal></title>
|
||||
<para>
|
||||
Usage:
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
</section>
|
||||
<section xml:id="sec-option-declarations-util-mkPackageOption">
|
||||
<title><literal>mkPackageOption</literal>,
|
||||
<literal>mkPackageOptionMD</literal></title>
|
||||
<para>
|
||||
Usage:
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
mkPackageOption pkgs "name" { default = [ "path" "in" "pkgs" ]; example = "literal example"; }
|
||||
</programlisting>
|
||||
<para>
|
||||
Creates an Option attribute set for an option that specifies
|
||||
the package a module should use for some purpose.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="strong">Note</emphasis>: You shouldn’t
|
||||
necessarily make package options for all of your modules. You
|
||||
can always overwrite a specific package throughout nixpkgs by
|
||||
using
|
||||
<link xlink:href="https://nixos.org/manual/nixpkgs/stable/#chap-overlays">nixpkgs
|
||||
overlays</link>.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
The second argument is the name of the option, used in the
|
||||
description <quote>The <name> package to use.</quote>.
|
||||
You can also pass an example value, either a literal string or
|
||||
a package’s attribute path.
|
||||
</para>
|
||||
<para>
|
||||
You can omit the default path if the name of the option is
|
||||
also attribute path in nixpkgs.
|
||||
</para>
|
||||
<para>
|
||||
During the transition to CommonMark documentation
|
||||
<literal>mkPackageOption</literal> creates an option with a
|
||||
DocBook description attribute, once the transition is
|
||||
completed it will create a CommonMark description instead.
|
||||
<literal>mkPackageOptionMD</literal> always creates an option
|
||||
with a CommonMark description attribute and will be removed
|
||||
some time after the transition is completed.
|
||||
</para>
|
||||
<para>
|
||||
Creates an Option attribute set for an option that specifies the
|
||||
package a module should use for some purpose.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="strong">Note</emphasis>: You shouldn’t
|
||||
necessarily make package options for all of your modules. You
|
||||
can always overwrite a specific package throughout nixpkgs by
|
||||
using
|
||||
<link xlink:href="https://nixos.org/manual/nixpkgs/stable/#chap-overlays">nixpkgs
|
||||
overlays</link>.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
The second argument is the name of the option, used in the
|
||||
description <quote>The <name> package to use.</quote>. You
|
||||
can also pass an example value, either a literal string or a
|
||||
package’s attribute path.
|
||||
</para>
|
||||
<para>
|
||||
You can omit the default path if the name of the option is also
|
||||
attribute path in nixpkgs.
|
||||
</para>
|
||||
<para>
|
||||
During the transition to CommonMark documentation
|
||||
<literal>mkPackageOption</literal> creates an option with a
|
||||
DocBook description attribute, once the transition is completed
|
||||
it will create a CommonMark description instead.
|
||||
<literal>mkPackageOptionMD</literal> always creates an option
|
||||
with a CommonMark description attribute and will be removed some
|
||||
time after the transition is completed.
|
||||
</para>
|
||||
<para>
|
||||
<anchor xml:id="ex-options-declarations-util-mkPackageOption" />
|
||||
<para>
|
||||
Examples:
|
||||
</para>
|
||||
<anchor xml:id="ex-options-declarations-util-mkPackageOption-hello" />
|
||||
<programlisting language="nix">
|
||||
Examples:
|
||||
</para>
|
||||
<anchor xml:id="ex-options-declarations-util-mkPackageOption-hello" />
|
||||
<programlisting language="nix">
|
||||
lib.mkPackageOptionMD pkgs "hello" { }
|
||||
# is like
|
||||
lib.mkOption {
|
||||
|
|
@ -197,8 +198,8 @@ lib.mkOption {
|
|||
description = lib.mdDoc "The hello package to use.";
|
||||
}
|
||||
</programlisting>
|
||||
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
|
||||
<programlisting language="nix">
|
||||
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
|
||||
<programlisting language="nix">
|
||||
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.";
|
||||
}
|
||||
</programlisting>
|
||||
<section xml:id="sec-option-declarations-eot">
|
||||
<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.
|
||||
</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.
|
||||
</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 (sddm, gdm …).
|
||||
</para>
|
||||
<para>
|
||||
There are two approaches we could take with this module
|
||||
structure:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Configuring the display managers independently by adding
|
||||
an enable option to every display manager module
|
||||
backend. (NixOS)
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Configuring the display managers in the central module
|
||||
by adding an option to select which display manager
|
||||
backend to use.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Both approaches have problems.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
<literal>enable</literal> option. As a result, this
|
||||
restriction has to be done explicitly by adding assertions
|
||||
in each display manager backend module.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
By using extensible option types, it is possible to create a
|
||||
placeholder option in the central module
|
||||
(<link linkend="ex-option-declaration-eot-service">Example:
|
||||
Extensible type placeholder in the service module</link>),
|
||||
and to extend it in each backend module
|
||||
(<link linkend="ex-option-declaration-eot-backend-gdm">Example:
|
||||
Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in
|
||||
the <literal>gdm</literal> module</link>,
|
||||
<link linkend="ex-option-declaration-eot-backend-sddm">Example:
|
||||
Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in
|
||||
the <literal>sddm</literal> module</link>).
|
||||
</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 enforces that there
|
||||
can only be a single display manager enabled.
|
||||
</para>
|
||||
<anchor xml:id="ex-option-declaration-eot-service" />
|
||||
<para>
|
||||
<emphasis role="strong">Example: Extensible type placeholder
|
||||
in the service module</emphasis>
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="sec-option-declarations-eot">
|
||||
<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.
|
||||
</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.
|
||||
</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 (sddm, gdm
|
||||
…).
|
||||
</para>
|
||||
<para>
|
||||
There are two approaches we could take with this module structure:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Configuring the display managers independently by adding an
|
||||
enable option to every display manager module backend. (NixOS)
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Configuring the display managers in the central module by
|
||||
adding an option to select which display manager backend to
|
||||
use.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Both approaches have problems.
|
||||
</para>
|
||||
<para>
|
||||
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 <literal>enable</literal> option.
|
||||
As a result, this restriction has to be done explicitly by adding
|
||||
assertions in each display manager backend module.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
By using extensible option types, it is possible to create a
|
||||
placeholder option in the central module
|
||||
(<link linkend="ex-option-declaration-eot-service">Example:
|
||||
Extensible type placeholder in the service module</link>), and to
|
||||
extend it in each backend module
|
||||
(<link linkend="ex-option-declaration-eot-backend-gdm">Example:
|
||||
Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in the
|
||||
<literal>gdm</literal> module</link>,
|
||||
<link linkend="ex-option-declaration-eot-backend-sddm">Example:
|
||||
Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in the
|
||||
<literal>sddm</literal> module</link>).
|
||||
</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 enforces that there can only be
|
||||
a single display manager enabled.
|
||||
</para>
|
||||
<anchor xml:id="ex-option-declaration-eot-service" />
|
||||
<para>
|
||||
<emphasis role="strong">Example: Extensible type placeholder in
|
||||
the service module</emphasis>
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
services.xserver.displayManager.enable = mkOption {
|
||||
description = "Display manager to use";
|
||||
type = with types; nullOr (enum [ ]);
|
||||
};
|
||||
</programlisting>
|
||||
<anchor xml:id="ex-option-declaration-eot-backend-gdm" />
|
||||
<para>
|
||||
<emphasis role="strong">Example: Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in
|
||||
the <literal>gdm</literal> module</emphasis>
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
<anchor xml:id="ex-option-declaration-eot-backend-gdm" />
|
||||
<para>
|
||||
<emphasis role="strong">Example: Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in the
|
||||
<literal>gdm</literal> module</emphasis>
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
services.xserver.displayManager.enable = mkOption {
|
||||
type = with types; nullOr (enum [ "gdm" ]);
|
||||
};
|
||||
</programlisting>
|
||||
<anchor xml:id="ex-option-declaration-eot-backend-sddm" />
|
||||
<para>
|
||||
<emphasis role="strong">Example: Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in
|
||||
the <literal>sddm</literal> module</emphasis>
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
<anchor xml:id="ex-option-declaration-eot-backend-sddm" />
|
||||
<para>
|
||||
<emphasis role="strong">Example: Extending
|
||||
<literal>services.xserver.displayManager.enable</literal> in the
|
||||
<literal>sddm</literal> module</emphasis>
|
||||
</para>
|
||||
<programlisting language="nix">
|
||||
services.xserver.displayManager.enable = mkOption {
|
||||
type = with types; nullOr (enum [ "sddm" ]);
|
||||
};
|
||||
</programlisting>
|
||||
<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.
|
||||
</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>.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
<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.
|
||||
</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>.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
|
|
|||
Loading…
Reference in a new issue