lib/options.nix

   1 # Nixpkgs/NixOS option handling.
   2 { lib }:
   3
   4 let
   5   inherit (lib)
   6     all
   7     collect
   8     concatLists
   9     concatMap
  10     concatMapStringsSep
  11     filter
  12     foldl'
  13     head
  14     tail
  15     isAttrs
  16     isBool
  17     isDerivation
  18     isFunction
  19     isInt
  20     isList
  21     isString
  22     length
  23     mapAttrs
  24     optional
  25     optionals
  26     take
  27     ;
  28   inherit (lib.attrsets)
  29     attrByPath
  30     optionalAttrs
  31     ;
  32   inherit (lib.strings)
  33     concatMapStrings
  34     concatStringsSep
  35     ;
  36   inherit (lib.types)
  37     mkOptionType
  38     ;
  39   inherit (lib.lists)
  40     last
  41     ;
  42   prioritySuggestion = ''
  43    Use `lib.mkForce value` or `lib.mkDefault value` to change the priority on any of these definitions.
  44   '';
  45 in
  46 rec {
  47
  48   /* Returns true when the given argument is an option
  49
  50      Type: isOption :: a -> bool
  51
  52      Example:
  53        isOption 1             // => false
  54        isOption (mkOption {}) // => true
  55   */
  56   isOption = lib.isType "option";
  57
  58   /* Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
  59
  60      All keys default to `null` when not given.
  61
  62      Example:
  63        mkOption { }  // => { _type = "option"; }
  64        mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; }
  65   */
  66   mkOption =
  67     {
  68     # Default value used when no definition is given in the configuration.
  69     default ? null,
  70     # Textual representation of the default, for the manual.
  71     defaultText ? null,
  72     # Example value used in the manual.
  73     example ? null,
  74     # String describing the option.
  75     description ? null,
  76     # Related packages used in the manual (see `genRelatedPackages` in ../nixos/lib/make-options-doc/default.nix).
  77     relatedPackages ? null,
  78     # Option type, providing type-checking and value merging.
  79     type ? null,
  80     # Function that converts the option value to something else.
  81     apply ? null,
  82     # Whether the option is for NixOS developers only.
  83     internal ? null,
  84     # Whether the option shows up in the manual. Default: true. Use false to hide the option and any sub-options from submodules. Use "shallow" to hide only sub-options.
  85     visible ? null,
  86     # Whether the option can be set only once
  87     readOnly ? null,
  88     } @ attrs:
  89     attrs // { _type = "option"; };
  90
  91   /* Creates an Option attribute set for a boolean value option i.e an
  92      option to be toggled on or off:
  93
  94      Example:
  95        mkEnableOption "foo"
  96        => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
  97   */
  98   mkEnableOption =
  99     # Name for the created option
 100     name: mkOption {
 101     default = false;
 102     example = true;
 103     description = "Whether to enable ${name}.";
 104     type = lib.types.bool;
 105   };
 106
 107   /* Creates an Option attribute set for an option that specifies the
 108      package a module should use for some purpose.
 109
 110      The package is specified in the third argument under `default` as a list of strings
 111      representing its attribute path in nixpkgs (or another package set).
 112      Because of this, you need to pass nixpkgs itself (usually `pkgs` in a module;
 113      alternatively to nixpkgs itself, another package set) as the first argument.
 114
 115      If you pass another package set you should set the `pkgsText` option.
 116      This option is used to display the expression for the package set. It is `"pkgs"` by default.
 117      If your expression is complex you should parenthesize it, as the `pkgsText` argument
 118      is usually immediately followed by an attribute lookup (`.`).
 119
 120      The second argument may be either a string or a list of strings.
 121      It provides the display name of the package in the description of the generated option
 122      (using only the last element if the passed value is a list)
 123      and serves as the fallback value for the `default` argument.
 124
 125      To include extra information in the description, pass `extraDescription` to
 126      append arbitrary text to the generated description.
 127
 128      You can also pass an `example` value, either a literal string or an attribute path.
 129
 130      The `default` argument can be omitted if the provided name is
 131      an attribute of pkgs (if `name` is a string) or a valid attribute path in pkgs (if `name` is a list).
 132      You can also set `default` to just a string in which case it is interpreted as an attribute name
 133      (a singleton attribute path, if you will).
 134
 135      If you wish to explicitly provide no default, pass `null` as `default`.
 136
 137      If you want users to be able to set no package, pass `nullable = true`.
 138      In this mode a `default = null` will not be interpreted as no default and is interpreted literally.
 139
 140      Type: mkPackageOption :: pkgs -> (string|[string]) -> { nullable? :: bool, default? :: string|[string], example? :: null|string|[string], extraDescription? :: string, pkgsText? :: string } -> option
 141
 142      Example:
 143        mkPackageOption pkgs "hello" { }
 144        => { ...; default = pkgs.hello; defaultText = literalExpression "pkgs.hello"; description = "The hello package to use."; type = package; }
 145
 146      Example:
 147        mkPackageOption pkgs "GHC" {
 148          default = [ "ghc" ];
 149          example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
 150        }
 151        => { ...; default = pkgs.ghc; defaultText = literalExpression "pkgs.ghc"; description = "The GHC package to use."; example = literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])"; type = package; }
 152
 153      Example:
 154        mkPackageOption pkgs [ "python3Packages" "pytorch" ] {
 155          extraDescription = "This is an example and doesn't actually do anything.";
 156        }
 157        => { ...; default = pkgs.python3Packages.pytorch; defaultText = literalExpression "pkgs.python3Packages.pytorch"; description = "The pytorch package to use. This is an example and doesn't actually do anything."; type = package; }
 158
 159      Example:
 160        mkPackageOption pkgs "nushell" {
 161          nullable = true;
 162        }
 163        => { ...; default = pkgs.nushell; defaultText = literalExpression "pkgs.nushell"; description = "The nushell package to use."; type = nullOr package; }
 164
 165      Example:
 166        mkPackageOption pkgs "coreutils" {
 167          default = null;
 168        }
 169        => { ...; description = "The coreutils package to use."; type = package; }
 170
 171      Example:
 172        mkPackageOption pkgs "dbus" {
 173          nullable = true;
 174          default = null;
 175        }
 176        => { ...; default = null; description = "The dbus package to use."; type = nullOr package; }
 177
 178      Example:
 179        mkPackageOption pkgs.javaPackages "OpenJFX" {
 180          default = "openjfx20";
 181          pkgsText = "pkgs.javaPackages";
 182        }
 183        => { ...; default = pkgs.javaPackages.openjfx20; defaultText = literalExpression "pkgs.javaPackages.openjfx20"; description = "The OpenJFX package to use."; type = package; }
 184   */
 185   mkPackageOption =
 186     # Package set (an instantiation of nixpkgs such as pkgs in modules or another package set)
 187     pkgs:
 188       # Name for the package, shown in option description
 189       name:
 190       {
 191         # Whether the package can be null, for example to disable installing a package altogether (defaults to false)
 192         nullable ? false,
 193         # The attribute path where the default package is located (may be omitted, in which case it is copied from `name`)
 194         default ? name,
 195         # A string or an attribute path to use as an example (may be omitted)
 196         example ? null,
 197         # Additional text to include in the option description (may be omitted)
 198         extraDescription ? "",
 199         # Representation of the package set passed as pkgs (defaults to `"pkgs"`)
 200         pkgsText ? "pkgs"
 201       }:
 202       let
 203         name' = if isList name then last name else name;
 204         default' = if isList default then default else [ default ];
 205         defaultText = concatStringsSep "." default';
 206         defaultValue = attrByPath default'
 207           (throw "${defaultText} cannot be found in ${pkgsText}") pkgs;
 208         defaults = if default != null then {
 209           default = defaultValue;
 210           defaultText = literalExpression ("${pkgsText}." + defaultText);
 211         } else optionalAttrs nullable {
 212           default = null;
 213         };
 214       in mkOption (defaults // {
 215         description = "The ${name'} package to use."
 216           + (if extraDescription == "" then "" else " ") + extraDescription;
 217         type = with lib.types; (if nullable then nullOr else lib.id) package;
 218       } // optionalAttrs (example != null) {
 219         example = literalExpression
 220           (if isList example then "${pkgsText}." + concatStringsSep "." example else example);
 221       });
 222
 223   /* Alias of mkPackageOption. Previously used to create options with markdown
 224      documentation, which is no longer required.
 225   */
 226   mkPackageOptionMD = mkPackageOption;
 227
 228   /* This option accepts anything, but it does not produce any result.
 229
 230      This is useful for sharing a module across different module sets
 231      without having to implement similar features as long as the
 232      values of the options are not accessed. */
 233   mkSinkUndeclaredOptions = attrs: mkOption ({
 234     internal = true;
 235     visible = false;
 236     default = false;
 237     description = "Sink for option definitions.";
 238     type = mkOptionType {
 239       name = "sink";
 240       check = x: true;
 241       merge = loc: defs: false;
 242     };
 243     apply = x: throw "Option value is not readable because the option is not declared.";
 244   } // attrs);
 245
 246   mergeDefaultOption = loc: defs:
 247     let list = getValues defs; in
 248     if length list == 1 then head list
 249     else if all isFunction list then x: mergeDefaultOption loc (map (f: f x) list)
 250     else if all isList list then concatLists list
 251     else if all isAttrs list then foldl' lib.mergeAttrs {} list
 252     else if all isBool list then foldl' lib.or false list
 253     else if all isString list then lib.concatStrings list
 254     else if all isInt list && all (x: x == head list) list then head list
 255     else throw "Cannot merge definitions of `${showOption loc}'. Definition values:${showDefs defs}";
 256
 257   mergeOneOption = mergeUniqueOption { message = ""; };
 258
 259   mergeUniqueOption = { message }: loc: defs:
 260     if length defs == 1
 261     then (head defs).value
 262     else assert length defs > 1;
 263       throw "The option `${showOption loc}' is defined multiple times while it's expected to be unique.\n${message}\nDefinition values:${showDefs defs}\n${prioritySuggestion}";
 264
 265   /* "Merge" option definitions by checking that they all have the same value. */
 266   mergeEqualOption = loc: defs:
 267     if defs == [] then abort "This case should never happen."
 268     # Return early if we only have one element
 269     # This also makes it work for functions, because the foldl' below would try
 270     # to compare the first element with itself, which is false for functions
 271     else if length defs == 1 then (head defs).value
 272     else (foldl' (first: def:
 273       if def.value != first.value then
 274         throw "The option `${showOption loc}' has conflicting definition values:${showDefs [ first def ]}\n${prioritySuggestion}"
 275       else
 276         first) (head defs) (tail defs)).value;
 277
 278   /* Extracts values of all "value" keys of the given list.
 279
 280      Type: getValues :: [ { value :: a; } ] -> [a]
 281
 282      Example:
 283        getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
 284        getValues [ ]                               // => [ ]
 285   */
 286   getValues = map (x: x.value);
 287
 288   /* Extracts values of all "file" keys of the given list
 289
 290      Type: getFiles :: [ { file :: a; } ] -> [a]
 291
 292      Example:
 293        getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
 294        getFiles [ ]                                         // => [ ]
 295   */
 296   getFiles = map (x: x.file);
 297
 298   # Generate documentation template from the list of option declaration like
 299   # the set generated with filterOptionSets.
 300   optionAttrSetToDocList = optionAttrSetToDocList' [];
 301
 302   optionAttrSetToDocList' = _: options:
 303     concatMap (opt:
 304       let
 305         name = showOption opt.loc;
 306         docOption = {
 307           loc = opt.loc;
 308           inherit name;
 309           description = opt.description or null;
 310           declarations = filter (x: x != unknownModule) opt.declarations;
 311           internal = opt.internal or false;
 312           visible =
 313             if (opt?visible && opt.visible == "shallow")
 314             then true
 315             else opt.visible or true;
 316           readOnly = opt.readOnly or false;
 317           type = opt.type.description or "unspecified";
 318         }
 319         // optionalAttrs (opt ? example) {
 320           example =
 321             builtins.addErrorContext "while evaluating the example of option `${name}`" (
 322               renderOptionValue opt.example
 323             );
 324         }
 325         // optionalAttrs (opt ? defaultText || opt ? default) {
 326           default =
 327             builtins.addErrorContext "while evaluating the ${if opt?defaultText then "defaultText" else "default value"} of option `${name}`" (
 328               renderOptionValue (opt.defaultText or opt.default)
 329             );
 330         }
 331         // optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) { inherit (opt) relatedPackages; };
 332
 333         subOptions =
 334           let ss = opt.type.getSubOptions opt.loc;
 335           in if ss != {} then optionAttrSetToDocList' opt.loc ss else [];
 336         subOptionsVisible = docOption.visible && opt.visible or null != "shallow";
 337       in
 338         # To find infinite recursion in NixOS option docs:
 339         # builtins.trace opt.loc
 340         [ docOption ] ++ optionals subOptionsVisible subOptions) (collect isOption options);
 341
 342
 343   /* This function recursively removes all derivation attributes from
 344      `x` except for the `name` attribute.
 345
 346      This is to make the generation of `options.xml` much more
 347      efficient: the XML representation of derivations is very large
 348      (on the order of megabytes) and is not actually used by the
 349      manual generator.
 350
 351      This function was made obsolete by renderOptionValue and is kept for
 352      compatibility with out-of-tree code.
 353   */
 354   scrubOptionValue = x:
 355     if isDerivation x then
 356       { type = "derivation"; drvPath = x.name; outPath = x.name; name = x.name; }
 357     else if isList x then map scrubOptionValue x
 358     else if isAttrs x then mapAttrs (n: v: scrubOptionValue v) (removeAttrs x ["_args"])
 359     else x;
 360
 361
 362   /* Ensures that the given option value (default or example) is a `_type`d string
 363      by rendering Nix values to `literalExpression`s.
 364   */
 365   renderOptionValue = v:
 366     if v ? _type && v ? text then v
 367     else literalExpression (lib.generators.toPretty {
 368       multiline = true;
 369       allowPrettyValues = true;
 370     } v);
 371
 372
 373   /* For use in the `defaultText` and `example` option attributes. Causes the
 374      given string to be rendered verbatim in the documentation as Nix code. This
 375      is necessary for complex values, e.g. functions, or values that depend on
 376      other values or packages.
 377   */
 378   literalExpression = text:
 379     if ! isString text then throw "literalExpression expects a string."
 380     else { _type = "literalExpression"; inherit text; };
 381
 382   literalExample = lib.warn "literalExample is deprecated, use literalExpression instead, or use literalMD for a non-Nix description." literalExpression;
 383
 384   /* Transition marker for documentation that's already migrated to markdown
 385      syntax. This is a no-op and no longer needed.
 386   */
 387   mdDoc = lib.id;
 388
 389   /* For use in the `defaultText` and `example` option attributes. Causes the
 390      given MD text to be inserted verbatim in the documentation, for when
 391      a `literalExpression` would be too hard to read.
 392   */
 393   literalMD = text:
 394     if ! isString text then throw "literalMD expects a string."
 395     else { _type = "literalMD"; inherit text; };
 396
 397   # Helper functions.
 398
 399   /* Convert an option, described as a list of the option parts to a
 400      human-readable version.
 401
 402      Example:
 403        (showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
 404        (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
 405        (showOption ["windowManager" "2bwm" "enable"]) == "windowManager.\"2bwm\".enable"
 406
 407      Placeholders will not be quoted as they are not actual values:
 408        (showOption ["foo" "*" "bar"]) == "foo.*.bar"
 409        (showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"
 410   */
 411   showOption = parts: let
 412     escapeOptionPart = part:
 413       let
 414         # We assume that these are "special values" and not real configuration data.
 415         # If it is real configuration data, it is rendered incorrectly.
 416         specialIdentifiers = [
 417           "<name>"          # attrsOf (submodule {})
 418           "*"               # listOf (submodule {})
 419           "<function body>" # functionTo
 420         ];
 421       in if builtins.elem part specialIdentifiers
 422          then part
 423          else lib.strings.escapeNixIdentifier part;
 424     in (concatStringsSep ".") (map escapeOptionPart parts);
 425   showFiles = files: concatStringsSep " and " (map (f: "`${f}'") files);
 426
 427   showDefs = defs: concatMapStrings (def:
 428     let
 429       # Pretty print the value for display, if successful
 430       prettyEval = builtins.tryEval
 431         (lib.generators.toPretty { }
 432           (lib.generators.withRecursion { depthLimit = 10; throwOnDepthLimit = false; } def.value));
 433       # Split it into its lines
 434       lines = filter (v: ! isList v) (builtins.split "\n" prettyEval.value);
 435       # Only display the first 5 lines, and indent them for better visibility
 436       value = concatStringsSep "\n    " (take 5 lines ++ optional (length lines > 5) "...");
 437       result =
 438         # Don't print any value if evaluating the value strictly fails
 439         if ! prettyEval.success then ""
 440         # Put it on a new line if it consists of multiple
 441         else if length lines > 1 then ":\n    " + value
 442         else ": " + value;
 443     in "\n- In `${def.file}'${result}"
 444   ) defs;
 445
 446   showOptionWithDefLocs = opt: ''
 447       ${showOption opt.loc}, with values defined in:
 448       ${concatMapStringsSep "\n" (defFile: "  - ${defFile}") opt.files}
 449     '';
 450
 451   unknownModule = "<unknown-file>";
 452
 453 }