Option Declarations
An option declaration specifies the name, type and description
of a NixOS configuration option. It is illegal to define an option
that has not 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.package
A derivation (such as pkgs.hello) or a
store path (such as
/nix/store/1ifi1cfbfs5iajmvwgrbmrnrw3a147h9-hello-2.10).
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.
An option declaration must follow the following rules:
A defaultText must be defined if and only if the type of the option
derives from package, packageSet or nixpkgsConfig
, and if and only if a default attribute is defined and if and only if
the value of the default attribute is not the default of the type of the
option declaration.
For example, a defaultText must be defined for
type = types.listOf types.package;
default = [ pkgs.foo; ];
defaultText = "[ pkgs.foo; ]";
.
But no defaultText must be defined for
type = types.listOf types.package;
default = [];
,
as [] is the default of types.listOf types.package.
A defaultText can be defined if the type of the option derives from
path and if a default attribute is defined.
The value of the example attribute must be wrapped with
literalExample if the type of the option derives from package,
packageSet or nixpkgsConfig.
The value of defaultText and literalExample must
be a string which contains a valid nix expression. The nix expression has to evaluate in
{pkgs}: value.
For example:
A defaultText could, e.g., be:
type = types.package;
default = pkgs.foo;
defaultText = "pkgs.foo";
But not defaultText = "pkgs.foo;";, as that
corresponds to {pkgs}: pkgs.foo;, which is an
invalid nix expression due to the ending with ;.
A literalExample could be used as, e.g.:
type = types.path;
example = literalExample "\"\${pkgs.bar}/bin/bar\"";
But not literalExample "\${pkgs.bar}/bin/bar";, as that corresponds
to {pkgs}: ${pkgs.bar}/bin/bar, which is an invalid nix expression
as the path is not a string anymore.
The type attribute must be defined for every option declaration.
NixOS ships the tool nixos-typecheck that can check an option declaration to:
Enforce that an option declaration has a defaultText if and only if the
type of the option derives from package, packageSet or
nixpkgsConfig and if a default attribute is defined.
Enforce that the value of the example attribute is wrapped with
literalExample if the type of the option derives from package,
packageSet or nixpkgsConfig.
Warn if a defaultText is defined in an option declaration if the type of
the option does not derive from package, packageSet or
nixpkgsConfig.
Warn if no type is defined in an option declaration.