commit fc614c37c653637e5475a0b0a987489b4d1f351d · pyrox.dev/nixpkgs

+1 -1

lib/options.nix

···

       177
        
               docOption = rec {

     

       178
        
                 loc = opt.loc;

     

       179
        
                 name = showOption opt.loc;

     

       180
       -
                 description = opt.description or (lib.warn "Option `${name}' has no description." "This option has no description.");

     

       181
        
                 declarations = filter (x: x != unknownModule) opt.declarations;

     

       182
        
                 internal = opt.internal or false;

     

       183
        
                 visible =

···

       177
        
               docOption = rec {

     

       178
        
                 loc = opt.loc;

     

       179
        
                 name = showOption opt.loc;

     

       180
       +
                 description = opt.description or null;

     

       181
        
                 declarations = filter (x: x != unknownModule) opt.declarations;

     

       182
        
                 internal = opt.internal or false;

     

       183
        
                 visible =

+4 -4

nixos/doc/manual/default.nix

···

       1
       -
       { pkgs, options, config, version, revision, extraSources ? [] }:

     

       2
        
       

     

       3
        
       with pkgs;

     

       4
        
       

     
···

       11
        
         #

     

       12
        
         # E.g. if some `options` came from modules in ${pkgs.customModules}/nix,

     

       13
        
         # you'd need to include `extraSources = [ pkgs.customModules ]`

     

       14
       -
         prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources);

     

       15
        
         stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;

     

       16
        
       

     

       17
        
         optionsDoc = buildPackages.nixosOptionsDoc {

     

       18
       -
           inherit options revision;

     

       19
        
           transformOptions = opt: opt // {

     

       20
        
             # Clean up declaration sites to not refer to the NixOS source tree.

     

       21
        
             declarations = map stripAnyPrefixes opt.declarations;

     
···

       161
        
       in rec {

     

       162
        
         inherit generatedSources;

     

       163
        
       

     

       164
       -
         inherit (optionsDoc) optionsJSON optionsDocBook;

     

       165
        
       

     

       166
        
         # Generate the NixOS manual.

     

       167
        
         manualHTML = runCommand "nixos-manual-html"

···

       1
       +
       { pkgs, options, config, version, revision, extraSources ? [], baseOptionsJSON ? null, prefix ? ../../.. }:

     

       2
        
       

     

       3
        
       with pkgs;

     

       4
        
       

     
···

       11
        
         #

     

       12
        
         # E.g. if some `options` came from modules in ${pkgs.customModules}/nix,

     

       13
        
         # you'd need to include `extraSources = [ pkgs.customModules ]`

     

       14
       +
         prefixesToStrip = map (p: "${toString p}/") ([ prefix ] ++ extraSources);

     

       15
        
         stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;

     

       16
        
       

     

       17
        
         optionsDoc = buildPackages.nixosOptionsDoc {

     

       18
       +
           inherit options revision baseOptionsJSON;

     

       19
        
           transformOptions = opt: opt // {

     

       20
        
             # Clean up declaration sites to not refer to the NixOS source tree.

     

       21
        
             declarations = map stripAnyPrefixes opt.declarations;

     
···

       161
        
       in rec {

     

       162
        
         inherit generatedSources;

     

       163
        
       

     

       164
       +
         inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;

     

       165
        
       

     

       166
        
         # Generate the NixOS manual.

     

       167
        
         manualHTML = runCommand "nixos-manual-html"

+27 -1

nixos/doc/manual/development/meta-attributes.section.md

···

       5
        
       special module.

     

       6
        
       

     

       7
        
       `meta` is a top level attribute like `options` and `config`. Available

     

       8
       -
       meta-attributes are `maintainers` and `doc`.

     

       9
        
       

     

       10
        
       Each of the meta-attributes must be defined at most once per module

     

       11
        
       file.

     
···

       24
        
         meta = {

     

       25
        
           maintainers = with lib.maintainers; [ ericsagnes ];

     

       26
        
           doc = ./default.xml;

     

       0
        
       
     

       27
        
         };

     

       28
        
       }

     

       29
        
       ```

     
···

       38
        
           ```ShellSession

     

       39
        
           $ nix-build nixos/release.nix -A manual.x86_64-linux

     

       40
        
           ```

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0

···

       5
        
       special module.

     

       6
        
       

     

       7
        
       `meta` is a top level attribute like `options` and `config`. Available

     

       8
       +
       meta-attributes are `maintainers`, `doc`, and `buildDocsInSandbox`.

     

       9
        
       

     

       10
        
       Each of the meta-attributes must be defined at most once per module

     

       11
        
       file.

     
···

       24
        
         meta = {

     

       25
        
           maintainers = with lib.maintainers; [ ericsagnes ];

     

       26
        
           doc = ./default.xml;

     

       27
       +
           buildDocsInSandbox = true;

     

       28
        
         };

     

       29
        
       }

     

       30
        
       ```

     
···

       39
        
           ```ShellSession

     

       40
        
           $ nix-build nixos/release.nix -A manual.x86_64-linux

     

       41
        
           ```

     

       42
       +
       

     

       43
       +
       -  `buildDocsInSandbox` indicates whether the option documentation for the

     

       44
       +
          module can be built in a derivation sandbox. This option is currently only

     

       45
       +
          honored for modules shipped by nixpkgs. User modules and modules taken from

     

       46
       +
          `NIXOS_EXTRA_MODULE_PATH` are always built outside of the sandbox, as has

     

       47
       +
          been the case in previous releases.

     

       48
       +
       

     

       49
       +
          Building NixOS option documentation in a sandbox allows caching of the built

     

       50
       +
          documentation, which greatly decreases the amount of time needed to evaluate

     

       51
       +
          a system configuration that has NixOS documentation enabled. The sandbox also

     

       52
       +
          restricts which attributes may be referenced by documentation attributes

     

       53
       +
          (such as option descriptions) to the `options` and `lib` module arguments and

     

       54
       +
          the `pkgs.formats` attribute of the `pkgs` argument, `config` and the rest of

     

       55
       +
          `pkgs` are disallowed and will cause doc build failures when used. This

     

       56
       +
          restriction is necessary because we cannot reproduce the full nixpkgs

     

       57
       +
          instantiation with configuration and overlays from a system configuration

     

       58
       +
          inside the sandbox. The `options` argument only includes options of modules

     

       59
       +
          that are also built inside the sandbox, referencing an option of a module

     

       60
       +
          that isn't built in the sandbox is also forbidden.

     

       61
       +
       

     

       62
       +
          The default is `true` and should usually not be changed; set it to `false`

     

       63
       +
          only if the module requires access to `pkgs` in its documentation (e.g.

     

       64
       +
          because it loads information from a linked package to build an option type)

     

       65
       +
          or if its documentation depends on other modules that also aren't sandboxed

     

       66
       +
          (e.g. by using types defined in the other module).

+42 -2

nixos/doc/manual/from_md/development/meta-attributes.section.xml

···

       8
        
         <para>

     

       9
        
           <literal>meta</literal> is a top level attribute like

     

       10
        
           <literal>options</literal> and <literal>config</literal>. Available

     

       11
       -
           meta-attributes are <literal>maintainers</literal> and

     

       12
       -
           <literal>doc</literal>.

     

       13
        
         </para>

     

       14
        
         <para>

     

       15
        
           Each of the meta-attributes must be defined at most once per module

     
···

       29
        
         meta = {

     

       30
        
           maintainers = with lib.maintainers; [ ericsagnes ];

     

       31
        
           doc = ./default.xml;

     

       0
        
       
     

       32
        
         };

     

       33
        
       }

     

       34
        
       </programlisting>

     
···

       50
        
             <programlisting>

     

       51
        
       $ nix-build nixos/release.nix -A manual.x86_64-linux

     

       52
        
       </programlisting>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       53
        
           </listitem>

     

       54
        
         </itemizedlist>

     

       55
        
       </section>

···

       8
        
         <para>

     

       9
        
           <literal>meta</literal> is a top level attribute like

     

       10
        
           <literal>options</literal> and <literal>config</literal>. Available

     

       11
       +
           meta-attributes are <literal>maintainers</literal>,

     

       12
       +
           <literal>doc</literal>, and <literal>buildDocsInSandbox</literal>.

     

       13
        
         </para>

     

       14
        
         <para>

     

       15
        
           Each of the meta-attributes must be defined at most once per module

     
···

       29
        
         meta = {

     

       30
        
           maintainers = with lib.maintainers; [ ericsagnes ];

     

       31
        
           doc = ./default.xml;

     

       32
       +
           buildDocsInSandbox = true;

     

       33
        
         };

     

       34
        
       }

     

       35
        
       </programlisting>

     
···

       51
        
             <programlisting>

     

       52
        
       $ nix-build nixos/release.nix -A manual.x86_64-linux

     

       53
        
       </programlisting>

     

       54
       +
           </listitem>

     

       55
       +
           <listitem>

     

       56
       +
             <para>

     

       57
       +
               <literal>buildDocsInSandbox</literal> indicates whether the

     

       58
       +
               option documentation for the module can be built in a derivation

     

       59
       +
               sandbox. This option is currently only honored for modules

     

       60
       +
               shipped by nixpkgs. User modules and modules taken from

     

       61
       +
               <literal>NIXOS_EXTRA_MODULE_PATH</literal> are always built

     

       62
       +
               outside of the sandbox, as has been the case in previous

     

       63
       +
               releases.

     

       64
       +
             </para>

     

       65
       +
             <para>

     

       66
       +
               Building NixOS option documentation in a sandbox allows caching

     

       67
       +
               of the built documentation, which greatly decreases the amount

     

       68
       +
               of time needed to evaluate a system configuration that has NixOS

     

       69
       +
               documentation enabled. The sandbox also restricts which

     

       70
       +
               attributes may be referenced by documentation attributes (such

     

       71
       +
               as option descriptions) to the <literal>options</literal> and

     

       72
       +
               <literal>lib</literal> module arguments and the

     

       73
       +
               <literal>pkgs.formats</literal> attribute of the

     

       74
       +
               <literal>pkgs</literal> argument, <literal>config</literal> and

     

       75
       +
               the rest of <literal>pkgs</literal> are disallowed and will

     

       76
       +
               cause doc build failures when used. This restriction is

     

       77
       +
               necessary because we cannot reproduce the full nixpkgs

     

       78
       +
               instantiation with configuration and overlays from a system

     

       79
       +
               configuration inside the sandbox. The <literal>options</literal>

     

       80
       +
               argument only includes options of modules that are also built

     

       81
       +
               inside the sandbox, referencing an option of a module that isn’t

     

       82
       +
               built in the sandbox is also forbidden.

     

       83
       +
             </para>

     

       84
       +
             <para>

     

       85
       +
               The default is <literal>true</literal> and should usually not be

     

       86
       +
               changed; set it to <literal>false</literal> only if the module

     

       87
       +
               requires access to <literal>pkgs</literal> in its documentation

     

       88
       +
               (e.g. because it loads information from a linked package to

     

       89
       +
               build an option type) or if its documentation depends on other

     

       90
       +
               modules that also aren’t sandboxed (e.g. by using types defined

     

       91
       +
               in the other module).

     

       92
       +
             </para>

     

       93
        
           </listitem>

     

       94
        
         </itemizedlist>

     

       95
        
       </section>

+53

nixos/lib/eval-cacheable-options.nix

···

       1
       +
       { libPath

     

       2
       +
       , pkgsLibPath

     

       3
       +
       , nixosPath

     

       4
       +
       , modules

     

       5
       +
       , stateVersion

     

       6
       +
       , release

     

       7
       +
       }:

     

       8
       +
       

     

       9
       +
       let

     

       10
       +
         lib = import libPath;

     

       11
       +
         modulesPath = "${nixosPath}/modules";

     

       12
       +
         # dummy pkgs set that contains no packages, only `pkgs.lib` from the full set.

     

       13
       +
         # not having `pkgs.lib` causes all users of `pkgs.formats` to fail.

     

       14
       +
         pkgs = import pkgsLibPath {

     

       15
       +
           inherit lib;

     

       16
       +
           pkgs = null;

     

       17
       +
         };

     

       18
       +
         utils = import "${nixosPath}/lib/utils.nix" {

     

       19
       +
           inherit config lib;

     

       20
       +
           pkgs = null;

     

       21
       +
         };

     

       22
       +
         # this is used both as a module and as specialArgs.

     

       23
       +
         # as a module it sets the _module special values, as specialArgs it makes `config`

     

       24
       +
         # unusable. this causes documentation attributes depending on `config` to fail.

     

       25
       +
         config = {

     

       26
       +
           _module.check = false;

     

       27
       +
           _module.args = {};

     

       28
       +
           system.stateVersion = stateVersion;

     

       29
       +
         };

     

       30
       +
         eval = lib.evalModules {

     

       31
       +
           modules = (map (m: "${modulesPath}/${m}") modules) ++ [

     

       32
       +
             config

     

       33
       +
           ];

     

       34
       +
           specialArgs = {

     

       35
       +
             inherit config pkgs utils;

     

       36
       +
           };

     

       37
       +
         };

     

       38
       +
         docs = import "${nixosPath}/doc/manual" {

     

       39
       +
           pkgs = pkgs // {

     

       40
       +
             inherit lib;

     

       41
       +
             # duplicate of the declaration in all-packages.nix

     

       42
       +
             buildPackages.nixosOptionsDoc = attrs:

     

       43
       +
               (import "${nixosPath}/lib/make-options-doc")

     

       44
       +
                 ({ inherit pkgs lib; } // attrs);

     

       45
       +
           };

     

       46
       +
           config = config.config;

     

       47
       +
           options = eval.options;

     

       48
       +
           version = release;

     

       49
       +
           revision = "release-${release}";

     

       50
       +
           prefix = modulesPath;

     

       51
       +
         };

     

       52
       +
       in

     

       53
       +
         docs.optionsNix

+15 -1

nixos/lib/make-options-doc/default.nix

···

       21
        
       , options

     

       22
        
       , transformOptions ? lib.id  # function for additional tranformations of the options

     

       23
        
       , revision ? "" # Specify revision for the options

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       24
        
       }:

     

       25
        
       

     

       26
        
       let

     
···

       99
        
         optionsJSON = pkgs.runCommand "options.json"

     

       100
        
           { meta.description = "List of NixOS options in JSON format";

     

       101
        
             buildInputs = [ pkgs.brotli ];

     

       0
        
       
     

       0
        
       
     

       102
        
           }

     

       103
        
           ''

     

       104
        
             # Export list of options in different format.

     

       105
        
             dst=$out/share/doc/nixos

     

       106
        
             mkdir -p $dst

     

       107
        
       

     

       108
       -
             cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix))} $dst/options.json

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       109
        
       

     

       110
        
             brotli -9 < $dst/options.json > $dst/options.json.br

     

       111

···

       21
        
       , options

     

       22
        
       , transformOptions ? lib.id  # function for additional tranformations of the options

     

       23
        
       , revision ? "" # Specify revision for the options

     

       24
       +
       # a set of options the docs we are generating will be merged into, as if by recursiveUpdate.

     

       25
       +
       # used to split the options doc build into a static part (nixos/modules) and a dynamic part

     

       26
       +
       # (non-nixos modules imported via configuration.nix, other module sources).

     

       27
       +
       , baseOptionsJSON ? null

     

       28
        
       }:

     

       29
        
       

     

       30
        
       let

     
···

       103
        
         optionsJSON = pkgs.runCommand "options.json"

     

       104
        
           { meta.description = "List of NixOS options in JSON format";

     

       105
        
             buildInputs = [ pkgs.brotli ];

     

       106
       +
             options = builtins.toFile "options.json"

     

       107
       +
               (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix));

     

       108
        
           }

     

       109
        
           ''

     

       110
        
             # Export list of options in different format.

     

       111
        
             dst=$out/share/doc/nixos

     

       112
        
             mkdir -p $dst

     

       113
        
       

     

       114
       +
             ${

     

       115
       +
               if baseOptionsJSON == null

     

       116
       +
                 then "cp $options $dst/options.json"

     

       117
       +
                 else ''

     

       118
       +
                   ${pkgs.python3Minimal}/bin/python ${./mergeJSON.py} \

     

       119
       +
                     ${baseOptionsJSON} $options \

     

       120
       +
                     > $dst/options.json

     

       121
       +
                 ''

     

       122
       +
             }

     

       123
        
       

     

       124
        
             brotli -9 < $dst/options.json > $dst/options.json.br

     

       125

+71

nixos/lib/make-options-doc/mergeJSON.py

···

       1
       +
       import collections

     

       2
       +
       import json

     

       3
       +
       import sys

     

       4
       +
       

     

       5
       +
       class Key:

     

       6
       +
           def __init__(self, path):

     

       7
       +
               self.path = path

     

       8
       +
           def __hash__(self):

     

       9
       +
               result = 0

     

       10
       +
               for id in self.path:

     

       11
       +
                   result ^= hash(id)

     

       12
       +
               return result

     

       13
       +
           def __eq__(self, other):

     

       14
       +
               return type(self) is type(other) and self.path == other.path

     

       15
       +
       

     

       16
       +
       Option = collections.namedtuple('Option', ['name', 'value'])

     

       17
       +
       

     

       18
       +
       # pivot a dict of options keyed by their display name to a dict keyed by their path

     

       19
       +
       def pivot(options):

     

       20
       +
           result = dict()

     

       21
       +
           for (name, opt) in options.items():

     

       22
       +
               result[Key(opt['loc'])] = Option(name, opt)

     

       23
       +
           return result

     

       24
       +
       

     

       25
       +
       # pivot back to indexed-by-full-name

     

       26
       +
       # like the docbook build we'll just fail if multiple options with differing locs

     

       27
       +
       # render to the same option name.

     

       28
       +
       def unpivot(options):

     

       29
       +
           result = dict()

     

       30
       +
           for (key, opt) in options.items():

     

       31
       +
               if opt.name in result:

     

       32
       +
                   raise RuntimeError(

     

       33
       +
                       'multiple options with colliding ids found',

     

       34
       +
                       opt.name,

     

       35
       +
                       result[opt.name]['loc'],

     

       36
       +
                       opt.value['loc'],

     

       37
       +
                   )

     

       38
       +
               result[opt.name] = opt.value

     

       39
       +
           return result

     

       40
       +
       

     

       41
       +
       options = pivot(json.load(open(sys.argv[1], 'r')))

     

       42
       +
       overrides = pivot(json.load(open(sys.argv[2], 'r')))

     

       43
       +
       

     

       44
       +
       # fix up declaration paths in lazy options, since we don't eval them from a full nixpkgs dir

     

       45
       +
       for (k, v) in options.items():

     

       46
       +
           v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}', v.value['declarations']))

     

       47
       +
       

     

       48
       +
       # merge both descriptions

     

       49
       +
       for (k, v) in overrides.items():

     

       50
       +
           cur = options.setdefault(k, v).value

     

       51
       +
           for (ok, ov) in v.value.items():

     

       52
       +
               if ok == 'declarations':

     

       53
       +
                   decls = cur[ok]

     

       54
       +
                   for d in ov:

     

       55
       +
                       if d not in decls:

     

       56
       +
                           decls += [d]

     

       57
       +
               elif ok == "type":

     

       58
       +
                   # ignore types of placeholder options

     

       59
       +
                   if ov != "_unspecified" or cur[ok] == "_unspecified":

     

       60
       +
                       cur[ok] = ov

     

       61
       +
               elif ov is not None or cur.get(ok, None) is None:

     

       62
       +
                   cur[ok] = ov

     

       63
       +
       

     

       64
       +
       # check that every option has a description

     

       65
       +
       # TODO: nixos-rebuild with flakes may hide the warning, maybe turn on -L by default for those?

     

       66
       +
       for (k, v) in options.items():

     

       67
       +
           if v.value.get('description', None) is None:

     

       68
       +
               print(f"\x1b[1;31mwarning: option {v.name} has no description\x1b[0m", file=sys.stderr)

     

       69
       +
               v.value['description'] = "This option has no description."

     

       70
       +
       

     

       71
       +
       json.dump(unpivot(options), fp=sys.stdout)

+3

nixos/modules/config/qt5.nix

···

       101
        
           environment.systemPackages = packages;

     

       102
        
       

     

       103
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       104
        
       }

···

       101
        
           environment.systemPackages = packages;

     

       102
        
       

     

       103
        
         };

     

       104
       +
       

     

       105
       +
         # uses relatedPackages

     

       106
       +
         meta.buildDocsInSandbox = false;

     

       107
        
       }

+3

nixos/modules/i18n/input-method/fcitx.nix

···

       40
        
           };

     

       41
        
           services.xserver.displayManager.sessionCommands = "${fcitxPackage}/bin/fcitx";

     

       42
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       43
        
       }

···

       40
        
           };

     

       41
        
           services.xserver.displayManager.sessionCommands = "${fcitxPackage}/bin/fcitx";

     

       42
        
         };

     

       43
       +
       

     

       44
       +
         # uses attributes of the linked package

     

       45
       +
         meta.buildDocsInSandbox = false;

     

       46
        
       }

+3

nixos/modules/i18n/input-method/ibus.nix

···

       80
        
             ibusPackage

     

       81
        
           ];

     

       82
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       83
        
       }

···

       80
        
             ibusPackage

     

       81
        
           ];

     

       82
        
         };

     

       83
       +
       

     

       84
       +
         # uses attributes of the linked package

     

       85
       +
         meta.buildDocsInSandbox = false;

     

       86
        
       }

+3 -1

nixos/modules/i18n/input-method/kime.nix

···

       45
        
       

     

       46
        
           environment.etc."xdg/kime/config.yaml".text = replaceStrings [ "\\\\" ] [ "\\" ] (builtins.toJSON cfg.config);

     

       47
        
         };

     

       48
       -
       }

     

       49
        
       

     

       0
        
       
     

       0
        
       
     

       0

···

       45
        
       

     

       46
        
           environment.etc."xdg/kime/config.yaml".text = replaceStrings [ "\\\\" ] [ "\\" ] (builtins.toJSON cfg.config);

     

       47
        
         };

     

       0
        
       
     

       48
        
       

     

       49
       +
         # uses attributes of the linked package

     

       50
       +
         meta.buildDocsInSandbox = false;

     

       51
       +
       }

+85 -10

nixos/modules/misc/documentation.nix

···

       1
       -
       { config, lib, pkgs, extendModules, noUserModules, ... }:

     

       2
        
       

     

       3
        
       with lib;

     

       4
        
       

     

       5
        
       let

     

       6
        
       

     

       7
        
         cfg = config.documentation;

     

       0
        
       
     

       8
        
       

     

       9
        
         /* Modules for which to show options even when not imported. */

     

       10
        
         extraDocModules = [ ../virtualisation/qemu-vm.nix ];

     

       11
        
       

     

       12
       -
         /* For the purpose of generating docs, evaluate options with each derivation

     

       13
       -
           in `pkgs` (recursively) replaced by a fake with path "\${pkgs.attribute.path}".

     

       14
       -
           It isn't perfect, but it seems to cover a vast majority of use cases.

     

       15
       -
           Caveat: even if the package is reached by a different means,

     

       16
       -
           the path above will be shown and not e.g. `${config.services.foo.package}`. */

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       17
        
         manual = import ../../doc/manual rec {

     

       18
        
           inherit pkgs config;

     

       19
        
           version = config.system.nixos.release;

     
···

       21
        
           extraSources = cfg.nixos.extraModuleSources;

     

       22
        
           options =

     

       23
        
             let

     

       24
       -
               extendNixOS = if cfg.nixos.includeAllModules then extendModules else noUserModules.extendModules;

     

       25
       -
               scrubbedEval = extendNixOS {

     

       26
       -
                 modules = extraDocModules;

     

       27
       -
                 specialArgs.pkgs = scrubDerivations "pkgs" pkgs;

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       28
        
               };

     

       29
        
               scrubDerivations = namePrefix: pkgSet: mapAttrs

     

       30
        
                 (name: value:

     
···

       36
        
                 )

     

       37
        
                 pkgSet;

     

       38
        
             in scrubbedEval.options;

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       39
        
         };

     

       40
        
       

     

       41
        
       

     
···

       188
        
                 <listitem><para>This includes the HTML manual and the <command>nixos-help</command> command if

     

       189
        
                           <option>documentation.doc.enable</option> is set.</para></listitem>

     

       190
        
                 </itemizedlist>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       191
        
               '';

     

       192
        
             };

     

       193

···

       1
       +
       { config, options, lib, pkgs, utils, modules, baseModules, extraModules, modulesPath, ... }:

     

       2
        
       

     

       3
        
       with lib;

     

       4
        
       

     

       5
        
       let

     

       6
        
       

     

       7
        
         cfg = config.documentation;

     

       8
       +
         allOpts = options;

     

       9
        
       

     

       10
        
         /* Modules for which to show options even when not imported. */

     

       11
        
         extraDocModules = [ ../virtualisation/qemu-vm.nix ];

     

       12
        
       

     

       13
       +
         canCacheDocs = m:

     

       14
       +
           let

     

       15
       +
             f = import m;

     

       16
       +
             instance = f (mapAttrs (n: _: abort "evaluating ${n} for `meta` failed") (functionArgs f));

     

       17
       +
           in

     

       18
       +
             cfg.nixos.splitOptionDocBuild

     

       19
       +
               && builtins.isPath m

     

       20
       +
               && isFunction f

     

       21
       +
               && instance ? options

     

       22
       +
               && instance.meta.buildDocsInSandbox or true;

     

       23
       +
       

     

       24
       +
         docModules =

     

       25
       +
           let

     

       26
       +
             p = partition canCacheDocs (baseModules ++ extraDocModules);

     

       27
       +
           in

     

       28
       +
             {

     

       29
       +
               lazy = p.right;

     

       30
       +
               eager = p.wrong ++ optionals cfg.nixos.includeAllModules (extraModules ++ modules);

     

       31
       +
             };

     

       32
       +
       

     

       33
        
         manual = import ../../doc/manual rec {

     

       34
        
           inherit pkgs config;

     

       35
        
           version = config.system.nixos.release;

     
···

       37
        
           extraSources = cfg.nixos.extraModuleSources;

     

       38
        
           options =

     

       39
        
             let

     

       40
       +
               scrubbedEval = evalModules {

     

       41
       +
                 modules = [ {

     

       42
       +
                   _module.check = false;

     

       43
       +
                 } ] ++ docModules.eager;

     

       44
       +
                 specialArgs = {

     

       45
       +
                   pkgs = scrubDerivations "pkgs" pkgs;

     

       46
       +
                   # allow access to arbitrary options for eager modules, eg for getting

     

       47
       +
                   # option types from lazy modules

     

       48
       +
                   options = allOpts;

     

       49
       +
                   inherit modulesPath utils;

     

       50
       +
                 };

     

       51
        
               };

     

       52
        
               scrubDerivations = namePrefix: pkgSet: mapAttrs

     

       53
        
                 (name: value:

     
···

       59
        
                 )

     

       60
        
                 pkgSet;

     

       61
        
             in scrubbedEval.options;

     

       62
       +
           baseOptionsJSON =

     

       63
       +
             let

     

       64
       +
               filter =

     

       65
       +
                 builtins.filterSource

     

       66
       +
                   (n: t:

     

       67
       +
                     (t == "directory" -> baseNameOf n != "tests")

     

       68
       +
                     && (t == "file" -> hasSuffix ".nix" n)

     

       69
       +
                   );

     

       70
       +
             in

     

       71
       +
               pkgs.runCommand "lazy-options.json" {

     

       72
       +
                 libPath = filter "${toString pkgs.path}/lib";

     

       73
       +
                 pkgsLibPath = filter "${toString pkgs.path}/pkgs/pkgs-lib";

     

       74
       +
                 nixosPath = filter "${toString pkgs.path}/nixos";

     

       75
       +
                 modules = map (p: ''"${removePrefix "${modulesPath}/" (toString p)}"'') docModules.lazy;

     

       76
       +
               } ''

     

       77
       +
                 export NIX_STORE_DIR=$TMPDIR/store

     

       78
       +
                 export NIX_STATE_DIR=$TMPDIR/state

     

       79
       +
                 ${pkgs.nix}/bin/nix-instantiate \

     

       80
       +
                   --show-trace \

     

       81
       +
                   --eval --json --strict \

     

       82
       +
                   --argstr libPath "$libPath" \

     

       83
       +
                   --argstr pkgsLibPath "$pkgsLibPath" \

     

       84
       +
                   --argstr nixosPath "$nixosPath" \

     

       85
       +
                   --arg modules "[ $modules ]" \

     

       86
       +
                   --argstr stateVersion "${options.system.stateVersion.default}" \

     

       87
       +
                   --argstr release "${config.system.nixos.release}" \

     

       88
       +
                   $nixosPath/lib/eval-cacheable-options.nix > $out \

     

       89
       +
                   || {

     

       90
       +
                     echo -en "\e[1;31m"

     

       91
       +
                     echo 'Cacheable portion of option doc build failed.'

     

       92
       +
                     echo 'Usually this means that an option attribute that ends up in documentation (eg' \

     

       93
       +
                       '`default` or `description`) depends on the restricted module arguments' \

     

       94
       +
                       '`config` or `pkgs`.'

     

       95
       +
                     echo

     

       96
       +
                     echo 'Rebuild your configuration with `--show-trace` to find the offending' \

     

       97
       +
                       'location. Remove the references to restricted arguments (eg by escaping' \

     

       98
       +
                       'their antiquotations or adding a `defaultText`) or disable the sandboxed' \

     

       99
       +
                       'build for the failing module by setting `meta.buildDocsInSandbox = false`.'

     

       100
       +
                     echo -en "\e[0m"

     

       101
       +
                     exit 1

     

       102
       +
                   } >&2

     

       103
       +
               '';

     

       104
        
         };

     

       105
        
       

     

       106
        
       

     
···

       253
        
                 <listitem><para>This includes the HTML manual and the <command>nixos-help</command> command if

     

       254
        
                           <option>documentation.doc.enable</option> is set.</para></listitem>

     

       255
        
                 </itemizedlist>

     

       256
       +
               '';

     

       257
       +
             };

     

       258
       +
       

     

       259
       +
             nixos.splitOptionDocBuild = mkOption {

     

       260
       +
               type = types.bool;

     

       261
       +
               default = true;

     

       262
       +
               description = ''

     

       263
       +
                 Whether to split the option docs build into a cacheable and an uncacheable part.

     

       264
       +
                 Splitting the build can substantially decrease the amount of time needed to build

     

       265
       +
                 the manual, but some user modules may be incompatible with this splitting.

     

       266
        
               '';

     

       267
        
             };

     

       268

+15

nixos/modules/misc/meta.nix

···

       54
        
               '';

     

       55
        
             };

     

       56
        
       

     

       57
       +
             buildDocsInSandbox = mkOption {

     

       58
       +
               type = types.bool // {

     

       59
       +
                 merge = loc: defs: defs;

     

       60
       +
               };

     

       61
       +
               internal = true;

     

       62
       +
               default = true;

     

       63
       +
               description = ''

     

       64
       +
                 Whether to include this module in the split options doc build.

     

       65
       +
                 Disable if the module references `config`, `pkgs` or other module

     

       66
       +
                 arguments that cannot be evaluated as constants.

     

       67
       +
       

     

       68
       +
                 This option should be defined at most once per module.

     

       69
       +
               '';

     

       70
       +
             };

     

       71
       +
       

     

       72
        
           };

     

       73
        
         };

     

       74

+3

nixos/modules/misc/nixpkgs.nix

···

       248
        
             )

     

       249
        
           ];

     

       250
        
         };

     

       251
       +
       

     

       252
       +
         # needs a full nixpkgs path to import nixpkgs

     

       253
       +
         meta.buildDocsInSandbox = false;

     

       254
        
       }

+2

nixos/modules/misc/version.nix

···

       119
        
       

     

       120
        
         };

     

       121
        
       

     

       122
       +
         # uses version info nixpkgs, which requires a full nixpkgs path

     

       123
       +
         meta.buildDocsInSandbox = false;

     

       124
        
       }

+2

nixos/modules/programs/dmrconfig.nix

···

       7
        
       

     

       8
        
       in {

     

       9
        
         meta.maintainers = [ maintainers.etu ];

     

       0
        
       
     

       0
        
       
     

       10
        
       

     

       11
        
         ###### interface

     

       12
        
         options = {

···

       7
        
       

     

       8
        
       in {

     

       9
        
         meta.maintainers = [ maintainers.etu ];

     

       10
       +
         # uses relatedPackages

     

       11
       +
         meta.buildDocsInSandbox = false;

     

       12
        
       

     

       13
        
         ###### interface

     

       14
        
         options = {

+2

nixos/modules/programs/gnupg.nix

···

       149
        
           ];

     

       150
        
         };

     

       151
        
       

     

       152
       +
         # uses attributes of the linked package

     

       153
       +
         meta.buildDocsInSandbox = false;

     

       154
        
       }

+3

nixos/modules/programs/tmux.nix

···

       185
        
         imports = [

     

       186
        
           (lib.mkRenamedOptionModule [ "programs" "tmux" "extraTmuxConf" ] [ "programs" "tmux" "extraConfig" ])

     

       187
        
         ];

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       188
        
       }

···

       185
        
         imports = [

     

       186
        
           (lib.mkRenamedOptionModule [ "programs" "tmux" "extraTmuxConf" ] [ "programs" "tmux" "extraConfig" ])

     

       187
        
         ];

     

       188
       +
       

     

       189
       +
         # uses relatedPackages

     

       190
       +
         meta.buildDocsInSandbox = false;

     

       191
        
       }

+4 -1

nixos/modules/services/backup/sanoid.nix

···

       51
        
         datasetOptions = rec {

     

       52
        
           use_template = mkOption {

     

       53
        
             description = "Names of the templates to use for this dataset.";

     

       54
       -
             type = types.listOf (types.enum (attrNames cfg.templates));

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       55
        
             default = [ ];

     

       56
        
           };

     

       57
        
           useTemplate = use_template;

···

       51
        
         datasetOptions = rec {

     

       52
        
           use_template = mkOption {

     

       53
        
             description = "Names of the templates to use for this dataset.";

     

       54
       +
             type = types.listOf (types.str // {

     

       55
       +
               check = (types.enum (attrNames cfg.templates)).check;

     

       56
       +
               description = "configured template name";

     

       57
       +
             });

     

       58
        
             default = [ ];

     

       59
        
           };

     

       60
        
           useTemplate = use_template;

+2

nixos/modules/services/desktops/pipewire/pipewire-media-session.nix

···

       29
        
       

     

       30
        
         meta = {

     

       31
        
           maintainers = teams.freedesktop.members;

     

       0
        
       
     

       0
        
       
     

       32
        
         };

     

       33
        
       

     

       34
        
         ###### interface

···

       29
        
       

     

       30
        
         meta = {

     

       31
        
           maintainers = teams.freedesktop.members;

     

       32
       +
           # uses attributes of the linked package

     

       33
       +
           buildDocsInSandbox = false;

     

       34
        
         };

     

       35
        
       

     

       36
        
         ###### interface

+2

nixos/modules/services/desktops/pipewire/pipewire.nix

···

       40
        
       

     

       41
        
         meta = {

     

       42
        
           maintainers = teams.freedesktop.members;

     

       0
        
       
     

       0
        
       
     

       43
        
         };

     

       44
        
       

     

       45
        
         ###### interface

···

       40
        
       

     

       41
        
         meta = {

     

       42
        
           maintainers = teams.freedesktop.members;

     

       43
       +
           # uses attributes of the linked package

     

       44
       +
           buildDocsInSandbox = false;

     

       45
        
         };

     

       46
        
       

     

       47
        
         ###### interface

+3

nixos/modules/services/hardware/thinkfan.nix

···

       221
        
           boot.extraModprobeConfig = "options thinkpad_acpi experimental=1 fan_control=1";

     

       222
        
       

     

       223
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       224
        
       }

···

       221
        
           boot.extraModprobeConfig = "options thinkpad_acpi experimental=1 fan_control=1";

     

       222
        
       

     

       223
        
         };

     

       224
       +
       

     

       225
       +
         # uses relatedPackages

     

       226
       +
         meta.buildDocsInSandbox = false;

     

       227
        
       }

+3

nixos/modules/services/misc/matrix-appservice-irc.nix

···

       226
        
             isSystemUser = true;

     

       227
        
           };

     

       228
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       229
        
       }

···

       226
        
             isSystemUser = true;

     

       227
        
           };

     

       228
        
         };

     

       229
       +
       

     

       230
       +
         # uses attributes of the linked package

     

       231
       +
         meta.buildDocsInSandbox = false;

     

       232
        
       }

+3

nixos/modules/services/networking/dnscrypt-proxy2.nix

···

       118
        
             };

     

       119
        
           };

     

       120
        
         };

     

       121
       +
       

     

       122
       +
         # uses attributes of the linked package

     

       123
       +
         meta.buildDocsInSandbox = false;

     

       124
        
       }

+2

nixos/modules/services/networking/kea.nix

···

       378
        
         ]);

     

       379
        
       

     

       380
        
         meta.maintainers = with maintainers; [ hexa ];

     

       0
        
       
     

       0
        
       
     

       381
        
       }

···

       378
        
         ]);

     

       379
        
       

     

       380
        
         meta.maintainers = with maintainers; [ hexa ];

     

       381
       +
         # uses attributes of the linked package

     

       382
       +
         meta.buildDocsInSandbox = false;

     

       383
        
       }

+2 -1

nixos/modules/services/networking/searx.nix

···

       228
        
         };

     

       229
        
       

     

       230
        
         meta.maintainers = with maintainers; [ rnhmjoj ];

     

       231
       -
       

     

       0
        
       
     

       232
        
       }

···

       228
        
         };

     

       229
        
       

     

       230
        
         meta.maintainers = with maintainers; [ rnhmjoj ];

     

       231
       +
         # uses relatedPackages

     

       232
       +
         meta.buildDocsInSandbox = false;

     

       233
        
       }

+3

nixos/modules/services/security/vaultwarden/default.nix

···

       179
        
             wantedBy = [ "multi-user.target" ];

     

       180
        
           };

     

       181
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       182
        
       }

···

       179
        
             wantedBy = [ "multi-user.target" ];

     

       180
        
           };

     

       181
        
         };

     

       182
       +
       

     

       183
       +
         # uses attributes of the linked package

     

       184
       +
         meta.buildDocsInSandbox = false;

     

       185
        
       }

+3

nixos/modules/services/web-apps/dex.nix

···

       112
        
             };

     

       113
        
           };

     

       114
        
         };

     

       115
       +
       

     

       116
       +
         # uses attributes of the linked package

     

       117
       +
         meta.buildDocsInSandbox = false;

     

       118
        
       }

+2

nixos/modules/services/web-apps/gerrit.nix

···

       237
        
         };

     

       238
        
       

     

       239
        
         meta.maintainers = with lib.maintainers; [ edef zimbatm ];

     

       0
        
       
     

       0
        
       
     

       240
        
       }

···

       237
        
         };

     

       238
        
       

     

       239
        
         meta.maintainers = with lib.maintainers; [ edef zimbatm ];

     

       240
       +
         # uses attributes of the linked package

     

       241
       +
         meta.buildDocsInSandbox = false;

     

       242
        
       }

+3

nixos/modules/services/web-apps/jirafeau.nix

···

       167
        
             "d ${cfg.dataDir}/async/ 0750 ${user} ${group} - -"

     

       168
        
           ];

     

       169
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       170
        
       }

···

       167
        
             "d ${cfg.dataDir}/async/ 0750 ${user} ${group} - -"

     

       168
        
           ];

     

       169
        
         };

     

       170
       +
       

     

       171
       +
         # uses attributes of the linked package

     

       172
       +
         meta.buildDocsInSandbox = false;

     

       173
        
       }

+2

nixos/modules/services/web-apps/nextcloud.nix

···

       932
        
         ]);

     

       933
        
       

     

       934
        
         meta.doc = ./nextcloud.xml;

     

       0
        
       
     

       0
        
       
     

       935
        
       }

···

       932
        
         ]);

     

       933
        
       

     

       934
        
         meta.doc = ./nextcloud.xml;

     

       935
       +
         # uses relatedPackages

     

       936
       +
         meta.buildDocsInSandbox = false;

     

       937
        
       }

+3

nixos/modules/services/web-apps/powerdns-admin.nix

···

       146
        
             group = "powerdnsadmin";

     

       147
        
           };

     

       148
        
         };

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       149
        
       }

···

       146
        
             group = "powerdnsadmin";

     

       147
        
           };

     

       148
        
         };

     

       149
       +
       

     

       150
       +
         # uses attributes of the linked package

     

       151
       +
         meta.buildDocsInSandbox = false;

     

       152
        
       }

+2

nixos/modules/services/x11/xserver.nix

···

       865
        
       

     

       866
        
         };

     

       867
        
       

     

       868
       +
         # uses relatedPackages

     

       869
       +
         meta.buildDocsInSandbox = false;

     

       870
        
       }

+2

nixos/modules/system/activation/top-level.nix

···

       317
        
       

     

       318
        
         };

     

       319
        
       

     

       320
       +
         # uses extendModules to generate a type

     

       321
       +
         meta.buildDocsInSandbox = false;

     

       322
        
       }

+3

nixos/modules/virtualisation/qemu-vm.nix

···

       999
        
             ];

     

       1000
        
       

     

       1001
        
         };

     

       1002
       +
       

     

       1003
       +
         # uses types of services/x11/xserver.nix

     

       1004
       +
         meta.buildDocsInSandbox = false;

     

       1005
        
       }

+3

nixos/modules/virtualisation/xen-dom0.nix

···

       451
        
       

     

       452
        
         };

     

       453
        
       

     

       454
       +
       

     

       455
       +
         # uses relatedPackages

     

       456
       +
         meta.buildDocsInSandbox = false;

     

       457
        
       }