core/lib/options.nix

# Nixpkgs/NixOS option handling.
{ lib }:

let
  inherit (lib)
    all
    collect
    concatLists
    concatMap
    concatMapStringsSep
    filter
    foldl'
    head
    tail
    isAttrs
    isBool
    isDerivation
    isFunction
    isInt
    isList
    isString
    length
    mapAttrs
    optional
    optionals
    take
    ;
  inherit (lib.attrsets) attrByPath optionalAttrs;
  inherit (lib.strings) concatMapStrings concatStringsSep;
  inherit (lib.types) mkOptionType;
  inherit (lib.lists) last;
  prioritySuggestion = ''
    Use `lib.mkForce value` or `lib.mkDefault value` to change the priority on any of these definitions.
  '';
in
rec {

  /*
    Returns true when the given argument is an option

    Type: isOption :: a -> bool

    Example:
      isOption 1             // => false
      isOption (mkOption {}) // => true
  */
  isOption = lib.isType "option";

  /*
    Creates an Option attribute set. mkOption accepts an attribute set with the following keys:

    All keys default to `null` when not given.

    Example:
      mkOption { }  // => { _type = "option"; }
      mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; }
  */
  mkOption =
    {
      # Default value used when no definition is given in the configuration.
      default ? null,
      # Textual representation of the default, for the manual.
      defaultText ? null,
      # Example value used in the manual.
      example ? null,
      # String describing the option.
      description ? null,
      # Related packages used in the manual (see `genRelatedPackages` in ../nixos/lib/make-options-doc/default.nix).
      relatedPackages ? null,
      # Option type, providing type-checking and value merging.
      type ? null,
      # Function that converts the option value to something else.
      apply ? null,
      # Whether the option is for NixOS developers only.
      internal ? null,
      # 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.
      visible ? null,
      # Whether the option can be set only once
      readOnly ? null,
    }@attrs:
    attrs // { _type = "option"; };

  /*
    Creates an Option attribute set for a boolean value option i.e an
    option to be toggled on or off:

    Example:
      mkEnableOption "foo"
      => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
  */
  mkEnableOption =
    # Name for the created option
    name:
    mkOption {
      default = false;
      example = true;
      description = "Whether to enable ${name}.";
      type = lib.types.bool;
    };

  /*
    Creates an Option attribute set for an option that specifies the
    package a module should use for some purpose.

    The package is specified in the third argument under `default` as a list of strings
    representing its attribute path in nixpkgs (or another package set).
    Because of this, you need to pass nixpkgs itself (usually `pkgs` in a module;
    alternatively to nixpkgs itself, another package set) as the first argument.

    If you pass another package set you should set the `pkgsText` option.
    This option is used to display the expression for the package set. It is `"pkgs"` by default.
    If your expression is complex you should parenthesize it, as the `pkgsText` argument
    is usually immediately followed by an attribute lookup (`.`).

    The second argument may be either a string or a list of strings.
    It provides the display name of the package in the description of the generated option
    (using only the last element if the passed value is a list)
    and serves as the fallback value for the `default` argument.

    To include extra information in the description, pass `extraDescription` to
    append arbitrary text to the generated description.

    You can also pass an `example` value, either a literal string or an attribute path.

    The `default` argument can be omitted if the provided name is
    an attribute of pkgs (if `name` is a string) or a valid attribute path in pkgs (if `name` is a list).
    You can also set `default` to just a string in which case it is interpreted as an attribute name
    (a singleton attribute path, if you will).

    If you wish to explicitly provide no default, pass `null` as `default`.

    If you want users to be able to set no package, pass `nullable = true`.
    In this mode a `default = null` will not be interpreted as no default and is interpreted literally.

    Type: mkPackageOption :: pkgs -> (string|[string]) -> { nullable? :: bool, default? :: string|[string], example? :: null|string|[string], extraDescription? :: string, pkgsText? :: string } -> option

    Example:
      mkPackageOption pkgs "hello" { }
      => { ...; default = pkgs.hello; defaultText = literalExpression "pkgs.hello"; description = "The hello package to use."; type = package; }

    Example:
      mkPackageOption pkgs "GHC" {
        default = [ "ghc" ];
        example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
      }
      => { ...; 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; }

    Example:
      mkPackageOption pkgs [ "python3Packages" "pytorch" ] {
        extraDescription = "This is an example and doesn't actually do anything.";
      }
      => { ...; 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; }

    Example:
      mkPackageOption pkgs "nushell" {
        nullable = true;
      }
      => { ...; default = pkgs.nushell; defaultText = literalExpression "pkgs.nushell"; description = "The nushell package to use."; type = nullOr package; }

    Example:
      mkPackageOption pkgs "coreutils" {
        default = null;
      }
      => { ...; description = "The coreutils package to use."; type = package; }

    Example:
      mkPackageOption pkgs "dbus" {
        nullable = true;
        default = null;
      }
      => { ...; default = null; description = "The dbus package to use."; type = nullOr package; }

    Example:
      mkPackageOption pkgs.javaPackages "OpenJFX" {
        default = "openjfx20";
        pkgsText = "pkgs.javaPackages";
      }
      => { ...; default = pkgs.javaPackages.openjfx20; defaultText = literalExpression "pkgs.javaPackages.openjfx20"; description = "The OpenJFX package to use."; type = package; }
  */
  mkPackageOption =
    # Package set (an instantiation of nixpkgs such as pkgs in modules or another package set)
    pkgs:
    # Name for the package, shown in option description
    name:
    {
      # Whether the package can be null, for example to disable installing a package altogether (defaults to false)
      nullable ? false,
      # The attribute path where the default package is located (may be omitted, in which case it is copied from `name`)
      default ? name,
      # A string or an attribute path to use as an example (may be omitted)
      example ? null,
      # Additional text to include in the option description (may be omitted)
      extraDescription ? "",
      # Representation of the package set passed as pkgs (defaults to `"pkgs"`)
      pkgsText ? "pkgs",
    }:
    let
      name' = if isList name then last name else name;
      default' = if isList default then default else [ default ];
      defaultText = concatStringsSep "." default';
      defaultValue = attrByPath default' (throw "${defaultText} cannot be found in ${pkgsText}") pkgs;
      defaults =
        if default != null then
          {
            default = defaultValue;
            defaultText = literalExpression ("${pkgsText}." + defaultText);
          }
        else
          optionalAttrs nullable { default = null; };
    in
    mkOption (
      defaults
      // {
        description =
          "The ${name'} package to use." + (if extraDescription == "" then "" else " ") + extraDescription;
        type = with lib.types; (if nullable then nullOr else lib.id) package;
      }
      // optionalAttrs (example != null) {
        example = literalExpression (
          if isList example then "${pkgsText}." + concatStringsSep "." example else example
        );
      }
    );

  /*
    Alias of mkPackageOption. Previously used to create options with markdown
    documentation, which is no longer required.
  */
  mkPackageOptionMD = mkPackageOption;

  /*
    This option accepts 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
    values of the options are not accessed.
  */
  mkSinkUndeclaredOptions =
    attrs:
    mkOption (
      {
        internal = true;
        visible = false;
        default = false;
        description = "Sink for option definitions.";
        type = mkOptionType {
          name = "sink";
          check = x: true;
          merge = loc: defs: false;
        };
        apply = x: throw "Option value is not readable because the option is not declared.";
      }
      // attrs
    );

  mergeDefaultOption =
    loc: defs:
    let
      list = getValues defs;
    in
    if length list == 1 then
      head list
    else if all isFunction list then
      x: mergeDefaultOption 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}'. Definition values:${showDefs defs}";

  /*
    Require a single definition.

    WARNING: Does not perform nested checks, as this does not run the merge function!
  */
  mergeOneOption = mergeUniqueOption { message = ""; };

  /*
    Require a single definition.

    NOTE: When the type is not checked completely by check, pass a merge function for further checking (of sub-attributes, etc).
  */
  mergeUniqueOption =
    args@{
      message,
      # WARNING: the default merge function assumes that the definition is a valid (option) value. You MUST pass a merge function if the return value needs to be
      #   - type checked beyond what .check does (which should be very litte; only on the value head; not attribute values, etc)
      #   - if you want attribute values to be checked, or list items
      #   - if you want coercedTo-like behavior to work
      merge ? loc: defs: (head defs).value,
    }:
    loc: defs:
    if length defs == 1 then
      merge loc defs
    else
      assert length defs > 1;
      throw "The option `${showOption loc}' is defined multiple times while it's expected to be unique.\n${message}\nDefinition values:${showDefs defs}\n${prioritySuggestion}";

  # "Merge" option definitions by checking that they all have the same value.
  mergeEqualOption =
    loc: defs:
    if defs == [ ] then
      abort "This case should never happen."
    # Return early if we only have one element
    # This also makes it work for functions, because the foldl' below would try
    # to compare the first element with itself, which is false for functions
    else if length defs == 1 then
      (head defs).value
    else
      (foldl' (
        first: def:
        if def.value != first.value then
          throw "The option `${showOption loc}' has conflicting definition values:${
            showDefs [
              first
              def
            ]
          }\n${prioritySuggestion}"
        else
          first
      ) (head defs) (tail defs)).value;

  /*
    Extracts values of all "value" keys of the given list.

    Type: getValues :: [ { value :: a; } ] -> [a]

    Example:
      getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
      getValues [ ]                               // => [ ]
  */
  getValues = map (x: x.value);

  /*
    Extracts values of all "file" keys of the given list

    Type: getFiles :: [ { file :: a; } ] -> [a]

    Example:
      getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
      getFiles [ ]                                         // => [ ]
  */
  getFiles = map (x: x.file);

  # Generate documentation template from the list of option declaration like
  # the set generated with filterOptionSets.
  optionAttrSetToDocList = optionAttrSetToDocList' [ ];

  optionAttrSetToDocList' =
    _: options:
    concatMap (
      opt:
      let
        name = showOption opt.loc;
        docOption =
          {
            loc = opt.loc;
            inherit name;
            description = opt.description or null;
            declarations = filter (x: x != unknownModule) opt.declarations;
            internal = opt.internal or false;
            visible = if (opt ? visible && opt.visible == "shallow") then true else opt.visible or true;
            readOnly = opt.readOnly or false;
            type = opt.type.description or "unspecified";
          }
          // optionalAttrs (opt ? example) {
            example = builtins.addErrorContext "while evaluating the example of option `${name}`" (
              renderOptionValue opt.example
            );
          }
          // optionalAttrs (opt ? defaultText || opt ? default) {
            default = builtins.addErrorContext "while evaluating the ${
              if opt ? defaultText then "defaultText" else "default value"
            } of option `${name}`" (renderOptionValue (opt.defaultText or opt.default));
          }
          // optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) {
            inherit (opt) relatedPackages;
          };

        subOptions =
          let
            ss = opt.type.getSubOptions opt.loc;
          in
          if ss != { } then optionAttrSetToDocList' opt.loc ss else [ ];
        subOptionsVisible = docOption.visible && opt.visible or null != "shallow";
      in
      # To find infinite recursion in NixOS option docs:
      # builtins.trace opt.loc
      [ docOption ] ++ optionals subOptionsVisible subOptions
    ) (collect isOption 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.

    This function was made obsolete by renderOptionValue and is kept for
    compatibility with out-of-tree code.
  */
  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;

  /*
    Ensures that the given option value (default or example) is a `_type`d string
    by rendering Nix values to `literalExpression`s.
  */
  renderOptionValue =
    v:
    if v ? _type && v ? text then
      v
    else
      literalExpression (
        lib.generators.toPretty {
          multiline = true;
          allowPrettyValues = true;
        } v
      );

  /*
    For use in the `defaultText` and `example` option attributes. Causes the
    given string to be rendered verbatim in the documentation as Nix code. This
    is necessary for complex values, e.g. functions, or values that depend on
    other values or packages.
  */
  literalExpression =
    text:
    if !isString text then
      throw "literalExpression expects a string."
    else
      {
        _type = "literalExpression";
        inherit text;
      };

  literalExample = lib.warn "lib.literalExample is deprecated, use lib.literalExpression instead, or use lib.literalMD for a non-Nix description." literalExpression;

  /*
    Transition marker for documentation that's already migrated to markdown
    syntax. Has been a no-op for some while and been removed from nixpkgs.
    Kept here to alert downstream users who may not be aware of the migration's
    completion that it should be removed from modules.
  */
  mdDoc = lib.warn "lib.mdDoc will be removed from nixpkgs in 24.11. Option descriptions are now in Markdown by default; you can remove any remaining uses of lib.mdDoc.";

  /*
    For use in the `defaultText` and `example` option attributes. Causes the
    given MD text to be inserted verbatim in the documentation, for when
    a `literalExpression` would be too hard to read.
  */
  literalMD =
    text:
    if !isString text then
      throw "literalMD expects a string."
    else
      {
        _type = "literalMD";
        inherit text;
      };

  # Helper functions.

  /*
    Convert an option, described as a list of the option parts to a
    human-readable version.

    Example:
      (showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
      (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
      (showOption ["windowManager" "2bwm" "enable"]) == "windowManager.\"2bwm\".enable"

    Placeholders will not be quoted as they are not actual values:
      (showOption ["foo" "*" "bar"]) == "foo.*.bar"
      (showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"
  */
  showOption =
    parts:
    let
      escapeOptionPart =
        part:
        let
          # We assume that these are "special values" and not real configuration data.
          # If it is real configuration data, it is rendered incorrectly.
          specialIdentifiers = [
            "<name>" # attrsOf (submodule {})
            "*" # listOf (submodule {})
            "<function body>" # functionTo
          ];
        in
        if builtins.elem part specialIdentifiers then part else lib.strings.escapeNixIdentifier part;
    in
    (concatStringsSep ".") (map escapeOptionPart parts);
  showFiles = files: concatStringsSep " and " (map (f: "`${f}'") files);

  showDefs =
    defs:
    concatMapStrings (
      def:
      let
        # Pretty print the value for display, if successful
        prettyEval = builtins.tryEval (
          lib.generators.toPretty { } (
            lib.generators.withRecursion {
              depthLimit = 10;
              throwOnDepthLimit = false;
            } def.value
          )
        );
        # Split it into its lines
        lines = filter (v: !isList v) (builtins.split "\n" prettyEval.value);
        # Only display the first 5 lines, and indent them for better visibility
        value = concatStringsSep "\n    " (take 5 lines ++ optional (length lines > 5) "...");
        result =
          # Don't print any value if evaluating the value strictly fails
          if !prettyEval.success then
            ""
          # Put it on a new line if it consists of multiple
          else if length lines > 1 then
            ":\n    " + value
          else
            ": " + value;
      in
      "\n- In `${def.file}'${result}"
    ) defs;

  showOptionWithDefLocs = opt: ''
    ${showOption opt.loc}, with values defined in:
    ${concatMapStringsSep "\n" (defFile: "  - ${defFile}") opt.files}
  '';

  unknownModule = "<unknown-file>";

}