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