nixos/doc/manual/development/option-def.section.md

   1 # Option Definitions {#sec-option-definitions}
   2
   3 Option definitions are generally straight-forward bindings of values to
   4 option names, like
   5
   6 ```nix
   7 {
   8   config = {
   9     services.httpd.enable = true;
  10   };
  11 }
  12 ```
  13
  14 However, sometimes you need to wrap an option definition or set of
  15 option definitions in a *property* to achieve certain effects:
  16
  17 ## Delaying Conditionals {#sec-option-definitions-delaying-conditionals}
  18
  19 If a set of option definitions is conditional on the value of another
  20 option, you may need to use `mkIf`. Consider, for instance:
  21
  22 ```nix
  23 {
  24   config = if config.services.httpd.enable then {
  25     environment.systemPackages = [ /* ... */ ];
  26     # ...
  27   } else {};
  28 }
  29 ```
  30
  31 This definition will cause Nix to fail with an "infinite recursion"
  32 error. Why? Because the value of `config.services.httpd.enable` depends
  33 on the value being constructed here. After all, you could also write the
  34 clearly circular and contradictory:
  35
  36 ```nix
  37 {
  38   config = if config.services.httpd.enable then {
  39     services.httpd.enable = false;
  40   } else {
  41     services.httpd.enable = true;
  42   };
  43 }
  44 ```
  45
  46 The solution is to write:
  47
  48 ```nix
  49 {
  50   config = mkIf config.services.httpd.enable {
  51     environment.systemPackages = [ /* ... */ ];
  52     # ...
  53   };
  54 }
  55 ```
  56
  57 The special function `mkIf` causes the evaluation of the conditional to
  58 be "pushed down" into the individual definitions, as if you had written:
  59
  60 ```nix
  61 {
  62   config = {
  63     environment.systemPackages = if config.services.httpd.enable then [ /* ... */ ] else [];
  64     # ...
  65   };
  66 }
  67 ```
  68
  69 ## Setting Priorities {#sec-option-definitions-setting-priorities}
  70
  71 A module can override the definitions of an option in other modules by
  72 setting an *override priority*. All option definitions that do not have the lowest
  73 priority value are discarded. By default, option definitions have
  74 priority 100 and option defaults have priority 1500.
  75 You can specify an explicit priority by using `mkOverride`, e.g.
  76
  77 ```nix
  78 {
  79   services.openssh.enable = mkOverride 10 false;
  80 }
  81 ```
  82
  83 This definition causes all other definitions with priorities above 10 to
  84 be discarded. The function `mkForce` is equal to `mkOverride 50`, and
  85 `mkDefault` is equal to `mkOverride 1000`.
  86
  87 ## Ordering Definitions {#sec-option-definitions-ordering}
  88
  89 It is also possible to influence the order in which the definitions for an option are
  90 merged by setting an *order priority* with `mkOrder`. The default order priority is 1000.
  91 The functions `mkBefore` and `mkAfter` are equal to `mkOrder 500` and `mkOrder 1500`, respectively.
  92 As an example,
  93
  94 ```nix
  95 {
  96   hardware.firmware = mkBefore [ myFirmware ];
  97 }
  98 ```
  99
 100 This definition ensures that `myFirmware` comes before other unordered
 101 definitions in the final list value of `hardware.firmware`.
 102
 103 Note that this is different from [override priorities](#sec-option-definitions-setting-priorities):
 104 setting an order does not affect whether the definition is included or not.
 105
 106 ## Merging Configurations {#sec-option-definitions-merging}
 107
 108 In conjunction with `mkIf`, it is sometimes useful for a module to
 109 return multiple sets of option definitions, to be merged together as if
 110 they were declared in separate modules. This can be done using
 111 `mkMerge`:
 112
 113 ```nix
 114 {
 115   config = mkMerge
 116     [ # Unconditional stuff.
 117       { environment.systemPackages = [ /* ... */ ];
 118       }
 119       # Conditional stuff.
 120       (mkIf config.services.bla.enable {
 121         environment.systemPackages = [ /* ... */ ];
 122       })
 123     ];
 124 }
 125 ```