diff options
Diffstat (limited to 'nixos/doc/manual/development/option-def.xml')
-rw-r--r-- | nixos/doc/manual/development/option-def.xml | 99 |
1 files changed, 0 insertions, 99 deletions
diff --git a/nixos/doc/manual/development/option-def.xml b/nixos/doc/manual/development/option-def.xml deleted file mode 100644 index 50a705d0cb8..00000000000 --- a/nixos/doc/manual/development/option-def.xml +++ /dev/null @@ -1,99 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-option-definitions"> - <title>Option Definitions</title> - - <para> - Option definitions are generally straight-forward bindings of values to - option names, like -<programlisting> -config = { - services.httpd.enable = true; -}; -</programlisting> - However, sometimes you need to wrap an option definition or set of option - definitions in a <emphasis>property</emphasis> to achieve certain effects: - </para> - - <simplesect xml:id="sec-option-definitions-delaying-conditionals"> - <title>Delaying Conditionals</title> - <para> - If a set of option definitions is conditional on the value of another - option, you may need to use <varname>mkIf</varname>. Consider, for instance: -<programlisting> -config = if config.services.httpd.enable then { - environment.systemPackages = [ <replaceable>...</replaceable> ]; - <replaceable>...</replaceable> -} else {}; -</programlisting> - This definition will cause Nix to fail with an “infinite recursion” - error. Why? Because the value of - <option>config.services.httpd.enable</option> depends on the value being - constructed here. After all, you could also write the clearly circular and - contradictory: -<programlisting> -config = if config.services.httpd.enable then { - services.httpd.enable = false; -} else { - services.httpd.enable = true; -}; -</programlisting> - The solution is to write: -<programlisting> -config = mkIf config.services.httpd.enable { - environment.systemPackages = [ <replaceable>...</replaceable> ]; - <replaceable>...</replaceable> -}; -</programlisting> - The special function <varname>mkIf</varname> causes the evaluation of the - conditional to be “pushed down” into the individual definitions, as if - you had written: -<programlisting> -config = { - environment.systemPackages = if config.services.httpd.enable then [ <replaceable>...</replaceable> ] else []; - <replaceable>...</replaceable> -}; -</programlisting> - </para> - </simplesect> - - <simplesect xml:id="sec-option-definitions-setting-priorities"> - <title>Setting Priorities</title> - <para> - A module can override the definitions of an option in other modules by - setting a <emphasis>priority</emphasis>. 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 - <varname>mkOverride</varname>, e.g. -<programlisting> -services.openssh.enable = mkOverride 10 false; -</programlisting> - This definition causes all other definitions with priorities above 10 to be - discarded. The function <varname>mkForce</varname> is equal to - <varname>mkOverride 50</varname>. - </para> - </simplesect> - - <simplesect xml:id="sec-option-definitions-merging"> - <title>Merging Configurations</title> - <para> - In conjunction with <literal>mkIf</literal>, it is sometimes useful for a - module to return multiple sets of option definitions, to be merged together - as if they were declared in separate modules. This can be done using - <varname>mkMerge</varname>: -<programlisting> -config = mkMerge - [ # Unconditional stuff. - { environment.systemPackages = [ <replaceable>...</replaceable> ]; - } - # Conditional stuff. - (mkIf config.services.bla.enable { - environment.systemPackages = [ <replaceable>...</replaceable> ]; - }) - ]; -</programlisting> - </para> - </simplesect> -</section> |