diff options
author | Naïm Favier <n@monade.li> | 2022-12-02 13:39:47 +0100 |
---|---|---|
committer | Naïm Favier <n@monade.li> | 2022-12-02 14:15:24 +0100 |
commit | e8927c46b8693b1d0b1d6e12cd602c6647217d3a (patch) | |
tree | f742957d53cbcbdee782de8966dadde425d21001 /nixos/doc/manual/development | |
parent | 3dc19ce82d5a435ff63a2d8771aaf4a8243f0c0f (diff) |
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`.
Diffstat (limited to 'nixos/doc/manual/development')
-rw-r--r-- | nixos/doc/manual/development/option-def.section.md | 26 |
1 files changed, 22 insertions, 4 deletions
diff --git a/nixos/doc/manual/development/option-def.section.md b/nixos/doc/manual/development/option-def.section.md index 91b24cd4a3a16..22cf38873cf07 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} |