lix-project/lix
20
57
Fork 31
Code Issues 349 Code Review (Gerrit) Projects 3 Releases Wiki Activity

treewide: generate global settings from data

Browse source 
Change-Id: If048b73a55d42522827eb9c140a066ba061e957c
This commit is contained in:
alois31 2024-08-05 19:18:43 +02:00
parent 21fc0ddce5
commit 2e0c1a5ea9
Signed by: alois31
GPG key ID: E0F59EA5E5216914
128 changed files with 2103 additions and 1473 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
doc/manual/meson.build
View file

@ -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',

24
doc/manual/src/command-ref/meson.build
View file

@ -31,17 +31,23 @@ nix3_cli_files = custom_target(
conf_file_md = custom_target(
command : [
nix_eval_for_docs,
'--expr',
'(import @INPUT0@).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile @INPUT1@))',
python.full_path(),
'@SOURCE_ROOT@/src/code-generation/build_settings.py',
'--kernel', host_machine.system(),
'--docs', '@OUTPUT@',
'--experimental-features', '@SOURCE_ROOT@/src/libutil/experimental-features',
'@INPUT@',
],
capture : true,
input : [
'../../utils.nix',
conf_file_json,
experimental_features_shortlist_md,
deprecated_features_shortlist_md,
libexpr_setting_definitions,
libfetchers_setting_definitions,
file_transfer_setting_definitions,
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,
)

38
doc/manual/src/contributing/hacking.md
View file

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

141
src/code-generation/build_settings.py Normal file
View file

@ -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()

12
src/code-generation/common.py
View file

@ -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++')

215
src/libexpr/eval-settings.hh
View file

@ -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"(
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.
)"};
#include "libexpr-settings.gen.inc"
/**
* 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;

34
src/libexpr/meson.build
View file

@ -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

11
src/libexpr/settings/allow-import-from-derivation.md Normal file
View file

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

21
src/libexpr/settings/allow-unsafe-native-code-during-evaluation.md Normal file
View file

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

10
src/libexpr/settings/allowed-uris.md Normal file
View file

@ -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`.

12
src/libexpr/settings/debugger-on-trace.md Normal file
View file

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

7
src/libexpr/settings/eval-cache.md Normal file
View file

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

15
src/libexpr/settings/eval-system.md Normal file
View file

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

8
src/libexpr/settings/ignore-try.md Normal file
View file

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

7
src/libexpr/settings/max-call-depth.md Normal file
View file

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

11
src/libexpr/settings/nix-path.md Normal file
View file

@ -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).

19
src/libexpr/settings/pure-eval.md Normal file
View file

@ -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>)

86
src/libexpr/settings/repl-overlays.md Normal file
View file

@ -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
```

11
src/libexpr/settings/restrict-eval.md Normal file
View file

@ -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`.

20
src/libexpr/settings/trace-function-calls.md Normal file
View file

@ -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`.

7
src/libexpr/settings/trace-verbose.md Normal file
View file

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

99
src/libfetchers/fetch-settings.hh
View file

@ -20,104 +20,7 @@ struct FetchSettings : public Config
{
FetchSettings();
Setting<StringMap> accessTokens{this, {}, "access-tokens",
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};
#include "libfetchers-settings.gen.inc"
};
// FIXME: don't use a global variable.

27
src/libfetchers/meson.build
View file

@ -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

22
src/libfetchers/settings/accept-flake-config.md Normal file
View file

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

51
src/libfetchers/settings/access-tokens.md Normal file
View file

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

7
src/libfetchers/settings/allow-dirty.md Normal file
View file

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

9
src/libfetchers/settings/commit-lockfile-summary.md Normal file
View file

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

13
src/libfetchers/settings/flake-registry.md Normal file
View file

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

8
src/libfetchers/settings/use-registries.md Normal file
View file

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

7
src/libfetchers/settings/warn-dirty.md Normal file
View file

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

9
src/libstore/file-transfer-settings/connect-timeout.md Normal file
View file

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

7
src/libstore/file-transfer-settings/download-attempts.md Normal file
View file

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

10
src/libstore/file-transfer-settings/http-connections.md Normal file
View file

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

7
src/libstore/file-transfer-settings/http2.md Normal file
View file

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

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

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

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

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

34
src/libstore/filetransfer.hh
View file

@ -15,39 +15,7 @@ namespace nix {
struct FileTransferSettings : Config
{
Setting<bool> enableHttp2{this, true, "http2",
"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."};
#include "file-transfer-settings.gen.inc"
};
extern FileTransferSettings fileTransferSettings;

982
src/libstore/globals.hh
View file

File diff suppressed because it is too large Load diff

119
src/libstore/meson.build
View file

@ -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

14
src/libstore/settings/allow-symlinked-store.md Normal file
View file

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

7
src/libstore/settings/allowed-impure-host-deps.md Normal file
View file

@ -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).

9
src/libstore/settings/always-allow-substitutes.md Normal file
View file

@ -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).

11
src/libstore/settings/auto-allocate-uids.md Normal file
View file

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

11
src/libstore/settings/auto-optimise-store.md Normal file
View file

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

14
src/libstore/settings/build-dir.md Normal file
View file

@ -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).

14
src/libstore/settings/build-hook.md Normal file
View file

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

7
src/libstore/settings/build-poll-interval.md Normal file
View file

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

43
src/libstore/settings/build-users-group.md Normal file
View file

@ -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

13
src/libstore/settings/builders-use-substitutes.md Normal file
View file

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

12
src/libstore/settings/builders.md Normal file
View file

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

10
src/libstore/settings/compress-build-log.md Normal file
View file

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

16
src/libstore/settings/cores.md Normal file
View file

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

8
src/libstore/settings/darwin-log-sandbox-violations.md Normal file
View file

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

32
src/libstore/settings/diff-hook.md Normal file
View file

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

8
src/libstore/settings/download-speed.md Normal file
View file

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

10
src/libstore/settings/enable-core-dumps.md Normal file
View file

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

21
src/libstore/settings/extra-platforms.md Normal file
View file

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

10
src/libstore/settings/fallback.md Normal file
View file

@ -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`.

10
src/libstore/settings/fsync-metadata.md Normal file
View file

@ -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`.

7
src/libstore/settings/gc-reserved-space.md Normal file
View file

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

23
src/libstore/settings/hashed-mirrors.md Normal file
View file

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

14
src/libstore/settings/id-count.md Normal file
View file

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

11
src/libstore/settings/ignored-acls.md Normal file
View file

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

9
src/libstore/settings/impersonate-linux-26.md Normal file
View file

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

11
src/libstore/settings/keep-build-log.md Normal file
View file

@ -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`.

17
src/libstore/settings/keep-derivations.md Normal file
View file

@ -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).

22
src/libstore/settings/keep-env-derivations.md Normal file
View file

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

7
src/libstore/settings/keep-failed.md Normal file
View file

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

7
src/libstore/settings/keep-going.md Normal file
View file

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

17
src/libstore/settings/keep-outputs.md Normal file
View file

@ -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`.

7
src/libstore/settings/log-lines.md Normal file
View file

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

10
src/libstore/settings/max-build-log-size.md Normal file
View file

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

13
src/libstore/settings/max-free.md Normal file
View file

@ -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).

14
src/libstore/settings/max-jobs.md Normal file
View file

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

16
src/libstore/settings/max-silent-time.md Normal file
View file

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

10
src/libstore/settings/max-substitution-jobs.md Normal file
View file

@ -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`.

7
src/libstore/settings/min-free-check-interval.md Normal file
View file

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

10
src/libstore/settings/min-free.md Normal file
View file

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

7
src/libstore/settings/nar-buffer-size.md Normal file
View file

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

10
src/libstore/settings/narinfo-cache-negative-ttl.md Normal file
View file

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

14
src/libstore/settings/narinfo-cache-positive-ttl.md Normal file
View file

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

29
src/libstore/settings/netrc-file.md Normal file
View file

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

27
src/libstore/settings/plugin-files.md Normal file
View file

@ -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).

46
src/libstore/settings/post-build-hook.md Normal file
View file

@ -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`.

20
src/libstore/settings/pre-build-hook.md Normal file
View file

@ -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`.

7
src/libstore/settings/print-missing.md Normal file
View file

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

18
src/libstore/settings/require-drop-supplementary-groups.md Normal file
View file

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

17
src/libstore/settings/require-sigs.md Normal file
View file

@ -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.)

11
src/libstore/settings/run-diff-hook.md Normal file
View file

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

10
src/libstore/settings/sandbox-build-dir.md Normal file
View file

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

11
src/libstore/settings/sandbox-dev-shm-size.md Normal file
View file

@ -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%`.

7
src/libstore/settings/sandbox-fallback.md Normal file
View file

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

20
src/libstore/settings/sandbox-paths.md Normal file
View file

@ -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`.

36
src/libstore/settings/sandbox.md Normal file
View file

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

11
src/libstore/settings/secret-key-files.md Normal file
View file

@ -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`.

19
src/libstore/settings/ssl-cert-file.md Normal file
View file

@ -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`

14
src/libstore/settings/start-id.md Normal file
View file

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

11
src/libstore/settings/store.md Normal file
View file

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

10
src/libstore/settings/substitute.md Normal file
View file

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

20
src/libstore/settings/substituters.md Normal file
View file

@ -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)

Some files were not shown because too many files have changed in this diff Show more