path: root/lib/modules.nix

{ lib }:

with lib.lists;
with lib.strings;
with lib.trivial;
with lib.attrsets;
with lib.options;
with lib.debug;
with lib.types;

rec {

  /* Evaluate a set of modules.  The result is a set of two
     attributes: ‘options’: the nested set of all option declarations,
     and ‘config’: the nested set of all option values.
     !!! Please think twice before adding to this argument list! The more
     that is specified here instead of in the modules themselves the harder
     it is to transparently move a set of modules to be a submodule of another
     config (as the proper arguments need to be replicated at each call to
     evalModules) and the less declarative the module set is. */
  evalModules = { modules
                , prefix ? []
                , # This should only be used for special arguments that need to be evaluated
                  # when resolving module structure (like in imports). For everything else,
                  # there's _module.args. If specialArgs.modulesPath is defined it will be
                  # used as the base path for disabledModules.
                  specialArgs ? {}
                , # This would be remove in the future, Prefer _module.args option instead.
                  args ? {}
                , # This would be remove in the future, Prefer _module.check option instead.
                  check ? true
                }:
    let
      # This internal module declare internal options under the `_module'
      # attribute.  These options are fragile, as they are used by the
      # module system to change the interpretation of modules.
      internalModule = rec {
        _file = ./modules.nix;

        key = _file;

        options = {
          _module.args = mkOption {
            type = types.attrsOf types.unspecified;
            internal = true;
            description = "Arguments passed to each module.";
          };

          _module.check = mkOption {
            type = types.bool;
            internal = true;
            default = check;
            description = "Whether to check whether all option definitions have matching declarations.";
          };
        };

        config = {
          _module.args = args;
        };
      };

      closed = closeModules (modules ++ [ internalModule ]) ({ inherit config options lib; } // specialArgs);

      options = mergeModules prefix (reverseList (filterModules (specialArgs.modulesPath or "") closed));

      # Traverse options and extract the option values into the final
      # config set.  At the same time, check whether all option
      # definitions have matching declarations.
      # !!! _module.check's value can't depend on any other config values
      # without an infinite recursion. One way around this is to make the
      # 'config' passed around to the modules be unconditionally unchecked,
      # and only do the check in 'result'.
      config = yieldConfig prefix options;
      yieldConfig = prefix: set:
        let res = removeAttrs (mapAttrs (n: v:
          if isOption v then v.value
          else yieldConfig (prefix ++ [n]) v) set) ["_definedNames"];
        in
        if options._module.check.value && set ? _definedNames then
          foldl' (res: m:
            foldl' (res: name:
              if set ? ${name} then res else throw "The option `${showOption (prefix ++ [name])}' defined in `${m.file}' does not exist.")
              res m.names)
            res set._definedNames
        else
          res;
      result = { inherit options config; };
    in result;


 # Filter disabled modules. Modules can be disabled allowing
 # their implementation to be replaced.
 filterModules = modulesPath: modules:
   let
     moduleKey = m: if isString m then toString modulesPath + "/" + m else toString m;
     disabledKeys = map moduleKey (concatMap (m: m.disabledModules) modules);
   in
     filter (m: !(elem m.key disabledKeys)) modules;

  /* Close a set of modules under the ‘imports’ relation. */
  closeModules = modules: args:
    let
      toClosureList = file: parentKey: imap1 (n: x:
        if isAttrs x || isFunction x then
          let key = "${parentKey}:anon-${toString n}"; in
          unifyModuleSyntax file key (unpackSubmodule (applyIfFunction key) x args)
        else
          let file = toString x; key = toString x; in
          unifyModuleSyntax file key (applyIfFunction key (import x) args));
    in
      builtins.genericClosure {
        startSet = toClosureList unknownModule "" modules;
        operator = m: toClosureList m.file m.key m.imports;
      };

  /* Massage a module into canonical form, that is, a set consisting
     of ‘options’, ‘config’ and ‘imports’ attributes. */
  unifyModuleSyntax = file: key: m:
    let metaSet = if m ? meta
      then { meta = m.meta; }
      else {};
    in
    if m ? config || m ? options then
      let badAttrs = removeAttrs m ["_file" "key" "disabledModules" "imports" "options" "config" "meta"]; in
      if badAttrs != {} then
        throw "Module `${key}' has an unsupported attribute `${head (attrNames badAttrs)}'. This is caused by assignments to the top-level attributes `config' or `options'."
      else
        { file = m._file or file;
          key = toString m.key or key;
          disabledModules = m.disabledModules or [];
          imports = m.imports or [];
          options = m.options or {};
          config = mkMerge [ (m.config or {}) metaSet ];
        }
    else
      { file = m._file or file;
        key = toString m.key or key;
        disabledModules = m.disabledModules or [];
        imports = m.require or [] ++ m.imports or [];
        options = {};
        config = mkMerge [ (removeAttrs m ["_file" "key" "disabledModules" "require" "imports"]) metaSet ];
      };

  applyIfFunction = key: f: args@{ config, options, lib, ... }: if isFunction f then
    let
      # Module arguments are resolved in a strict manner when attribute set
      # deconstruction is used.  As the arguments are now defined with the
      # config._module.args option, the strictness used on the attribute
      # set argument would cause an infinite loop, if the result of the
      # option is given as argument.
      #
      # To work-around the strictness issue on the deconstruction of the
      # attributes set argument, we create a new attribute set which is
      # constructed to satisfy the expected set of attributes.  Thus calling
      # a module will resolve strictly the attributes used as argument but
      # not their values.  The values are forwarding the result of the
      # evaluation of the option.
      requiredArgs = builtins.attrNames (lib.functionArgs f);
      context = name: ''while evaluating the module argument `${name}' in "${key}":'';
      extraArgs = builtins.listToAttrs (map (name: {
        inherit name;
        value = builtins.addErrorContext (context name)
          (args.${name} or config._module.args.${name});
      }) requiredArgs);

      # Note: we append in the opposite order such that we can add an error
      # context on the explicited arguments of "args" too. This update
      # operator is used to make the "args@{ ... }: with args.lib;" notation
      # works.
    in f (args // extraArgs)
  else
    f;

  /* We have to pack and unpack submodules. We cannot wrap the expected
     result of the function as we would no longer be able to list the arguments
     of the submodule. (see applyIfFunction) */
  unpackSubmodule = unpack: m: args:
    if isType "submodule" m then
      { _file = m.file; } // (unpack m.submodule args)
    else unpack m args;

  packSubmodule = file: m:
    { _type = "submodule"; file = file; submodule = m; };

  /* Merge a list of modules.  This will recurse over the option
     declarations in all modules, combining them into a single set.
     At the same time, for each option declaration, it will merge the
     corresponding option definitions in all machines, returning them
     in the ‘value’ attribute of each option. */
  mergeModules = prefix: modules:
    mergeModules' prefix modules
      (concatMap (m: map (config: { inherit (m) file; inherit config; }) (pushDownProperties m.config)) modules);

  mergeModules' = prefix: options: configs:
    let
     /* byName is like foldAttrs, but will look for attributes to merge in the
        specified attribute name.

        byName "foo" (module: value: ["module.hidden=${module.hidden},value=${value}"])
        [
          {
            hidden="baz";
            foo={qux="bar"; gla="flop";};
          }
          {
            hidden="fli";
            foo={qux="gne"; gli="flip";};
          }
        ]
        ===>
        {
          gla = [ "module.hidden=baz,value=flop" ];
          gli = [ "module.hidden=fli,value=flip" ];
          qux = [ "module.hidden=baz,value=bar" "module.hidden=fli,value=gne" ];
        }
      */
      byName = attr: f: modules:
        foldl' (acc: module:
                acc // (mapAttrs (n: v:
                                   (acc.${n} or []) ++ f module v
                                 ) module.${attr}
                       )
               ) {} modules;
      # an attrset 'name' => list of submodules that declare ‘name’.
      declsByName = byName "options" (module: option:
          [{ inherit (module) file; options = option; }]
        ) options;
      # an attrset 'name' => list of submodules that define ‘name’.
      defnsByName = byName "config" (module: value:
          map (config: { inherit (module) file; inherit config; }) (pushDownProperties value)
        ) configs;
      # extract the definitions for each loc
      defnsByName' = byName "config" (module: value:
          [{ inherit (module) file; inherit value; }]
        ) configs;
    in
    (flip mapAttrs declsByName (name: decls:
      # We're descending into attribute ‘name’.
        let
          loc = prefix ++ [name];
          defns = defnsByName.${name} or [];
          defns' = defnsByName'.${name} or [];
          nrOptions = count (m: isOption m.options) decls;
        in
          if nrOptions == length decls then
            let opt = fixupOptionType loc (mergeOptionDecls loc decls);
            in evalOptionValue loc opt defns'
          else if nrOptions != 0 then
            let
              firstOption = findFirst (m: isOption m.options) "" decls;
              firstNonOption = findFirst