diff options
author | Alyssa Ross <hi@alyssa.is> | 2024-02-26 16:20:28 +0100 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2024-02-26 16:20:28 +0100 |
commit | 647438344bfc1f77791391e2b4f98eef865c63dc (patch) | |
tree | ef580867fc6cc413940e4330d939cf1afda082cb /nixpkgs/lib | |
parent | b084c6a0fab7f32c904c5c8e8db8dddcefbe507f (diff) | |
parent | e3474e1d1e53b70e2b2af73ea26d6340e82f6b8b (diff) | |
download | nixlib-647438344bfc1f77791391e2b4f98eef865c63dc.tar nixlib-647438344bfc1f77791391e2b4f98eef865c63dc.tar.gz nixlib-647438344bfc1f77791391e2b4f98eef865c63dc.tar.bz2 nixlib-647438344bfc1f77791391e2b4f98eef865c63dc.tar.lz nixlib-647438344bfc1f77791391e2b4f98eef865c63dc.tar.xz nixlib-647438344bfc1f77791391e2b4f98eef865c63dc.tar.zst nixlib-647438344bfc1f77791391e2b4f98eef865c63dc.zip |
Merge commit 'e3474e1d1e53'
Diffstat (limited to 'nixpkgs/lib')
-rw-r--r-- | nixpkgs/lib/modules.nix | 73 |
1 files changed, 72 insertions, 1 deletions
diff --git a/nixpkgs/lib/modules.nix b/nixpkgs/lib/modules.nix index c51999c2e332..61964d466781 100644 --- a/nixpkgs/lib/modules.nix +++ b/nixpkgs/lib/modules.nix @@ -1256,7 +1256,78 @@ let (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; |