public/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Revert "nixos/doc: re-format"

Browse Source 
This reverts commit ea6e8775bd. The new
format is not an improvement.
This commit is contained in:
Eelco Dolstra
2019-09-19 19:17:30 +02:00
parent db3d31b903
commit b0ccd6dd16
124 changed files with 5709 additions and 1940 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nixos/doc/manual/development/option-declarations.xml
+61 -19
View File
@@ -6,7 +6,9 @@
<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 {
@@ -17,8 +19,13 @@ 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>
@@ -30,7 +37,9 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attri
</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>
@@ -40,7 +49,10 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attri
</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>
@@ -60,7 +72,8 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attri
</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>
@@ -71,15 +84,22 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attri
<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>
@@ -87,12 +107,14 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attri
<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>
@@ -103,22 +125,37 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming"> package attri
</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'>
@@ -147,11 +184,16 @@ 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>