Option Declarations
An option declaration specifies the name, type and description
of a NixOS configuration option. It is illegal to define an option
that hasn’t been declared in any module. A option declaration
generally looks like this:
options = {
name = mkOption {
type = type specification;
default = default value;
example = example value;
description = "Description for use in the NixOS manual.";
};
};
The function mkOption accepts the following arguments.
type
The type of the option (see below). It may be omitted,
but that’s not advisable since it may lead to errors that are
hard to diagnose.
default
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 ever used, an error will be thrown.
example
An example value that will be shown in the NixOS manual.
description
A textual description of the option, in DocBook format,
that will be included in the NixOS manual.
Here is a non-exhaustive list of option types:
types.bool
A Boolean.
types.int
An integer.
types.str
A string.
types.lines
A string. If there are multiple definitions, they are
concatenated, with newline characters in between.
types.path
A path, defined as anything that, when coerced to a
string, starts with a slash. This includes derivations.
types.listOf t
A list of elements of type t
(e.g., types.listOf types.str is a list of
strings). Multiple definitions are concatenated together.
types.attrsOf t
A set of elements of type t
(e.g., types.attrsOf types.int is a set of
name/value pairs, the values being integers).
types.nullOr t
Either the value null or something of
type t.
You can also create new types using the function
mkOptionType. See
lib/types.nix in Nixpkgs for details.