Merge pull request #286544 from hercules-ci/doRename-doc

      (opt.highestPrio or defaultOverridePriority)

      (f opt.value);

  doRename = { from, to, visible, warn, use, withPriority ? true, condition ? true }:

  /*

    Return a module that help declares an option that has been renamed.

    When a value is defined for the old option, it is forwarded to the `to` option.

   */

  doRename = {

    # List of strings representing the attribute path of the old option.

    from,

    # List of strings representing the attribute path of the new option.

    to,

    # Boolean, whether the old option is to be included in documentation.

    visible,

    # Whether to warn when a value is defined for the old option.

    # NOTE: This requires the NixOS assertions module to be imported, so

    #        - this generally does not work in submodules

    #        - this may or may not work outside NixOS

    warn,

    # A function that is applied to the option value, to form the value

    # of the old `from` option.

    #

    # For example, the identity function can be passed, to return the option value unchanged.

    # ```nix

    # use = x: x;

    # ```

    #

    # To add a warning, you can pass the partially applied `warn` function.

    # ```nix

    # use = lib.warn "Obsolete option `${opt.old}' is used. Use `${opt.to}' instead.";

    # ```

    use,

    # Legacy option, enabled by default: whether to preserve the priority of definitions in `old`.

    withPriority ? true,

    # A boolean that defines the `mkIf` condition for `to`.

    # If the condition evaluates to `true`, and the `to` path points into an

    # `attrsOf (submodule ...)`, then `doRename` would cause an empty module to

    # be created, even if the `from` option is undefined.

    # By setting this to an expression that may return `false`, you can inhibit

    # this undesired behavior.

    #

    # Example:

    #

    # ```nix

    # { config, lib, ... }:

    # let

    #   inherit (lib) mkOption mkEnableOption types doRename;

    # in

    # {

    #   options = {

    #

    #     # Old service

    #     services.foo.enable = mkEnableOption "foo";

    #

    #     # New multi-instance service

    #     services.foos = mkOption {

    #       type = types.attrsOf (types.submodule …);

    #     };

    #   };

    #   imports = [

    #     (doRename {

    #       from = [ "services" "foo" "bar" ];

    #       to = [ "services" "foos" "" "bar" ];

    #       visible = true;

    #       warn = false;

    #       use = x: x;

    #       withPriority = true;

    #       # Only define services.foos."" if needed. (It's not just about `bar`)

    #       condition = config.services.foo.enable;

    #     })

    #   ];

    # }

    # ```

    condition ? true

  }:

    { config, options, ... }:

    let

      fromOpt = getAttrFromPath from options;