nixpkgs/nixos/doc/manual/development/option-declarations.xml

69 lines
2 KiB
XML
Raw Normal View History

<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
2016-05-22 09:29:33 +00:00
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
2016-05-22 09:29:33 +00:00
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>