2016-09-13 05:04:02 +00:00
|
|
|
|
<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-types">
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<title>Options Types</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Option types are a way to put constraints on the values a module option can
|
|
|
|
|
take. Types are also responsible of how values are merged in case of multiple
|
|
|
|
|
value definitions.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
2016-09-07 01:03:32 +00:00
|
|
|
|
|
2018-09-01 19:49:04 +00:00
|
|
|
|
<section xml:id="sec-option-types-basic">
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<title>Basic Types</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Basic types are the simplest available types in the module system. Basic
|
|
|
|
|
types include multiple string types that mainly differ in how definition
|
|
|
|
|
merging is handled.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<variablelist>
|
2018-05-06 22:35:45 +00:00
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.attrs</varname>
|
2018-05-06 22:35:45 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A free-form attribute set.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.bool</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A boolean, its values can be <literal>true</literal> or
|
|
|
|
|
<literal>false</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.path</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A filesystem path, defined as anything that when coerced to a string
|
|
|
|
|
starts with a slash. Even if derivations can be considered as path, the
|
|
|
|
|
more specific <literal>types.package</literal> should be preferred.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.package</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A derivation or a store path.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Integer-related types:
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.int</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A signed integer.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.ints.{s8, s16, s32}</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Signed integers with a fixed length (8, 16 or 32 bits). They go from
|
|
|
|
|
<inlineequation><mathphrase>−2<superscript>n</superscript>/2</mathphrase>
|
|
|
|
|
</inlineequation> to <inlineequation>
|
|
|
|
|
<mathphrase>2<superscript>n</superscript>/2−1</mathphrase>
|
|
|
|
|
</inlineequation> respectively (e.g. <literal>−128</literal> to
|
|
|
|
|
<literal>127</literal> for 8 bits).
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.ints.unsigned</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
An unsigned integer (that is >= 0).
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2018-10-19 10:20:48 +00:00
|
|
|
|
<varlistentry xml:id='types.ints.ux'>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.ints.{u8, u16, u32}</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Unsigned integers with a fixed length (8, 16 or 32 bits). They go from
|
|
|
|
|
<inlineequation><mathphrase>0</mathphrase></inlineequation> to
|
|
|
|
|
<inlineequation>
|
|
|
|
|
<mathphrase>2<superscript>n</superscript>−1</mathphrase>
|
|
|
|
|
</inlineequation> respectively (e.g. <literal>0</literal> to
|
|
|
|
|
<literal>255</literal> for 8 bits).
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.ints.positive</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A positive integer (that is > 0).
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2018-10-19 10:20:48 +00:00
|
|
|
|
<varlistentry>
|
|
|
|
|
<term>
|
|
|
|
|
<varname>types.port</varname>
|
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A port number. This type is an alias to
|
|
|
|
|
<link linkend='types.ints.ux'><varname>types.ints.u16</varname></link>.
|
2018-10-19 10:20:48 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</variablelist>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
String-related types:
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.str</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A string. Multiple definitions cannot be merged.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.lines</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A string. Multiple definitions are concatenated with a new line
|
|
|
|
|
<literal>"\n"</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.commas</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A string. Multiple definitions are concatenated with a comma
|
|
|
|
|
<literal>","</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.envVar</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A string. Multiple definitions are concatenated with a collon
|
|
|
|
|
<literal>":"</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>types.strMatching</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A string matching a specific regular expression. Multiple definitions
|
|
|
|
|
cannot be merged. The regular expression is processed using
|
|
|
|
|
<literal>builtins.match</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
2016-09-07 01:03:32 +00:00
|
|
|
|
</section>
|
|
|
|
|
|
2018-09-01 19:49:04 +00:00
|
|
|
|
<section xml:id="sec-option-types-value">
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<title>Value Types</title>
|
|
|
|
|
|
|
|
|
|
<para>
|
|
|
|
|
Value types are types that take a value parameter.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.enum</varname> <replaceable>l</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
One element of the list <replaceable>l</replaceable>, e.g.
|
|
|
|
|
<literal>types.enum [ "left" "right" ]</literal>. Multiple definitions
|
|
|
|
|
cannot be merged.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.separatedString</varname> <replaceable>sep</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A string with a custom separator <replaceable>sep</replaceable>, e.g.
|
|
|
|
|
<literal>types.separatedString "|"</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.ints.between</varname> <replaceable>lowest</replaceable> <replaceable>highest</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
An integer between <replaceable>lowest</replaceable> and
|
|
|
|
|
<replaceable>highest</replaceable> (both inclusive). Useful for creating
|
|
|
|
|
types like <literal>types.port</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.submodule</varname> <replaceable>o</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A set of sub options <replaceable>o</replaceable>.
|
|
|
|
|
<replaceable>o</replaceable> can be an attribute set or a function
|
|
|
|
|
returning an attribute set. Submodules are used in composed types to
|
|
|
|
|
create modular options. Submodule are detailed in
|
|
|
|
|
<xref
|
2018-05-01 23:57:09 +00:00
|
|
|
|
linkend='section-option-types-submodule' />.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
</section>
|
|
|
|
|
|
2018-09-01 19:49:04 +00:00
|
|
|
|
<section xml:id="sec-option-types-composed">
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<title>Composed Types</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Composed types are types that take a type as parameter. <literal>listOf
|
|
|
|
|
int</literal> and <literal>either int str</literal> are examples of composed
|
|
|
|
|
types.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.listOf</varname> <replaceable>t</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A list of <replaceable>t</replaceable> type, e.g. <literal>types.listOf
|
|
|
|
|
int</literal>. Multiple definitions are merged with list concatenation.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.attrsOf</varname> <replaceable>t</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
An attribute set of where all the values are of
|
|
|
|
|
<replaceable>t</replaceable> type. Multiple definitions result in the
|
|
|
|
|
joined attribute set.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.loaOf</varname> <replaceable>t</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
An attribute set or a list of <replaceable>t</replaceable> type. Multiple
|
|
|
|
|
definitions are merged according to the value.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.nullOr</varname> <replaceable>t</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
<literal>null</literal> or type <replaceable>t</replaceable>. Multiple
|
|
|
|
|
definitions are merged according to type <replaceable>t</replaceable>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.uniq</varname> <replaceable>t</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Ensures that type <replaceable>t</replaceable> cannot be merged. It is
|
|
|
|
|
used to ensure option definitions are declared only once.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.either</varname> <replaceable>t1</replaceable> <replaceable>t2</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable>,
|
|
|
|
|
e.g. <literal>with types; either int str</literal>. Multiple definitions
|
|
|
|
|
cannot be merged.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2019-08-01 13:55:33 +00:00
|
|
|
|
<varlistentry>
|
|
|
|
|
<term>
|
|
|
|
|
<varname>types.oneOf</varname> [ <replaceable>t1</replaceable> <replaceable>t2</replaceable> ... ]
|
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable> and so forth,
|
|
|
|
|
e.g. <literal>with types; oneOf [ int str bool ]</literal>. Multiple definitions
|
|
|
|
|
cannot be merged.
|
2019-08-01 13:55:33 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
2018-06-01 01:07:15 +00:00
|
|
|
|
<varname>types.coercedTo</varname> <replaceable>from</replaceable> <replaceable>f</replaceable> <replaceable>to</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Type <replaceable>to</replaceable> or type
|
|
|
|
|
<replaceable>from</replaceable> which will be coerced to type
|
|
|
|
|
<replaceable>to</replaceable> using function <replaceable>f</replaceable>
|
|
|
|
|
which takes an argument of type <replaceable>from</replaceable> and
|
|
|
|
|
return a value of type <replaceable>to</replaceable>. Can be used to
|
|
|
|
|
preserve backwards compatibility of an option if its type was changed.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
|
|
|
|
</section>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<section xml:id='section-option-types-submodule'>
|
|
|
|
|
<title>Submodule</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
<literal>submodule</literal> is a very powerful type that defines a set of
|
|
|
|
|
sub-options that are handled like a separate module.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
It takes a parameter <replaceable>o</replaceable>, that should be a set, or
|
|
|
|
|
a function returning a set with an <literal>options</literal> key defining
|
|
|
|
|
the sub-options. Submodule option definitions are type-checked accordingly
|
|
|
|
|
to the <literal>options</literal> declarations. Of course, you can nest
|
|
|
|
|
submodule option definitons for even higher modularity.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
The option set can be defined directly
|
|
|
|
|
(<xref linkend='ex-submodule-direct' />) or as reference
|
|
|
|
|
(<xref linkend='ex-submodule-reference' />).
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<example xml:id='ex-submodule-direct'>
|
|
|
|
|
<title>Directly defined submodule</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
options.mod = mkOption {
|
|
|
|
|
description = "submodule example";
|
2017-09-10 00:50:07 +00:00
|
|
|
|
type = with types; submodule {
|
2016-09-13 05:04:02 +00:00
|
|
|
|
options = {
|
|
|
|
|
foo = mkOption {
|
|
|
|
|
type = int;
|
|
|
|
|
};
|
|
|
|
|
bar = mkOption {
|
|
|
|
|
type = str;
|
|
|
|
|
};
|
|
|
|
|
};
|
2017-09-10 00:50:07 +00:00
|
|
|
|
};
|
2018-05-01 23:57:09 +00:00
|
|
|
|
};</screen>
|
|
|
|
|
</example>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<example xml:id='ex-submodule-reference'>
|
|
|
|
|
<title>Submodule defined as a reference</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
let
|
|
|
|
|
modOptions = {
|
|
|
|
|
options = {
|
|
|
|
|
foo = mkOption {
|
|
|
|
|
type = int;
|
|
|
|
|
};
|
|
|
|
|
bar = mkOption {
|
|
|
|
|
type = int;
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
in
|
|
|
|
|
options.mod = mkOption {
|
|
|
|
|
description = "submodule example";
|
2017-09-10 00:50:07 +00:00
|
|
|
|
type = with types; submodule modOptions;
|
2018-05-01 23:57:09 +00:00
|
|
|
|
};</screen>
|
|
|
|
|
</example>
|
|
|
|
|
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
The <literal>submodule</literal> type is especially interesting when used
|
|
|
|
|
with composed types like <literal>attrsOf</literal> or
|
|
|
|
|
<literal>listOf</literal>. When composed with <literal>listOf</literal>
|
|
|
|
|
(<xref linkend='ex-submodule-listof-declaration' />),
|
|
|
|
|
<literal>submodule</literal> allows multiple definitions of the submodule
|
|
|
|
|
option set (<xref linkend='ex-submodule-listof-definition' />).
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<example xml:id='ex-submodule-listof-declaration'>
|
|
|
|
|
<title>Declaration of a list of submodules</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
options.mod = mkOption {
|
|
|
|
|
description = "submodule example";
|
|
|
|
|
type = with types; listOf (submodule {
|
|
|
|
|
options = {
|
|
|
|
|
foo = mkOption {
|
|
|
|
|
type = int;
|
|
|
|
|
};
|
|
|
|
|
bar = mkOption {
|
|
|
|
|
type = str;
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
});
|
2018-05-01 23:57:09 +00:00
|
|
|
|
};</screen>
|
|
|
|
|
</example>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<example xml:id='ex-submodule-listof-definition'>
|
|
|
|
|
<title>Definition of a list of submodules</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
config.mod = [
|
|
|
|
|
{ foo = 1; bar = "one"; }
|
|
|
|
|
{ foo = 2; bar = "two"; }
|
2018-05-01 23:57:09 +00:00
|
|
|
|
];</screen>
|
|
|
|
|
</example>
|
|
|
|
|
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
When composed with <literal>attrsOf</literal>
|
|
|
|
|
(<xref linkend='ex-submodule-attrsof-declaration' />),
|
|
|
|
|
<literal>submodule</literal> allows multiple named definitions of the
|
|
|
|
|
submodule option set (<xref linkend='ex-submodule-attrsof-definition' />).
|
2017-09-10 00:50:07 +00:00
|
|
|
|
</para>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<example xml:id='ex-submodule-attrsof-declaration'>
|
|
|
|
|
<title>Declaration of attribute sets of submodules</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
options.mod = mkOption {
|
|
|
|
|
description = "submodule example";
|
|
|
|
|
type = with types; attrsOf (submodule {
|
|
|
|
|
options = {
|
|
|
|
|
foo = mkOption {
|
|
|
|
|
type = int;
|
|
|
|
|
};
|
|
|
|
|
bar = mkOption {
|
|
|
|
|
type = str;
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
});
|
2018-05-01 23:57:09 +00:00
|
|
|
|
};</screen>
|
|
|
|
|
</example>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<example xml:id='ex-submodule-attrsof-definition'>
|
|
|
|
|
<title>Declaration of attribute sets of submodules</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
config.mod.one = { foo = 1; bar = "one"; };
|
2018-05-01 23:57:09 +00:00
|
|
|
|
config.mod.two = { foo = 2; bar = "two"; };</screen>
|
|
|
|
|
</example>
|
|
|
|
|
</section>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-09-01 19:49:04 +00:00
|
|
|
|
<section xml:id="sec-option-types-extending">
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<title>Extending types</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Types are mainly characterized by their <literal>check</literal> and
|
|
|
|
|
<literal>merge</literal> functions.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>check</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
The function to type check the value. Takes a value as parameter and
|
|
|
|
|
return a boolean. It is possible to extend a type check with the
|
|
|
|
|
<literal>addCheck</literal> function
|
|
|
|
|
(<xref
|
|
|
|
|
linkend='ex-extending-type-check-1' />), or to fully
|
|
|
|
|
override the check function
|
|
|
|
|
(<xref linkend='ex-extending-type-check-2' />).
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
<example xml:id='ex-extending-type-check-1'>
|
|
|
|
|
<title>Adding a type check</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
byte = mkOption {
|
|
|
|
|
description = "An integer between 0 and 255.";
|
2019-03-11 21:56:56 +00:00
|
|
|
|
type = types.addCheck types.int (x: x >= 0 && x <= 255);
|
2018-05-01 23:57:09 +00:00
|
|
|
|
};</screen>
|
|
|
|
|
</example>
|
|
|
|
|
<example xml:id='ex-extending-type-check-2'>
|
|
|
|
|
<title>Overriding a type check</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
<screen>
|
|
|
|
|
nixThings = mkOption {
|
|
|
|
|
description = "words that start with 'nix'";
|
|
|
|
|
type = types.str // {
|
|
|
|
|
check = (x: lib.hasPrefix "nix" x)
|
|
|
|
|
};
|
2018-05-01 23:57:09 +00:00
|
|
|
|
};</screen>
|
|
|
|
|
</example>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>merge</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Function to merge the options values when multiple values are set. The
|
|
|
|
|
function takes two parameters, <literal>loc</literal> the option path as
|
|
|
|
|
a list of strings, and <literal>defs</literal> the list of defined values
|
|
|
|
|
as a list. It is possible to override a type merge function for custom
|
|
|
|
|
needs.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
|
|
|
|
</section>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-09-01 19:49:04 +00:00
|
|
|
|
<section xml:id="sec-option-types-custom">
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<title>Custom Types</title>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Custom types can be created with the <literal>mkOptionType</literal>
|
|
|
|
|
function. As type creation includes some more complex topics such as
|
|
|
|
|
submodule handling, it is recommended to get familiar with
|
|
|
|
|
<filename
|
|
|
|
|
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/types.nix">types.nix</filename>
|
|
|
|
|
code before creating a new type.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
|
2018-05-01 23:57:09 +00:00
|
|
|
|
<para>
|
|
|
|
|
The only required parameter is <literal>name</literal>.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>name</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A string representation of the type function name.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>definition</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Description of the type used in documentation. Give information of the
|
|
|
|
|
type and any of its arguments.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>check</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A function to type check the definition value. Takes the definition value
|
|
|
|
|
as a parameter and returns a boolean indicating the type check result,
|
|
|
|
|
<literal>true</literal> for success and <literal>false</literal> for
|
|
|
|
|
failure.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>merge</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
A function to merge multiple definitions values. Takes two parameters:
|
|
|
|
|
</para>
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<replaceable>loc</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
The option path as a list of strings, e.g. <literal>["boot" "loader
|
|
|
|
|
"grub" "enable"]</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<replaceable>defs</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
The list of sets of defined <literal>value</literal> and
|
|
|
|
|
<literal>file</literal> where the value was defined, e.g. <literal>[ {
|
|
|
|
|
file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 }
|
|
|
|
|
]</literal>. The <literal>merge</literal> function should return the
|
|
|
|
|
merged value or throw an error in case the values are impossible or
|
|
|
|
|
not meant to be merged.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>getSubOptions</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
For composed types that can take a submodule as type parameter, this
|
|
|
|
|
function generate sub-options documentation. It takes the current option
|
|
|
|
|
prefix as a list and return the set of sub-options. Usually defined in a
|
|
|
|
|
recursive manner by adding a term to the prefix, e.g. <literal>prefix:
|
|
|
|
|
elemType.getSubOptions (prefix ++
|
|
|
|
|
[<replaceable>"prefix"</replaceable>])</literal> where
|
|
|
|
|
<replaceable>"prefix"</replaceable> is the newly added prefix.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>getSubModules</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
For composed types that can take a submodule as type parameter, this
|
|
|
|
|
function should return the type parameters submodules. If the type
|
|
|
|
|
parameter is called <literal>elemType</literal>, the function should just
|
|
|
|
|
recursively look into submodules by returning
|
|
|
|
|
<literal>elemType.getSubModules;</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>substSubModules</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
For composed types that can take a submodule as type parameter, this
|
|
|
|
|
function can be used to substitute the parameter of a submodule type. It
|
|
|
|
|
takes a module as parameter and return the type with the submodule
|
|
|
|
|
options substituted. It is usually defined as a type function call with a
|
|
|
|
|
recursive call to <literal>substSubModules</literal>, e.g for a type
|
|
|
|
|
<literal>composedType</literal> that take an <literal>elemtype</literal>
|
|
|
|
|
type parameter, this function should be defined as <literal>m:
|
|
|
|
|
composedType (elemType.substSubModules m)</literal>.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>typeMerge</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A function to merge multiple type declarations. Takes the type to merge
|
|
|
|
|
<literal>functor</literal> as parameter. A <literal>null</literal> return
|
|
|
|
|
value means that type cannot be merged.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<replaceable>f</replaceable>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
The type to merge <literal>functor</literal>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Note: There is a generic <literal>defaultTypeMerge</literal> that work
|
|
|
|
|
with most of value and composed types.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>functor</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
An attribute set representing the type. It is used for type operations
|
|
|
|
|
and has the following keys:
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
<variablelist>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>type</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
The type function.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>wrapped</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Holds the type parameter for composed types.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>payload</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
Holds the value parameter for value types. The types that have a
|
|
|
|
|
<literal>payload</literal> are the <literal>enum</literal>,
|
|
|
|
|
<literal>separatedString</literal> and <literal>submodule</literal>
|
|
|
|
|
types.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
<varlistentry>
|
2018-06-01 01:03:51 +00:00
|
|
|
|
<term>
|
|
|
|
|
<varname>binOp</varname>
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
2019-09-19 17:17:30 +00:00
|
|
|
|
A binary operation that can merge the payloads of two same types.
|
|
|
|
|
Defined as a function that take two payloads as parameters and return
|
|
|
|
|
the payloads merged.
|
2018-05-01 23:57:09 +00:00
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
</variablelist>
|
|
|
|
|
</section>
|
2016-09-13 05:04:02 +00:00
|
|
|
|
</section>
|