nixpkgs/nixos/doc/manual/development/option-declarations.xml
2016-11-06 00:05:58 +01:00

157 lines
5.8 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-option-declarations">
<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 hasnt been declared in any module. An option declaration
generally looks like this:
<programlisting>
options = {
<replaceable>name</replaceable> = mkOption {
type = <replaceable>type specification</replaceable>;
default = <replaceable>default value</replaceable>;
example = <replaceable>example value</replaceable>;
description = "<replaceable>Description for use in the NixOS manual.</replaceable>";
};
};
</programlisting>
</para>
<para>The function <varname>mkOption</varname> accepts the following arguments.
<variablelist>
<varlistentry>
<term><varname>type</varname></term>
<listitem>
<para>The type of the option (see <xref linkend='sec-option-types' />).
It may be omitted, but thats not advisable since it may lead to errors
that are hard to diagnose.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>default</varname></term>
<listitem>
<para>The default value used if no value is defined by any
module. A default is not required; in that case, if the option
value is never used, an error will be thrown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>example</varname></term>
<listitem>
<para>An example value that will be shown in the NixOS manual.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>description</varname></term>
<listitem>
<para>A textual description of the option, in DocBook format,
that will be included in the NixOS manual.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<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 (slim, kdm, gdm ...).
</para>
<para>There are two approach to this module structure:
<itemizedlist>
<listitem><para>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.</para>
</listitem>
</itemizedlist>
</para>
<para>Both approachs have problems.</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.</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.</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
linkend='ex-option-declaration-eot-backend-kdm' />).</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.</para>
<example xml:id='ex-option-declaration-eot-service'><title>Extensible type
placeholder in the service module</title>
<screen>
services.xserver.displayManager.enable = mkOption {
description = "Display manager to use";
type = with types; nullOr (enum [ ]);
};</screen></example>
<example xml:id='ex-option-declaration-eot-backend-slim'><title>Extending
<literal>services.xserver.displayManager.enable</literal> in the
<literal>slim</literal> module</title>
<screen>
services.xserver.displayManager.enable = mkOption {
type = with types; nullOr (enum [ "slim" ]);
};</screen></example>
<example xml:id='ex-option-declaration-eot-backend-kdm'><title>Extending
<literal>services.foo.backend</literal> in the <literal>kdm</literal>
module</title>
<screen>
services.xserver.displayManager.enable = mkOption {
type = with types; nullOr (enum [ "kdm" ]);
};</screen></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.</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>