nixpkgs-suyu/nixos/doc/manual/from_md/development/option-declarations.section.xml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

328 lines
12 KiB
XML
Raw Normal View History

<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>