nixpkgs/lib/options.nix
Eelco Dolstra 0e333688ce Big cleanup of the NixOS module system
The major changes are:

* The evaluation is now driven by the declared options.  In
  particular, this fixes the long-standing problem with lack of
  laziness of disabled option definitions.  Thus, a configuration like

    config = mkIf false {
      environment.systemPackages = throw "bla";
    };

  will now evaluate without throwing an error.  This also improves
  performance since we're not evaluating unused option definitions.

* The implementation of properties is greatly simplified.

* There is a new type constructor "submodule" that replaces
  "optionSet".  Unlike "optionSet", "submodule" gets its option
  declarations as an argument, making it more like "listOf" and other
  type constructors.  A typical use is:

    foo = mkOption {
      type = type.attrsOf (type.submodule (
        { config, ... }:
        { bar = mkOption { ... };
          xyzzy = mkOption { ... };
        }));
    };

  Existing uses of "optionSet" are automatically mapped to
  "submodule".

* Modules are now checked for unsupported attributes: you get an error
  if a module contains an attribute other than "config", "options" or
  "imports".

* The new implementation is faster and uses much less memory.
2013-10-28 22:45:55 +01:00

274 lines
9.2 KiB
Nix
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Nixpkgs/NixOS option handling.
let lib = import ./default.nix; in
with import ./trivial.nix;
with import ./lists.nix;
with import ./misc.nix;
with import ./attrsets.nix;
rec {
isOption = lib.isType "option";
mkOption = attrs: attrs // {
_type = "option";
# name (this is the name of the attributem it is automatically generated by the traversal)
# default (value used when no definition exists)
# example (documentation)
# description (documentation)
# type (option type, provide a default merge function and ensure type correctness)
# merge (function used to merge definitions into one definition: [ /type/ ] -> /type/)
# apply (convert the option value to ease the manipulation of the option result)
# options (set of sub-options declarations & definitions)
# extraConfigs (list of possible configurations)
};
mkEnableOption = name: mkOption {
default = false;
example = true;
description = "Whether to enable ${name}.";
type = lib.types.bool;
};
mapSubOptions = f: opt:
if opt ? options then
opt // {
options = imap f (toList opt.options);
}
else
opt;
# Make the option declaration more user-friendly by adding default
# settings and some verifications based on the declaration content (like
# type correctness).
addOptionMakeUp = {name, recurseInto}: decl:
let
init = {
inherit name;
merge = mergeDefaultOption;
apply = lib.id;
};
functionsFromType = opt:
opt // (builtins.intersectAttrs { merge = 1; check = 1; } (decl.type or {}));
addDeclaration = opt: opt // decl;
ensureMergeInputType = opt:
if opt ? check then
opt // {
merge = list:
if all opt.check list then
opt.merge list
else
throw "A value of the option `${name}' has a bad type.";
}
else opt;
checkDefault = opt:
if opt ? check && opt ? default then
opt // {
default =
if opt.check opt.default then
opt.default
else
throw "The default value of the option `${name}' has a bad type.";
}
else opt;
handleOptionSets = opt:
if opt ? type && opt.type.hasOptions then
let
# Evaluate sub-modules.
subModuleMerge = path: vals:
lib.fix (args:
let
result = recurseInto path (opt.options ++ imap (index: v: args: {
key = rec {
#!!! Would be nice if we had the file the val was from
option = path;
number = index;
outPath = "option ${option} config number ${toString number}";
};
} // (lib.applyIfFunction v args)) (toList vals)) args;
name = lib.removePrefix (opt.name + ".") path;
extraArgs = opt.extraArgs or {};
individualExtraArgs = opt.individualExtraArgs or {};
in {
inherit (result) config options;
inherit name;
} //
(opt.extraArgs or {}) //
(if hasAttr name individualExtraArgs then getAttr name individualExtraArgs else {})
);
# Add _options in sub-modules to make it viewable from other
# modules.
subModuleMergeConfig = path: vals:
let result = subModuleMerge path vals; in
{ _args = result; } // result.config;
in
opt // {
merge = list:
opt.type.iter
subModuleMergeConfig
opt.name
(opt.merge list);
options =
let path = opt.type.docPath opt.name; in
(subModuleMerge path []).options;
}
else
opt;
in
foldl (opt: f: f opt) init [
# default settings
functionsFromType
# user settings
addDeclaration
# override settings
ensureMergeInputType
checkDefault
handleOptionSets
];
# !!! This function will be removed because this can be done with the
# multiple option declarations.
addDefaultOptionValues = defs: opts: opts //
builtins.listToAttrs (map (defName:
{ name = defName;
value =
let
defValue = builtins.getAttr defName defs;
optValue = builtins.getAttr defName opts;
in
if isOption defValue
then
# `defValue' is an option.
if hasAttr defName opts
then builtins.getAttr defName opts
else defValue.default
else
# `defValue' is an attribute set containing options.
# So recurse.
if hasAttr defName opts && isAttrs optValue
then addDefaultOptionValues defValue optValue
else addDefaultOptionValues defValue {};
}
) (attrNames defs));
mergeDefaultOption = list:
if length list == 1 then head list
else if all builtins.isFunction list then x: mergeDefaultOption (map (f: f x) list)
else if all isList list then concatLists list
else if all isAttrs list then fold lib.mergeAttrs {} list
else if all builtins.isBool list then fold lib.or false list
else if all builtins.isString list then lib.concatStrings list
else if all builtins.isInt list && all (x: x == head list) list
then head list
else throw "Cannot merge values.";
mergeTypedOption = typeName: predicate: merge: list:
if all predicate list then merge list
else throw "Expect a ${typeName}.";
mergeEnableOption = mergeTypedOption "boolean"
(x: true == x || false == x) (fold lib.or false);
mergeListOption = mergeTypedOption "list" isList concatLists;
mergeStringOption = mergeTypedOption "string"
(x: if builtins ? isString then builtins.isString x else x + "")
lib.concatStrings;
mergeOneOption = list:
if list == [] then abort "This case should never happen."
else if length list != 1 then throw "Multiple definitions. Only one is allowed for this option."
else head list;
fixableMergeFun = merge: f: config:
merge (
# generate the list of option sets.
f config
);
fixableMergeModules = merge: initModules: {...}@args: config:
fixableMergeFun merge (config:
lib.moduleClosure initModules (args // { inherit config; })
) config;
fixableDefinitionsOf = initModules: {...}@args:
fixableMergeModules (modules: (lib.moduleMerge "" modules).config) initModules args;
fixableDeclarationsOf = initModules: {...}@args:
fixableMergeModules (modules: (lib.moduleMerge "" modules).options) initModules args;
definitionsOf = initModules: {...}@args:
(lib.fix (module:
fixableMergeModules (lib.moduleMerge "") initModules args module.config
)).config;
declarationsOf = initModules: {...}@args:
(lib.fix (module:
fixableMergeModules (lib.moduleMerge "") initModules args module.config
)).options;
# Generate documentation template from the list of option declaration like
# the set generated with filterOptionSets.
optionAttrSetToDocList = attrs:
let options = collect isOption attrs; in
fold (opt: rest:
let
docOption = {
inherit (opt) name;
description = opt.description or (throw "Option ${opt.name}: No description.");
declarations = map (x: toString x.source) opt.declarations;
#definitions = map (x: toString x.source) opt.definitions;
internal = opt.internal or false;
visible = opt.visible or true;
}
// optionalAttrs (opt ? example) { example = scrubOptionValue opt.example; }
// optionalAttrs (opt ? default) { default = scrubOptionValue opt.default; }
// optionalAttrs (opt ? defaultText) { default = opt.defaultText; };
subOptions =
if opt ? options then
optionAttrSetToDocList opt.options
else
[];
in
# FIXME: expensive (O(n^2)
[ docOption ] ++ subOptions ++ rest
) [] options;
/* This function recursively removes all derivation attributes from
`x' except for the `name' attribute. This is to make the
generation of `options.xml' much more efficient: the XML
representation of derivations is very large (on the order of
megabytes) and is not actually used by the manual generator. */
scrubOptionValue = x:
if isDerivation x then { type = "derivation"; drvPath = x.name; outPath = x.name; name = x.name; }
else if isList x then map scrubOptionValue x
else if isAttrs x then mapAttrs (n: v: scrubOptionValue v) (removeAttrs x ["_args"])
else x;
/* For use in the example option attribute. It causes the given
text to be included verbatim in documentation. This is necessary
for example values that are not simple values, e.g.,
functions. */
literalExample = text: { _type = "literalExample"; inherit text; };
/* Helper functions. */
showOption = concatStringsSep ".";
}