treewide: generate global settings from data

Change-Id: If048b73a55d42522827eb9c140a066ba061e957c

doc/manual/meson.build

@@ -15,39 +15,6 @@ nix_eval_for_docs_common = nix_for_docs + [
 ]
 nix_eval_for_docs = nix_eval_for_docs_common + '--raw'
 
-conf_file_json = custom_target(
-  command : nix_for_docs + [ 'show-config', '--json' ],
-  capture : true,
-  output : 'conf-file.json',
-  env : nix_env_for_docs,
-  # FIXME: put the actual lib targets in here? meson have introspection challenge 2024 though.
-  build_always_stale : true,
-)
-
-nix_conf_file_md_body = custom_target(
-  command : nix_eval_for_docs + [
-    '--expr',
-    '(import @INPUT0@).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile @INPUT1@))',
-  ],
-  capture : true,
-  input : [
-    'utils.nix',
-    conf_file_json,
-  ],
-  output : 'conf-file.md.body',
-  env : nix_env_for_docs,
-)
-
-nix_conf_file_md = custom_target(
-  command : [ 'cat', '@INPUT@' ],
-  capture : true,
-  input : [
-    'src/command-ref/conf-file.md',
-    nix_conf_file_md_body,
-  ],
-  output : 'conf-file.md',
-)
-
 language_json = custom_target(
   command: [nix, '__dump-language'],
   output : 'language.json',

doc/manual/src/command-ref/meson.build

@@ -31,17 +31,23 @@ nix3_cli_files = custom_target(
 
 conf_file_md = custom_target(
   command : [
-    nix_eval_for_docs,
+    python.full_path(),
-    '--expr',
+    '@SOURCE_ROOT@/src/code-generation/build_settings.py',
-    '(import @INPUT0@).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile @INPUT1@))',
+    '--kernel', host_machine.system(),
+    '--docs', '@OUTPUT@',
+    '--experimental-features', '@SOURCE_ROOT@/src/libutil/experimental-features',
+    '@INPUT@',
   ],
-  capture : true,
   input : [
-    '../../utils.nix',
+    libexpr_setting_definitions,
-    conf_file_json,
+    libfetchers_setting_definitions,
-    experimental_features_shortlist_md,
+    file_transfer_setting_definitions,
-    deprecated_features_shortlist_md,
+    libstore_setting_definitions,
+    archive_setting_definitions,
+    feature_setting_definitions,
+    logging_setting_definitions,
+    daemon_setting_definitions,
+    develop_settings_definitions,
   ],
   output : 'conf-file.md',
-  env : nix_env_for_docs,
 )

doc/manual/src/contributing/hacking.md

@@ -400,16 +400,46 @@ The following properties are supported:
 Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.
 Set `buildUnreleasedNotes = true;` in `flake.nix` to build the release notes on the fly.
 
-## Adding experimental or deprecated features
+## Adding experimental or deprecated features, or global settings
 
-Experimental and deprecated features are generally referenced both in the code and in the documentation.
+Experimental and deprecated features, and global settings are generally referenced both in the code and in the documentation.
 To prevent duplication or divergence, they are defined in data files, and a script generates the necessary glue.
-
 The data file format is similar to the release notes: it consists of a YAML metadata header, followed by the documentation in Markdown format.
-The following metadata properties are supported:
+
+### Experimental or deprecated features
+
+Experimental and deprecated features support the following metadata properties:
 * `name` (required): user-facing name of the feature, to be used in `nix.conf` options and on the command line.
   This should also be the stem of the file name (with extension `md`).
 * `internalName` (required): identifier used to refer to the feature inside the C++ code.
 
 Experimental feature data files should live in `src/libutil/experimental-features`, and deprecated features in `src/libutil/deprecated-features`.
 They must be listed in the `experimental_feature_definitions` or `deprecated_feature_definitions` lists in `src/libutil/meson.build` respectively to be considered by the build system.
+
+### Global settings
+
+Global settings support the following metadata properties:
+* `name` (required): user-facing name of the setting, to be used as key in `nix.conf` and in the `--option` command line argument.
+* `internalName` (required): identifier used to refer to the setting inside the C++ code.
+* `platforms` (optional): a list specifying the platforms on which this setting is available.
+  If not specified, it is available on all platforms.
+  Valid platform names are `darwin`, `linux`.
+* `type` (optional): C++ type of the setting value.
+  This specifies the setting object type as `Setting<T>`; if more control is required, use `settingType` instead.
+* `settingType` (required if `type` is not specified): C++ type of the setting object.
+* `default` (optional): default value of the setting.
+  `null`, truth values, integers, strings and lists are supported as long as the correct YAML type is used, `type` is not taken into account).
+  Other types, machine-dependent values or non-standard representations must be handled using `defaultExpr` and `defaultText` instead.
+* `defaultExpr` (required if `default` is not specified): a string containing the C++ expression representing the default value.
+* `defaultText` (required if `default` is not specified): a string containing the Markdown expression representing the default value in the documentation.
+  Literal values are conventionally surrounded by backticks, and a system-dependent value is signaled by `*machine-specific*`.
+* `aliases` (optional): a list of secondary user-facing names under which the setting is available.
+  Defaults to empty if not specified.
+* `experimentalFeature` (optional): the user-facing name of the experimental feature which needs to be enabled to change the setting.
+  If not specified, no experimental feature is required.
+* `deprecated` (optional): whether the setting is deprecated and shown as such in the documentation for `nix.conf`.
+  Defaults to false if not specified.
+
+Settings are not collected in a single place in the source tree, so an appropriate place needs to be found for the setting to live.
+Look for related setting definition files under second-level subdirectories of `src` whose name includes `settings`.
+Then add the new file there, and don't forget to register it in the appropriate `meson.build` file.

src/code-generation/build_settings.py

@@ -0,0 +1,141 @@
+from typing import List, NamedTuple, Optional
+
+from build_experimental_features import ExperimentalFeature
+from common import cxx_literal, generate_file, load_data
+
+KNOWN_KEYS = set([
+    'name',
+    'internalName',
+    'platforms',
+    'type',
+    'settingType',
+    'default',
+    'defaultExpr',
+    'defaultText',
+    'aliases',
+    'experimentalFeature',
+    'deprecated',
+])
+
+class Setting(NamedTuple):
+    name: str
+    internal_name: str
+    description: str
+    platforms: Optional[List[str]]
+    setting_type: str
+    default_expr: str
+    default_text: str
+    aliases: List[str]
+    experimental_feature: Optional[str]
+    deprecated: bool
+
+    def parse(datum):
+        unknown_keys = set(datum.keys()) - KNOWN_KEYS
+        if unknown_keys:
+            raise ValueError('unknown keys', unknown_keys)
+        default_text = f'`{nix_conf_literal(datum["default"])}`' if 'default' in datum else datum['defaultText']
+        if default_text == '``':
+            default_text = '*empty*'
+        return Setting(
+            name = datum['name'],
+            internal_name = datum['internalName'],
+            description = datum.content,
+            platforms = datum.get('platforms', None),
+            setting_type = f'Setting<{datum["type"]}>' if 'type' in datum else datum['settingType'],
+            default_expr = cxx_literal(datum['default']) if 'default' in datum else datum['defaultExpr'],
+            default_text = default_text,
+            aliases = datum.get('aliases', []),
+            experimental_feature = datum.get('experimentalFeature', None),
+            deprecated = datum.get('deprecated', False),
+        )
+
+platform_names = {
+    'darwin': 'Darwin',
+    'linux': 'Linux',
+}
+
+def nix_conf_literal(v):
+    if v is None:
+        return ''
+    elif isinstance(v, bool) and v == False: # 0 == False
+        return 'false'
+    elif isinstance(v, bool) and v == True: # 1 == True
+        return 'true'
+    elif isinstance(v, int):
+        return str(v)
+    elif isinstance(v, str):
+        return v
+    elif isinstance(v, list):
+        return ' '.join([nix_conf_literal(item) for item in v])
+    else:
+        raise NotImplementedError(f'Cannot represent {repr(v)} in nix.conf')
+
+def indent(prefix, body):
+    return ''.join(['\n' if line == '' else f'{prefix}{line}\n' for line in body.split('\n')])
+
+def main():
+    import argparse
+
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--kernel', help='Name of the kernel Lix will run on')
+    ap.add_argument('--header', help='Path of the header to generate')
+    ap.add_argument('--docs', help='Path of the documentation file to generate')
+    ap.add_argument('--experimental-features', help='Directory containing the experimental feature definitions')
+    ap.add_argument('defs', help='Setting definition files', nargs='+')
+    args = ap.parse_args()
+
+    settings = load_data(args.defs, Setting.parse)
+
+    experimental_feature_names = set([setting.experimental_feature for (_, setting) in settings])
+    experimental_feature_names.discard(None)
+    experimental_feature_files = [f'{args.experimental_features}/{name}.md' for name in experimental_feature_names]
+    experimental_features = load_data(experimental_feature_files, ExperimentalFeature.parse)
+    experimental_features = dict(map(lambda path_and_feature:
+        (path_and_feature[1].name, f'Xp::{path_and_feature[1].internal_name}'), experimental_features))
+    experimental_features[None] = 'std::nullopt'
+
+    generate_file(args.header, settings, lambda setting: setting.name, lambda setting:
+        f'''{setting.setting_type} {setting.internal_name} {{
+    this,
+    {setting.default_expr},
+    {cxx_literal(setting.name)},
+    {cxx_literal(setting.description)},
+    {cxx_literal(setting.aliases)},
+    true,
+    {experimental_features[setting.experimental_feature]},
+    {cxx_literal(setting.deprecated)}
+}};
+
+''' if setting.platforms is None or args.kernel in setting.platforms else '')
+    generate_file(args.docs, settings, lambda setting: setting.name, lambda setting:
+        f'''- <span id="conf-{setting.name}">[`{setting.name}`](#conf-{setting.name})</span>
+
+{indent("  ", setting.description)}
+''' + (f'''  > **Note**
+  > This setting is only available on {', '.join([platform_names[platform] for platform in setting.platforms])} systems.
+
+''' if setting.platforms is not None else '') + (f'''  > **Warning**
+  > This setting is part of an
+  > [experimental feature](@docroot@/contributing/experimental-features.md).
+
+  To change this setting, you need to make sure the corresponding experimental feature,
+  [`{setting.experimental_feature}`](@docroot@/contributing/experimental-features.md#xp-feature-{setting.experimental_feature}),
+  is enabled.
+  For example, include the following in [`nix.conf`](#):
+
+  ```
+  extra-experimental-features = {setting.experimental_feature}
+  {setting.name} = ...
+  ```
+
+''' if setting.experimental_feature is not None else '') + ('''  > **Warning**
+  > This setting is deprecated and will be removed in a future version of Lix.
+
+''' if setting.deprecated else '') + f'''  **Default:** {setting.default_text}
+
+''' + (f'''  **Deprecated alias:** {', '.join([f'`{item}`' for item in setting.aliases])}
+
+''' if setting.aliases != [] else ''))
+
+if __name__ == '__main__':
+    main()

src/code-generation/common.py

@@ -23,8 +23,18 @@ def cxx_escape_character(c):
         return str.format(r'\U{:08x}', ord(c))
 
 def cxx_literal(v):
-    if isinstance(v, str):
+    if v is None:
+        return 'std::nullopt'
+    elif isinstance(v, bool) and v == False: # 0 == False
+        return 'false'
+    elif isinstance(v, bool) and v == True: # 1 == True
+        return 'true'
+    elif isinstance(v, int):
+        return str(v)
+    elif isinstance(v, str):
         return ''.join(['"', *(cxx_escape_character(c) for c in v), '"'])
+    elif isinstance(v, list):
+        return f'{{{", ".join([cxx_literal(item) for item in v])}}}'
     else:
         raise NotImplementedError(f'cannot represent {repr(v)} in C++')
 

src/libexpr/eval-settings.hh

@@ -14,226 +14,13 @@ struct EvalSettings : Config
 
     static std::string resolvePseudoUrl(std::string_view url);
 
-    Setting<bool> enableNativeCode{this, false, "allow-unsafe-native-code-during-evaluation", R"(
+    #include "libexpr-settings.gen.inc"
-        Enable built-in functions that allow executing native code.
-
-        In particular, this adds:
-        - `builtins.importNative` *path* *symbol*
-
-          Runs function with *symbol* from a dynamic shared object (DSO) at *path*.
-          This may be used to add new builtins to the Nix language.
-          The procedure must have the following signature:
-          ```cpp
-          extern "C" typedef void (*ValueInitialiser) (EvalState & state, Value & v);
-          ```
-
-        - `builtins.exec` *arguments*
-
-          Execute a program, where *arguments* are specified as a list of strings, and parse its output as a Nix expression.
-    )"};
-
-    Setting<Strings> nixPath{
-        this, getDefaultNixPath(), "nix-path",
-        R"(
-          List of directories to be searched for `<...>` file references
-
-          In particular, outside of [pure evaluation mode](#conf-pure-eval), this determines the value of
-          [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath).
-        )"};
-
-    Setting<std::string> currentSystem{
-        this, "", "eval-system",
-        R"(
-          This option defines
-          [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem)
-          in the Nix language if it is set as a non-empty string.
-          Otherwise, if it is defined as the empty string (the default), the value of the
-          [`system` ](#conf-system)
-          configuration setting is used instead.
-
-          Unlike `system`, this setting does not change what kind of derivations can be built locally.
-          This is useful for evaluating Nix code on one system to produce derivations to be built on another type of system.
-        )"};
 
     /**
      * Implements the `eval-system` vs `system` defaulting logic
      * described for `eval-system`.
      */
     const std::string & getCurrentSystem();
-
-    Setting<bool> restrictEval{
-        this, false, "restrict-eval",
-        R"(
-          If set to `true`, the Nix evaluator will not allow access to any
-          files outside of the Nix search path (as set via the `NIX_PATH`
-          environment variable or the `-I` option), or to URIs outside of
-          [`allowed-uris`](../command-ref/conf-file.md#conf-allowed-uris).
-          The default is `false`.
-        )"};
-
-    Setting<bool> pureEval{this, false, "pure-eval",
-        R"(
-          Pure evaluation mode ensures that the result of Nix expressions is fully determined by explicitly declared inputs, and not influenced by external state:
-
-          - File system and network access is restricted to accesses to immutable data only:
-            - Path literals relative to the home directory like `~/lix` are rejected at parse time.
-            - Access to absolute paths that did not result from Nix language evaluation is rejected when such paths are given as parameters to builtins like, for example, [`builtins.readFile`](@docroot@/language/builtins.md#builtins-readFile).
-
-              Access is nonetheless allowed to (absolute) paths in the Nix store that are returned by builtins like [`builtins.filterSource`](@docroot@/language/builtins.md#builtins-filterSource), [`builtins.fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball) and similar.
-            - Impure fetches such as not specifying a commit ID for `builtins.fetchGit` or not specifying a hash for `builtins.fetchTarball` are rejected.
-            - In flakes, access to relative paths outside of the root of the flake's source tree (often, a git repository) is rejected.
-          - The evaluator ignores `NIX_PATH`, `-I` and the `nix-path` setting. Thus, [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath) is an empty list.
-          - The builtins [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem) and [`builtins.currentTime`](@docroot@/language/builtin-constants.md#builtins-currentTime) are absent from `builtins`.
-          - [`builtins.getEnv`](@docroot@/language/builtin-constants.md#builtins-currentSystem) always returns empty string for any variable.
-          - [`builtins.storePath`](@docroot@/language/builtins.md#builtins-storePath) throws an error (Lix may change this, tracking issue: <https://git.lix.systems/lix-project/lix/issues/402>)
-        )"
-        };
-
-    Setting<bool> enableImportFromDerivation{
-        this, true, "allow-import-from-derivation",
-        R"(
-          By default, Lix allows you to `import` from a derivation, allowing
-          building at evaluation time. With this option set to false, Lix will
-          throw an error when evaluating an expression that uses this feature,
-          allowing users to ensure their evaluation will not require any
-          builds to take place.
-        )"};
-
-    Setting<Strings> allowedUris{this, {}, "allowed-uris",
-        R"(
-          A list of URI prefixes to which access is allowed in restricted
-          evaluation mode. For example, when set to
-          `https://github.com/NixOS`, builtin functions such as `fetchGit` are
-          allowed to access `https://github.com/NixOS/patchelf.git`.
-        )"};
-
-
-    Setting<bool> traceFunctionCalls{this, false, "trace-function-calls",
-        R"(
-          If set to `true`, the Nix evaluator will trace every function call.
-          Nix will print a log message at the "vomit" level for every function
-          entrance and function exit.
-
-              function-trace entered undefined position at 1565795816999559622
-              function-trace exited undefined position at 1565795816999581277
-              function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150
-              function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684
-
-          The `undefined position` means the function call is a builtin.
-
-          Use the `contrib/stack-collapse.py` script distributed with the Nix
-          source code to convert the trace logs in to a format suitable for
-          `flamegraph.pl`.
-        )"};
-
-    Setting<bool> useEvalCache{this, true, "eval-cache",
-        "Whether to use the flake evaluation cache."};
-
-    Setting<bool> ignoreExceptionsDuringTry{this, false, "ignore-try",
-        R"(
-          If set to true, ignore exceptions inside 'tryEval' calls when evaluating nix expressions in
-          debug mode (using the --debugger flag). By default the debugger will pause on all exceptions.
-        )"};
-
-    Setting<bool> traceVerbose{this, false, "trace-verbose",
-        "Whether `builtins.traceVerbose` should trace its first argument when evaluated."};
-
-    Setting<unsigned int> maxCallDepth{this, 10000, "max-call-depth",
-        "The maximum function call depth to allow before erroring."};
-
-    Setting<bool> builtinsTraceDebugger{this, false, "debugger-on-trace",
-        R"(
-          If set to true and the `--debugger` flag is given,
-          [`builtins.trace`](@docroot@/language/builtins.md#builtins-trace) will
-          enter the debugger like
-          [`builtins.break`](@docroot@/language/builtins.md#builtins-break).
-
-          This is useful for debugging warnings in third-party Nix code.
-        )"};
-
-    PathsSetting<Paths> replOverlays{this, Paths(), "repl-overlays",
-        R"(
-          A list of files containing Nix expressions that can be used to add
-          default bindings to [`nix
-          repl`](@docroot@/command-ref/new-cli/nix3-repl.md) sessions.
-
-          Each file is called with three arguments:
-          1. An [attribute set](@docroot@/language/values.html#attribute-set)
-             containing at least a
-             [`currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem)
-             attribute (this is identical to
-             [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem),
-             except that it's available in
-             [`pure-eval`](@docroot@/command-ref/conf-file.html#conf-pure-eval)
-             mode).
-          2. The top-level bindings produced by the previous `repl-overlays`
-             value (or the default top-level bindings).
-          3. The final top-level bindings produced by calling all
-             `repl-overlays`.
-
-          For example, the following file would alias `pkgs` to
-          `legacyPackages.${info.currentSystem}` (if that attribute is defined):
-
-          ```nix
-          info: final: prev:
-          if prev ? legacyPackages
-             && prev.legacyPackages ? ${info.currentSystem}
-          then
-          {
-            pkgs = prev.legacyPackages.${info.currentSystem};
-          }
-          else
-          { }
-          ```
-
-          Here's a more elaborate `repl-overlay`, which provides the following
-          variables:
-          - The original, unmodified variables are aliased to `original`.
-          - `legacyPackages.${system}` (if it exists) or `packages.${system}`
-            (otherwise) is aliased to `pkgs`.
-          - All attribute set variables with a `${system}` attribute are
-            abbreviated in the same manner; e.g. `devShells.${system}` is
-            shortened to `devShells`.
-
-          For example, the following attribute set:
-
-          ```nix
-          info: final: attrs: let
-            # Equivalent to nixpkgs `lib.optionalAttrs`.
-            optionalAttrs = predicate: attrs:
-              if predicate
-              then attrs
-              else {};
-
-            # If `attrs.${oldName}.${info.currentSystem}` exists, alias `${newName}` to
-            # it.
-            collapseRenamed = oldName: newName:
-              optionalAttrs (builtins.hasAttr oldName attrs
-                && builtins.hasAttr info.currentSystem attrs.${oldName})
-              {
-                ${newName} = attrs.${oldName}.${info.currentSystem};
-              };
-
-            # Alias `attrs.${oldName}.${info.currentSystem} to `${newName}`.
-            collapse = name: collapseRenamed name name;
-
-            # Alias all `attrs` keys with an `${info.currentSystem}` attribute.
-            collapseAll =
-              builtins.foldl'
-              (prev: name: prev // collapse name)
-              {}
-              (builtins.attrNames attrs);
-          in
-            # Preserve the original bindings as `original`.
-            (optionalAttrs (! attrs ? original)
-              {
-                original = attrs;
-              })
-            // (collapseRenamed "packages" "pkgs")
-            // (collapseRenamed "legacyPackages" "pkgs")
-            // collapseAll
-          ```
-        )"};
 };
 
 extern EvalSettings evalSettings;

src/libexpr/meson.build

@@ -13,6 +13,37 @@ foreach header : [ 'imported-drv-to-derivation.nix', 'fetchurl.nix' ]
 endforeach
 subdir('flake')
 
+libexpr_setting_definitions = files(
+  'settings/allow-import-from-derivation.md',
+  'settings/allow-unsafe-native-code-during-evaluation.md',
+  'settings/allowed-uris.md',
+  'settings/debugger-on-trace.md',
+  'settings/eval-cache.md',
+  'settings/eval-system.md',
+  'settings/ignore-try.md',
+  'settings/max-call-depth.md',
+  'settings/nix-path.md',
+  'settings/pure-eval.md',
+  'settings/repl-overlays.md',
+  'settings/restrict-eval.md',
+  'settings/trace-function-calls.md',
+  'settings/trace-verbose.md',
+)
+libexpr_settings_header = custom_target(
+  command : [
+    python.full_path(),
+    '@SOURCE_ROOT@/src/code-generation/build_settings.py',
+    '--kernel', host_machine.system(),
+    '--header', '@OUTPUT@',
+    '--experimental-features', '@SOURCE_ROOT@/src/libutil/experimental-features',
+    '@INPUT@',
+  ],
+  input : libexpr_setting_definitions,
+  output : 'libexpr-settings.gen.inc',
+  install : true,
+  install_dir : includedir / 'lib/libexpr',
+)
+
 libexpr_sources = files(
   'attr-path.cc',
   'attr-set.cc',
@@ -84,6 +115,7 @@ libexpr_headers = files(
 libexpr = library(
   'lixexpr',
   libexpr_sources,
+  libexpr_settings_header,
   libexpr_generated_headers,
   dependencies : [
     liblixutil,
@@ -112,6 +144,7 @@ install_headers(
 
 liblixexpr = declare_dependency(
   include_directories : include_directories('.'),
+  sources : libexpr_settings_header,
   link_with : libexpr,
 )
 
@@ -119,6 +152,7 @@ liblixexpr = declare_dependency(
 if is_static
   liblixexpr_mstatic = declare_dependency(
     include_directories : include_directories('.'),
+    sources : libexpr_settings_header,
     link_whole : libexpr,
   )
 else

src/libexpr/settings/allow-import-from-derivation.md

@@ -0,0 +1,11 @@
+---
+name: allow-import-from-derivation
+internalName: enableImportFromDerivation
+type: bool
+default: true
+---
+By default, Lix allows you to `import` from a derivation, allowing
+building at evaluation time. With this option set to false, Lix will
+throw an error when evaluating an expression that uses this feature,
+allowing users to ensure their evaluation will not require any
+builds to take place.

src/libexpr/settings/allow-unsafe-native-code-during-evaluation.md

@@ -0,0 +1,21 @@
+---
+name: allow-unsafe-native-code-during-evaluation
+internalName: enableNativeCode
+type: bool
+default: false
+---
+Enable built-in functions that allow executing native code.
+
+In particular, this adds:
+- `builtins.importNative` *path* *symbol*
+
+  Runs function with *symbol* from a dynamic shared object (DSO) at *path*.
+  This may be used to add new builtins to the Nix language.
+  The procedure must have the following signature:
+  ```cpp
+  extern "C" typedef void (*ValueInitialiser) (EvalState & state, Value & v);
+  ```
+
+- `builtins.exec` *arguments*
+
+  Execute a program, where *arguments* are specified as a list of strings, and parse its output as a Nix expression.

src/libexpr/settings/allowed-uris.md

@@ -0,0 +1,10 @@
+---
+name: allowed-uris
+internalName: allowedUris
+type: Strings
+default: []
+---
+A list of URI prefixes to which access is allowed in restricted
+evaluation mode. For example, when set to
+`https://github.com/NixOS`, builtin functions such as `fetchGit` are
+allowed to access `https://github.com/NixOS/patchelf.git`.

src/libexpr/settings/debugger-on-trace.md

@@ -0,0 +1,12 @@
+---
+name: debugger-on-trace
+internalName: builtinsTraceDebugger
+type: bool
+default: false
+---
+If set to true and the `--debugger` flag is given,
+[`builtins.trace`](@docroot@/language/builtins.md#builtins-trace) will
+enter the debugger like
+[`builtins.break`](@docroot@/language/builtins.md#builtins-break).
+
+This is useful for debugging warnings in third-party Nix code.

src/libexpr/settings/eval-cache.md

@@ -0,0 +1,7 @@
+---
+name: eval-cache
+internalName: useEvalCache
+type: bool
+default: true
+---
+Whether to use the flake evaluation cache.

src/libexpr/settings/eval-system.md

@@ -0,0 +1,15 @@
+---
+name: eval-system
+internalName: currentSystem
+type: std::string
+default: ''
+---
+This option defines
+[`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem)
+in the Nix language if it is set as a non-empty string.
+Otherwise, if it is defined as the empty string (the default), the value of the
+[`system` ](#conf-system)
+configuration setting is used instead.
+
+Unlike `system`, this setting does not change what kind of derivations can be built locally.
+This is useful for evaluating Nix code on one system to produce derivations to be built on another type of system.

src/libexpr/settings/ignore-try.md

@@ -0,0 +1,8 @@
+---
+name: ignore-try
+internalName: ignoreExceptionsDuringTry
+type: bool
+default: false
+---
+If set to true, ignore exceptions inside 'tryEval' calls when evaluating nix expressions in
+debug mode (using the --debugger flag). By default the debugger will pause on all exceptions.

src/libexpr/settings/max-call-depth.md

@@ -0,0 +1,7 @@
+---
+name: max-call-depth
+internalName: maxCallDepth
+type: unsigned int
+default: 10000
+---
+The maximum function call depth to allow before erroring.

src/libexpr/settings/nix-path.md

@@ -0,0 +1,11 @@
+---
+name: nix-path
+internalName: nixPath
+type: Strings
+defaultExpr: 'getDefaultNixPath()'
+defaultText: '*machine-specific*'
+---
+List of directories to be searched for `<...>` file references
+
+In particular, outside of [pure evaluation mode](#conf-pure-eval), this determines the value of
+[`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath).

src/libexpr/settings/pure-eval.md

@@ -0,0 +1,19 @@
+---
+name: pure-eval
+internalName: pureEval
+type: bool
+default: false
+---
+Pure evaluation mode ensures that the result of Nix expressions is fully determined by explicitly declared inputs, and not influenced by external state:
+
+- File system and network access is restricted to accesses to immutable data only:
+  - Path literals relative to the home directory like `~/lix` are rejected at parse time.
+  - Access to absolute paths that did not result from Nix language evaluation is rejected when such paths are given as parameters to builtins like, for example, [`builtins.readFile`](@docroot@/language/builtins.md#builtins-readFile).
+
+    Access is nonetheless allowed to (absolute) paths in the Nix store that are returned by builtins like [`builtins.filterSource`](@docroot@/language/builtins.md#builtins-filterSource), [`builtins.fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball) and similar.
+  - Impure fetches such as not specifying a commit ID for `builtins.fetchGit` or not specifying a hash for `builtins.fetchTarball` are rejected.
+  - In flakes, access to relative paths outside of the root of the flake's source tree (often, a git repository) is rejected.
+- The evaluator ignores `NIX_PATH`, `-I` and the `nix-path` setting. Thus, [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath) is an empty list.
+- The builtins [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem) and [`builtins.currentTime`](@docroot@/language/builtin-constants.md#builtins-currentTime) are absent from `builtins`.
+- [`builtins.getEnv`](@docroot@/language/builtin-constants.md#builtins-currentSystem) always returns empty string for any variable.
+- [`builtins.storePath`](@docroot@/language/builtins.md#builtins-storePath) throws an error (Lix may change this, tracking issue: <https://git.lix.systems/lix-project/lix/issues/402>)

src/libexpr/settings/repl-overlays.md

@@ -0,0 +1,86 @@
+---
+name: repl-overlays
+internalName: replOverlays
+settingType: PathsSetting<Paths>
+default: []
+---
+A list of files containing Nix expressions that can be used to add
+default bindings to [`nix
+repl`](@docroot@/command-ref/new-cli/nix3-repl.md) sessions.
+
+Each file is called with three arguments:
+1. An [attribute set](@docroot@/language/values.html#attribute-set)
+   containing at least a
+   [`currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem)
+   attribute (this is identical to
+   [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem),
+   except that it's available in
+   [`pure-eval`](@docroot@/command-ref/conf-file.html#conf-pure-eval)
+   mode).
+2. The top-level bindings produced by the previous `repl-overlays`
+   value (or the default top-level bindings).
+3. The final top-level bindings produced by calling all
+   `repl-overlays`.
+
+For example, the following file would alias `pkgs` to
+`legacyPackages.${info.currentSystem}` (if that attribute is defined):
+
+```nix
+info: final: prev:
+if prev ? legacyPackages
+   && prev.legacyPackages ? ${info.currentSystem}
+then
+{
+  pkgs = prev.legacyPackages.${info.currentSystem};
+}
+else
+{ }
+```
+
+Here's a more elaborate `repl-overlay`, which provides the following
+variables:
+- The original, unmodified variables are aliased to `original`.
+- `legacyPackages.${system}` (if it exists) or `packages.${system}`
+  (otherwise) is aliased to `pkgs`.
+- All attribute set variables with a `${system}` attribute are
+  abbreviated in the same manner; e.g. `devShells.${system}` is
+  shortened to `devShells`.
+
+For example, the following attribute set:
+
+```nix
+info: final: attrs: let
+  # Equivalent to nixpkgs `lib.optionalAttrs`.
+  optionalAttrs = predicate: attrs:
+    if predicate
+    then attrs
+    else {};
+
+  # If `attrs.${oldName}.${info.currentSystem}` exists, alias `${newName}` to
+  # it.
+  collapseRenamed = oldName: newName:
+    optionalAttrs (builtins.hasAttr oldName attrs
+      && builtins.hasAttr info.currentSystem attrs.${oldName})
+    {
+      ${newName} = attrs.${oldName}.${info.currentSystem};
+    };
+
+  # Alias `attrs.${oldName}.${info.currentSystem} to `${newName}`.
+  collapse = name: collapseRenamed name name;
+
+  # Alias all `attrs` keys with an `${info.currentSystem}` attribute.
+  collapseAll =
+    builtins.foldl'
+    (prev: name: prev // collapse name)
+    {}
+    (builtins.attrNames attrs);
+in
+  # Preserve the original bindings as `original`.
+  (optionalAttrs (! attrs ? original)
+    {
+      original = attrs;
+    })
+  // (collapseRenamed "packages" "pkgs")
+  // (collapseRenamed "legacyPackages" "pkgs")
+  // collapseAll
+```

src/libexpr/settings/restrict-eval.md

@@ -0,0 +1,11 @@
+---
+name: restrict-eval
+internalName: restrictEval
+type: bool
+default: false
+---
+If set to `true`, the Nix evaluator will not allow access to any
+files outside of the Nix search path (as set via the `NIX_PATH`
+environment variable or the `-I` option), or to URIs outside of
+[`allowed-uris`](../command-ref/conf-file.md#conf-allowed-uris).
+The default is `false`.

src/libexpr/settings/trace-function-calls.md

@@ -0,0 +1,20 @@
+---
+name: trace-function-calls
+internalName: traceFunctionCalls
+type: bool
+default: false
+---
+If set to `true`, the Nix evaluator will trace every function call.
+Nix will print a log message at the "vomit" level for every function
+entrance and function exit.
+
+    function-trace entered undefined position at 1565795816999559622
+    function-trace exited undefined position at 1565795816999581277
+    function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150
+    function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684
+
+The `undefined position` means the function call is a builtin.
+
+Use the `contrib/stack-collapse.py` script distributed with the Nix
+source code to convert the trace logs in to a format suitable for
+`flamegraph.pl`.

src/libexpr/settings/trace-verbose.md

@@ -0,0 +1,7 @@
+---
+name: trace-verbose
+internalName: traceVerbose
+type: bool
+default: false
+---
+Whether `builtins.traceVerbose` should trace its first argument when evaluated.

src/libfetchers/fetch-settings.hh

@@ -20,104 +20,7 @@ struct FetchSettings : public Config
 {
     FetchSettings();
 
-    Setting<StringMap> accessTokens{this, {}, "access-tokens",
+    #include "libfetchers-settings.gen.inc"
-        R"(
-          Access tokens used to access protected GitHub, GitLab, or
-          other locations requiring token-based authentication.
-
-          Access tokens are specified as a string made up of
-          space-separated `host=token` values.  The specific token
-          used is selected by matching the `host` portion against the
-          "host" specification of the input. The actual use of the
-          `token` value is determined by the type of resource being
-          accessed:
-
-          * Github: the token value is the OAUTH-TOKEN string obtained
-            as the Personal Access Token from the Github server (see
-            https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps).
-
-          * Gitlab: the token value is either the OAuth2 token or the
-            Personal Access Token (these are different types tokens
-            for gitlab, see
-            https://docs.gitlab.com/12.10/ee/api/README.html#authentication).
-            The `token` value should be `type:tokenstring` where
-            `type` is either `OAuth2` or `PAT` to indicate which type
-            of token is being specified.
-
-          Example `~/.config/nix/nix.conf`:
-
-          ```
-          access-tokens = github.com=23ac...b289 gitlab.mycompany.com=PAT:A123Bp_Cd..EfG gitlab.com=OAuth2:1jklw3jk
-          ```
-
-          Example `~/code/flake.nix`:
-
-          ```nix
-          input.foo = {
-            type = "gitlab";
-            host = "gitlab.mycompany.com";
-            owner = "mycompany";
-            repo = "pro";
-          };
-          ```
-
-          This example specifies three tokens, one each for accessing
-          github.com, gitlab.mycompany.com, and gitlab.com.
-
-          The `input.foo` uses the "gitlab" fetcher, which might
-          requires specifying the token type along with the token
-          value.
-          )"};
-
-    Setting<bool> allowDirty{this, true, "allow-dirty",
-        "Whether to allow dirty Git/Mercurial trees."};
-
-    Setting<bool> warnDirty{this, true, "warn-dirty",
-        "Whether to warn about dirty Git/Mercurial trees."};
-
-    Setting<std::string> flakeRegistry{this, "vendored", "flake-registry",
-        R"(
-          Path or URI of the global flake registry.
-
-          URIs are deprecated. When set to 'vendored', defaults to a vendored
-          copy of https://channels.nixos.org/flake-registry.json.
-
-          When empty, disables the global flake registry.
-        )",
-        {}, true, Xp::Flakes};
-
-
-    Setting<bool> useRegistries{this, true, "use-registries",
-        "Whether to use flake registries to resolve flake references.",
-        {}, true, Xp::Flakes};
-
-    Setting<AcceptFlakeConfig> acceptFlakeConfig{
-        this, AcceptFlakeConfig::Ask, "accept-flake-config",
-        R"(
-          Whether to accept Lix configuration from the `nixConfig` attribute of
-          a flake. Doing so as a trusted user allows Nix flakes to gain root
-          access on your machine if they set one of the several
-          trusted-user-only settings that execute commands as root.
-
-          If set to `true`, such configuration will be accepted without asking;
-          this is almost always a very bad idea. Setting this to `ask` will
-          prompt the user each time whether to allow a certain configuration
-          option set this way, and offer to optionally remember their choice.
-          When set to `false`, the configuration will be automatically
-          declined.
-
-          See [multi-user installations](@docroot@/installation/multi-user.md)
-          for more details on the Lix security model.
-        )",
-        {}, true, Xp::Flakes};
-
-    Setting<std::string> commitLockFileSummary{
-        this, "", "commit-lockfile-summary",
-        R"(
-          The commit summary to use when committing changed flake lock files. If
-          empty, the summary is generated based on the action performed.
-        )",
-        {}, true, Xp::Flakes};
 };
 
 // FIXME: don't use a global variable.

src/libfetchers/meson.build

@@ -22,8 +22,33 @@ libfetchers_headers = files(
   'registry.hh',
 )
 
+libfetchers_setting_definitions = files(
+  'settings/accept-flake-config.md',
+  'settings/access-tokens.md',
+  'settings/allow-dirty.md',
+  'settings/commit-lockfile-summary.md',
+  'settings/flake-registry.md',
+  'settings/use-registries.md',
+  'settings/warn-dirty.md',
+)
+libfetchers_settings_header = custom_target(
+  command : [
+    python.full_path(),
+    '@SOURCE_ROOT@/src/code-generation/build_settings.py',
+    '--kernel', host_machine.system(),
+    '--header', '@OUTPUT@',
+    '--experimental-features', '@SOURCE_ROOT@/src/libutil/experimental-features',
+    '@INPUT@',
+  ],
+  input : libfetchers_setting_definitions,
+  output : 'libfetchers-settings.gen.inc',
+  install : true,
+  install_dir : includedir / 'lix/libfetchers',
+)
+
 libfetchers = library(
   'lixfetchers',
+  libfetchers_settings_header,
   libfetchers_sources,
   dependencies : [
     liblixstore,
@@ -54,6 +79,7 @@ configure_file(
 
 liblixfetchers = declare_dependency(
   include_directories : include_directories('.'),
+  sources : libfetchers_settings_header,
   link_with : libfetchers,
 )
 
@@ -61,6 +87,7 @@ liblixfetchers = declare_dependency(
 if is_static
   liblixfetchers_mstatic = declare_dependency(
     include_directories : include_directories('.'),
+    sources : libfetchers_settings_header,
     link_whole : libfetchers,
   )
 else

src/libfetchers/settings/accept-flake-config.md

@@ -0,0 +1,22 @@
+---
+name: accept-flake-config
+internalName: acceptFlakeConfig
+type: AcceptFlakeConfig
+defaultExpr: AcceptFlakeConfig::Ask
+defaultText: '`ask`'
+experimentalFeature: flakes
+---
+Whether to accept Lix configuration from the `nixConfig` attribute of
+a flake. Doing so as a trusted user allows Nix flakes to gain root
+access on your machine if they set one of the several
+trusted-user-only settings that execute commands as root.
+
+If set to `true`, such configuration will be accepted without asking;
+this is almost always a very bad idea. Setting this to `ask` will
+prompt the user each time whether to allow a certain configuration
+option set this way, and offer to optionally remember their choice.
+When set to `false`, the configuration will be automatically
+declined.
+
+See [multi-user installations](@docroot@/installation/multi-user.md)
+for more details on the Lix security model.

src/libfetchers/settings/access-tokens.md

@@ -0,0 +1,51 @@
+---
+name: access-tokens
+internalName: accessTokens
+type: StringMap
+default: []
+---
+Access tokens used to access protected GitHub, GitLab, or
+other locations requiring token-based authentication.
+
+Access tokens are specified as a string made up of
+space-separated `host=token` values.  The specific token
+used is selected by matching the `host` portion against the
+"host" specification of the input. The actual use of the
+`token` value is determined by the type of resource being
+accessed:
+
+* Github: the token value is the OAUTH-TOKEN string obtained
+  as the Personal Access Token from the Github server (see
+  https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps).
+
+* Gitlab: the token value is either the OAuth2 token or the
+  Personal Access Token (these are different types tokens
+  for gitlab, see
+  https://docs.gitlab.com/12.10/ee/api/README.html#authentication).
+  The `token` value should be `type:tokenstring` where
+  `type` is either `OAuth2` or `PAT` to indicate which type
+  of token is being specified.
+
+Example `~/.config/nix/nix.conf`:
+
+```
+access-tokens = github.com=23ac...b289 gitlab.mycompany.com=PAT:A123Bp_Cd..EfG gitlab.com=OAuth2:1jklw3jk
+```
+
+Example `~/code/flake.nix`:
+
+```nix
+input.foo = {
+  type = "gitlab";
+  host = "gitlab.mycompany.com";
+  owner = "mycompany";
+  repo = "pro";
+};
+```
+
+This example specifies three tokens, one each for accessing
+github.com, gitlab.mycompany.com, and gitlab.com.
+
+The `input.foo` uses the "gitlab" fetcher, which might
+requires specifying the token type along with the token
+value.

src/libfetchers/settings/allow-dirty.md

@@ -0,0 +1,7 @@
+---
+name: allow-dirty
+internalName: allowDirty
+type: bool
+default: true
+---
+Whether to allow dirty Git/Mercurial trees.

src/libfetchers/settings/commit-lockfile-summary.md

@@ -0,0 +1,9 @@
+---
+name: commit-lockfile-summary
+internalName: commitLockFileSummary
+type: std::string
+default: ''
+experimentalFeature: flakes
+---
+The commit summary to use when committing changed flake lock files. If
+empty, the summary is generated based on the action performed.

src/libfetchers/settings/flake-registry.md

@@ -0,0 +1,13 @@
+---
+name: flake-registry
+internalName: flakeRegistry
+type: std::string
+default: vendored
+experimentalFeature: flakes
+---
+Path or URI of the global flake registry.
+
+URIs are deprecated. When set to 'vendored', defaults to a vendored
+copy of https://channels.nixos.org/flake-registry.json.
+
+When empty, disables the global flake registry.

src/libfetchers/settings/use-registries.md

@@ -0,0 +1,8 @@
+---
+name: use-registries
+internalName: useRegistries
+type: bool
+default: true
+experimentalFeature: flakes
+---
+Whether to use flake registries to resolve flake references.

src/libfetchers/settings/warn-dirty.md

@@ -0,0 +1,7 @@
+---
+name: warn-dirty
+internalName: warnDirty
+type: bool
+default: true
+---
+Whether to warn about dirty Git/Mercurial trees.

src/libstore/file-transfer-settings/connect-timeout.md

@@ -0,0 +1,9 @@
+---
+name: connect-timeout
+internalName: connectTimeout
+type: unsigned long
+default: 0
+---
+The timeout (in seconds) for establishing connections in the
+binary cache substituter. It corresponds to `curl`’s
+`--connect-timeout` option. A value of 0 means no limit.

src/libstore/file-transfer-settings/download-attempts.md

@@ -0,0 +1,7 @@
+---
+name: download-attempts
+internalName: tries
+type: unsigned int
+default: 5
+---
+How often Lix will attempt to download a file before giving up.

src/libstore/file-transfer-settings/http-connections.md

@@ -0,0 +1,10 @@
+---
+name: http-connections
+internalName: httpConnections
+type: size_t
+default: 25
+aliases: [binary-caches-parallel-connections]
+---
+The maximum number of parallel TCP connections used to fetch
+files from binary caches and by other downloads. It defaults
+to 25. 0 means no limit.

src/libstore/file-transfer-settings/http2.md

@@ -0,0 +1,7 @@
+---
+name: http2
+internalName: enableHttp2
+type: bool
+default: true
+---
+Whether to enable HTTP/2 support.

src/libstore/file-transfer-settings/stalled-download-timeout.md

@@ -0,0 +1,9 @@
+---
+name: stalled-download-timeout
+internalName: stalledDownloadTimeout
+type: unsigned long
+default: 300
+---
+The timeout (in seconds) for receiving data from servers
+during download. Lix cancels idle downloads after this
+timeout's duration.

src/libstore/file-transfer-settings/user-agent-suffix.md

@@ -0,0 +1,7 @@
+---
+name: user-agent-suffix
+internalName: userAgentSuffix
+type: std::string
+default: ''
+---
+String appended to the user agent in HTTP requests.

src/libstore/filetransfer.hh

@@ -15,39 +15,7 @@ namespace nix {
 
 struct FileTransferSettings : Config
 {
-    Setting<bool> enableHttp2{this, true, "http2",
+    #include "file-transfer-settings.gen.inc"
-        "Whether to enable HTTP/2 support."};
-
-    Setting<std::string> userAgentSuffix{this, "", "user-agent-suffix",
-        "String appended to the user agent in HTTP requests."};
-
-    Setting<size_t> httpConnections{
-        this, 25, "http-connections",
-        R"(
-          The maximum number of parallel TCP connections used to fetch
-          files from binary caches and by other downloads. It defaults
-          to 25. 0 means no limit.
-        )",
-        {"binary-caches-parallel-connections"}};
-
-    Setting<unsigned long> connectTimeout{
-        this, 0, "connect-timeout",
-        R"(
-          The timeout (in seconds) for establishing connections in the
-          binary cache substituter. It corresponds to `curl`’s
-          `--connect-timeout` option. A value of 0 means no limit.
-        )"};
-
-    Setting<unsigned long> stalledDownloadTimeout{
-        this, 300, "stalled-download-timeout",
-        R"(
-          The timeout (in seconds) for receiving data from servers
-          during download. Lix cancels idle downloads after this
-          timeout's duration.
-        )"};
-
-    Setting<unsigned int> tries{this, 5, "download-attempts",
-        "How often Lix will attempt to download a file before giving up."};
 };
 
 extern FileTransferSettings fileTransferSettings;

src/libstore/meson.build

@@ -28,6 +28,120 @@ if enable_embedded_sandbox_shell
   libstore_generated_headers += embedded_sandbox_shell_gen
 endif
 
+libstore_settings_headers = []
+
+file_transfer_setting_definitions = files(
+  'file-transfer-settings/connect-timeout.md',
+  'file-transfer-settings/download-attempts.md',
+  'file-transfer-settings/http-connections.md',
+  'file-transfer-settings/http2.md',
+  'file-transfer-settings/stalled-download-timeout.md',
+  'file-transfer-settings/user-agent-suffix.md',
+)
+libstore_settings_headers += custom_target(
+  command : [
+    python.full_path(),
+    '@SOURCE_ROOT@/src/code-generation/build_settings.py',
+    '--kernel', host_machine.system(),
+    '--header', '@OUTPUT@',
+    '--experimental-features', '@SOURCE_ROOT@/src/libutil/experimental-features',
+    '@INPUT@',
+  ],
+  input : file_transfer_setting_definitions,
+  output : 'file-transfer-settings.gen.inc',
+  install : true,
+  install_dir : includedir / 'lix/libstore',
+)
+
+libstore_setting_definitions = files(
+  'settings/allow-symlinked-store.md',
+  'settings/allowed-impure-host-deps.md',
+  'settings/always-allow-substitutes.md',
+  'settings/auto-allocate-uids.md',
+  'settings/auto-optimise-store.md',
+  'settings/build-dir.md',
+  'settings/build-hook.md',
+  'settings/build-poll-interval.md',
+  'settings/build-users-group.md',
+  'settings/builders-use-substitutes.md',
+  'settings/builders.md',
+  'settings/compress-build-log.md',
+  'settings/cores.md',
+  'settings/darwin-log-sandbox-violations.md',
+  'settings/diff-hook.md',
+  'settings/download-speed.md',
+  'settings/enable-core-dumps.md',
+  'settings/extra-platforms.md',
+  'settings/fallback.md',
+  'settings/fsync-metadata.md',
+  'settings/gc-reserved-space.md',
+  'settings/hashed-mirrors.md',
+  'settings/id-count.md',
+  'settings/ignored-acls.md',
+  'settings/impersonate-linux-26.md',
+  'settings/keep-build-log.md',
+  'settings/keep-derivations.md',
+  'settings/keep-env-derivations.md',
+  'settings/keep-failed.md',
+  'settings/keep-going.md',
+  'settings/keep-outputs.md',
+  'settings/log-lines.md',
+  'settings/max-build-log-size.md',
+  'settings/max-free.md',
+  'settings/max-jobs.md',
+  'settings/max-silent-time.md',
+  'settings/max-substitution-jobs.md',
+  'settings/min-free-check-interval.md',
+  'settings/min-free.md',
+  'settings/nar-buffer-size.md',
+  'settings/narinfo-cache-negative-ttl.md',
+  'settings/narinfo-cache-positive-ttl.md',
+  'settings/netrc-file.md',
+  'settings/plugin-files.md',
+  'settings/post-build-hook.md',
+  'settings/pre-build-hook.md',
+  'settings/print-missing.md',
+  'settings/require-drop-supplementary-groups.md',
+  'settings/require-sigs.md',
+  'settings/run-diff-hook.md',
+  'settings/sandbox-build-dir.md',
+  'settings/sandbox-dev-shm-size.md',
+  'settings/sandbox-fallback.md',
+  'settings/sandbox-paths.md',
+  'settings/sandbox.md',
+  'settings/secret-key-files.md',
+  'settings/ssl-cert-file.md',
+  'settings/start-id.md',
+  'settings/store.md',
+  'settings/substitute.md',
+  'settings/substituters.md',
+  'settings/sync-before-registering.md',
+  'settings/system-features.md',
+  'settings/system.md',
+  'settings/tarball-ttl.md',
+  'settings/temp-dir.md',
+  'settings/timeout.md',
+  'settings/trusted-public-keys.md',
+  'settings/trusted-substituters.md',
+  'settings/use-cgroups.md',
+  'settings/use-sqlite-wal.md',
+  'settings/use-xdg-base-directories.md',
+)
+libstore_settings_headers += custom_target(
+  command : [
+    python.full_path(),
+    '@SOURCE_ROOT@/src/code-generation/build_settings.py',
+    '--kernel', host_machine.system(),
+    '--header', '@OUTPUT@',
+    '--experimental-features', '@SOURCE_ROOT@/src/libutil/experimental-features',
+    '@INPUT@',
+  ],
+  input : libstore_setting_definitions,
+  output : 'libstore-settings.gen.inc',
+  install : true,
+  install_dir : includedir / 'lix/libstore',
+)
+
 libstore_sources = files(
   'binary-cache-store.cc',
   'build-result.cc',
@@ -232,8 +346,9 @@ endif
 
 libstore = library(
   'lixstore',
-  libstore_generated_headers,
   libstore_sources,
+  libstore_settings_headers,
+  libstore_generated_headers,
   dependencies : dependencies,
   cpp_args : cpp_args,
   cpp_pch : cpp_pch,
@@ -247,6 +362,7 @@ install_headers(libstore_headers, subdir : 'lix/libstore', preserve_path : true)
 # Used by libfetchers.
 liblixstore = declare_dependency(
   include_directories : include_directories('.'),
+  sources : libstore_settings_headers,
   link_with : libstore,
 )
 
@@ -254,6 +370,7 @@ liblixstore = declare_dependency(
 if is_static
   liblixstore_mstatic = declare_dependency(
     include_directories : include_directories('.'),
+    sources : libstore_settings_headers,
     link_whole : libstore,
   )
 else

src/libstore/settings/allow-symlinked-store.md

@@ -0,0 +1,14 @@
+---
+name: allow-symlinked-store
+internalName: allowSymlinkedStore
+type: bool
+default: false
+---
+If set to `true`, Lix will stop complaining if the store directory
+(typically /nix/store) contains symlink components.
+
+This risks making some builds "impure" because builders sometimes
+"canonicalise" paths by resolving all symlink components. Problems
+occur if those builds are then deployed to machines where /nix/store
+resolves to a different location from that of the build machine. You
+can enable this setting if you are sure you're not going to do that.

src/libstore/settings/allowed-impure-host-deps.md

@@ -0,0 +1,7 @@
+---
+name: allowed-impure-host-deps
+internalName: allowedImpureHostPrefixes
+type: PathSet
+default: []
+---
+Which prefixes to allow derivations to ask for access to (primarily for Darwin).

src/libstore/settings/always-allow-substitutes.md

@@ -0,0 +1,9 @@
+---
+name: always-allow-substitutes
+internalName: alwaysAllowSubstitutes
+type: bool
+default: false
+---
+If set to `true`, Lix will ignore the `allowSubstitutes` attribute in
+derivations and always attempt to use available substituters.
+For more information on `allowSubstitutes`, see [the manual chapter on advanced attributes](../language/advanced-attributes.md).

src/libstore/settings/auto-allocate-uids.md

@@ -0,0 +1,11 @@
+---
+name: auto-allocate-uids
+internalName: autoAllocateUids
+type: bool
+default: false
+experimentalFeature: auto-allocate-uids
+---
+Whether to select UIDs for builds automatically, instead of using the
+users in `build-users-group`.
+
+UIDs are allocated starting at 872415232 (0x34000000) on Linux and 56930 on macOS.

src/libstore/settings/auto-optimise-store.md

@@ -0,0 +1,11 @@
+---
+name: auto-optimise-store
+internalName: autoOptimiseStore
+type: bool
+default: false
+---
+If set to `true`, Lix automatically detects files in the store
+that have identical contents, and replaces them with hard links to
+a single copy. This saves disk space. If set to `false` (the
+default), you can still run `nix-store --optimise` to get rid of
+duplicate files.

src/libstore/settings/build-dir.md

@@ -0,0 +1,14 @@
+---
+name: build-dir
+internalName: buildDir
+settingType: PathsSetting<std::optional<Path>>
+default: null
+---
+The directory on the host, in which derivations' temporary build directories are created.
+
+If not set, Nix will use the [`temp-dir`](#conf-temp-dir) setting if set, otherwise the system temporary directory indicated by the `TMPDIR` environment variable.
+Note that builds are often performed by the Nix daemon, so its `TMPDIR` is used, and not that of the Nix command line interface.
+
+This is also the location where [`--keep-failed`](@docroot@/command-ref/opt-common.md#opt-keep-failed) leaves its files.
+
+If Nix runs without sandbox, or if the platform does not support sandboxing with bind mounts (e.g. macOS), then the [`builder`](@docroot@/language/derivations.md#attr-builder)'s environment will contain this directory, instead of the virtual location [`sandbox-build-dir`](#conf-sandbox-build-dir).

src/libstore/settings/build-hook.md

@@ -0,0 +1,14 @@
+---
+name: build-hook
+internalName: buildHook
+type: Strings
+default: []
+deprecated: true
+---
+The path to the helper program that executes remote builds.
+
+Lix communicates with the build hook over `stdio` using a custom protocol to request builds that cannot be performed directly by the Nix daemon.
+The default value is the internal Lix binary that implements remote building.
+
+> **Warning**
+> Change this setting only if you really know what you’re doing.

src/libstore/settings/build-poll-interval.md

@@ -0,0 +1,7 @@
+---
+name: build-poll-interval
+internalName: pollInterval
+type: unsigned int
+default: 5
+---
+How often (in seconds) to poll for locks.

src/libstore/settings/build-users-group.md

@@ -0,0 +1,43 @@
+---
+name: build-users-group
+internalName: buildUsersGroup
+type: std::string
+defaultExpr: '""' # overridden in the code if running as root
+defaultText: '*running as root:* `nixbld`, *otherwise:* *empty*'
+---
+This options specifies the Unix group containing the Lix build user
+accounts. In multi-user Lix installations, builds should not be
+performed by the Lix account since that would allow users to
+arbitrarily modify the Nix store and database by supplying specially
+crafted builders; and they cannot be performed by the calling user
+since that would allow them to influence the build result.
+
+Therefore, if this option is non-empty and specifies a valid group,
+builds will be performed under the user accounts that are a member
+of the group specified here (as listed in `/etc/group`). Those user
+accounts should not be used for any other purpose\!
+
+Lix will never run two builds under the same user account at the
+same time. This is to prevent an obvious security hole: a malicious
+user writing a Nix expression that modifies the build result of a
+legitimate Nix expression being built by another user. Therefore it
+is good to have as many Lix build user accounts as you can spare.
+(Remember: uids are cheap.)
+
+The build users should have permission to create files in the Nix
+store, but not delete them. Therefore, `/nix/store` should be owned
+by the Nix account, its group should be the group specified here,
+and its mode should be `1775`.
+
+If the build users group is empty, builds will be performed under
+the uid of the Lix process (that is, the uid of the caller if
+both `NIX_REMOTE` is either empty or `auto` and the Nix store is
+owned by that user, or, alternatively, the uid under which the Nix
+daemon runs if `NIX_REMOTE` is `daemon` or if it is `auto` and the
+store is not owned by the caller). Obviously, this should not be used
+with a nix daemon accessible to untrusted clients.
+
+For the avoidance of doubt, explicitly setting this to *empty* with a
+Lix daemon running as root means that builds will be executed as root
+with respect to the rest of the system.
+We intend to fix this: https://git.lix.systems/lix-project/lix/issues/242

src/libstore/settings/builders-use-substitutes.md

@@ -0,0 +1,13 @@
+---
+name: builders-use-substitutes
+internalName: buildersUseSubstitutes
+type: bool
+default: false
+---
+If set to `true`, Lix will instruct remote build machines to use
+their own binary substitutes if available. In practical terms, this
+means that remote hosts will fetch as many build dependencies as
+possible from their own substitutes (e.g, from `cache.nixos.org`),
+instead of waiting for this host to upload them all. This can
+drastically reduce build times if the network connection between
+this computer and the remote build host is slow.

src/libstore/settings/builders.md

@@ -0,0 +1,12 @@
+---
+name: builders
+internalName: builders
+type: std::string
+defaultExpr: '"@" + nixConfDir + "/machines"'
+defaultText: '`@/etc/nix/machines`'
+---
+A semicolon-separated list of build machines.
+For the exact format and examples, see [the manual chapter on remote builds](../advanced-topics/distributed-builds.md)
+
+Defaults to `@$NIX_CONF_DIR/machines`.
+The default shown below is only accurate when the value of `NIX_CONF_DIR` has not been overridden at build time or using the environment variable.

src/libstore/settings/compress-build-log.md

@@ -0,0 +1,10 @@
+---
+name: compress-build-log
+internalName: compressLog
+type: bool
+default: true
+aliases: [build-compress-log]
+---
+If set to `true` (the default), build logs written to
+`/nix/var/log/nix/drvs` will be compressed on the fly using bzip2.
+Otherwise, they will not be compressed.

src/libstore/settings/cores.md

@@ -0,0 +1,16 @@
+---
+name: cores
+internalName: buildCores
+type: unsigned int
+defaultExpr: 'getDefaultCores()'
+defaultText: '*machine-specific*'
+aliases: [build-cores]
+---
+Sets the value of the `NIX_BUILD_CORES` environment variable in the
+invocation of builders. Builders can use this variable at their
+discretion to control the maximum amount of parallelism. For
+instance, in Nixpkgs, if the derivation attribute
+`enableParallelBuilding` is set to `true`, the builder passes the
+`-jN` flag to GNU Make. It can be overridden using the `--cores`
+command line switch and defaults to `1`. The value `0` means that
+the builder should use all available CPU cores in the system.

src/libstore/settings/darwin-log-sandbox-violations.md

@@ -0,0 +1,8 @@
+---
+name: darwin-log-sandbox-violations
+internalName: darwinLogSandboxViolations
+platforms: [darwin]
+type: bool
+default: false
+---
+Whether to log Darwin sandbox access violations to the system log.

src/libstore/settings/diff-hook.md

@@ -0,0 +1,32 @@
+---
+name: diff-hook
+internalName: diffHook
+settingType: PathsSetting<std::optional<Path>>
+default: null
+---
+Path to an executable capable of diffing build results. The hook is
+executed if `run-diff-hook` is true, and the output of a build is
+known to not be the same. This program is not executed to determine
+if two results are the same.
+
+The diff hook is executed by the same user and group who ran the
+build. However, the diff hook does not have write access to the
+store path just built.
+
+The diff hook program receives three parameters:
+
+1.  A path to the previous build's results
+
+2.  A path to the current build's results
+
+3.  The path to the build's derivation
+
+4.  The path to the build's scratch directory. This directory will
+    exist only if the build was run with `--keep-failed`.
+
+The stderr and stdout output from the diff hook will not be
+displayed to the user. Instead, it will print to the nix-daemon's
+log.
+
+When using the Nix daemon, `diff-hook` must be set in the `nix.conf`
+configuration file, and cannot be passed at the command line.

src/libstore/settings/download-speed.md

@@ -0,0 +1,8 @@
+---
+name: download-speed
+internalName: downloadSpeed
+type: unsigned int
+default: 0
+---
+Specify the maximum transfer rate in kilobytes per second you want
+Lix to use for downloads.

src/libstore/settings/enable-core-dumps.md

@@ -0,0 +1,10 @@
+---
+name: enable-core-dumps
+internalName: enableCoreDumps
+type: bool
+default: false
+---
+If set to `false` (the default), `RLIMIT_CORE` has a soft limit of zero.
+If set to `true`, the soft limit is infinite.
+
+The hard limit is always infinite.

src/libstore/settings/extra-platforms.md

@@ -0,0 +1,21 @@
+---
+name: extra-platforms
+internalName: extraPlatforms
+type: StringSet
+defaultExpr: 'getDefaultExtraPlatforms()'
+defaultText: '*machine-specific*'
+---
+System types of executables that can be run on this machine.
+
+Lix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals any of the values specified here or in the [`system` option](#conf-system).
+
+Setting this can be useful to build derivations locally on compatible machines:
+- `i686-linux` executables can be run on `x86_64-linux` machines (set by default)
+- `x86_64-darwin` executables can be run on macOS `aarch64-darwin` with Rosetta 2 (set by default where applicable)
+- `armv6` and `armv5tel` executables can be run on `armv7`
+- some `aarch64` machines can also natively run 32-bit ARM code
+- `qemu-user` may be used to support non-native platforms (though this
+may be slow and buggy)
+
+Build systems will usually detect the target platform to be the current physical system and therefore produce machine code incompatible with what may be intended in the derivation.
+You should design your derivation's `builder` accordingly and cross-check the results when using this option against natively-built versions of your derivation.

src/libstore/settings/fallback.md

@@ -0,0 +1,10 @@
+---
+name: fallback
+internalName: tryFallback
+type: bool
+default: false
+aliases: [build-fallback]
+---
+If set to `true`, Lix will fall back to building from source if a
+binary substitute fails. This is equivalent to the `--fallback`
+flag. The default is `false`.

src/libstore/settings/fsync-metadata.md

@@ -0,0 +1,10 @@
+---
+name: fsync-metadata
+internalName: fsyncMetadata
+type: bool
+default: true
+---
+If set to `true`, changes to the Nix store metadata (in
+`/nix/var/nix/db`) are synchronously flushed to disk. This improves
+robustness in case of system crashes, but reduces performance. The
+default is `true`.

src/libstore/settings/gc-reserved-space.md

@@ -0,0 +1,7 @@
+---
+name: gc-reserved-space
+internalName: reservedSize
+type: off_t
+default: 8388608 # 8 * 1024 * 1024
+---
+Amount of reserved disk space for the garbage collector.

src/libstore/settings/hashed-mirrors.md

@@ -0,0 +1,23 @@
+---
+name: hashed-mirrors
+internalName: hashedMirrors
+type: Strings
+default: []
+---
+A list of web servers used by `builtins.fetchurl` to obtain files by
+hash. Given a hash type *ht* and a base-16 hash *h*, Lix will try to
+download the file from *hashed-mirror*/*ht*/*h*. This allows files to
+be downloaded even if they have disappeared from their original URI.
+For example, given an example mirror `http://tarballs.nixos.org/`,
+when building the derivation
+
+```nix
+builtins.fetchurl {
+  url = "https://example.org/foo-1.2.3.tar.xz";
+  sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae";
+}
+```
+
+Lix will attempt to download this file from
+`http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae`
+first. If it is not available there, if will try the original URI.

src/libstore/settings/id-count.md

@@ -0,0 +1,14 @@
+---
+name: id-count
+internalName: uidCount
+type: uint32_t
+defaultExpr: |
+  #if __linux__
+    maxIdsPerBuild * 128
+  #else
+    128
+  #endif
+defaultText: '*Linux:* `8388608`, *other platforms:* `128`'
+experimentalFeature: auto-allocate-uids
+---
+The number of UIDs/GIDs to use for dynamic ID allocation.

src/libstore/settings/ignored-acls.md

@@ -0,0 +1,11 @@
+---
+name: ignored-acls
+internalName: ignoredAcls
+platforms: [linux]
+type: StringSet
+default: [security.csm, security.selinux, system.nfs4_acl]
+---
+A list of ACLs that should be ignored, normally Lix attempts to
+remove all ACLs from files and directories in the Nix store, but
+some ACLs like `security.selinux` or `system.nfs4_acl` can't be
+removed even by root. Therefore it's best to just ignore them.

src/libstore/settings/impersonate-linux-26.md

@@ -0,0 +1,9 @@
+---
+name: impersonate-linux-26
+internalName: impersonateLinux26
+platforms: [linux]
+type: bool
+default: false
+aliases: [build-impersonate-linux-26]
+---
+Whether to impersonate a Linux 2.6 machine on newer kernels.

src/libstore/settings/keep-build-log.md

@@ -0,0 +1,11 @@
+---
+name: keep-build-log
+internalName: keepLog
+type: bool
+default: true
+aliases: [build-keep-log]
+---
+If set to `true` (the default), Lix will write the build log of a
+derivation (i.e. the standard output and error of its builder) to
+the directory `/nix/var/log/nix/drvs`. The build log can be
+retrieved using the command `nix-store -l path`.

src/libstore/settings/keep-derivations.md

@@ -0,0 +1,17 @@
+---
+name: keep-derivations
+internalName: gcKeepDerivations
+type: bool
+default: true
+aliases: [gc-keep-derivations]
+---
+If `true` (default), the garbage collector will keep the derivations
+from which non-garbage store paths were built. If `false`, they will
+be deleted unless explicitly registered as a root (or reachable from
+other roots).
+
+Keeping derivation around is useful for querying and traceability
+(e.g., it allows you to ask with what dependencies or options a
+store path was built), so by default this option is on. Turn it off
+to save a bit of disk space (or a lot if `keep-outputs` is also
+turned on).

src/libstore/settings/keep-env-derivations.md

@@ -0,0 +1,22 @@
+---
+name: keep-env-derivations
+internalName: envKeepDerivations
+type: bool
+default: false
+aliases: [env-keep-derivations]
+---
+If `false` (default), derivations are not stored in Nix user
+environments. That is, the derivations of any build-time-only
+dependencies may be garbage-collected.
+
+If `true`, when you add a Nix derivation to a user environment, the
+path of the derivation is stored in the user environment. Thus, the
+derivation will not be garbage-collected until the user environment
+generation is deleted (`nix-env --delete-generations`). To prevent
+build-time-only dependencies from being collected, you should also
+turn on `keep-outputs`.
+
+The difference between this option and `keep-derivations` is that
+this one is “sticky”: it applies to any user environment created
+while this option was enabled, while `keep-derivations` only applies
+at the moment the garbage collector is run.

src/libstore/settings/keep-failed.md

@@ -0,0 +1,7 @@
+---
+name: keep-failed
+internalName: keepFailed
+type: bool
+default: false
+---
+Whether to keep temporary directories of failed builds.

src/libstore/settings/keep-going.md

@@ -0,0 +1,7 @@
+---
+name: keep-going
+internalName: keepGoing
+type: bool
+default: false
+---
+Whether to keep building derivations when another build fails.

src/libstore/settings/keep-outputs.md

@@ -0,0 +1,17 @@
+---
+name: keep-outputs
+internalName: gcKeepOutputs
+type: bool
+default: false
+aliases: [gc-keep-outputs]
+---
+If `true`, the garbage collector will keep the outputs of
+non-garbage derivations. If `false` (default), outputs will be
+deleted unless they are GC roots themselves (or reachable from other
+roots).
+
+In general, outputs must be registered as roots separately. However,
+even if the output of a derivation is registered as a root, the
+collector will still delete store paths that are used only at build
+time (e.g., the C compiler, or source tarballs downloaded from the
+network). To prevent it from doing so, set this option to `true`.

src/libstore/settings/log-lines.md

@@ -0,0 +1,7 @@
+---
+name: log-lines
+internalName: logLines
+type: size_t
+default: 25
+---
+The number of lines of the tail of the log to show if a build fails.

src/libstore/settings/max-build-log-size.md

@@ -0,0 +1,10 @@
+---
+name: max-build-log-size
+internalName: maxLogSize
+type: unsigned long
+default: 0
+aliases: [build-max-log-size]
+---
+This option defines the maximum number of bytes that a builder can
+write to its stdout/stderr. If the builder exceeds this limit, it’s
+killed. A value of `0` (the default) means that there is no limit.

src/libstore/settings/max-free.md

@@ -0,0 +1,13 @@
+---
+name: max-free
+internalName: maxFree
+type: uint64_t
+# n.b. this is deliberately int64 max rather than uint64 max because
+# this goes through the Nix language JSON parser and thus needs to be
+# representable in Nix language integers.
+defaultExpr: 'std::numeric_limits<int64_t>::max()'
+defaultText: '*infinity*'
+---
+When a garbage collection is triggered by the `min-free` option, it
+stops as soon as `max-free` bytes are available. The default is
+infinity (i.e. delete all garbage).

src/libstore/settings/max-jobs.md

@@ -0,0 +1,14 @@
+---
+name: max-jobs
+internalName: maxBuildJobs
+settingType: MaxBuildJobsSetting
+default: 1
+aliases: [build-max-jobs]
+---
+This option defines the maximum number of jobs that Lix will try to
+build in parallel. The default is `1`. The special value `auto`
+causes Lix to use the number of CPUs in your system. `0` is useful
+when using remote builders to prevent any local builds (except for
+`preferLocalBuild` derivation attribute which executes locally
+regardless). It can be overridden using the `--max-jobs` (`-j`)
+command line switch.

src/libstore/settings/max-silent-time.md

@@ -0,0 +1,16 @@
+---
+name: max-silent-time
+internalName: maxSilentTime
+type: time_t
+default: 0
+aliases: [build-max-silent-time]
+---
+This option defines the maximum number of seconds that a builder can
+go without producing any data on standard output or standard error.
+This is useful (for instance in an automated build system) to catch
+builds that are stuck in an infinite loop, or to catch remote builds
+that are hanging due to network problems. It can be overridden using
+the `--max-silent-time` command line switch.
+
+The value `0` means that there is no timeout. This is also the
+default.

src/libstore/settings/max-substitution-jobs.md

@@ -0,0 +1,10 @@
+---
+name: max-substitution-jobs
+internalName: maxSubstitutionJobs
+type: unsigned int
+default: 16
+aliases: [substitution-max-jobs]
+---
+This option defines the maximum number of substitution jobs that Nix
+will try to run in parallel. The default is `16`. The minimum value
+one can choose is `1` and lower values will be interpreted as `1`.

src/libstore/settings/min-free-check-interval.md

@@ -0,0 +1,7 @@
+---
+name: min-free-check-interval
+internalName: minFreeCheckInterval
+type: uint64_t
+default: 5
+---
+Number of seconds between checking free disk space.

src/libstore/settings/min-free.md

@@ -0,0 +1,10 @@
+---
+name: min-free
+internalName: minFree
+type: uint64_t
+default: 0
+---
+When free disk space in `/nix/store` drops below `min-free` during a
+build, Lix performs a garbage-collection until `max-free` bytes are
+available or there is no more garbage. A value of `0` (the default)
+disables this feature.

src/libstore/settings/nar-buffer-size.md

@@ -0,0 +1,7 @@
+---
+name: nar-buffer-size
+internalName: narBufferSize
+type: size_t
+default: 33554432 # 32 * 1024 * 1024
+---
+Maximum size of NARs before spilling them to disk.

src/libstore/settings/narinfo-cache-negative-ttl.md

@@ -0,0 +1,10 @@
+---
+name: narinfo-cache-negative-ttl
+internalName: ttlNegativeNarInfoCache
+type: unsigned int
+default: 3600
+---
+The TTL in seconds for negative lookups. If a store path is queried
+from a substituter but was not found, there will be a negative
+lookup cached in the local disk cache database for the specified
+duration.

src/libstore/settings/narinfo-cache-positive-ttl.md

@@ -0,0 +1,14 @@
+---
+name: narinfo-cache-positive-ttl
+internalName: ttlPositiveNarInfoCache
+type: unsigned int
+default: 2592000 # 30 * 24 * 3600
+---
+The TTL in seconds for positive lookups. If a store path is queried
+from a substituter, the result of the query will be cached in the
+local disk cache database including some of the NAR metadata. The
+default TTL is a month, setting a shorter TTL for positive lookups
+can be useful for binary caches that have frequent garbage
+collection, in which case having a more frequent cache invalidation
+would prevent trying to pull the path again and failing with a hash
+mismatch if the build isn't reproducible.

src/libstore/settings/netrc-file.md

@@ -0,0 +1,29 @@
+---
+name: netrc-file
+internalName: netrcFile
+type: std::string
+defaultExpr: 'fmt("%s/%s", nixConfDir, "netrc")'
+defaultText: '`/etc/nix/netrc`'
+---
+If set to an absolute path to a `netrc` file, Lix will use the HTTP
+authentication credentials in this file when trying to download from
+a remote host through HTTP or HTTPS.
+
+The `netrc` file consists of a list of accounts in the following
+format:
+
+    machine my-machine
+    login my-username
+    password my-password
+
+For the exact syntax, see [the `curl`
+documentation](https://ec.haxx.se/usingcurl-netrc.html).
+
+> **Note**
+>
+> This must be an absolute path, and `~` is not resolved. For
+> example, `~/.netrc` won't resolve to your home directory's
+> `.netrc`.
+
+Defaults to `$NIX_CONF_DIR/netrc`.
+The default shown below is only accurate when the value of `NIX_CONF_DIR` has not been overridden at build time or using the environment variable.

src/libstore/settings/plugin-files.md

@@ -0,0 +1,27 @@
+---
+name: plugin-files
+internalName: pluginFiles
+settingType: PluginFilesSetting
+default: []
+---
+A list of plugin files to be loaded by Nix. Each of these files will
+be dlopened by Nix, allowing them to affect execution through static
+initialization. In particular, these plugins may construct static
+instances of RegisterPrimOp to add new primops or constants to the
+expression language, RegisterStoreImplementation to add new store
+implementations, RegisterCommand to add new subcommands to the `nix`
+command, and RegisterSetting to add new nix config settings. See the
+constructors for those types for more details.
+
+Warning! These APIs are inherently unstable and may change from
+release to release.
+
+Since these files are loaded into the same address space as Nix
+itself, they must be DSOs compatible with the instance of Nix
+running at the time (i.e. compiled against the same headers, not
+linked to any incompatible libraries). They should not be linked to
+any Lix libs directly, as those will be available already at load
+time.
+
+If an entry in the list is a directory, all files in the directory
+are loaded as plugins (non-recursively).

src/libstore/settings/post-build-hook.md

@@ -0,0 +1,46 @@
+---
+name: post-build-hook
+internalName: postBuildHook
+type: std::string
+default: ''
+---
+Optional. The path to a program to execute after each build.
+
+This option is only settable in the global `nix.conf`, or on the
+command line by trusted users.
+
+When using the nix-daemon, the daemon executes the hook as `root`.
+If the nix-daemon is not involved, the hook runs as the user
+executing the nix-build.
+
+  - The hook executes after an evaluation-time build.
+
+  - The hook does not execute on substituted paths.
+
+  - The hook's output always goes to the user's terminal.
+
+  - If the hook fails, the build succeeds but no further builds
+    execute.
+
+  - The hook executes synchronously, and blocks other builds from
+    progressing while it runs.
+
+The program executes with no arguments. The program's environment
+contains the following environment variables:
+
+  - `DRV_PATH`
+    The derivation for the built paths.
+
+    Example:
+    `/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv`
+
+  - `OUT_PATHS`
+    Output paths of the built derivation, separated by a space
+    character.
+
+    Example:
+    `/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev
+    /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
+    /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
+    /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
+    /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23`.

src/libstore/settings/pre-build-hook.md

@@ -0,0 +1,20 @@
+---
+name: pre-build-hook
+internalName: preBuildHook
+type: std::string
+default: ''
+---
+If set, the path to a program that can set extra derivation-specific
+settings for this system. This is used for settings that can't be
+captured by the derivation model itself and are too variable between
+different versions of the same system to be hard-coded into nix.
+
+The hook is passed the derivation path and, if sandboxes are
+enabled, the sandbox directory. It can then modify the sandbox and
+send a series of commands to modify various settings to stdout. The
+currently recognized commands are:
+
+  - `extra-sandbox-paths`\
+    Pass a list of files and directories to be included in the
+    sandbox for this build. One entry per line, terminated by an
+    empty line. Entries have the same format as `sandbox-paths`.

src/libstore/settings/print-missing.md

@@ -0,0 +1,7 @@
+---
+name: print-missing
+internalName: printMissing
+type: bool
+default: true
+---
+Whether to print what paths need to be built or downloaded.

src/libstore/settings/require-drop-supplementary-groups.md

@@ -0,0 +1,18 @@
+---
+name: require-drop-supplementary-groups
+internalName: requireDropSupplementaryGroups
+platforms: [linux]
+type: bool
+defaultExpr: 'getuid() == 0'
+defaultText: '*running as root:* `true`, *otherwise:* `false`'
+---
+Following the principle of least privilege,
+Lix will attempt to drop supplementary groups when building with sandboxing.
+
+However this can fail under some circumstances.
+For example, if the user lacks the `CAP_SETGID` capability.
+Search `setgroups(2)` for `EPERM` to find more detailed information on this.
+
+If you encounter such a failure, setting this option to `false` will let you ignore it and continue.
+But before doing so, you should consider the security implications carefully.
+Not dropping supplementary groups means the build sandbox will be less restricted than intended.

src/libstore/settings/require-sigs.md

@@ -0,0 +1,17 @@
+---
+name: require-sigs
+internalName: requireSigs
+type: bool
+default: true
+---
+If set to `true` (the default), any non-content-addressed path added
+or copied to the Nix store (e.g. when substituting from a binary
+cache) must have a signature by a trusted key. A trusted key is one
+listed in `trusted-public-keys`, or a public key counterpart to a
+private key stored in a file listed in `secret-key-files`.
+
+Set to `false` to disable signature checking and trust all
+non-content-addressed paths unconditionally.
+
+(Content-addressed paths are inherently trustworthy and thus
+unaffected by this configuration option.)

src/libstore/settings/run-diff-hook.md

@@ -0,0 +1,11 @@
+---
+name: run-diff-hook
+internalName: runDiffHook
+type: bool
+default: false
+---
+If true, enable the execution of the `diff-hook` program.
+
+When using the Nix daemon, `run-diff-hook` must be set in the
+`nix.conf` configuration file, and cannot be passed at the command
+line.

src/libstore/settings/sandbox-build-dir.md

@@ -0,0 +1,10 @@
+---
+name: sandbox-build-dir
+internalName: sandboxBuildDir
+platforms: [linux]
+type: std::string
+default: /build
+---
+The build directory inside the sandbox.
+
+This directory is backed by [`build-dir`](#conf-build-dir) on the host.

src/libstore/settings/sandbox-dev-shm-size.md

@@ -0,0 +1,11 @@
+---
+name: sandbox-dev-shm-size
+internalName: sandboxShmSize
+platforms: [linux]
+type: std::string
+default: 50%
+---
+This option determines the maximum size of the `tmpfs` filesystem
+mounted on `/dev/shm` in Linux sandboxes. For the format, see the
+description of the `size` option of `tmpfs` in mount(8). The default
+is `50%`.

src/libstore/settings/sandbox-fallback.md

@@ -0,0 +1,7 @@
+---
+name: sandbox-fallback
+internalName: sandboxFallback
+type: bool
+default: true
+---
+Whether to disable sandboxing when the kernel doesn't allow it.

src/libstore/settings/sandbox-paths.md

@@ -0,0 +1,20 @@
+---
+name: sandbox-paths
+internalName: sandboxPaths
+type: PathSet
+default: []
+aliases: [build-chroot-dirs, build-sandbox-paths]
+---
+A list of paths bind-mounted into Nix sandbox environments. You can
+use the syntax `target=source` to mount a path in a different
+location in the sandbox; for instance, `/bin=/nix-bin` will mount
+the path `/nix-bin` as `/bin` inside the sandbox. If *source* is
+followed by `?`, then it is not an error if *source* does not exist;
+for example, `/dev/nvidiactl?` specifies that `/dev/nvidiactl` will
+only be mounted in the sandbox if it exists in the host filesystem.
+
+If the source is in the Nix store, then its closure will be added to
+the sandbox as well.
+
+Depending on how Lix was built, the default value for this option
+may be empty or provide `/bin/sh` as a bind-mount of `bash`.

src/libstore/settings/sandbox.md

@@ -0,0 +1,36 @@
+---
+name: sandbox
+internalName: sandboxMode
+type: SandboxMode
+defaultExpr: |
+  #if __linux__
+    smEnabled
+  #else
+    smDisabled
+  #endif
+defaultText: '*Linux:* `true`, *other platforms:* `false`'
+aliases: [build-use-chroot, build-use-sandbox]
+---
+If set to `true`, builds will be performed in a *sandboxed
+environment*, i.e., they’re isolated from the normal file system
+hierarchy and will only see their dependencies in the Nix store,
+the temporary build directory, private versions of `/proc`,
+`/dev`, `/dev/shm` and `/dev/pts` (on Linux), and the paths
+configured with the `sandbox-paths` option. This is useful to
+prevent undeclared dependencies on files in directories such as
+`/usr/bin`. In addition, on Linux, builds run in private PID,
+mount, network, IPC and UTS namespaces to isolate them from other
+processes in the system (except that fixed-output derivations do
+not run in private network namespace to ensure they can access the
+network).
+
+Currently, sandboxing only work on Linux and macOS. The use of a
+sandbox requires that Lix is run as root (so you should use the
+“build users” feature to perform the actual builds under different
+users than root).
+
+If this option is set to `relaxed`, then fixed-output derivations
+and derivations that have the `__noChroot` attribute set to `true`
+do not run in sandboxes.
+
+The default is `true` on Linux and `false` on all other platforms.

src/libstore/settings/secret-key-files.md

@@ -0,0 +1,11 @@
+---
+name: secret-key-files
+internalName: secretKeyFiles
+type: Strings
+default: []
+---
+A whitespace-separated list of files containing secret (private)
+keys. These are used to sign locally-built paths. They can be
+generated using `nix-store --generate-binary-cache-key`. The
+corresponding public key can be distributed to other users, who
+can add it to `trusted-public-keys` in their `nix.conf`.

src/libstore/settings/ssl-cert-file.md

@@ -0,0 +1,19 @@
+---
+name: ssl-cert-file
+internalName: caFile
+type: Path
+defaultExpr: 'getDefaultSSLCertFile()'
+defaultText: '*machine-specific*'
+---
+The path of a file containing CA certificates used to
+authenticate `https://` downloads. Lix by default will use
+the first of the following files that exists:
+
+1. `/etc/ssl/certs/ca-certificates.crt`
+2. `/nix/var/nix/profiles/default/etc/ssl/certs/ca-bundle.crt`
+
+The path can be overridden by the following environment
+variables, in order of precedence:
+
+1. `NIX_SSL_CERT_FILE`
+2. `SSL_CERT_FILE`

src/libstore/settings/start-id.md

@@ -0,0 +1,14 @@
+---
+name: start-id
+internalName: startId
+type: uint32_t
+defaultExpr: |
+  #if __linux__
+    0x34000000
+  #else
+    56930
+  #endif
+defaultText: '*Linux:* `872415232`, *other platforms:* `56930`'
+experimentalFeature: auto-allocate-uids
+---
+The first UID and GID to use for dynamic ID allocation.

src/libstore/settings/store.md

@@ -0,0 +1,11 @@
+---
+name: store
+internalName: storeUri
+type: std::string
+defaultExpr: 'getEnv("NIX_REMOTE").value_or("auto")'
+defaultText: '`auto`'
+---
+The [URL of the Nix store](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format)
+to use for most operations.
+See [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md)
+for supported store types and settings.

src/libstore/settings/substitute.md

@@ -0,0 +1,10 @@
+---
+name: substitute
+internalName: useSubstitutes
+type: bool
+default: true
+aliases: [build-use-substitutes]
+---
+If set to `true` (default), Lix will use binary substitutes if
+available. This option can be disabled to force building from
+source.

src/libstore/settings/substituters.md

@@ -0,0 +1,20 @@
+---
+name: substituters
+internalName: substituters
+type: Strings
+default: [https://cache.nixos.org/]
+aliases: [binary-caches]
+---
+A list of [URLs of Nix stores](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format) to be used as substituters, separated by whitespace.
+A substituter is an additional [store](@docroot@/glossary.md#gloss-store) from which Lix can obtain [store objects](@docroot@/glossary.md#gloss-store-object) instead of building them.
+
+Substituters are tried based on their priority value, which each substituter can set independently.
+Lower value means higher priority.
+The default is `https://cache.nixos.org`, which has a priority of 40.
+
+At least one of the following conditions must be met for Lix to use a substituter:
+
+- The substituter is in the [`trusted-substituters`](#conf-trusted-substituters) list
+- The user calling Lix is in the [`trusted-users`](#conf-trusted-users) list
+
+In addition, each store path should be trusted as described in [`trusted-public-keys`](#conf-trusted-public-keys)