commit e14de56613fc8e42fb6249031efe9e7abbb65286 · pyrox.dev/nixpkgs

+21 -11

lib/modules.nix

···

       231
       231
        
            correspond to the definition of 'loc' in 'opt.file'. */

     

       232
       232
        
         mergeOptionDecls = loc: opts:

     

       233
       233
        
           foldl' (res: opt:

     

       234
       234
       -
             if opt.options ? default && res ? default ||

     

       235
       235
       -
                opt.options ? example && res ? example ||

     

       236
       236
       -
                opt.options ? description && res ? description ||

     

       237
       237
       -
                opt.options ? apply && res ? apply ||

     

       238
       238
       -
                # Accept to merge options which have identical types.

     

       239
       239
       -
                opt.options ? type && res ? type && opt.options.type.name != res.type.name

     

       234
       234
       +
             let t  = res.type;

     

       235
       235
       +
                 t' = opt.options.type;

     

       236
       236
       +
                 mergedType = t.typeMerge t'.functor;

     

       237
       237
       +
                 typesMergeable = mergedType != null;

     

       238
       238
       +
                 typeSet = if (bothHave "type") && typesMergeable

     

       239
       239
       +
                              then { type = mergedType; }

     

       240
       240
       +
                              else {};

     

       241
       241
       +
                 bothHave = k: opt.options ? ${k} && res ? ${k};

     

       242
       242
       +
             in

     

       243
       243
       +
             if bothHave "default" ||

     

       244
       244
       +
                bothHave "example" ||

     

       245
       245
       +
                bothHave "description" ||

     

       246
       246
       +
                bothHave "apply" ||

     

       247
       247
       +
                (bothHave "type" && (! typesMergeable))

     

       240
       248
        
             then

     

       241
       249
        
               throw "The option `${showOption loc}' in `${opt.file}' is already declared in ${showFiles res.declarations}."

     

       242
       250
        
             else

     
···

       258
       266
        
               in opt.options // res //

     

       259
       267
        
                 { declarations = res.declarations ++ [opt.file];

     

       260
       268
        
                   options = submodules;

     

       261
       261
       -
                 }

     

       269
       269
       +
                 } // typeSet

     

       262
       270
        
           ) { inherit loc; declarations = []; options = []; } opts;

     

       263
       271
        
       

     

       264
       272
        
         /* Merge all the definitions of an option to produce the final

     
···

       422
       430
        
             options = opt.options or

     

       423
       431
        
               (throw "Option `${showOption loc'}' has type optionSet but has no option attribute, in ${showFiles opt.declarations}.");

     

       424
       432
        
             f = tp:

     

       433
       433
       +
               let optionSetIn = type: (tp.name == type) && (tp.functor.wrapped.name == "optionSet");

     

       434
       434
       +
               in

     

       425
       435
        
               if tp.name == "option set" || tp.name == "submodule" then

     

       426
       436
        
                 throw "The option ${showOption loc} uses submodules without a wrapping type, in ${showFiles opt.declarations}."

     

       427
       427
       -
               else if tp.name == "attribute set of option sets" then types.attrsOf (types.submodule options)

     

       428
       428
       -
               else if tp.name == "list or attribute set of option sets" then types.loaOf (types.submodule options)

     

       429
       429
       -
               else if tp.name == "list of option sets" then types.listOf (types.submodule options)

     

       430
       430
       -
               else if tp.name == "null or option set" then types.nullOr (types.submodule options)

     

       437
       437
       +
               else if optionSetIn "attrsOf" then types.attrsOf (types.submodule options)

     

       438
       438
       +
               else if optionSetIn "loaOf"   then types.loaOf   (types.submodule options)

     

       439
       439
       +
               else if optionSetIn "listOf"  then types.listOf  (types.submodule options)

     

       440
       440
       +
               else if optionSetIn "nullOr"  then types.nullOr  (types.submodule options)

     

       431
       441
        
               else tp;

     

       432
       442
        
           in

     

       433
       443
        
             if opt.type.getSubModules or null == null

+1 -1

lib/options.nix

···

       92
       92
        
                 internal = opt.internal or false;

     

       93
       93
        
                 visible = opt.visible or true;

     

       94
       94
        
                 readOnly = opt.readOnly or false;

     

       95
       95
       -
                 type = opt.type.name or null;

     

       95
       95
       +
                 type = opt.type.description or null;

     

       96
       96
        
               }

     

       97
       97
        
               // (if opt ? example then { example = scrubOptionValue opt.example; } else {})

     

       98
       98
        
               // (if opt ? default then { default = scrubOptionValue opt.default; } else {})

+115 -27

lib/types.nix

···

       17
       17
        
         };

     

       18
       18
        
       

     

       19
       19
        
       

     

       20
       20
       +
         # Default type merging function

     

       21
       21
       +
         # takes two type functors and return the merged type

     

       22
       22
       +
         defaultTypeMerge = f: f':

     

       23
       23
       +
           let wrapped = f.wrapped.typeMerge f'.wrapped.functor;

     

       24
       24
       +
               payload = f.binOp f.payload f'.payload;

     

       25
       25
       +
           in

     

       26
       26
       +
           # cannot merge different types

     

       27
       27
       +
           if f.name != f'.name

     

       28
       28
       +
              then null

     

       29
       29
       +
           # simple types

     

       30
       30
       +
           else if    (f.wrapped == null && f'.wrapped == null)

     

       31
       31
       +
                   && (f.payload == null && f'.payload == null)

     

       32
       32
       +
              then f.type

     

       33
       33
       +
           # composed types

     

       34
       34
       +
           else if (f.wrapped != null && f'.wrapped != null) && (wrapped != null)

     

       35
       35
       +
              then f.type wrapped

     

       36
       36
       +
           # value types

     

       37
       37
       +
           else if (f.payload != null && f'.payload != null) && (payload != null)

     

       38
       38
       +
              then f.type payload

     

       39
       39
       +
           else null;

     

       40
       40
       +
       

     

       41
       41
       +
         # Default type functor

     

       42
       42
       +
         defaultFunctor = name: {

     

       43
       43
       +
           inherit name;

     

       44
       44
       +
           type    = types."${name}" or null;

     

       45
       45
       +
           wrapped = null;

     

       46
       46
       +
           payload = null;

     

       47
       47
       +
           binOp   = a: b: null;

     

       48
       48
       +
         };

     

       49
       49
       +
       

     

       20
       50
        
         isOptionType = isType "option-type";

     

       21
       51
        
         mkOptionType =

     

       22
       22
       -
           { # Human-readable representation of the type.

     

       52
       52
       +
           { # Human-readable representation of the type, should be equivalent to

     

       53
       53
       +
             # the type function name.

     

       23
       54
        
             name

     

       55
       55
       +
           , # Description of the type, defined recursively by embedding the the wrapped type if any.

     

       56
       56
       +
             description ? null

     

       24
       57
        
           , # Function applied to each definition that should return true if

     

       25
       58
        
             # its type-correct, false otherwise.

     

       26
       59
        
             check ? (x: true)

     
···

       36
       69
        
             getSubOptions ? prefix: {}

     

       37
       70
        
           , # List of modules if any, or null if none.

     

       38
       71
        
             getSubModules ? null

     

       39
       39
       -
           , # Function for building the same option type  with a different list of

     

       72
       72
       +
           , # Function for building the same option type with a different list of

     

       40
       73
        
             # modules.

     

       41
       74
        
             substSubModules ? m: null

     

       75
       75
       +
           , # Function that merge type declarations.

     

       76
       76
       +
             # internal, takes a functor as argument and returns the merged type.

     

       77
       77
       +
             # returning null means the type is not mergeable

     

       78
       78
       +
             typeMerge ? defaultTypeMerge functor

     

       79
       79
       +
           , # The type functor.

     

       80
       80
       +
             # internal, representation of the type as an attribute set.

     

       81
       81
       +
             #   name: name of the type

     

       82
       82
       +
             #   type: type function.

     

       83
       83
       +
             #   wrapped: the type wrapped in case of compound types.

     

       84
       84
       +
             #   payload: values of the type, two payloads of the same type must be 

     

       85
       85
       +
             #            combinable with the binOp binary operation.

     

       86
       86
       +
             #   binOp: binary operation that merge two payloads of the same type.

     

       87
       87
       +
             functor ? defaultFunctor name

     

       42
       88
        
           }:

     

       43
       89
        
           { _type = "option-type";

     

       44
       44
       -
             inherit name check merge getSubOptions getSubModules substSubModules;

     

       90
       90
       +
             inherit name check merge getSubOptions getSubModules substSubModules typeMerge functor;

     

       91
       91
       +
             description = if description == null then name else description;

     

       45
       92
        
           };

     

       46
       93
        
       

     

       47
       94
        
       

     
···

       52
       99
        
           };

     

       53
       100
        
       

     

       54
       101
        
           bool = mkOptionType {

     

       55
       55
       -
             name = "boolean";

     

       102
       102
       +
             name = "bool";

     

       103
       103
       +
             description = "boolean";

     

       56
       104
        
             check = isBool;

     

       57
       105
        
             merge = mergeEqualOption;

     

       58
       106
        
           };

     

       59
       107
        
       

     

       60
       60
       -
           int = mkOptionType {

     

       61
       61
       -
             name = "integer";

     

       108
       108
       +
           int = mkOptionType rec {

     

       109
       109
       +
             name = "int";

     

       110
       110
       +
             description = "integer";

     

       62
       111
        
             check = isInt;

     

       63
       112
        
             merge = mergeOneOption;

     

       64
       113
        
           };

     

       65
       114
        
       

     

       66
       115
        
           str = mkOptionType {

     

       67
       67
       -
             name = "string";

     

       116
       116
       +
             name = "str";

     

       117
       117
       +
             description = "string";

     

       68
       118
        
             check = isString;

     

       69
       119
        
             merge = mergeOneOption;

     

       70
       120
        
           };

     

       71
       121
        
       

     

       72
       122
        
           # Merge multiple definitions by concatenating them (with the given

     

       73
       123
        
           # separator between the values).

     

       74
       74
       -
           separatedString = sep: mkOptionType {

     

       75
       75
       -
             name = "string";

     

       124
       124
       +
           separatedString = sep: mkOptionType rec {

     

       125
       125
       +
             name = "separatedString";

     

       126
       126
       +
             description = "string";

     

       76
       127
        
             check = isString;

     

       77
       128
        
             merge = loc: defs: concatStringsSep sep (getValues defs);

     

       129
       129
       +
             functor = (defaultFunctor name) // {

     

       130
       130
       +
               payload = sep;

     

       131
       131
       +
               binOp = sepLhs: sepRhs:

     

       132
       132
       +
                 if sepLhs == sepRhs then sepLhs

     

       133
       133
       +
                 else null;

     

       134
       134
       +
             };

     

       78
       135
        
           };

     

       79
       136
        
       

     

       80
       137
        
           lines = separatedString "\n";

     
···

       86
       143
        
           string = separatedString "";

     

       87
       144
        
       

     

       88
       145
        
           attrs = mkOptionType {

     

       89
       89
       -
             name = "attribute set";

     

       146
       146
       +
             name = "attrs";

     

       147
       147
       +
             description = "attribute set";

     

       90
       148
        
             check = isAttrs;

     

       91
       149
        
             merge = loc: foldl' (res: def: mergeAttrs res def.value) {};

     

       92
       150
        
           };

     
···

       114
       172
        
           # drop this in the future:

     

       115
       173
        
           list = builtins.trace "`types.list' is deprecated; use `types.listOf' instead" types.listOf;

     

       116
       174
        
       

     

       117
       117
       -
           listOf = elemType: mkOptionType {

     

       118
       118
       -
             name = "list of ${elemType.name}s";

     

       175
       175
       +
           listOf = elemType: mkOptionType rec {

     

       176
       176
       +
             name = "listOf";

     

       177
       177
       +
             description = "list of ${elemType.description}s";

     

       119
       178
        
             check = isList;

     

       120
       179
        
             merge = loc: defs:

     

       121
       180
        
               map (x: x.value) (filter (x: x ? value) (concatLists (imap (n: def:

     
···

       132
       191
        
             getSubOptions = prefix: elemType.getSubOptions (prefix ++ ["*"]);

     

       133
       192
        
             getSubModules = elemType.getSubModules;

     

       134
       193
        
             substSubModules = m: listOf (elemType.substSubModules m);

     

       194
       194
       +
             functor = (defaultFunctor name) // { wrapped = elemType; };

     

       135
       195
        
           };

     

       136
       196
        
       

     

       137
       137
       -
           attrsOf = elemType: mkOptionType {

     

       138
       138
       -
             name = "attribute set of ${elemType.name}s";

     

       197
       197
       +
           attrsOf = elemType: mkOptionType rec {

     

       198
       198
       +
             name = "attrsOf";

     

       199
       199
       +
             description = "attribute set of ${elemType.description}s";

     

       139
       200
        
             check = isAttrs;

     

       140
       201
        
             merge = loc: defs:

     

       141
       202
        
               mapAttrs (n: v: v.value) (filterAttrs (n: v: v ? value) (zipAttrsWith (name: defs:

     
···

       147
       208
        
             getSubOptions = prefix: elemType.getSubOptions (prefix ++ ["<name>"]);

     

       148
       209
        
             getSubModules = elemType.getSubModules;

     

       149
       210
        
             substSubModules = m: attrsOf (elemType.substSubModules m);

     

       211
       211
       +
             functor = (defaultFunctor name) // { wrapped = elemType; };

     

       150
       212
        
           };

     

       151
       213
        
       

     

       152
       214
        
           # List or attribute set of ...

     
···

       165
       227
        
                   def;

     

       166
       228
        
               listOnly = listOf elemType;

     

       167
       229
        
               attrOnly = attrsOf elemType;

     

       168
       168
       -
             in mkOptionType {

     

       169
       169
       -
               name = "list or attribute set of ${elemType.name}s";

     

       230
       230
       +
             in mkOptionType rec {

     

       231
       231
       +
               name = "loaOf";

     

       232
       232
       +
               description = "list or attribute set of ${elemType.description}s";

     

       170
       233
        
               check = x: isList x || isAttrs x;

     

       171
       234
        
               merge = loc: defs: attrOnly.merge loc (imap convertIfList defs);

     

       172
       235
        
               getSubOptions = prefix: elemType.getSubOptions (prefix ++ ["<name?>"]);

     

       173
       236
        
               getSubModules = elemType.getSubModules;

     

       174
       237
        
               substSubModules = m: loaOf (elemType.substSubModules m);

     

       238
       238
       +
               functor = (defaultFunctor name) // { wrapped = elemType; };

     

       175
       239
        
             };

     

       176
       240
        
       

     

       177
       241
        
           # List or element of ...

     

       178
       178
       -
           loeOf = elemType: mkOptionType {

     

       179
       179
       -
             name = "element or list of ${elemType.name}s";

     

       242
       242
       +
           loeOf = elemType: mkOptionType rec {

     

       243
       243
       +
             name = "loeOf";

     

       244
       244
       +
             description = "element or list of ${elemType.description}s";

     

       180
       245
        
             check = x: isList x || elemType.check x;

     

       181
       246
        
             merge = loc: defs:

     

       182
       247
        
               let

     
···

       189
       254
        
               else if !isString res then

     

       190
       255
        
                 throw "The option `${showOption loc}' does not have a string value, in ${showFiles (getFiles defs)}."

     

       191
       256
        
               else res;

     

       257
       257
       +
             functor = (defaultFunctor name) // { wrapped = elemType; };

     

       192
       258
        
           };

     

       193
       259
        
       

     

       194
       194
       -
           uniq = elemType: mkOptionType {

     

       195
       195
       -
             inherit (elemType) name check;

     

       260
       260
       +
           uniq = elemType: mkOptionType rec {

     

       261
       261
       +
             name = "uniq";

     

       262
       262
       +
             inherit (elemType) description check;

     

       196
       263
        
             merge = mergeOneOption;

     

       197
       264
        
             getSubOptions = elemType.getSubOptions;

     

       198
       265
        
             getSubModules = elemType.getSubModules;

     

       199
       266
        
             substSubModules = m: uniq (elemType.substSubModules m);

     

       267
       267
       +
             functor = (defaultFunctor name) // { wrapped = elemType; };

     

       200
       268
        
           };

     

       201
       269
        
       

     

       202
       202
       -
           nullOr = elemType: mkOptionType {

     

       203
       203
       -
             name = "null or ${elemType.name}";

     

       270
       270
       +
           nullOr = elemType: mkOptionType rec {

     

       271
       271
       +
             name = "nullOr";

     

       272
       272
       +
             description = "null or ${elemType.description}";

     

       204
       273
        
             check = x: x == null || elemType.check x;

     

       205
       274
        
             merge = loc: defs:

     

       206
       275
        
               let nrNulls = count (def: def.value == null) defs; in

     
···

       211
       280
        
             getSubOptions = elemType.getSubOptions;

     

       212
       281
        
             getSubModules = elemType.getSubModules;

     

       213
       282
        
             substSubModules = m: nullOr (elemType.substSubModules m);

     

       283
       283
       +
             functor = (defaultFunctor name) // { wrapped = elemType; };

     

       214
       284
        
           };

     

       215
       285
        
       

     

       216
       286
        
           submodule = opts:

     
···

       236
       306
        
                   args = { name = ""; }; }).options;

     

       237
       307
        
               getSubModules = opts';

     

       238
       308
        
               substSubModules = m: submodule m;

     

       309
       309
       +
               functor = (defaultFunctor name) // {

     

       310
       310
       +
                 # Merging of submodules is done as part of mergeOptionDecls, as we have to annotate

     

       311
       311
       +
                 # each submodule with its location.

     

       312
       312
       +
                 payload = [];

     

       313
       313
       +
                 binOp = lhs: rhs: [];

     

       314
       314
       +
               };

     

       239
       315
        
             };

     

       240
       316
        
       

     

       241
       317
        
           enum = values:

     
···

       245
       321
        
                 else if builtins.isInt v then builtins.toString v

     

       246
       322
        
                 else ''<${builtins.typeOf v}>'';

     

       247
       323
        
             in

     

       248
       248
       -
             mkOptionType {

     

       249
       249
       -
               name = "one of ${concatMapStringsSep ", " show values}";

     

       324
       324
       +
             mkOptionType rec {

     

       325
       325
       +
               name = "enum";

     

       326
       326
       +
               description = "one of ${concatMapStringsSep ", " show values}";

     

       250
       327
        
               check = flip elem values;

     

       251
       328
        
               merge = mergeOneOption;

     

       329
       329
       +
               functor = (defaultFunctor name) // { payload = values; binOp = a: b: unique (a ++ b); };

     

       252
       330
        
             };

     

       253
       331
        
       

     

       254
       254
       -
           either = t1: t2: mkOptionType {

     

       255
       255
       -
             name = "${t1.name} or ${t2.name}";

     

       332
       332
       +
           either = t1: t2: mkOptionType rec {

     

       333
       333
       +
             name = "either";

     

       334
       334
       +
             description = "${t1.description} or ${t2.description}";

     

       256
       335
        
             check = x: t1.check x || t2.check x;

     

       257
       336
        
             merge = mergeOneOption;

     

       337
       337
       +
             typeMerge = f':

     

       338
       338
       +
               let mt1 = t1.typeMerge (elemAt f'.wrapped 0).functor;

     

       339
       339
       +
                   mt2 = t2.typeMerge (elemAt f'.wrapped 1).functor;

     

       340
       340
       +
               in

     

       341
       341
       +
                  if (name == f'.name) && (mt1 != null) && (mt2 != null)

     

       342
       342
       +
                  then functor.type mt1 mt2

     

       343
       343
       +
                  else null;

     

       344
       344
       +
             functor = (defaultFunctor name) // { wrapped = [ t1 t2 ]; };

     

       258
       345
        
           };

     

       259
       346
        
       

     

       260
       347
        
           # Obsolete alternative to configOf.  It takes its option

     

       261
       348
        
           # declarations from the ‘options’ attribute of containing option

     

       262
       349
        
           # declaration.

     

       263
       350
        
           optionSet = mkOptionType {

     

       264
       264
       -
             name = builtins.trace "types.optionSet is deprecated; use types.submodule instead" "option set";

     

       351
       351
       +
             name = builtins.trace "types.optionSet is deprecated; use types.submodule instead" "optionSet";

     

       352
       352
       +
             description = "option set";

     

       265
       353
        
           };

     

       266
       354
        
       

     

       267
       355
        
           # Augment the given type with an additional type check function.

+88

nixos/doc/manual/development/option-declarations.xml

···

       65
       65
        
       

     

       66
       66
        
       </para>

     

       67
       67
        
       

     

       68
       68
       +
       <section xml:id="sec-option-declarations-eot"><title>Extensible Option 

     

       69
       69
       +
           Types</title>

     

       70
       70
       +
       

     

       71
       71
       +
         <para>Extensible option types is a feature that allow to extend certain types 

     

       72
       72
       +
           declaration through multiple module files.

     

       73
       73
       +
           This feature only work with a restricted set of types, namely 

     

       74
       74
       +
           <literal>enum</literal> and <literal>submodules</literal> and any composed

     

       75
       75
       +
           forms of them.</para>

     

       76
       76
       +
       

     

       77
       77
       +
         <para>Extensible option types can be used for <literal>enum</literal> options 

     

       78
       78
       +
           that affects multiple modules, or as an alternative to related 

     

       79
       79
       +
           <literal>enable</literal> options.</para>

     

       80
       80
       +
       

     

       81
       81
       +
         <para>As an example, we will take the case of display managers. There is a

     

       82
       82
       +
           central display manager module for generic display manager options and a

     

       83
       83
       +
           module file per display manager backend (slim, kdm, gdm ...).

     

       84
       84
       +
         </para>

     

       85
       85
       +
       

     

       86
       86
       +
         <para>There are two approach to this module structure:

     

       87
       87
       +
       

     

       88
       88
       +
         <itemizedlist>

     

       89
       89
       +
           <listitem><para>Managing the display managers independently by adding an

     

       90
       90
       +
               enable option to every display manager module backend. (NixOS)</para>

     

       91
       91
       +
           </listitem>

     

       92
       92
       +
           <listitem><para>Managing the display managers in the central module by

     

       93
       93
       +
               adding an option to select which display manager backend to use.</para>

     

       94
       94
       +
           </listitem>

     

       95
       95
       +
         </itemizedlist>

     

       96
       96
       +
         </para>

     

       97
       97
       +
       

     

       98
       98
       +
         <para>Both approachs have problems.</para>

     

       99
       99
       +
           

     

       100
       100
       +
         <para>Making backends independent can quickly become hard to manage. For

     

       101
       101
       +
           display managers, there can be only one enabled at a time, but the type

     

       102
       102
       +
           system can not enforce this restriction as there is no relation between

     

       103
       103
       +
           each backend <literal>enable</literal> option. As a result, this restriction

     

       104
       104
       +
           has to be done explicitely by adding assertions in each display manager

     

       105
       105
       +
           backend module.</para>

     

       106
       106
       +
       

     

       107
       107
       +
         <para>On the other hand, managing the display managers backends in the

     

       108
       108
       +
           central module will require to change the central module option every time

     

       109
       109
       +
           a new backend is added or removed.</para>

     

       110
       110
       +
       

     

       111
       111
       +
         <para>By using extensible option types, it is possible to create a placeholder 

     

       112
       112
       +
           option in the central module (<xref linkend='ex-option-declaration-eot-service' 

     

       113
       113
       +
             />), and to extend it in each backend module (<xref 

     

       114
       114
       +
             linkend='ex-option-declaration-eot-backend-slim' />, <xref 

     

       115
       115
       +
             linkend='ex-option-declaration-eot-backend-kdm' />).</para>

     

       116
       116
       +
        

     

       117
       117
       +
         <para>As a result, <literal>displayManager.enable</literal> option values can

     

       118
       118
       +
         be added without changing the main service module file and the type system

     

       119
       119
       +
         automatically enforce that there can only be a single display manager

     

       120
       120
       +
         enabled.</para>

     

       121
       121
       +
       

     

       122
       122
       +
       <example xml:id='ex-option-declaration-eot-service'><title>Extensible type 

     

       123
       123
       +
           placeholder in the service module</title>

     

       124
       124
       +
       <screen>

     

       125
       125
       +
       services.xserver.displayManager.enable = mkOption {

     

       126
       126
       +
         description = "Display manager to use";

     

       127
       127
       +
         type = with types; nullOr (enum [ ]);

     

       128
       128
       +
       };</screen></example>

     

       129
       129
       +
       

     

       130
       130
       +
       <example xml:id='ex-option-declaration-eot-backend-slim'><title>Extending 

     

       131
       131
       +
           <literal>services.xserver.displayManager.enable</literal> in the 

     

       132
       132
       +
           <literal>slim</literal> module</title>

     

       133
       133
       +
       <screen>

     

       134
       134
       +
       services.xserver.displayManager.enable = mkOption {

     

       135
       135
       +
         type = with types; nullOr (enum [ "slim" ]);

     

       136
       136
       +
       };</screen></example>

     

       137
       137
       +
       

     

       138
       138
       +
       <example xml:id='ex-option-declaration-eot-backend-kdm'><title>Extending 

     

       139
       139
       +
           <literal>services.foo.backend</literal> in the <literal>kdm</literal> 

     

       140
       140
       +
           module</title>

     

       141
       141
       +
       <screen>

     

       142
       142
       +
       services.xserver.displayManager.enable = mkOption {

     

       143
       143
       +
         type = with types; nullOr (enum [ "kdm" ]);

     

       144
       144
       +
       };</screen></example>

     

       145
       145
       +
       

     

       146
       146
       +
       <para>The placeholder declaration is a standard <literal>mkOption</literal> 

     

       147
       147
       +
         declaration, but it is important that extensible option declarations only use 

     

       148
       148
       +
         the <literal>type</literal> argument.</para>

     

       149
       149
       +
       

     

       150
       150
       +
       <para>Extensible option types work with any of the composed variants of 

     

       151
       151
       +
         <literal>enum</literal> such as 

     

       152
       152
       +
         <literal>with types; nullOr (enum [ "foo" "bar" ])</literal> 

     

       153
       153
       +
         or <literal>with types; listOf (enum [ "foo" "bar" ])</literal>.</para>

     

       154
       154
       +
       

     

       155
       155
       +
       </section>

     

       68
       156
        
       </section>

+84 -26

nixos/doc/manual/development/option-types.xml

···

       62
       62
        
           <listitem><para>A string. Multiple definitions are concatenated with a 

     

       63
       63
        
               collon <literal>":"</literal>.</para></listitem>

     

       64
       64
        
         </varlistentry>

     

       65
       65
       +
       </variablelist>

     

       66
       66
       +
       

     

       67
       67
       +
        </section>

     

       68
       68
       +
       

     

       69
       69
       +
        <section><title>Value Types</title>

     

       70
       70
       +
       

     

       71
       71
       +
          <para>Value types are type that take a value parameter. The only value type 

     

       72
       72
       +
            in the library is <literal>enum</literal>.</para>

     

       73
       73
       +
       

     

       74
       74
       +
       <variablelist>

     

       65
       75
        
         <varlistentry>

     

       66
       66
       -
           <term><varname>types.separatedString</varname> 

     

       76
       76
       +
           <term><varname>types.enum</varname> <replaceable>l</replaceable></term>

     

       77
       77
       +
           <listitem><para>One element of the list <replaceable>l</replaceable>, e.g. 

     

       78
       78
       +
               <literal>types.enum [ "left" "right" ]</literal>. Multiple definitions 

     

       79
       79
       +
               cannot be merged.</para></listitem>

     

       80
       80
       +
         </varlistentry>

     

       81
       81
       +
         <varlistentry>

     

       82
       82
       +
           <term><varname>types.separatedString</varname>

     

       67
       83
        
             <replaceable>sep</replaceable></term>

     

       68
       68
       -
           <listitem><para>A string with a custom separator 

     

       69
       69
       -
               <replaceable>sep</replaceable>, e.g. <literal>types.separatedString 

     

       84
       84
       +
           <listitem><para>A string with a custom separator

     

       85
       85
       +
               <replaceable>sep</replaceable>, e.g. <literal>types.separatedString

     

       70
       86
        
                 "|"</literal>.</para></listitem>

     

       71
       87
        
         </varlistentry>

     

       88
       88
       +
         <varlistentry>

     

       89
       89
       +
           <term><varname>types.submodule</varname> <replaceable>o</replaceable></term>

     

       90
       90
       +
           <listitem><para>A set of sub options <replaceable>o</replaceable>.

     

       91
       91
       +
               <replaceable>o</replaceable> can be an attribute set or a function

     

       92
       92
       +
               returning an attribute set. Submodules are used in composed types to

     

       93
       93
       +
               create modular options. Submodule are detailed in <xref

     

       94
       94
       +
                 linkend='section-option-types-submodule' />.</para></listitem>

     

       95
       95
       +
         </varlistentry>

     

       72
       96
        
       </variablelist>

     

       73
       73
       -
       

     

       74
       97
        
        </section>

     

       75
       98
        
       

     

       76
       99
        
        <section><title>Composed Types</title>

     

       77
       100
        
       

     

       78
       78
       -
          <para>Composed types allow to create complex types by taking another type(s) 

     

       79
       79
       -
            or value(s) as parameter(s).

     

       80
       80
       -
            It is possible to compose types multiple times, e.g. <literal>with types; 

     

       81
       81
       -
              nullOr (enum [ "left" "right" ])</literal>.</para>

     

       101
       101
       +
          <para>Composed types are types that take a type as parameter. <literal>listOf 

     

       102
       102
       +
              int</literal> and <literal>either int str</literal> are examples of 

     

       103
       103
       +
            composed types.</para>

     

       82
       104
        
       

     

       83
       105
        
       <variablelist>

     

       84
       106
        
         <varlistentry>

     
···

       112
       134
        
               once.</para></listitem>

     

       113
       135
        
         </varlistentry>

     

       114
       136
        
         <varlistentry>

     

       115
       115
       -
           <term><varname>types.enum</varname> <replaceable>l</replaceable></term>

     

       116
       116
       -
           <listitem><para>One element of the list <replaceable>l</replaceable>, e.g. 

     

       117
       117
       -
               <literal>types.enum [ "left" "right" ]</literal>. Multiple definitions 

     

       118
       118
       -
               cannot be merged</para></listitem>

     

       119
       119
       -
         </varlistentry>

     

       120
       120
       -
         <varlistentry>

     

       121
       137
        
           <term><varname>types.either</varname> <replaceable>t1</replaceable> 

     

       122
       138
        
             <replaceable>t2</replaceable></term>

     

       123
       139
        
           <listitem><para>Type <replaceable>t1</replaceable> or type 

     

       124
       140
        
               <replaceable>t2</replaceable>, e.g. <literal>with types; either int 

     

       125
       141
        
                 str</literal>. Multiple definitions cannot be 

     

       126
       142
        
               merged.</para></listitem>

     

       127
       127
       -
         </varlistentry>

     

       128
       128
       -
         <varlistentry>

     

       129
       129
       -
           <term><varname>types.submodule</varname> <replaceable>o</replaceable></term>

     

       130
       130
       -
           <listitem><para>A set of sub options <replaceable>o</replaceable>. 

     

       131
       131
       -
               <replaceable>o</replaceable> can be an attribute set or a function 

     

       132
       132
       -
               returning an attribute set. Submodules are used in composed types to 

     

       133
       133
       -
               create modular options. Submodule are detailed in <xref 

     

       134
       134
       -
                 linkend='section-option-types-submodule' />.</para></listitem>

     

       135
       143
        
         </varlistentry>

     

       136
       144
        
       </variablelist>

     

       137
       145
        
       

     
···

       190
       198
        
         description = "submodule example";

     

       191
       199
        
         type = with types; listOf (submodule modOptions);

     

       192
       200
        
       };</screen></example>

     

       193
       193
       -
       

     

       194
       201
        
       

     

       195
       202
        
       <section><title>Composed with <literal>listOf</literal></title>

     

       196
       203
        
       

     
···

       317
       324
        
       <variablelist>

     

       318
       325
        
         <varlistentry>

     

       319
       326
        
           <term><varname>name</varname></term>

     

       320
       320
       -
           <listitem><para>A string representation of the type function name, name 

     

       321
       321
       -
               usually changes accordingly parameters passed to 

     

       322
       322
       -
               types.</para></listitem>

     

       327
       327
       +
           <listitem><para>A string representation of the type function 

     

       328
       328
       +
               name.</para></listitem>

     

       329
       329
       +
         </varlistentry>

     

       330
       330
       +
         <varlistentry>

     

       331
       331
       +
           <term><varname>definition</varname></term>

     

       332
       332
       +
           <listitem><para>Description of the type used in documentation. Give 

     

       333
       333
       +
               information of the type and any of its arguments.</para></listitem>

     

       323
       334
        
         </varlistentry>

     

       324
       335
        
         <varlistentry>

     

       325
       336
        
           <term><varname>check</varname></term>

     
···

       381
       392
        
               <literal>composedType</literal> that take an <literal>elemtype</literal> 

     

       382
       393
        
               type parameter, this function should be defined as <literal>m: 

     

       383
       394
        
                 composedType (elemType.substSubModules m)</literal>.</para></listitem>

     

       395
       395
       +
         </varlistentry>

     

       396
       396
       +
         <varlistentry>

     

       397
       397
       +
           <term><varname>typeMerge</varname></term>

     

       398
       398
       +
           <listitem><para>A function to merge multiple type declarations. Takes the 

     

       399
       399
       +
               type to merge <literal>functor</literal> as parameter. A 

     

       400
       400
       +
               <literal>null</literal> return value means that type cannot be 

     

       401
       401
       +
               merged.</para>

     

       402
       402
       +
             <variablelist>

     

       403
       403
       +
               <varlistentry>

     

       404
       404
       +
                 <term><replaceable>f</replaceable></term>

     

       405
       405
       +
                 <listitem><para>The type to merge  

     

       406
       406
       +
                     <literal>functor</literal>.</para></listitem>

     

       407
       407
       +
               </varlistentry>

     

       408
       408
       +
             </variablelist>

     

       409
       409
       +
             <para>Note: There is a generic <literal>defaultTypeMerge</literal> that 

     

       410
       410
       +
               work with most of value and composed types.</para>

     

       411
       411
       +
           </listitem>

     

       412
       412
       +
         </varlistentry>

     

       413
       413
       +
         <varlistentry>

     

       414
       414
       +
           <term><varname>functor</varname></term>

     

       415
       415
       +
           <listitem><para>An attribute set representing the type. It is used for type 

     

       416
       416
       +
               operations and has the following keys:</para>

     

       417
       417
       +
             <variablelist>

     

       418
       418
       +
               <varlistentry>

     

       419
       419
       +
                 <term><varname>type</varname></term>

     

       420
       420
       +
                 <listitem><para>The type function.</para></listitem>

     

       421
       421
       +
               </varlistentry>

     

       422
       422
       +
               <varlistentry>

     

       423
       423
       +
                 <term><varname>wrapped</varname></term>

     

       424
       424
       +
                 <listitem><para>Holds the type parameter for composed types.</para>

     

       425
       425
       +
                 </listitem>

     

       426
       426
       +
               </varlistentry>

     

       427
       427
       +
               <varlistentry>

     

       428
       428
       +
                 <term><varname>payload</varname></term>

     

       429
       429
       +
                 <listitem><para>Holds the value parameter for value types. 

     

       430
       430
       +
                     The types that have a <literal>payload</literal> are the

     

       431
       431
       +
                     <literal>enum</literal>, <literal>separatedString</literal> and

     

       432
       432
       +
                     <literal>submodule</literal> types.</para></listitem>

     

       433
       433
       +
               </varlistentry>

     

       434
       434
       +
               <varlistentry>

     

       435
       435
       +
                 <term><varname>binOp</varname></term>

     

       436
       436
       +
                 <listitem><para>A binary operation that can merge the payloads of two 

     

       437
       437
       +
                     same types. Defined as a function that take two payloads as 

     

       438
       438
       +
                     parameters and return the payloads merged.</para></listitem>

     

       439
       439
       +
               </varlistentry>

     

       440
       440
       +
             </variablelist>

     

       441
       441
       +
           </listitem>

     

       384
       442
        
         </varlistentry>

     

       385
       443
        
       </variablelist>

     

       386
       444

+4 -1

nixos/doc/manual/release-notes/rl-1703.xml

···

       75
       75
        
       

     

       76
       76
        
       <itemizedlist>

     

       77
       77
        
         <listitem>

     

       78
       78
       -
           <para></para>

     

       78
       78
       +
           <para>Module type system have a new extensible option types feature that

     

       79
       79
       +
             allow to extend certain types, such as enum, through multiple option

     

       80
       80
       +
             declarations of the same option across multiple modules.

     

       81
       81
       +
           </para>

     

       79
       82
        
         </listitem>

     

       80
       83
        
       </itemizedlist>

     

       81
       84

+1 -1

nixos/modules/installer/tools/nixos-option.sh

···

       256
       256
        
         // optionalAttrs (opt ? default) { inherit (opt) default; }

     

       257
       257
        
         // optionalAttrs (opt ? example) { inherit (opt) example; }

     

       258
       258
        
         // optionalAttrs (opt ? description) { inherit (opt) description; }

     

       259
       259
       -
         // optionalAttrs (opt ? type) { typename = opt.type.name; }

     

       259
       259
       +
         // optionalAttrs (opt ? type) { typename = opt.type.description; }

     

       260
       260
        
         // optionalAttrs (opt ? options) { inherit (opt) options; }

     

       261
       261
        
         // {

     

       262
       262
        
           # to disambiguate the xml output.