···

       
139
       
139
       
 
       
      optionAttrSetToDocList optionAttrSetToDocList'

     

       
140
       
140
       
 
       
      scrubOptionValue literalExpression literalExample literalDocBook

     

       
141
       
141
       
 
       
      showOption showOptionWithDefLocs showFiles

     

       
142
       
142
       
-
       
      unknownModule mkOption mkPackageOption

     

       
142
       
142
       
+
       
      unknownModule mkOption mkPackageOption mkPackageOptionMD

     

       
143
       
143
       
 
       
      mdDoc literalMD;

     

       
144
       
144
       
 
       
    inherit (self.types) isType setType defaultTypeMerge defaultFunctor

     

       
145
       
145
       
 
       
      isOptionType mkOptionType;

     

···

       
136
       
136
       
 
       
      let default' = if !isList default then [ default ] else default;

     

       
137
       
137
       
 
       
      in mkOption {

     

       
138
       
138
       
 
       
        type = lib.types.package;

     

       
139
       
139
       
-
       
        description = lib.mdDoc "The ${name} package to use.";

     

       
139
       
139
       
+
       
        description = "The ${name} package to use.";

     

       
140
       
140
       
 
       
        default = attrByPath default'

     

       
141
       
141
       
 
       
          (throw "${concatStringsSep "." default'} cannot be found in pkgs") pkgs;

     

       
142
       
142
       
 
       
        defaultText = literalExpression ("pkgs." + concatStringsSep "." default');

     

       
143
       
143
       
 
       
        ${if example != null then "example" else null} = literalExpression

     

       
144
       
144
       
 
       
          (if isList example then "pkgs." + concatStringsSep "." example else example);

     

       
145
       
145
       
 
       
      };

     

       
146
       
146
       
+
       


     

       
147
       
147
       
+
       
  /* Like mkPackageOption, but emit an mdDoc description instead of DocBook. */

     

       
148
       
148
       
+
       
  mkPackageOptionMD = args: name: extra:

     

       
149
       
149
       
+
       
    let option = mkPackageOption args name extra;

     

       
150
       
150
       
+
       
    in option // { description = lib.mdDoc option.description; };

     

       
146
       
151
       
 
       


     

       
147
       
152
       
 
       
  /* This option accepts anything, but it does not produce any result.

     

       
148
       
153
       
 
       


     

···

       
88
       
88
       
 
       
}

     

       
89
       
89
       
 
       
```

     

       
90
       
90
       
 
       


     

       
91
       
91
       
-
       
### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption}

     

       
91
       
91
       
+
       
### `mkPackageOption`, `mkPackageOptionMD` {#sec-option-declarations-util-mkPackageOption}

     

       
92
       
92
       
 
       


     

       
93
       
93
       
 
       
Usage:

     

       
94
       
94
       
 
       


     
···

       
105
       
105
       
 
       
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.

     

       
106
       
106
       
 
       


     

       
107
       
107
       
 
       
You can omit the default path if the name of the option is also attribute path in nixpkgs.

     

       
108
       
108
       
+
       


     

       
109
       
109
       
+
       
During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed.

     

       
108
       
110
       
 
       


     

       
109
       
111
       
 
       
::: {#ex-options-declarations-util-mkPackageOption .title}

     

       
110
       
112
       
 
       
Examples:

     

···

       
138
       
138
       
 
       
}

     

       
139
       
139
       
 
       
</programlisting>

     

       
140
       
140
       
 
       
      <section xml:id="sec-option-declarations-util-mkPackageOption">

     

       
141
       
141
       
-
       
        <title><literal>mkPackageOption</literal></title>

     

       
141
       
141
       
+
       
        <title><literal>mkPackageOption</literal>,

     

       
142
       
142
       
+
       
        <literal>mkPackageOptionMD</literal></title>

     

       
142
       
143
       
 
       
        <para>

     

       
143
       
144
       
 
       
          Usage:

     

       
144
       
145
       
 
       
        </para>

     
···

       
171
       
172
       
 
       
        <para>

     

       
172
       
173
       
 
       
          You can omit the default path if the name of the option is

     

       
173
       
174
       
 
       
          also attribute path in nixpkgs.

     

       
175
       
175
       
+
       
        </para>

     

       
176
       
176
       
+
       
        <para>

     

       
177
       
177
       
+
       
          During the transition to CommonMark documentation

     

       
178
       
178
       
+
       
          <literal>mkPackageOption</literal> creates an option with a

     

       
179
       
179
       
+
       
          DocBook description attribute, once the transition is

     

       
180
       
180
       
+
       
          completed it will create a CommonMark description instead.

     

       
181
       
181
       
+
       
          <literal>mkPackageOptionMD</literal> always creates an option

     

       
182
       
182
       
+
       
          with a CommonMark description attribute and will be removed

     

       
183
       
183
       
+
       
          some time after the transition is completed.

     

       
174
       
184
       
 
       
        </para>

     

       
175
       
185
       
 
       
        <anchor xml:id="ex-options-declarations-util-mkPackageOption" />

     

       
176
       
186
       
 
       
        <para>

     

···

       
315
       
315
       
 
       
        "  };\n" +

     

       
316
       
316
       
 
       
        "\n" +

     

       
317
       
317
       
 
       
        "  example.enable = mkEnableOption (lib.mdDoc ''your thing'');\n" +

     

       
318
       
318
       
+
       
        "  example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" +

     

       
318
       
319
       
 
       
        "  imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];",

     

       
319
       
320
       
 
       
        file = sys.stderr)

     

       
320
       
321
       
 
       


     

···

       
50
       
50
       
 
       
          (name: value:

     

       
51
       
51
       
 
       
            let

     

       
52
       
52
       
 
       
              wholeName = "${namePrefix}.${name}";

     

       
53
       
53
       
-
       
              guard = lib.warn "Attempt to evaluate package ${wholeName} in option documentation; this is not supported and will eventually be an error. Use `mkPackageOption` or `literalExpression` instead.";

     

       
53
       
53
       
+
       
              guard = lib.warn "Attempt to evaluate package ${wholeName} in option documentation; this is not supported and will eventually be an error. Use `mkPackageOption{,MD}` or `literalExpression` instead.";

     

       
54
       
54
       
 
       
            in if isAttrs value then

     

       
55
       
55
       
 
       
              scrubDerivations wholeName value

     

       
56
       
56
       
 
       
              // optionalAttrs (isDerivation value) {

     

···

       
27
       
27
       
 
       
        '';

     

       
28
       
28
       
 
       
      };

     

       
29
       
29
       
 
       


     

       
30
       
30
       
-
       
      package = mkPackageOption pkgs "1Password GUI" {

     

       
30
       
30
       
+
       
      package = mkPackageOptionMD pkgs "1Password GUI" {

     

       
31
       
31
       
 
       
        default = [ "_1password-gui" ];

     

       
32
       
32
       
 
       
      };

     

       
33
       
33
       
 
       
    };

     

···

       
18
       
18
       
 
       
    programs._1password = {

     

       
19
       
19
       
 
       
      enable = mkEnableOption (lib.mdDoc "the 1Password CLI tool");

     

       
20
       
20
       
 
       


     

       
21
       
21
       
-
       
      package = mkPackageOption pkgs "1Password CLI" {

     

       
21
       
21
       
+
       
      package = mkPackageOptionMD pkgs "1Password CLI" {

     

       
22
       
22
       
 
       
        default = [ "_1password" ];

     

       
23
       
23
       
 
       
      };

     

       
24
       
24
       
 
       
    };

     

···

       
16
       
16
       
 
       
        group.

     

       
17
       
17
       
 
       
      '';

     

       
18
       
18
       
 
       
    };

     

       
19
       
19
       
-
       
    package = mkPackageOption pkgs "flashrom" { };

     

       
19
       
19
       
+
       
    package = mkPackageOptionMD pkgs "flashrom" { };

     

       
20
       
20
       
 
       
  };

     

       
21
       
21
       
 
       


     

       
22
       
22
       
 
       
  config = mkIf cfg.enable {

     

···

       
1
       
1
       
 
       
{ pkgs, config, lib, ... }:

     

       
2
       
2
       
 
       
let

     

       
3
       
3
       
-
       
  inherit (lib) mdDoc mkEnableOption mkPackageOption optional optionalString;

     

       
3
       
3
       
+
       
  inherit (lib) mdDoc mkEnableOption mkPackageOptionMD optional optionalString;

     

       
4
       
4
       
 
       
  cfg = config.programs.skim;

     

       
5
       
5
       
 
       
in

     

       
6
       
6
       
 
       
{

     
···

       
8
       
8
       
 
       
    programs.skim = {

     

       
9
       
9
       
 
       
      fuzzyCompletion = mkEnableOption (mdDoc "fuzzy completion with skim");

     

       
10
       
10
       
 
       
      keybindings = mkEnableOption (mdDoc "skim keybindings");

     

       
11
       
11
       
-
       
      package = mkPackageOption pkgs "skim" {};

     

       
11
       
11
       
+
       
      package = mkPackageOptionMD pkgs "skim" {};

     

       
12
       
12
       
 
       
    };

     

       
13
       
13
       
 
       
  };

     

       
14
       
14
       
 
       


     

···

       
15
       
15
       
 
       
      description = lib.mdDoc "Whether streamdeck-ui should be started automatically.";

     

       
16
       
16
       
 
       
    };

     

       
17
       
17
       
 
       


     

       
18
       
18
       
-
       
    package = mkPackageOption pkgs "streamdeck-ui" {

     

       
18
       
18
       
+
       
    package = mkPackageOptionMD pkgs "streamdeck-ui" {

     

       
19
       
19
       
 
       
      default = [ "streamdeck-ui" ];

     

       
20
       
20
       
 
       
    };

     

       
21
       
21
       
 
       


     

···

       
55
       
55
       
 
       
    services.dgraph = {

     

       
56
       
56
       
 
       
      enable = mkEnableOption (lib.mdDoc "Dgraph native GraphQL database with a graph backend");

     

       
57
       
57
       
 
       


     

       
58
       
58
       
-
       
      package = lib.mkPackageOption pkgs "dgraph" { };

     

       
58
       
58
       
+
       
      package = lib.mkPackageOptionMD pkgs "dgraph" { };

     

       
59
       
59
       
 
       


     

       
60
       
60
       
 
       
      settings = mkOption {

     

       
61
       
61
       
 
       
        type = settingsFormat.type;

     

···

       
128
       
128
       
 
       
          '';

     

       
129
       
129
       
 
       
        };

     

       
130
       
130
       
 
       
      };

     

       
131
       
131
       
-
       
      package = mkPackageOption pkgs "listmonk" {};

     

       
131
       
131
       
+
       
      package = mkPackageOptionMD pkgs "listmonk" {};

     

       
132
       
132
       
 
       
      settings = mkOption {

     

       
133
       
133
       
 
       
        type = types.submodule { freeformType = tomlFormat.type; };

     

       
134
       
134
       
 
       
        description = lib.mdDoc ''

     

···

       
7
       
7
       
 
       
  options = {

     

       
8
       
8
       
 
       
    services.input-remapper = {

     

       
9
       
9
       
 
       
      enable = mkEnableOption (lib.mdDoc "input-remapper, an easy to use tool to change the mapping of your input device buttons.");

     

       
10
       
10
       
-
       
      package = options.mkPackageOption pkgs "input-remapper" { };

     

       
10
       
10
       
+
       
      package = mkPackageOptionMD pkgs "input-remapper" { };

     

       
11
       
11
       
 
       
      enableUdevRules = mkEnableOption (lib.mdDoc "udev rules added by input-remapper to handle hotplugged devices. Currently disabled by default due to https://github.com/sezanzeb/input-remapper/issues/140");

     

       
12
       
12
       
 
       
      serviceWantedBy = mkOption {

     

       
13
       
13
       
 
       
        default = [ "graphical.target" ];

     

···

       
13
       
13
       
 
       
    services.polaris = {

     

       
14
       
14
       
 
       
      enable = mkEnableOption (lib.mdDoc "Polaris Music Server");

     

       
15
       
15
       
 
       


     

       
16
       
16
       
-
       
      package = mkPackageOption pkgs "polaris" { };

     

       
16
       
16
       
+
       
      package = mkPackageOptionMD pkgs "polaris" { };

     

       
17
       
17
       
 
       


     

       
18
       
18
       
 
       
      user = mkOption {

     

       
19
       
19
       
 
       
        type = types.str;

     

···

       
116
       
116
       
 
       
  };

     

       
117
       
117
       
 
       
in {

     

       
118
       
118
       
 
       
  options.networking.openconnect = {

     

       
119
       
119
       
-
       
    package = mkPackageOption pkgs "openconnect" { };

     

       
119
       
119
       
+
       
    package = mkPackageOptionMD pkgs "openconnect" { };

     

       
120
       
120
       
 
       


     

       
121
       
121
       
 
       
    interfaces = mkOption {

     

       
122
       
122
       
 
       
      description = lib.mdDoc "OpenConnect interfaces.";

     

···

       
14
       
14
       
 
       


     

       
15
       
15
       
 
       
      enable = mkEnableOption (lib.mdDoc "ShellHub Agent daemon");

     

       
16
       
16
       
 
       


     

       
17
       
17
       
-
       
      package = mkPackageOption pkgs "shellhub-agent" { };

     

       
17
       
17
       
+
       
      package = mkPackageOptionMD pkgs "shellhub-agent" { };

     

       
18
       
18
       
 
       


     

       
19
       
19
       
 
       
      preferredHostname = mkOption {

     

       
20
       
20
       
 
       
        type = types.str;

     

···

       
71
       
71
       
 
       
    services.vdirsyncer = {

     

       
72
       
72
       
 
       
      enable = mkEnableOption (mdDoc "vdirsyncer");

     

       
73
       
73
       
 
       


     

       
74
       
74
       
-
       
      package = mkPackageOption pkgs "vdirsyncer" {};

     

       
74
       
74
       
+
       
      package = mkPackageOptionMD pkgs "vdirsyncer" {};

     

       
75
       
75
       
 
       


     

       
76
       
76
       
 
       
      jobs = mkOption {

     

       
77
       
77
       
 
       
        description = mdDoc "vdirsyncer job configurations";

     

···

       
36
       
36
       
 
       
        which execute configured commands for any person or service that knows the URL

     

       
37
       
37
       
 
       
      '');

     

       
38
       
38
       
 
       


     

       
39
       
39
       
-
       
      package = mkPackageOption pkgs "webhook" {};

     

       
39
       
39
       
+
       
      package = mkPackageOptionMD pkgs "webhook" {};

     

       
40
       
40
       
 
       
      user = mkOption {

     

       
41
       
41
       
 
       
        type = types.str;

     

       
42
       
42
       
 
       
        default = defaultUser;

     

···

       
174
       
174
       
 
       
        };

     

       
175
       
175
       
 
       
      };

     

       
176
       
176
       
 
       


     

       
177
       
177
       
-
       
      package = mkPackageOption pkgs "transmission" {};

     

       
177
       
177
       
+
       
      package = mkPackageOptionMD pkgs "transmission" {};

     

       
178
       
178
       
 
       


     

       
179
       
179
       
 
       
      downloadDirPermissions = mkOption {

     

       
180
       
180
       
 
       
        type = with types; nullOr str;

     

···

       
1
       
1
       
 
       
{ config, lib, pkgs, ... }:

     

       
2
       
2
       
 
       


     

       
3
       
3
       
 
       
let

     

       
4
       
4
       
-
       
  inherit (lib) mdDoc mkEnableOption mkIf mkPackageOption singleton;

     

       
4
       
4
       
+
       
  inherit (lib) mdDoc mkEnableOption mkIf mkPackageOptionMD singleton;

     

       
5
       
5
       
 
       
  cfg = config.services.xserver.windowManager.katriawm;

     

       
6
       
6
       
 
       
in

     

       
7
       
7
       
 
       
{

     
···

       
9
       
9
       
 
       
  options = {

     

       
10
       
10
       
 
       
    services.xserver.windowManager.katriawm = {

     

       
11
       
11
       
 
       
      enable = mkEnableOption (mdDoc "katriawm");

     

       
12
       
12
       
-
       
      package = mkPackageOption pkgs "katriawm" {};

     

       
12
       
12
       
+
       
      package = mkPackageOptionMD pkgs "katriawm" {};

     

       
13
       
13
       
 
       
    };

     

       
14
       
14
       
 
       
  };

     

       
15
       
15
       
 
       


     

···

       
10
       
10
       
 
       
  options.services.xserver.windowManager.qtile = {

     

       
11
       
11
       
 
       
    enable = mkEnableOption (lib.mdDoc "qtile");

     

       
12
       
12
       
 
       


     

       
13
       
13
       
-
       
    package = mkPackageOption pkgs "qtile" { };

     

       
13
       
13
       
+
       
    package = mkPackageOptionMD pkgs "qtile" { };

     

       
14
       
14
       
 
       
  };

     

       
15
       
15
       
 
       


     

       
16
       
16
       
 
       
  config = mkIf cfg.enable {

     

···

       
142
       
142
       
 
       
      '';

     

       
143
       
143
       
 
       
    };

     

       
144
       
144
       
 
       


     

       
145
       
145
       
-
       
    package = (mkPackageOption pkgs "systemd" {

     

       
145
       
145
       
+
       
    package = (mkPackageOptionMD pkgs "systemd" {

     

       
146
       
146
       
 
       
      default = "systemdStage1";

     

       
147
       
147
       
 
       
    }) // {

     

       
148
       
148
       
 
       
      visible = false;