nixpkgs-suyu/nixos/doc/manual/from_md/development/option-declarations.section.xml
2022-03-17 00:10:36 +00:00

327 lines
12 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" 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:
</para>
<programlisting language="bash">
options = {
name = mkOption {
type = type specification;
default = default value;
example = example value;
description = &quot;Description for use in the NixOS manual.&quot;;
};
};
</programlisting>
<para>
The attribute names within the <literal>name</literal> 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
<literal>services.nix-serve.bindAddress</literal> references the
<literal>nix-serve</literal> Nixpkgs package.
</para>
<para>
The function <literal>mkOption</literal> accepts the following
arguments.
</para>
<variablelist>
<varlistentry>
<term>
<literal>type</literal>
</term>
<listitem>
<para>
The type of the option (see
<xref linkend="sec-option-types" />). This argument is
mandatory for nixpkgs modules. Setting this is highly
recommended for the sake of documentation and type checking.
In case it is not set, a fallback type with unspecified
behavior is used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>default</literal>
</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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>defaultText</literal>
</term>
<listitem>
<para>
A textual representation of the default value to be rendered
verbatim in the manual. Useful if the default value is a
complex expression or depends on other values or packages. Use
<literal>lib.literalExpression</literal> for a Nix expression,
<literal>lib.literalDocBook</literal> for a plain English
description in DocBook format.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>example</literal>
</term>
<listitem>
<para>
An example value that will be shown in the NixOS manual. You
can use <literal>lib.literalExpression</literal> and
<literal>lib.literalDocBook</literal> in the same way as in
<literal>defaultText</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>description</literal>
</term>
<listitem>
<para>
A textual description of the option, in DocBook format, that
will be included in the NixOS manual.
</para>
</listitem>
</varlistentry>
</variablelist>
<section xml:id="sec-option-declarations-util">
<title>Utility functions for common option patterns</title>
<section xml:id="sec-option-declarations-util-mkEnableOption">
<title><literal>mkEnableOption</literal></title>
<para>
Creates an Option attribute set for a boolean value option i.e
an option to be toggled on or off.
</para>
<para>
This function takes a single string argument, the name of the
thing to be toggled.
</para>
<para>
The options description is <quote>Whether to enable
&lt;name&gt;.</quote>.
</para>
<para>
For example:
</para>
<anchor xml:id="ex-options-declarations-util-mkEnableOption-magic" />
<programlisting language="bash">
lib.mkEnableOption &quot;magic&quot;
# is like
lib.mkOption {
type = lib.types.bool;
default = false;
example = true;
description = &quot;Whether to enable magic.&quot;;
}
</programlisting>
<section xml:id="sec-option-declarations-util-mkPackageOption">
<title><literal>mkPackageOption</literal></title>
<para>
Usage:
</para>
<programlisting language="bash">
mkPackageOption pkgs &quot;name&quot; { default = [ &quot;path&quot; &quot;in&quot; &quot;pkgs&quot; ]; example = &quot;literal example&quot;; }
</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 shouldnt
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 &lt;name&gt; package to use.</quote>.
You can also pass an example value, either a literal string or
a packages attribute path.
</para>
<para>
You can omit the default path if the name of the option is
also attribute path in nixpkgs.
</para>
<anchor xml:id="ex-options-declarations-util-mkPackageOption" />
<para>
Examples:
</para>
<anchor xml:id="ex-options-declarations-util-mkPackageOption-hello" />
<programlisting language="bash">
lib.mkPackageOption pkgs &quot;hello&quot; { }
# is like
lib.mkOption {
type = lib.types.package;
default = pkgs.hello;
defaultText = lib.literalExpression &quot;pkgs.hello&quot;;
description = &quot;The hello package to use.&quot;;
}
</programlisting>
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
<programlisting language="bash">
lib.mkPackageOption pkgs &quot;GHC&quot; {
default = [ &quot;ghc&quot; ];
example = &quot;pkgs.haskell.package.ghc922.ghc.withPackages (hkgs: [ hkgs.primes ])&quot;;
}
# is like
lib.mkOption {
type = lib.types.package;
default = pkgs.ghc;
defaultText = lib.literalExpression &quot;pkgs.ghc&quot;;
example = lib.literalExpression &quot;pkgs.haskell.package.ghc922.ghc.withPackages (hkgs: [ hkgs.primes ])&quot;;
description = &quot;The GHC package to use.&quot;;
}
</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 backends
<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="bash">
services.xserver.displayManager.enable = mkOption {
description = &quot;Display manager to use&quot;;
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="bash">
services.xserver.displayManager.enable = mkOption {
type = with types; nullOr (enum [ &quot;gdm&quot; ]);
};
</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="bash">
services.xserver.displayManager.enable = mkOption {
type = with types; nullOr (enum [ &quot;sddm&quot; ]);
};
</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 [ &quot;foo&quot; &quot;bar&quot; ])</literal>
or
<literal>with types; listOf (enum [ &quot;foo&quot; &quot;bar&quot; ])</literal>.
</para>
</section>
</section>
</section>
</section>
</section>