alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

Merge pull request #155669 from schuelermine/patch-mkPackageOption

Browse source 
lib/options: Add mkPackageOption
This commit is contained in:
pennae 2022-01-24 13:35:32 +00:00 committed by GitHub
parent 16d0f35e6b c008b3d100
commit 865a9ed3f5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 324 additions and 103 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
lib/options.nix
View file

@ -26,6 +26,7 @@ let
take
;
inherit (lib.attrsets)
attrByPath
optionalAttrs
;
inherit (lib.strings)
@ -99,6 +100,49 @@ rec {
type = lib.types.bool;
};
/* Creates an Option attribute set for an option that specifies the
package a module should use for some purpose.
Type: mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> option
The package is specified as a list of strings representing its attribute path in nixpkgs.
Because of this, you need to pass nixpkgs itself as the first argument.
The second argument is the name of the option, used in the description "The <name> package to use.".
You can also pass an example value, either a literal string or a package's attribute path.
You can omit the default path if the name of the option is also attribute path in nixpkgs.
Example:
mkPackageOption pkgs "hello" { }
=> { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }
Example:
mkPackageOption pkgs "GHC" {
default = [ "ghc" ];
example = "pkgs.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
=> { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; }
*/
mkPackageOption =
# Package set (a specific version of nixpkgs)
pkgs:
# Name for the package, shown in option description
name:
{ default ? [ name ], example ? null }:
let default' = if !isList default then [ default ] else default;
in mkOption {
type = lib.types.package;
description = "The ${name} package to use.";
default = attrByPath default'
(throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs;
defaultText = literalExpression ("pkgs." + concatStringsSep "." default');
${if example != null then "example" else null} = literalExpression
(if isList example then "pkgs." + concatStringsSep "." example else example);
};
/* This option accepts anything, but it does not produce any result.
This is useful for sharing a module across different module sets

74
nixos/doc/manual/development/option-declarations.section.md
View file

@ -57,6 +57,80 @@ The function `mkOption` accepts the following arguments.
: A textual description of the option, in DocBook format, that will be
included in the NixOS manual.
## Utility functions for common option patterns {#sec-option-declarations-util}
### `mkEnableOption` {#sec-option-declarations-util-mkEnableOption}
Creates an Option attribute set for a boolean value option i.e an
option to be toggled on or off.
This function takes a single string argument, the name of the thing to be toggled.
The option's description is "Whether to enable \<name\>.".
For example:
::: {#ex-options-declarations-util-mkEnableOption-magic .example}
```nix
lib.mkEnableOption "magic"
# is like
lib.mkOption {
type = lib.types.bool;
default = false;
example = true;
description = "Whether to enable magic.";
}
```
### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption}
Usage:
```nix
mkPackageOption pkgs "name" { default = [ "path" "in" "pkgs" ]; example = "literal example"; }
```
Creates an Option attribute set for an option that specifies the package a module should use for some purpose.
**Note**: You shouldn’t necessarily make package options for all of your modules. You can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).
The default package is specified as a list of strings representing its attribute path in nixpkgs. Because of this, you need to pass nixpkgs itself as the first argument.
The second argument is the name of the option, used in the description "The \<name\> package to use.". You can also pass an example value, either a literal string or a package's attribute path.
You can omit the default path if the name of the option is also attribute path in nixpkgs.
::: {#ex-options-declarations-util-mkPackageOption .title}
Examples:
::: {#ex-options-declarations-util-mkPackageOption-hello .example}
```nix
lib.mkPackageOption pkgs "hello" { }
# is like
lib.mkOption {
type = lib.types.package;
default = pkgs.hello;
defaultText = lib.literalExpression "pkgs.hello";
description = "The hello package to use.";
}
```
::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
```nix
lib.mkPackageOption pkgs "GHC" {
default = [ "ghc" ];
example = "pkgs.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
# is like
lib.mkOption {
type = lib.types.package;
default = pkgs.ghc;
defaultText = lib.literalExpression "pkgs.ghc";
example = lib.literalExpression "pkgs.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])";
description = "The GHC package to use.";
}
```
## Extensible Option Types {#sec-option-declarations-eot}
Extensible option types is a feature that allow to extend certain types

189
nixos/doc/manual/from_md/development/option-declarations.section.xml
View file

@ -97,25 +97,122 @@ options = {
</listitem>
</varlistentry>
</variablelist>
<section xml:id="sec-option-declarations-util">
<title>Utility functions for common option patterns</title>
<section xml:id="sec-option-declarations-util-mkEnableOption">
<title><literal>mkEnableOption</literal></title>
<para>
Creates an Option attribute set for a boolean value option i.e
an option to be toggled on or off.
</para>
<para>
This function takes a single string argument, the name of the
thing to be toggled.
</para>
<para>
The option’s description is <quote>Whether to enable
&lt;name&gt;.</quote>.
</para>
<para>
For example:
</para>
<anchor xml:id="ex-options-declarations-util-mkEnableOption-magic" />
<programlisting language="bash">
lib.mkEnableOption &quot;magic&quot;
# is like
lib.mkOption {
type = lib.types.bool;
default = false;
example = true;
description = &quot;Whether to enable magic.&quot;;
}
</programlisting>
<section xml:id="sec-option-declarations-util-mkPackageOption">
<title><literal>mkPackageOption</literal></title>
<para>
Usage:
</para>
<programlisting language="bash">
mkPackageOption pkgs &quot;name&quot; { default = [ &quot;path&quot; &quot;in&quot; &quot;pkgs&quot; ]; example = &quot;literal example&quot;; }
</programlisting>
<para>
Creates an Option attribute set for an option that specifies
the package a module should use for some purpose.
</para>
<para>
<emphasis role="strong">Note</emphasis>: You shouldn’t
necessarily make package options for all of your modules. You
can always overwrite a specific package throughout nixpkgs by
using
<link xlink:href="https://nixos.org/manual/nixpkgs/stable/#chap-overlays">nixpkgs
overlays</link>.
</para>
<para>
The default package is specified as a list of strings
representing its attribute path in nixpkgs. Because of this,
you need to pass nixpkgs itself as the first argument.
</para>
<para>
The second argument is the name of the option, used in the
description <quote>The &lt;name&gt; package to use.</quote>.
You can also pass an example value, either a literal string or
a package’s attribute path.
</para>
<para>
You can omit the default path if the name of the option is
also attribute path in nixpkgs.
</para>
<anchor xml:id="ex-options-declarations-util-mkPackageOption" />
<para>
Examples:
</para>
<anchor xml:id="ex-options-declarations-util-mkPackageOption-hello" />
<programlisting language="bash">
lib.mkPackageOption pkgs &quot;hello&quot; { }
# is like
lib.mkOption {
type = lib.types.package;
default = pkgs.hello;
defaultText = lib.literalExpression &quot;pkgs.hello&quot;;
description = &quot;The hello package to use.&quot;;
}
</programlisting>
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
<programlisting language="bash">
lib.mkPackageOption pkgs &quot;GHC&quot; {
default = [ &quot;ghc&quot; ];
example = &quot;pkgs.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])&quot;;
}
# is like
lib.mkOption {
type = lib.types.package;
default = pkgs.ghc;
defaultText = lib.literalExpression &quot;pkgs.ghc&quot;;
example = lib.literalExpression &quot;pkgs.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])&quot;;
description = &quot;The GHC package to use.&quot;;
}
</programlisting>
<section xml:id="sec-option-declarations-eot">
<title>Extensible Option Types</title>
<para>
Extensible option types is a feature that allow to extend certain
types declaration through multiple module files. This feature only
work with a restricted set of types, namely
<literal>enum</literal> and <literal>submodules</literal> and any
composed forms of them.
Extensible option types is a feature that allow to extend
certain types declaration through multiple module files.
This feature only work with a restricted set of types,
namely <literal>enum</literal> and
<literal>submodules</literal> and any composed forms of
them.
</para>
<para>
Extensible option types can be used for <literal>enum</literal>
options that affects multiple modules, or as an alternative to
related <literal>enable</literal> options.
Extensible option types can be used for
<literal>enum</literal> options that affects multiple
modules, or as an alternative to related
<literal>enable</literal> options.
</para>
<para>
As an example, we will take the case of display managers. There is
a central display manager module for generic display manager
options and a module file per display manager backend (sddm, gdm
...).
As an example, we will take the case of display managers.
There is a central display manager module for generic
display manager options and a module file per display
manager backend (sddm, gdm ...).
</para>
<para>
There are two approach to this module structure:
@ -124,13 +221,15 @@ options = {
<listitem>
<para>
Managing the display managers independently by adding an
enable option to every display manager module backend. (NixOS)
enable option to every display manager module backend.
(NixOS)
</para>
</listitem>
<listitem>
<para>
Managing the display managers in the central module by adding
an option to select which display manager backend to use.
Managing the display managers in the central module by
adding an option to select which display manager backend
to use.
</para>
</listitem>
</itemizedlist>
@ -138,43 +237,44 @@ options = {
Both approaches have problems.
</para>
<para>
Making backends independent can quickly become hard to manage. For
display managers, there can be only one enabled at a time, but the
type system can not enforce this restriction as there is no
relation between each backend <literal>enable</literal> option. As
a result, this restriction has to be done explicitely by adding
assertions in each display manager backend module.
Making backends independent can quickly become hard to
manage. For display managers, there can be only one enabled
at a time, but the type system can not enforce this
restriction as there is no relation between each backend
<literal>enable</literal> option. As a result, this
restriction has to be done explicitely by adding assertions
in each display manager backend module.
</para>
<para>
On the other hand, managing the display managers backends in the
central module will require to change the central module option
every time a new backend is added or removed.
On the other hand, managing the display managers backends in
the central module will require to change the central module
option every time a new backend is added or removed.
</para>
<para>
By using extensible option types, it is possible to create a
placeholder option in the central module
(<link linkend="ex-option-declaration-eot-service">Example:
Extensible type placeholder in the service module</link>), and to
extend it in each backend module
Extensible type placeholder in the service module</link>),
and to extend it in each backend module
(<link linkend="ex-option-declaration-eot-backend-gdm">Example:
Extending
<literal>services.xserver.displayManager.enable</literal> in the
<literal>gdm</literal> module</link>,
<literal>services.xserver.displayManager.enable</literal> in
the <literal>gdm</literal> module</link>,
<link linkend="ex-option-declaration-eot-backend-sddm">Example:
Extending
<literal>services.xserver.displayManager.enable</literal> in the
<literal>sddm</literal> module</link>).
<literal>services.xserver.displayManager.enable</literal> in
the <literal>sddm</literal> module</link>).
</para>
<para>
As a result, <literal>displayManager.enable</literal> option
values can be added without changing the main service module file
and the type system automatically enforce that there can only be a
single display manager enabled.
values can be added without changing the main service module
file and the type system automatically enforce that there
can only be a single display manager enabled.
</para>
<anchor xml:id="ex-option-declaration-eot-service" />
<para>
<emphasis role="strong">Example: Extensible type placeholder in
the service module</emphasis>
<emphasis role="strong">Example: Extensible type placeholder
in the service module</emphasis>
</para>
<programlisting language="bash">
services.xserver.displayManager.enable = mkOption {
@ -185,8 +285,8 @@ services.xserver.displayManager.enable = mkOption {
<anchor xml:id="ex-option-declaration-eot-backend-gdm" />
<para>
<emphasis role="strong">Example: Extending
<literal>services.xserver.displayManager.enable</literal> in the
<literal>gdm</literal> module</emphasis>
<literal>services.xserver.displayManager.enable</literal> in
the <literal>gdm</literal> module</emphasis>
</para>
<programlisting language="bash">
services.xserver.displayManager.enable = mkOption {
@ -196,8 +296,8 @@ services.xserver.displayManager.enable = mkOption {
<anchor xml:id="ex-option-declaration-eot-backend-sddm" />
<para>
<emphasis role="strong">Example: Extending
<literal>services.xserver.displayManager.enable</literal> in the
<literal>sddm</literal> module</emphasis>
<literal>services.xserver.displayManager.enable</literal> in
the <literal>sddm</literal> module</emphasis>
</para>
<programlisting language="bash">
services.xserver.displayManager.enable = mkOption {
@ -206,16 +306,19 @@ services.xserver.displayManager.enable = mkOption {
</programlisting>
<para>
The placeholder declaration is a standard
<literal>mkOption</literal> declaration, but it is important that
extensible option declarations only use the
<literal>mkOption</literal> declaration, but it is important
that extensible option declarations only use the
<literal>type</literal> argument.
</para>
<para>
Extensible option types work with any of the composed variants of
<literal>enum</literal> such as
Extensible option types work with any of the composed
variants of <literal>enum</literal> such as
<literal>with types; nullOr (enum [ &quot;foo&quot; &quot;bar&quot; ])</literal>
or
<literal>with types; listOf (enum [ &quot;foo&quot; &quot;bar&quot; ])</literal>.
</para>
</section>
</section>
</section>
</section>
</section>