diff options
Diffstat (limited to 'nixos/doc')
-rw-r--r-- | nixos/doc/manual/default.nix | 6 | ||||
-rw-r--r-- | nixos/doc/manual/development/option-declarations.xml | 106 |
2 files changed, 108 insertions, 4 deletions
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 4ce6ea1c1118..ea8601497361 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -1,4 +1,4 @@ -{ pkgs, options, version, revision, extraSources ? [] }: +{ pkgs, options, internalModule, version, revision, extraSources ? [] }: with pkgs; with pkgs.lib; @@ -6,8 +6,10 @@ with pkgs.lib; let # Remove invisible and internal options. - optionsList = filter (opt: opt.visible && !opt.internal) (optionAttrSetToDocList options); + optionsList = filter (opt: opt.visible && !opt.internal) (optionAttrSetToDocList internalModule options); + # INFO: Please add 'defaultText' or 'literalExample' to the option + # definition to avoid this substitution! # Replace functions by the string <function> substFunction = x: if builtins.isAttrs x then mapAttrs (name: substFunction) x diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml index ea5d1241876e..08bde4a275d9 100644 --- a/nixos/doc/manual/development/option-declarations.xml +++ b/nixos/doc/manual/development/option-declarations.xml @@ -8,7 +8,7 @@ <para>An option declaration specifies the name, type and description of a NixOS configuration option. It is illegal to define an option -that hasn’t been declared in any module. A option declaration +that has not been declared in any module. A option declaration generally looks like this: <programlisting> @@ -145,6 +145,108 @@ options = { You can also create new types using the function <varname>mkOptionType</varname>. See -<filename>lib/types.nix</filename> in Nixpkgs for details.</para> +<filename>lib/types.nix</filename> in Nixpkgs for details. + +An option declaration must follow the following rules: +<itemizedlist mark='bullet'> + + <listitem> + <para>A <varname>defaultText</varname> must be defined if and only if the type of the option + derives from <varname>package</varname>, <varname>packageSet</varname> or <varname>nixpkgsConfig + </varname>, and if and only if a <varname>default</varname> attribute is defined and if and only if + the value of the <varname>default</varname> attribute is not the default of the type of the + option declaration. + + For example, a <varname>defaultText</varname> must be defined for +<programlisting> +type = types.listOf types.package; +default = [ pkgs.foo; ]; +defaultText = "[ pkgs.foo; ]"; +</programlisting>. + + But no <varname>defaultText</varname> must be defined for +<programlisting> +type = types.listOf types.package; +default = []; +</programlisting>, + as <varname>[]</varname> is the default of <varname>types.listOf types.package</varname>. + </para> + </listitem> + + <listitem> + <para>A <varname>defaultText</varname> can be defined if the type of the option derives from + <varname>path</varname> and if a <varname>default</varname> attribute is defined.</para> + </listitem> + + <listitem> + <para>The value of the <varname>example</varname> attribute must be wrapped with <varname> + literalExample</varname> if the type of the option derives from <varname>package</varname>, + <varname>packageSet</varname> or <varname>nixpkgsConfig</varname>.</para> + </listitem> + + <listitem> + <para>The value of <varname>defaultText</varname> and <varname>literalExample</varname> must + be a string which contains a valid nix expression. The nix expression has to evaluate in + <code>{pkgs}: <replaceable>value</replaceable></code>. + For example: + <itemizedlist> + <listitem> + <para>A <varname>defaultText</varname> could, e.g., be: +<programlisting> +type = types.package; +default = pkgs.foo; +defaultText = "pkgs.foo"; +</programlisting> + But not <code>defaultText = "pkgs.foo;";</code>, as that + corresponds to <code>{pkgs}: pkgs.foo;</code>, which is an + invalid nix expression due to the ending with <varname>;</varname>.</para> + </listitem> + + <listitem> + <para>A <varname>literalExample</varname> could be used as, e.g.: +<programlisting> +type = types.path; +example = literalExample "\"\${pkgs.bar}/bin/bar\""; +</programlisting> + But not <code>literalExample "\${pkgs.bar}/bin/bar";</code>, as that corresponds + to <code>{pkgs}: ${pkgs.bar}/bin/bar</code>, which is an invalid nix expression + as the <varname>path</varname> is not a <varname>string</varname> anymore.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>The <varname>type</varname> attribute must be defined for every option declaration.</para> + </listitem> + +</itemizedlist> + +NixOS ships the tool <varname>nixos-typecheck</varname> that can check an option declaration to: + +<itemizedlist mark='bullet'> + + <listitem> + <para>Enforce that an option declaration has a <varname>defaultText</varname> if and only if the + type of the option derives from <varname>package</varname>, <varname>packageSet</varname> or + <varname>nixpkgsConfig</varname> and if a <varname>default</varname> attribute is defined.</para> + </listitem> + + <listitem> + <para>Enforce that the value of the <varname>example</varname> attribute is wrapped with <varname> + literalExample</varname> if the type of the option derives from <varname>package</varname>, + <varname>packageSet</varname> or <varname>nixpkgsConfig</varname>.</para> + </listitem> + + <listitem> + <para>Warn if a <varname>defaultText</varname> is defined in an option declaration if the type of + the option does not derive from <varname>package</varname>, <varname>packageSet</varname> or + <varname>nixpkgsConfig</varname>.</para> + </listitem> + + <listitem> + <para>Warn if no <varname>type</varname> is defined in an option declaration.</para> + </listitem> + +</itemizedlist></para> </section> |