cad8957eab
- 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.
236 lines
11 KiB
Nix
236 lines
11 KiB
Nix
# Nixpkgs/NixOS option handling.
|
||
|
||
let lib = import ./default.nix; in
|
||
|
||
with import ./trivial.nix;
|
||
with import ./lists.nix;
|
||
with import ./attrsets.nix;
|
||
with import ./strings.nix;
|
||
with {inherit (import ./types.nix) types; };
|
||
|
||
rec {
|
||
|
||
isOption = lib.isType "option";
|
||
mkOption =
|
||
{ default ? null # Default value used when no definition is given in the configuration.
|
||
, defaultText ? null # Textual representation of the default, for in the manual.
|
||
, example ? null # Example value used in the manual.
|
||
, description ? null # String describing the option.
|
||
, type ? null # Option type, providing type-checking and value merging.
|
||
, apply ? null # Function that converts the option value to something else.
|
||
, internal ? null # Whether the option is for NixOS developers only.
|
||
, visible ? null # Whether the option shows up in the manual.
|
||
, readOnly ? null # Whether the option can be set only once
|
||
, options ? null # Obsolete, used by types.optionSet.
|
||
} @ attrs:
|
||
attrs // { _type = "option"; };
|
||
|
||
mkEnableOption = name: mkOption {
|
||
default = false;
|
||
example = true;
|
||
description = "Whether to enable ${name}.";
|
||
type = lib.types.bool;
|
||
};
|
||
|
||
# This option accept anything, but it does not produce any result. This
|
||
# is useful for sharing a module across different module sets without
|
||
# having to implement similar features as long as the value of the options
|
||
# are not expected.
|
||
mkSinkUndeclaredOptions = attrs: mkOption ({
|
||
internal = true;
|
||
visible = false;
|
||
default = false;
|
||
description = "Sink for option definitions.";
|
||
type = mkOptionType {
|
||
name = "sink";
|
||
typerep = "(sink)";
|
||
check = x: true;
|
||
merge = config: loc: defs: false;
|
||
};
|
||
apply = x: throw "Option value is not readable because the option is not declared.";
|
||
} // attrs);
|
||
|
||
mergeDefaultOption = config: loc: defs:
|
||
let list = getValues defs; in
|
||
if length list == 1 then head list
|
||
else if all isFunction list then x: mergeDefaultOption config loc (map (f: f x) list)
|
||
else if all isList list then concatLists list
|
||
else if all isAttrs list then foldl' lib.mergeAttrs {} list
|
||
else if all isBool list then foldl' lib.or false list
|
||
else if all isString list then lib.concatStrings list
|
||
else if all isInt list && all (x: x == head list) list then head list
|
||
else throw "Cannot merge definitions of `${showOption loc}' given in ${showFiles (getFiles defs)}.";
|
||
|
||
mergeOneOption = config: loc: defs:
|
||
if defs == [] then abort "This case should never happen."
|
||
else if length defs != 1 then
|
||
throw "The unique option `${showOption loc}' is defined multiple times, in ${showFiles (getFiles defs)}."
|
||
else (head defs).value;
|
||
|
||
/* "Merge" option definitions by checking that they all have the same value. */
|
||
mergeEqualOption = config: loc: defs:
|
||
if defs == [] then abort "This case should never happen."
|
||
else foldl' (val: def:
|
||
if def.value != val then
|
||
throw "The option `${showOption loc}' has conflicting definitions, in ${showFiles (getFiles defs)}."
|
||
else
|
||
val) (head defs).value defs;
|
||
|
||
getValues = map (x: x.value);
|
||
getFiles = map (x: x.file);
|
||
|
||
# Generate documentation template from the list of option declaration like
|
||
# the set generated with filterOptionSets.
|
||
optionAttrSetToDocList = optionAttrSetToDocList' [];
|
||
|
||
optionAttrSetToDocList' = prefix: internalModuleConfig: options:
|
||
concatMap (opt:
|
||
let
|
||
decls = filter (x: x != unknownModule) opt.declarations;
|
||
docOption = rec {
|
||
name = showOption opt.loc;
|
||
description = opt.description or (throw "Option `${name}' has no description.");
|
||
declarations = decls;
|
||
internal = opt.internal or false;
|
||
visible = opt.visible or true;
|
||
readOnly = opt.readOnly or false;
|
||
type = opt.type.name or null;
|
||
}
|
||
// (if opt ? example then { example = detectDerivation decls opt.example; } else {})
|
||
// (if opt ? default then { default = detectDerivation decls opt.default; } else {})
|
||
// (if opt ? defaultText then { default = opt.defaultText; } else {});
|
||
|
||
subOptions =
|
||
let ss = opt.type.getSubOptionsPrefixed opt.loc;
|
||
in if ss != {} then optionAttrSetToDocList' opt.loc internalModuleConfig (ss internalModuleConfig) else [];
|
||
in
|
||
[ docOption ] ++ subOptions) (collect isOption options);
|
||
|
||
# TODO: Use "extractOptionAttrSet" instead of "optionAttrSetToDocList'" to reduce the code size.
|
||
# It should be a drop-in-replacement. But first, examine the impact on the evaluation time.
|
||
# optionAttrSetToDocList = extractOptionAttrSet true [];
|
||
|
||
# Generate a machine readable specification of the list of option declarations.
|
||
optionAttrSetToParseableSpecifications = extractOptionAttrSet false [];
|
||
|
||
extractOptionAttrSet = toDoc: prefix: internalModuleConfig: options:
|
||
concatMap (opt:
|
||
let
|
||
optionName = showOption opt.loc;
|
||
|
||
# Check if a type contains derivations, that is check if a type nests
|
||
# a 'package', 'packageSet' or 'nixpkgsConfig' type.
|
||
hasDerivation = any (t: elem t opt.type.nestedTypes) ((map (x: x.typerep) (with types; [package packageSet])) ++ ["(nixpkgsConfig)"]);
|
||
|
||
# Check if type is 'path' which can potentially contain a derivation.
|
||
maybeHiddenDerivation = any (t: elem t opt.type.nestedTypes) (map (x: x.typerep) (with types; [path]));
|
||
|
||
isDefaultValue = elem opt.default opt.type.defaultValues;
|
||
|
||
/* Enforce that the example attribute is wrapped with 'literalExample'
|
||
for every type that contains derivations. */
|
||
example =
|
||
if opt ? example
|
||
then (if hasDerivation
|
||
then (if isLiteralExample opt.example
|
||
then { example = detectDerivation decls opt.example; }
|
||
else throw "The attribute ${optionName}.example must be wrapped with 'literalExample' in ${concatStringsSep " and " decls}!")
|
||
else { example = detectDerivation decls opt.example; })
|
||
else {};
|
||
|
||
/* Enforce that the 'defaultText' attribute is defined for every option
|
||
that has a 'default' attribute that contains derivations. */
|
||
default =
|
||
if opt ? default
|
||
then (if hasDerivation
|
||
then (if isDefaultValue
|
||
then { default = opt.default; }
|
||
else (if opt ? defaultText
|
||
then { default = literalExample (detectDerivation decls opt.defaultText); }
|
||
else throw "The option ${optionName} requires a 'defaultText' attribute in ${concatStringsSep " and " decls}!"))
|
||
else (if opt ? defaultText
|
||
then (if maybeHiddenDerivation
|
||
then (if (let eval = builtins.tryEval (findDerivation opt.default); in eval.success && !eval.value)
|
||
then builtins.trace
|
||
"The attribute ${optionName}.defaultText might not be necessary in ${concatStringsSep " and " decls}!"
|
||
{ default = literalExample (detectDerivation decls opt.defaultText); }
|
||
else { default = literalExample (detectDerivation decls opt.defaultText); })
|
||
else builtins.trace
|
||
"The attribute ${optionName}.defaultText is not used and can be removed in ${concatStringsSep " and " decls}!"
|
||
{ default = detectDerivation decls opt.default; })
|
||
else { default = detectDerivation decls opt.default; }))
|
||
else {};
|
||
|
||
decls = filter (x: x != unknownModule) opt.declarations;
|
||
|
||
docOption = {
|
||
name = optionName;
|
||
description = opt.description or (throw "Option `${optionName}' has no description.");
|
||
declarations = decls;
|
||
internal = opt.internal or false;
|
||
visible = opt.visible or true;
|
||
readOnly = opt.readOnly or false;
|
||
} // example // default // subOptions // typeKeys;
|
||
|
||
typeKeys = if toDoc then { type = opt.type.name or null; } else { type = opt.type.typerep; keys = opt.loc; };
|
||
|
||
subOptions =
|
||
if toDoc
|
||
then {}
|
||
else let ss = opt.type.getSubOptions;
|
||
in if ss != {} then { suboptions = (extractOptionAttrSet false [] internalModuleConfig (ss internalModuleConfig)); } else {};
|
||
|
||
subOptionsDoc =
|
||
if toDoc
|
||
then let ss = opt.type.getSubOptionsPrefixed opt.loc;
|
||
in if ss != {} then extractOptionAttrSet true opt.loc internalModuleConfig (ss internalModuleConfig) else []
|
||
else [];
|
||
in
|
||
[ docOption ] ++ subOptionsDoc )
|
||
(filter (opt: (opt.visible or true) && !(opt.internal or false)) (collect isOption options));
|
||
|
||
|
||
/* This function recursively checks for derivations within an
|
||
an expression, and throws an error if a derivation or a
|
||
store path is found. The function is used to ensure that no
|
||
derivation leaks from the 'default' or 'example' attributes
|
||
of an option.
|
||
This makes 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. */
|
||
detectDerivation = decl: x:
|
||
if isDerivation x then
|
||
throw "Found unexpected derivation in '${x.name}' in '${concatStringsSep " and " decl}'!"
|
||
else if isString x && isStorePath x then
|
||
throw "Found unexpected store path in '${x.name}' in '${concatStringsSep " and " decl}'!"
|
||
else if isList x then map (detectDerivation decl) x
|
||
else if isAttrs x then mapAttrs (n: v: (detectDerivation decl) v) (removeAttrs x ["_args"])
|
||
else x;
|
||
|
||
/* Same as detectDerivation, but returns a boolean instead of
|
||
throwing an exception. */
|
||
findDerivation = x:
|
||
if (isString x && isStorePath x) || isDerivation x then true
|
||
else if isList x then any findDerivation x
|
||
else if isAttrs x then any findDerivation (mapAttrsToList (_: v: v) (removeAttrs x ["_args"]))
|
||
else false;
|
||
|
||
|
||
|
||
/* 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. */
|
||
# TODO: A more general name would probably be "literalNix".
|
||
literalExample = text: { _type = "literalExample"; inherit text; };
|
||
|
||
isLiteralExample = x: isAttrs x && hasAttr "_type" x && x._type == "literalExample";
|
||
|
||
|
||
/* Helper functions. */
|
||
showOption = concatStringsSep ".";
|
||
showFiles = files: concatStringsSep " and " (map (f: "`${f}'") files);
|
||
unknownModule = "<unknown-file>";
|
||
|
||
}
|