From e8927c46b8693b1d0b1d6e12cd602c6647217d3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Na=C3=AFm=20Favier?= Date: Fri, 2 Dec 2022 13:39:47 +0100 Subject: [PATCH] nixos/doc: document `mkOrder` and friends Add a section on ordering option definitions. Also mention `mkDefault` in the section on `mkOverride`. Clarify the code a bit by renaming `defaultPriority` to `defaultOverridePriority` and introducing `defaultOrderPriority`. --- lib/modules.nix | 19 ++++----- .../manual/development/option-def.section.md | 26 ++++++++++-- .../development/option-def.section.xml | 40 ++++++++++++++++--- nixos/modules/virtualisation/qemu-vm.nix | 2 +- 4 files changed, 67 insertions(+), 20 deletions(-) diff --git a/lib/modules.nix b/lib/modules.nix index 204a2cc1ac12..f5e69ad4bcf5 100644 --- a/lib/modules.nix +++ b/lib/modules.nix @@ -833,7 +833,7 @@ rec { filterOverrides' = defs: let - getPrio = def: if def.value._type or "" == "override" then def.value.priority else defaultPriority; + getPrio = def: if def.value._type or "" == "override" then def.value.priority else defaultOverridePriority; highestPrio = foldl' (prio: def: min (getPrio def) prio) 9999 defs; strip = def: if def.value._type or "" == "override" then def // { value = def.value.content; } else def; in { @@ -842,7 +842,7 @@ rec { }; /* Sort a list of properties. The sort priority of a property is - 1000 by default, but can be overridden by wrapping the property + defaultOrderPriority by default, but can be overridden by wrapping the property using mkOrder. */ sortProperties = defs: let @@ -851,7 +851,7 @@ rec { then def // { value = def.value.content; inherit (def.value) priority; } else def; defs' = map strip defs; - compare = a: b: (a.priority or 1000) < (b.priority or 1000); + compare = a: b: (a.priority or defaultOrderPriority) < (b.priority or defaultOrderPriority); in sort compare defs'; # This calls substSubModules, whose entire purpose is only to ensure that @@ -887,10 +887,13 @@ rec { mkOptionDefault = mkOverride 1500; # priority of option defaults mkDefault = mkOverride 1000; # used in config sections of non-user modules to set a default + defaultOverridePriority = 100; mkImageMediaOverride = mkOverride 60; # image media profiles can be derived by inclusion into host config, hence needing to override host config, but do allow user to mkForce mkForce = mkOverride 50; mkVMOverride = mkOverride 10; # used by ‘nixos-rebuild build-vm’ + defaultPriority = lib.warnIf (lib.isInOldestRelease 2305) "lib.modules.defaultPriority is deprecated, please use lib.modules.defaultOverridePriority instead." defaultOverridePriority; + mkFixStrictness = lib.warn "lib.mkFixStrictness has no effect and will be removed. It returns its argument unmodified, so you can just remove any calls." id; mkOrder = priority: content: @@ -899,11 +902,9 @@ rec { }; mkBefore = mkOrder 500; + defaultOrderPriority = 1000; mkAfter = mkOrder 1500; - # The default priority for things that don't have a priority specified. - defaultPriority = 100; - # Convenient property used to transfer all definitions and their # properties from one option to another. This property is useful for # renaming options, and also for including properties from another module @@ -930,10 +931,10 @@ rec { # Similar to mkAliasAndWrapDefinitions but copies over the priority from the # option as well. # - # If a priority is not set, it assumes a priority of defaultPriority. + # If a priority is not set, it assumes a priority of defaultOverridePriority. mkAliasAndWrapDefsWithPriority = wrap: option: let - prio = option.highestPrio or defaultPriority; + prio = option.highestPrio or defaultOverridePriority; defsWithPrio = map (mkOverride prio) option.definitions; in mkAliasIfDef option (wrap (mkMerge defsWithPrio)); @@ -1115,7 +1116,7 @@ rec { # to definitions. mkDerivedConfig = opt: f: mkOverride - (opt.highestPrio or defaultPriority) + (opt.highestPrio or defaultOverridePriority) (f opt.value); doRename = { from, to, visible, warn, use, withPriority ? true }: diff --git a/nixos/doc/manual/development/option-def.section.md b/nixos/doc/manual/development/option-def.section.md index 91b24cd4a3a1..22cf38873cf0 100644 --- a/nixos/doc/manual/development/option-def.section.md +++ b/nixos/doc/manual/development/option-def.section.md @@ -59,17 +59,35 @@ config = { ## Setting Priorities {#sec-option-definitions-setting-priorities .unnumbered} A module can override the definitions of an option in other modules by -setting a *priority*. All option definitions that do not have the lowest +setting an *override priority*. All option definitions that do not have the lowest priority value are discarded. By default, option definitions have -priority 1000. You can specify an explicit priority by using -`mkOverride`, e.g. +priority 100 and option defaults have priority 1500. +You can specify an explicit priority by using `mkOverride`, e.g. ```nix services.openssh.enable = mkOverride 10 false; ``` This definition causes all other definitions with priorities above 10 to -be discarded. The function `mkForce` is equal to `mkOverride 50`. +be discarded. The function `mkForce` is equal to `mkOverride 50`, and +`mkDefault` is equal to `mkOverride 1000`. + +## Ordering Definitions {#sec-option-definitions-ordering .unnumbered} + +It is also possible to influence the order in which the definitions for an option are +merged by setting an *order priority* with `mkOrder`. The default order priority is 1000. +The functions `mkBefore` and `mkAfter` are equal to `mkOrder 500` and `mkOrder 1500`, respectively. +As an example, + +```nix +hardware.firmware = mkBefore [ myFirmware ]; +``` + +This definition ensures that `myFirmware` comes before other unordered +definitions in the final list value of `hardware.firmware`. + +Note that this is different from [override priorities](#sec-option-definitions-setting-priorities): +setting an order does not affect whether the definition is included or not. ## Merging Configurations {#sec-option-definitions-merging .unnumbered} diff --git a/nixos/doc/manual/from_md/development/option-def.section.xml b/nixos/doc/manual/from_md/development/option-def.section.xml index 8c9ef181affd..3c1a979e70f3 100644 --- a/nixos/doc/manual/from_md/development/option-def.section.xml +++ b/nixos/doc/manual/from_md/development/option-def.section.xml @@ -66,11 +66,11 @@ config = { Setting Priorities A module can override the definitions of an option in other - modules by setting a priority. All option - definitions that do not have the lowest priority value are - discarded. By default, option definitions have priority 1000. You - can specify an explicit priority by using - mkOverride, e.g. + modules by setting an override priority. All + option definitions that do not have the lowest priority value are + discarded. By default, option definitions have priority 100 and + option defaults have priority 1500. You can specify an explicit + priority by using mkOverride, e.g. services.openssh.enable = mkOverride 10 false; @@ -78,7 +78,35 @@ services.openssh.enable = mkOverride 10 false; This definition causes all other definitions with priorities above 10 to be discarded. The function mkForce is - equal to mkOverride 50. + equal to mkOverride 50, and + mkDefault is equal to + mkOverride 1000. + + +
+ Ordering Definitions + + It is also possible to influence the order in which the + definitions for an option are merged by setting an order + priority with mkOrder. The default + order priority is 1000. The functions mkBefore + and mkAfter are equal to + mkOrder 500 and + mkOrder 1500, respectively. As an example, + + +hardware.firmware = mkBefore [ myFirmware ]; + + + This definition ensures that myFirmware comes + before other unordered definitions in the final list value of + hardware.firmware. + + + Note that this is different from + override + priorities: setting an order does not affect whether the + definition is included or not.
diff --git a/nixos/modules/virtualisation/qemu-vm.nix b/nixos/modules/virtualisation/qemu-vm.nix index 9af7e07ccfba..eae898a08a69 100644 --- a/nixos/modules/virtualisation/qemu-vm.nix +++ b/nixos/modules/virtualisation/qemu-vm.nix @@ -806,7 +806,7 @@ in optional ( cfg.writableStore && cfg.useNixStoreImage && - opt.writableStore.highestPrio > lib.modules.defaultPriority) + opt.writableStore.highestPrio > lib.modules.defaultOverridePriority) '' You have enabled ${opt.useNixStoreImage} = true, without setting ${opt.writableStore} = false.