Declaration - Revision history

imported>Evertras at 09:00, 31 January 2024

2024-01-31T09:00:14Z

← Older revision		Revision as of 09:00, 31 January 2024
Line 53:		Line 53:
	== Simple Types ==		== Simple Types ==

	* <code>~~inferred~~</code>: Useful when it is used under a meta-type.		* <code>anything</code>: Useful when it is used under a meta-type.
	* <code>bool</code>: A Boolean useful for enable flags. The merge function is a logical OR between all definitions.		* <code>bool</code>: A Boolean useful for enable flags. The merge function is a logical OR between all definitions.
	* <code>int</code>: An Integer.		* <code>int</code>: An Integer.

imported>Mic92: string -> str

2023-12-14T11:39:34Z

string -> str

← Older revision		Revision as of 11:39, 14 December 2023
Line 42:		Line 42:
	with lib;		with lib;
	services.fooBar.option = mkOption {		services.fooBar.option = mkOption {
	type = with types; uniq ~~string~~;		type = with types; uniq str;
	description = "		description = "
	...		...
Line 56:		Line 56:
	* <code>bool</code>: A Boolean useful for enable flags. The merge function is a logical OR between all definitions.		* <code>bool</code>: A Boolean useful for enable flags. The merge function is a logical OR between all definitions.
	* <code>int</code>: An Integer.		* <code>int</code>: An Integer.
	* <code>~~string~~</code>: A string where all definitions are concatenated.		* <code>str</code>: A string where all definitions are concatenated.
	* <code>envVar</code>: A string where all definitions are concatenated with a colon between all definitions.		* <code>envVar</code>: A string where all definitions are concatenated with a colon between all definitions.
	* <code>attrs</code>: An attribute set. (you should prefer <code>attrsOf inferred</code>)		* <code>attrs</code>: An attribute set. (you should prefer <code>attrsOf inferred</code>)

imported>Fricklerhandwerk: add category: NixOS

2022-08-11T00:35:46Z

add category: NixOS

← Older revision		Revision as of 00:35, 11 August 2022
Line 75:		Line 75:

	* <code>optionSet</code>: '''DEPRECATED, probably use submodule instead''' This type is used to benefit from the modular system used by NixOS inside an option. When this type is enabled, it merge the <code>options</code> attribute of option declarations with each definition. The result is the fixed configuration of each module. This option is often see in conjunction with <code>attrsOf</code> or <code>listOf</code>. Modules declared in option declaration appear in the generated manual with a prefix representing the container type, respectively "<code>.<name></code>" and "<code>.*</code>". Reference to definition files do not appears in the generated manual because the system cannot track them.		* <code>optionSet</code>: '''DEPRECATED, probably use submodule instead''' This type is used to benefit from the modular system used by NixOS inside an option. When this type is enabled, it merge the <code>options</code> attribute of option declarations with each definition. The result is the fixed configuration of each module. This option is often see in conjunction with <code>attrsOf</code> or <code>listOf</code>. Modules declared in option declaration appear in the generated manual with a prefix representing the container type, respectively "<code>.<name></code>" and "<code>.*</code>". Reference to definition files do not appears in the generated manual because the system cannot track them.

			[[Category:NixOS]]

imported>Mth: Mth moved page NixOS:Declaration to Declaration

2019-06-09T16:30:30Z

Mth moved page NixOS:Declaration to Declaration

← Older revision		Revision as of 16:30, 9 June 2019
(No difference)

imported>Fadenb at 20:36, 28 June 2017

2017-06-28T20:36:05Z

← Older revision		Revision as of 20:36, 28 June 2017
Line 1:		Line 1:
	NixOS module has declarations to provide an interface for other modules. Option declarations are used to make NixOS aware of configuration possibilities or to hide the complexity of configuration. Option declarations are used to provide an interface over the inherent complexity of configuring the system.		NixOS module has declarations to provide an interface for other modules. Option declarations are used to make NixOS aware of configuration possibilities or to hide the complexity of configuration. Option declarations are used to provide an interface over the inherent complexity of configuring the system.

	See also [~~http~~://nixos.org/nixos/manual/#~~idm140067877106960~~ the manual].		See also [https://nixos.org/nixos/manual/index.html#sec-option-declarations the manual].

	= Option attributes =		= Option attributes =

imported>Fadenb: Created page with "NixOS module has declarations to provide an interface for other modules. Option declarations are used to make NixOS aware of configuration possibilities or to hide the comple..."

2017-06-28T20:35:54Z

Created page with "NixOS module has declarations to provide an interface for other modules. Option declarations are used to make NixOS aware of configuration possibilities or to hide the comple..."

New page

NixOS module has declarations to provide an interface for other modules. Option declarations are used to make NixOS aware of configuration possibilities or to hide the complexity of configuration. Option declarations are used to provide an interface over the inherent complexity of configuring the system.

See also [http://nixos.org/nixos/manual/#idm140067877106960 the manual].

= Option attributes =

Options are declared with the <code>mkOption</code> function which is provided by the Nix package collection library (<code>pkgs.lib</code> attribute set). An option declaration may contain the following attributes:
* <code>name</code> <code>(string)</code>: This attribute is by default set to the location of the option. The name is used in error messages and in the generated manual.
* <code>default</code> <code>('t)</code>: The value used when no definitions are provided.
* <code>example</code> <code>('t)</code>: The value used as example to show a possible configuration.
* <code>description</code> <code>(string)</code>: A multi-line text which describe in a few sentences what is achieved by the option.
* <code>type</code> <code>(/'t/)</code>: The expected type of the default value and the option definitions. The type may provide default code for <code>merge</code> and <code>check</code> attribute.
* <code>merge</code> <code>('t list -> 't)</code>: A function used to merge all definitions into one result which has the same type.
* <code>apply</code> <code>('t -> any)</code>: A function used to provide an abstraction over the merged result. This function is mostly used when an usual transformation is made of the result.
* <code>options</code> <code>(module list)</code>: This attribute contains a list of modules when the type allow to have embedded modules.

An option can be declared in multiple modules, with one condition which is that no attribute collisions exists between the declarations except for the <code>options</code> attribute.

== Evaluation ==

The evaluation is done with the following piece of code where <code>opt</code> is the option declaration. You can find this piece of code inside [https://github.com/NixOS/nixpkgs/blob/eb7a17a1cfc158b87e6d349f1fcc550761d122b9/lib/modules.nix#L154-L186 <code>lib/modules.nix</code>].

<pre>
merged =
if defsFinal == [] then
throw "The option `${showOption loc}' is used but not defined."
else
fold (def: res:
if opt.type.check def.value then res
else throw "The option value `${showOption loc}' in `${def.file}' is not a ${opt.type.name}.")
(opt.type.merge loc defsFinal) defsFinal;
value = (opt.apply or id) merged;
</pre>

The <code>apply</code> function is replaced by the identity function and the <code>merge</code> function is replaced by the [https://github.com/NixOS/nixpkgs/blob/785eaf2cea3c57daef96bb209f44589e3f48a7ff/lib/options.nix#L34-L43 <code>mergeDefaultOption</code>] function if they are not defined.

= Types =

Types are used to ensure the correctness of definitions and to provide a way to merge the definitions. All common types are available in [https://github.com/NixOS/nixpkgs/blob/master/lib/types.nix <code>lib/types.nix</code>]. To declare a type you have to write something like:

<pre>
with lib;
services.fooBar.option = mkOption {
type = with types; uniq string;
description = "
...
";
};
</pre>

The <code>check</code> function provided by the type can be a source of strictness, but this is rare because most of the time checked option definitions are fully used by the merge function.

== Simple Types ==

* <code>inferred</code>: Useful when it is used under a meta-type.
* <code>bool</code>: A Boolean useful for enable flags. The merge function is a logical OR between all definitions.
* <code>int</code>: An Integer.
* <code>string</code>: A string where all definitions are concatenated.
* <code>envVar</code>: A string where all definitions are concatenated with a colon between all definitions.
* <code>attrs</code>: An attribute set. (you should prefer <code>attrsOf inferred</code>)
* <code>package</code>: A derivation.

== Meta Types ==

Data meta-types:
* <code>listOf t</code>: A list of elements with the type <code>t</code>.
* <code>attrsOf t</code>: An attribute set of elements with the type <code>t</code>. The merge function zip all attribute sets into one. Attribute values of the resulting attribute set are merged with the merge function of the type <code>t</code>.

Definition meta-types:
* <code>uniq t</code>: This type define raise an error if more than one definitions exists. All other properties are inherited from the type <code>t</code>. This is useful to avoid ambiguous definitions.
* <code>none t</code>: This type define raise an error if at least one definitions exists. All other properties are inherited from the type <code>t</code>. This is useful to provide a computation result to other modules. See also the <code>apply</code> function of option declarations.
* <code>nullOr t</code>: This type allows an option to be null or type <code>t</code>.

== Module Type ==

* <code>optionSet</code>: '''DEPRECATED, probably use submodule instead''' This type is used to benefit from the modular system used by NixOS inside an option. When this type is enabled, it merge the <code>options</code> attribute of option declarations with each definition. The result is the fixed configuration of each module. This option is often see in conjunction with <code>attrsOf</code> or <code>listOf</code>. Modules declared in option declaration appear in the generated manual with a prefix representing the container type, respectively "<code>.<name></code>" and "<code>.*</code>". Reference to definition files do not appears in the generated manual because the system cannot track them.