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

Merge changes I7b4379a9,If048b73a,I4c802052 into main

Browse source 
* changes:
  libexpr: generate builtins from data
  treewide: generate global settings from data
  libutil: generate experimental and deprecated features from data
This commit is contained in:
alois31 2024-11-10 10:19:05 +00:00 committed by Gerrit Code Review
parent efb04754be c1746300a9
commit 27af6989bb
283 changed files with 4762 additions and 4112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored
View file

@ -37,5 +37,5 @@ buildtime.bin
# Rust build files when using Cargo (not actually supported for building but it spews the files anyway)
/target/
# Python compiled files from the test suite
# Python compiled files from the code generators and test suite
*.pyc

14
doc/manual/generate-features-shortlist.nix
View file

@ -1,14 +0,0 @@
# Usually "experimental" or "deprecated"
kind:
# "xp" or "dp"
kindShort:
with builtins;
with import ./utils.nix;
let
showExperimentalFeature = name: doc: ''
- [`${name}`](@docroot@/contributing/${kind}-features.md#${kindShort}-feature-${name})
'';
in
xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))

18
doc/manual/generate-features.nix
View file

@ -1,18 +0,0 @@
# Usually "experimental" or "deprecated"
_kind:
# "xp" or "dp"
kindShort:
with builtins;
with import ./utils.nix;
let
showFeature =
name: doc:
squash ''
## [`${name}`]{#${kindShort}-feature-${name}}
${doc}
'';
in
xps: (concatStringsSep "\n" (attrValues (mapAttrs showFeature xps)))

56
doc/manual/meson.build
View file

@ -15,56 +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',
)
nix_exp_features_json = custom_target(
command : [ nix, '__dump-xp-features' ],
capture : true,
output : 'xp-features.json',
# FIXME: put the actual lib targets in here? meson have introspection challenge 2024 though.
build_always_stale : true,
)
language_json = custom_target(
command: [nix, '__dump-language'],
output : 'language.json',
capture : true,
env : nix_env_for_docs,
# FIXME: put the actual lib targets in here? meson have introspection challenge 2024 though.
build_always_stale : true,
)
nix3_cli_json = custom_target(
command : [ nix, '__dump-cli' ],
capture : true,
@ -78,12 +28,8 @@ generate_manual_deps = files(
'generate-deps.py',
)
# Generates builtins.md and builtin-constants.md.
subdir('src/language')
# Generates new-cli pages, {experimental,deprecated}-features-shortlist.md, and conf-file.md.
# Generates new-cli pages and conf-file.md.
subdir('src/command-ref')
# Generates {experimental,deprecated}-feature-descriptions.md.
subdir('src/contributing')
# Generates rl-next-generated.md.
subdir('src/release-notes')

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

@ -1,37 +1,3 @@
experimental_features_shortlist_md = custom_target(
command : nix_eval_for_docs + [
'--expr',
'import @INPUT0@ "experimental" "xp" (builtins.fromJSON (builtins.readFile @INPUT1@))',
],
input : [
'../../generate-features-shortlist.nix',
nix_exp_features_json,
],
capture : true,
output : 'experimental-features-shortlist.md',
env : nix_env_for_docs,
)
dp_features_json = custom_target(
command : [nix, '__dump-dp-features'],
capture : true,
output : 'dp-features.json',
)
deprecated_features_shortlist_md = custom_target(
command : nix_eval_for_docs + [
'--expr',
'import @INPUT0@ "deprecated" "dp" (builtins.fromJSON (builtins.readFile @INPUT1@))',
],
input : [
'../../generate-features-shortlist.nix',
dp_features_json,
],
capture : true,
output : 'deprecated-features-shortlist.md',
env : nix_env_for_docs,
)
# Intermediate step for manpage generation.
# This splorks the output of generate-manpage.nix as JSON,
# which gets written as a directory tree below.
@ -65,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,
)

2
doc/manual/src/contributing/deprecated-features.md
View file

@ -34,4 +34,4 @@ However, we do not live in such an ideal world, and currently this goal is so fa
# Currently available deprecated features
{{#include @generated@/contributing/deprecated-feature-descriptions.md}}
{{#include @generated@/../../../src/libutil/deprecated-feature-descriptions.md}}

2
doc/manual/src/contributing/experimental-features.md
View file

@ -99,4 +99,4 @@ This means that experimental features and RFCs are orthogonal mechanisms, and ca
# Currently available experimental features
{{#include @generated@/contributing/experimental-feature-descriptions.md}}
{{#include @generated@/../../../src/libutil/experimental-feature-descriptions.md}}

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

@ -399,3 +399,76 @@ 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, global settings, or builtins
Experimental and deprecated features, global settings, and builtins 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.
### 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.
### Builtin functions
The following metadata properties are supported for builtin functions:
* `name` (required): the language-facing name (as a member of the `builtins` attribute set) of the function.
* `implementation` (optional): a C++ expression specifying the implementation of the builtin.
It must be a function of signature `void(EvalState &, PosIdx, Value * *, Value &)`.
If not specified, defaults to `prim_${name}`.
* `renameInGlobalScope` (optional): whether the definiton should be "hidden" in the global scope by prefixing its name with two underscores.
If not specified, defaults to `true`.
* `args` (required): list containing the names of the arguments, as shown in the documentation.
All arguments must be listed here since the function arity is derived as the length of this list.
* `experimental_feature` (optional): the user-facing name of the experimental feature which needs to be enabled for the bultin function to be available.
If not specified, no experimental feature is required.
New builtin function definition files must be added to `src/libexpr/builtins` and registered in the `builtin_definitions` list in `src/libexpr/meson.build`.
### Builtin constants
The following metadata properties are supported for builtin constants:
* `name` (required): the language-facing name (as a member of the `builtins` attribute set) of the constant.
* `type` (required): the Nix language type of the constant; the C++ type is automatically derived.
* `constructorArgs` (optional): list of strings containing C++ expressions passed as arguments to the appropriate `Value` constructor.
If the value computation is more complex, `implementation` can be used instead.
* `implementation` (required if `constructorArgs` is not specified): string containing a C++ expressing computing the value of the constant.
* `impure` (optional): whether the constant is considered impure.
Impure constants are not available when pure evaluation mode is activated.
Defaults to `false` when not specified.
New builtin constant definition files must be added to `src/libexpr/builtin-constants` and registered in the `builtin_constant_definitions` list in `src/libexpr/meson.build`.

28
doc/manual/src/contributing/meson.build
View file

@ -1,28 +0,0 @@
# Intermediate step for experimental-feature-descriptions.md.
# This splorks the output of generate-xp-features.nix as JSON,
# which gets written as a directory tree below.
experimental_feature_descriptions_md = custom_target(
command : nix_eval_for_docs + [
'--expr',
'import @INPUT0@ "experimental" "xp" (builtins.fromJSON (builtins.readFile @INPUT1@))',
],
input : [
'../../generate-features.nix',
nix_exp_features_json,
],
capture : true,
output : 'experimental-feature-descriptions.md',
)
deprecated_feature_descriptions_md = custom_target(
command : nix_eval_for_docs + [
'--expr',
'import @INPUT0@ "deprecated" "dp" (builtins.fromJSON (builtins.readFile @INPUT1@))',
],
input : [
'../../generate-features.nix',
dp_features_json,
],
capture : true,
output : 'deprecated-feature-descriptions.md',
)

2
doc/manual/src/language/builtin-constants.md
View file

@ -4,7 +4,7 @@ These constants are built into the Nix language evaluator:
<dl>
{{#include @generated@/language/builtin-constants.md}}
{{#include @generated@/../../../src/libexpr/builtin-constants.md}}
</dl>

2
doc/manual/src/language/builtins.md
View file

@ -15,6 +15,6 @@ For convenience, some built-ins can be accessed directly:
<dd><p><var>derivation</var> is described in
<a href="derivations.md">its own section</a>.</p></dd>
{{#include @generated@/language/builtins.md}}
{{#include @generated@/../../../src/libexpr/builtins.md}}
</dl>

27
doc/manual/src/language/meson.build
View file

@ -1,27 +0,0 @@
builtins_md = custom_target(
command : nix_eval_for_docs + [
'--expr',
'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@)).builtins',
],
capture : true,
input : [
'../../generate-builtins.nix',
language_json,
],
output : 'builtins.md',
env : nix_env_for_docs,
)
builtin_constants_md = custom_target(
command : nix_eval_for_docs + [
'--expr',
'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@)).constants',
],
capture : true,
input : [
'../../generate-builtin-constants.nix',
language_json,
],
output : 'builtin-constants.md',
env : nix_env_for_docs,
)

3
meson/clang-tidy/build_required_targets.py
View file

@ -14,7 +14,8 @@ def main():
args = ap.parse_args()
targets = [t for t in get_targets_of_rule(args.build_root, 'CUSTOM_COMMAND') if t.endswith('gen.hh')]
targets = [t for t in get_targets_of_rule(args.build_root, 'CUSTOM_COMMAND') if t.endswith('.gen.hh')]
targets += [t for t in get_targets_of_rule(args.build_root, 'CUSTOM_COMMAND') if t.endswith('.gen.inc')]
ninja_build(args.build_root, targets)
if __name__ == '__main__':

2
package.nix
View file

@ -245,9 +245,11 @@ stdenv.mkDerivation (finalAttrs: {
nativeBuildInputs =
[
# python3.withPackages does not splice properly, see https://github.com/NixOS/nixpkgs/issues/305858
(python3.pythonOnBuildForHost.withPackages (p: [
p.pytest
p.pytest-xdist
p.python-frontmatter
]))
meson
ninja

93
src/code-generation/build_builtin_constants.py Normal file
View file

@ -0,0 +1,93 @@
from typing import List, NamedTuple
from common import cxx_literal, generate_file, load_data
KNOWN_KEYS = set([
'name',
'type',
'constructorArgs',
'implementation',
'impure',
'renameInGlobalScope',
])
class BuiltinConstant(NamedTuple):
name: str
type: str
implementation: str
impure: bool
rename_in_global_scope: bool
documentation: str
def parse(datum):
unknown_keys = set(datum.keys()) - KNOWN_KEYS
if unknown_keys:
raise Exception('unknown keys', unknown_keys)
return BuiltinConstant(
name = datum['name'],
type = datum['type'],
implementation = ('{' + ', '.join([f'NewValueAs::{datum["type"]}', *datum['constructorArgs']]) + '}') if 'constructorArgs' in datum else datum['implementation'],
impure = datum.get('impure', False),
rename_in_global_scope = datum.get('renameInGlobalScope', True),
documentation = datum.content,
)
VALUE_TYPES = {
'attrs': 'nAttrs',
'boolean': 'nBool',
'integer': 'nInt',
'list': 'nList',
'null': 'nNull',
'string': 'nString',
}
HUMAN_TYPES = {
'attrs': 'set',
'boolean': 'Boolean',
'integer': 'integer',
'list': 'list',
'null': 'null',
'string': 'string',
}
def main():
import argparse
ap = argparse.ArgumentParser()
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('defs', help='Builtin definition files', nargs='+')
args = ap.parse_args()
builtin_constants = load_data(args.defs, BuiltinConstant.parse)
generate_file(args.header, builtin_constants, lambda constant:
# `builtins` is magic and must come first
'' if constant.name == 'builtins' else constant.name,
lambda constant:
f'''{'if (!evalSettings.pureEval) ' if constant.impure else ''}{{
addConstant({cxx_literal(('__' if constant.rename_in_global_scope else '') + constant.name)}, {constant.implementation}, {{
.type = {VALUE_TYPES[constant.type]},
.doc = {cxx_literal(constant.documentation)},
.impureOnly = {cxx_literal(constant.impure)},
}});
}}
''')
generate_file(args.docs, builtin_constants, lambda constant: constant.name, lambda constant:
f'''<dt id="builtins-{constant.name}">
<a href="#builtins-{constant.name}"><code>{constant.name}</code></a> ({HUMAN_TYPES[constant.type]})
</dt>
<dd>
{constant.documentation}
''' + ('''> **Note**
>
> Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
''' if constant.impure else '') + '''</dd>
''')
if __name__ == '__main__':
main()

82
src/code-generation/build_builtins.py Normal file
View file

@ -0,0 +1,82 @@
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',
'implementation',
'renameInGlobalScope',
'args',
'experimentalFeature',
])
class Builtin(NamedTuple):
name: str
implementation: str
rename_in_global_scope: bool
args: List[str]
experimental_feature: Optional[str]
documentation: str
def parse(datum):
unknown_keys = set(datum.keys()) - KNOWN_KEYS
if unknown_keys:
raise Exception('unknown keys', unknown_keys)
return Builtin(
name = datum['name'],
implementation = datum['implementation'] if 'implementation' in datum else f'prim_{datum["name"]}',
rename_in_global_scope = datum.get('renameInGlobalScope', True),
args = datum['args'],
experimental_feature = datum.get('experimentalFeature', None),
documentation = datum.content,
)
def main():
import argparse
ap = argparse.ArgumentParser()
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='Builtin definition files', nargs='+')
args = ap.parse_args()
builtins = load_data(args.defs, Builtin.parse)
experimental_feature_names = set([builtin.experimental_feature for (_, builtin) in builtins])
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, builtins, lambda builtin: builtin.name, lambda builtin:
f'''{'' if builtin.experimental_feature is None else f'if (experimentalFeatureSettings.isEnabled({experimental_features[builtin.experimental_feature]})) '}{{
addPrimOp({{
.name = {cxx_literal(('__' if builtin.rename_in_global_scope else '') + builtin.name)},
.args = {cxx_literal(builtin.args)},
.arity = {len(builtin.args)},
.doc = {cxx_literal(builtin.documentation)},
.fun = {builtin.implementation},
.experimentalFeature = {experimental_features[builtin.experimental_feature]},
}});
}}
''')
generate_file(args.docs, builtins, lambda builtin: builtin.name, lambda builtin:
f'''<dt id="builtins-{builtin.name}">
<a href="#builtins-{builtin.name}"><code>{builtin.name} {' '.join([f'<var>{arg}</var>' for arg in builtin.args])}</code></a>
</dt>
<dd>
{builtin.documentation}
''' + (f'''This function is only available if the [{builtin.experimental_feature}](@docroot@/contributing/experimental-features.md#xp-feature-{builtin.experimental_feature}) experimental feature is enabled.
''' if builtin.experimental_feature is not None else '') + '''</dd>
''')
if __name__ == '__main__':
main()

58
src/code-generation/build_experimental_features.py Normal file
View file

@ -0,0 +1,58 @@
from typing import NamedTuple
from common import cxx_literal, generate_file, load_data
KNOWN_KEYS = set([
'name',
'internalName',
])
class ExperimentalFeature(NamedTuple):
name: str
internal_name: str
description: str
def parse(datum):
unknown_keys = set(datum.keys()) - KNOWN_KEYS
if unknown_keys:
raise ValueError('unknown keys', unknown_keys)
return ExperimentalFeature(
name = datum['name'],
internal_name = datum['internalName'],
description = datum.content,
)
def main():
import argparse
ap = argparse.ArgumentParser()
ap.add_argument('--deprecated', action='store_true', help='Generate deprecated features')
ap.add_argument('--header', help='Path of the declaration header to generate')
ap.add_argument('--impl-header', help='Path of the implementation header to generate')
ap.add_argument('--descriptions', help='Path of the description file to generate')
ap.add_argument('--shortlist', help='Path of the shortlist file to generate')
ap.add_argument('defs', help='Experimental feature definition files', nargs='+')
args = ap.parse_args()
features = load_data(args.defs, ExperimentalFeature.parse)
generate_file(args.header, features, lambda feature: feature.name, lambda feature:
f' {feature.internal_name},\n')
generate_file(args.impl_header, features, lambda feature: feature.name, lambda feature:
f''' {{
.tag = {"Dep" if args.deprecated else "Xp"}::{feature.internal_name},
.name = {cxx_literal(feature.name)},
.description = {cxx_literal(feature.description)},
}},
''')
generate_file(args.descriptions, features, lambda feature: feature.name, lambda feature:
f'''## [`{feature.name}`]{{#{"dp" if args.deprecated else "xp"}-feature-{feature.name}}}
{feature.description}
''')
generate_file(args.shortlist, features, lambda feature: feature.name, lambda feature:
f' - [`{feature.name}`](@docroot@/contributing/{"deprecated" if args.deprecated else "experimental"}-features.md#{"dp" if args.deprecated else "xp"}-feature-{feature.name})\n')
if __name__ == '__main__':
main()

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

60
src/code-generation/common.py Normal file
View file

@ -0,0 +1,60 @@
import frontmatter
import pathlib
from collections import defaultdict
def cxx_escape_character(c):
if ord(c) >= 0x20 and ord(c) < 0x7f and c != '"' and c != '?' and c != '\\':
return c
elif c == '\t':
return r'\t'
elif c == '\n':
return r'\n'
elif c == '\r':
return r'\r'
elif c == '"':
return r'\"'
elif c == '?':
return r'\?'
elif c == '\\':
return r'\\'
elif ord(c) <= 0xffff:
return str.format(r'\u{:04x}', ord(c))
else:
return str.format(r'\U{:08x}', ord(c))
def cxx_literal(v):
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++')
def load_data(defs, parse_function):
data = []
for path in defs:
try:
datum = frontmatter.load(path)
data.append((path, parse_function(datum)))
except Exception as e:
e.add_note(f'in {path}')
raise
return data
def generate_file(path, data, sort_key_function, generate_function):
if path is not None:
with open(path, 'w') as out:
for path, datum in sorted(data, key=lambda pathAndDatum: sort_key_function(pathAndDatum[1])):
try:
out.write(generate_function(datum))
except Exception as e:
e.add_note(f'in {path}')
raise

14
src/libexpr/builtin-constants/builtins.md Normal file
View file

@ -0,0 +1,14 @@
---
name: builtins
type: attrs
constructorArgs: [buildBindings(128).finish()]
renameInGlobalScope: false
---
Contains all the [built-in functions](@docroot@/language/builtins.md) and values.
Since built-in functions were added over time, [testing for attributes](./operators.md#has-attribute) in `builtins` can be used for graceful fallback on older Nix installations:
```nix
# if hasContext is not available, we assume `s` has a context
if builtins ? hasContext then builtins.hasContext s else true
```

27
src/libexpr/builtin-constants/currentSystem.md Normal file
View file

@ -0,0 +1,27 @@
---
name: currentSystem
type: string
constructorArgs: [evalSettings.getCurrentSystem()]
impure: true
---
The value of the
[`eval-system`](@docroot@/command-ref/conf-file.md#conf-eval-system)
or else
[`system`](@docroot@/command-ref/conf-file.md#conf-system)
configuration option.
It can be used to set the `system` attribute for [`builtins.derivation`](@docroot@/language/derivations.md) such that the resulting derivation can be built on the same system that evaluates the Nix expression:
```nix
builtins.derivation {
# ...
system = builtins.currentSystem;
}
```
It can be overridden in order to create derivations for different system than the current one:
```console
$ nix-instantiate --system "mips64-linux" --eval --expr 'builtins.currentSystem'
"mips64-linux"
```

23
src/libexpr/builtin-constants/currentTime.md Normal file
View file

@ -0,0 +1,23 @@
---
name: currentTime
type: integer
constructorArgs: ['NixInt{time(0)}']
impure: true
---
Return the [Unix time](https://en.wikipedia.org/wiki/Unix_time) at first evaluation.
Repeated references to that name will re-use the initially obtained value.
Example:
```console
$ nix repl
Welcome to Nix 2.15.1 Type :? for help.
nix-repl> builtins.currentTime
1683705525
nix-repl> builtins.currentTime
1683705525
```
The [store path](@docroot@/glossary.md#gloss-store-path) of a derivation depending on `currentTime` will differ for each evaluation, unless both evaluate `builtins.currentTime` in the same second.

19
src/libexpr/builtin-constants/false.md Normal file
View file

@ -0,0 +1,19 @@
---
name: 'false'
type: boolean
constructorArgs: ['false']
renameInGlobalScope: false
---
Primitive value.
It can be returned by
[comparison operators](@docroot@/language/operators.md#Comparison)
and used in
[conditional expressions](@docroot@/language/constructs.md#Conditionals).
The name `false` is not special, and can be shadowed:
```nix-repl
nix-repl> let false = 1; in false
1
```

15
src/libexpr/builtin-constants/langVersion.md Normal file
View file

@ -0,0 +1,15 @@
---
name: langVersion
type: integer
constructorArgs: ['NixInt{6}']
---
The legacy version of the Nix language. Always is `6` on Lix,
matching Nix 2.18.
Code in the Nix language should use other means of feature detection
like detecting the presence of builtins, rather than trying to find
the version of the Nix implementation, as there may be other Nix
implementations with different feature combinations.
If the feature you want to write compatibility code for cannot be
detected by any means, please file a Lix bug.

21
src/libexpr/builtin-constants/nixPath.md Normal file
View file

@ -0,0 +1,21 @@
---
name: nixPath
type: list
implementation: getNixPath(*this, searchPath)
---
The search path used to resolve angle bracket path lookups.
Angle bracket expressions can be
[desugared](https://en.wikipedia.org/wiki/Syntactic_sugar)
using this and
[`builtins.findFile`](./builtins.html#builtins-findFile):
```nix
<nixpkgs>
```
is equivalent to:
```nix
builtins.findFile builtins.nixPath "nixpkgs"
```

14
src/libexpr/builtin-constants/nixVersion.md Normal file
View file

@ -0,0 +1,14 @@
---
name: nixVersion
type: string
constructorArgs: ['"2.18.3-lix"']
---
Legacy version of Nix. Always returns "2.18.3-lix" on Lix.
Code in the Nix language should use other means of feature detection
like detecting the presence of builtins, rather than trying to find
the version of the Nix implementation, as there may be other Nix
implementations with different feature combinations.
If the feature you want to write compatibility code for cannot be
detected by any means, please file a Lix bug.

14
src/libexpr/builtin-constants/null.md Normal file
View file

@ -0,0 +1,14 @@
---
name: 'null'
type: 'null'
constructorArgs: []
renameInGlobalScope: false
---
Primitive value.
The name `null` is not special, and can be shadowed:
```nix-repl
nix-repl> let null = 1; in null
1
```

13
src/libexpr/builtin-constants/storeDir.md Normal file
View file

@ -0,0 +1,13 @@
---
name: storeDir
type: string
constructorArgs: [store->storeDir]
---
Logical file system location of the [Nix store](@docroot@/glossary.md#gloss-store) currently in use.
This value is determined by the `store` parameter in [Store URLs](@docroot@/command-ref/new-cli/nix3-help-stores.md):
```shell-session
$ nix-instantiate --store 'dummy://?store=/blah' --eval --expr builtins.storeDir
"/blah"
```

19
src/libexpr/builtin-constants/true.md Normal file
View file

@ -0,0 +1,19 @@
---
name: 'true'
type: boolean
constructorArgs: ['true']
renameInGlobalScope: false
---
Primitive value.
It can be returned by
[comparison operators](@docroot@/language/operators.md#Comparison)
and used in
[conditional expressions](@docroot@/language/constructs.md#Conditionals).
The name `true` is not special, and can be shadowed:
```nix-repl
nix-repl> let true = 1; in true
1
```

6
src/libexpr/builtins/abort.md Normal file
View file

@ -0,0 +1,6 @@
---
name: abort
args: [s]
renameInGlobalScope: false
---
Abort Nix expression evaluation and print the error message *s*.

5
src/libexpr/builtins/add.md Normal file
View file

@ -0,0 +1,5 @@
---
name: add
args: [e1, e2]
---
Return the sum of the numbers *e1* and *e2*.

12
src/libexpr/builtins/addDrvOutputDependencies.md Normal file
View file

@ -0,0 +1,12 @@
---
name: addDrvOutputDependencies
args: [s]
---
Create a copy of the given string where a single constant string context element is turned into a "derivation deep" string context element.
The store path that is the constant string context element should point to a valid derivation, and end in `.drv`.
The original string context element must not be empty or have multiple elements, and it must not have any other type of element other than a constant or derivation deep element.
The latter is supported so this function is idempotent.
This is the opposite of [`builtins.unsafeDiscardOutputDependency`](#builtins-unsafeDiscardOutputDependency).

6
src/libexpr/builtins/all.md Normal file
View file

@ -0,0 +1,6 @@
---
name: all
args: [pred, list]
---
Return `true` if the function *pred* returns `true` for all elements
of *list*, and `false` otherwise.

6
src/libexpr/builtins/any.md Normal file
View file

@ -0,0 +1,6 @@
---
name: any
args: [pred, list]
---
Return `true` if the function *pred* returns `true` for at least one
element of *list*, and `false` otherwise.

7
src/libexpr/builtins/attrNames.md Normal file
View file

@ -0,0 +1,7 @@
---
name: attrNames
args: [set]
---
Return the names of the attributes in the set *set* in an
alphabetically sorted list. For instance, `builtins.attrNames { y
= 1; x = "foo"; }` evaluates to `[ "x" "y" ]`.

6
src/libexpr/builtins/attrValues.md Normal file
View file

@ -0,0 +1,6 @@
---
name: attrValues
args: [set]
---
Return the values of the attributes in the set *set* in the order
corresponding to the sorted attribute names.

8
src/libexpr/builtins/baseNameOf.md Normal file
View file

@ -0,0 +1,8 @@
---
name: baseNameOf
args: [s]
renameInGlobalScope: false
---
Return the *base name* of the string *s*, that is, everything
following the final slash in the string. This is similar to the GNU
`basename` command.

5
src/libexpr/builtins/bitAnd.md Normal file
View file

@ -0,0 +1,5 @@
---
name: bitAnd
args: [e1, e2]
---
Return the bitwise AND of the integers *e1* and *e2*.

5
src/libexpr/builtins/bitOr.md Normal file
View file

@ -0,0 +1,5 @@
---
name: bitOr
args: [e1, e2]
---
Return the bitwise OR of the integers *e1* and *e2*.

5
src/libexpr/builtins/bitXor.md Normal file
View file

@ -0,0 +1,5 @@
---
name: bitXor
args: [e1, e2]
---
Return the bitwise XOR of the integers *e1* and *e2*.

7
src/libexpr/builtins/break.md Normal file
View file

@ -0,0 +1,7 @@
---
name: break
args: [v]
renameInGlobalScope: false
---
In debug mode (enabled using `--debugger`), pause Nix expression evaluation and enter the REPL.
Otherwise, return the argument `v`.

13
src/libexpr/builtins/catAttrs.md Normal file
View file

@ -0,0 +1,13 @@
---
name: catAttrs
args: [attr, list]
---
Collect each attribute named *attr* from a list of attribute
sets. Attrsets that don't contain the named attribute are
ignored. For example,
```nix
builtins.catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
```
evaluates to `[1 2]`.

9
src/libexpr/builtins/ceil.md Normal file
View file

@ -0,0 +1,9 @@
---
name: ceil
args: [double]
---
Converts an IEEE-754 double-precision floating-point number (*double*) to
the next higher integer.
If the datatype is neither an integer nor a "float", an evaluation error will be
thrown.

9
src/libexpr/builtins/compareVersions.md Normal file
View file

@ -0,0 +1,9 @@
---
name: compareVersions
args: [s1, s2]
---
Compare two strings representing versions and return `-1` if
version *s1* is older than version *s2*, `0` if they are the same,
and `1` if *s1* is newer than *s2*. The version comparison
algorithm is the same as the one used by [`nix-env
-u`](../command-ref/nix-env.md#operation---upgrade).

5
src/libexpr/builtins/concatLists.md Normal file
View file

@ -0,0 +1,5 @@
---
name: concatLists
args: [lists]
---
Concatenate a list of lists into a single list.

6
src/libexpr/builtins/concatMap.md Normal file
View file

@ -0,0 +1,6 @@
---
name: concatMap
args: [f, list]
---
This function is equivalent to `builtins.concatLists (map f list)`
but is more efficient.

7
src/libexpr/builtins/concatStringsSep.md Normal file
View file

@ -0,0 +1,7 @@
---
name: concatStringsSep
args: [separator, list]
---
Concatenate a list of strings with a separator between each
element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] ==
"usr/local/bin"`.

7
src/libexpr/builtins/deepSeq.md Normal file
View file

@ -0,0 +1,7 @@
---
name: deepSeq
args: [e1, e2]
---
This is like `seq e1 e2`, except that *e1* is evaluated *deeply*:
if it’s a list or set, its elements or attributes are also
evaluated recursively.

8
src/libexpr/builtins/dirOf.md Normal file
View file

@ -0,0 +1,8 @@
---
name: dirOf
args: [s]
renameInGlobalScope: false
---
Return the directory part of the string *s*, that is, everything
before the final slash in the string. This is similar to the GNU
`dirname` command.

5
src/libexpr/builtins/div.md Normal file
View file

@ -0,0 +1,5 @@
---
name: div
args: [e1, e2]
---
Return the quotient of the numbers *e1* and *e2*.

6
src/libexpr/builtins/elem.md Normal file
View file

@ -0,0 +1,6 @@
---
name: elem
args: [x, xs]
---
Return `true` if a value equal to *x* occurs in the list *xs*, and
`false` otherwise.

6
src/libexpr/builtins/elemAt.md Normal file
View file

@ -0,0 +1,6 @@
---
name: elemAt
args: [xs, n]
---
Return element *n* from the list *xs*. Elements are counted starting
from 0. A fatal error occurs if the index is out of bounds.

72
src/libexpr/builtins/fetchClosure.md Normal file
View file

@ -0,0 +1,72 @@
---
name: fetchClosure
args: [args]
experimentalFeature: fetch-closure
---
Fetch a store path [closure](@docroot@/glossary.md#gloss-closure) from a binary cache, and return the store path as a string with context.
This function can be invoked in three ways, that we will discuss in order of preference.
**Fetch a content-addressed store path**
Example:
```nix
builtins.fetchClosure {
fromStore = "https://cache.nixos.org";
fromPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
}
```
This is the simplest invocation, and it does not require the user of the expression to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
If your store path is [input addressed](@docroot@/glossary.md#gloss-input-addressed-store-object) instead of content addressed, consider the other two invocations.
**Fetch any store path and rewrite it to a fully content-addressed store path**
Example:
```nix
builtins.fetchClosure {
fromStore = "https://cache.nixos.org";
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
}
```
This example fetches `/nix/store/r2jd...` from the specified binary cache,
and rewrites it into the content-addressed store path
`/nix/store/ldbh...`.
Like the previous example, no extra configuration or privileges are required.
To find out the correct value for `toPath` given a `fromPath`,
use [`nix store make-content-addressed`](@docroot@/command-ref/new-cli/nix3-store-make-content-addressed.md):
```console
# nix store make-content-addressed --from https://cache.nixos.org /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1
rewrote '/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1' to '/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1'
```
Alternatively, set `toPath = ""` and find the correct `toPath` in the error message.
**Fetch an input-addressed store path as is**
Example:
```nix
builtins.fetchClosure {
fromStore = "https://cache.nixos.org";
fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
inputAddressed = true;
}
```
It is possible to fetch an [input-addressed store path](@docroot@/glossary.md#gloss-input-addressed-store-object) and return it as is.
However, this is the least preferred way of invoking `fetchClosure`, because it requires that the input-addressed paths are trusted by the Lix configuration.
**`builtins.storePath`**
`fetchClosure` is similar to [`builtins.storePath`](#builtins-storePath) in that it allows you to use a previously built store path in a Nix expression.
However, `fetchClosure` is more reproducible because it specifies a binary cache from which the path can be fetched.
Also, using content-addressed store paths does not require users to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.

138
src/libexpr/builtins/fetchGit.md Normal file
View file

@ -0,0 +1,138 @@
---
name: fetchGit
args: [args]
renameInGlobalScope: false
---
Fetch a path from git. *args* can be a URL, in which case the HEAD
of the repo at that URL is fetched. Otherwise, it can be an
attribute with the following attributes (all except `url` optional):
- `url`
The URL of the repo.
- `name` (default: *basename of the URL*)
The name of the directory the repo should be exported to in the store.
- `rev` (default: *the tip of `ref`*)
The [Git revision] to fetch.
This is typically a commit hash.
[Git revision]: https://git-scm.com/docs/git-rev-parse#_specifying_revisions
- `ref` (default: `HEAD`)
The [Git reference] under which to look for the requested revision.
This is often a branch or tag name.
[Git reference]: https://git-scm.com/book/en/v2/Git-Internals-Git-References
By default, the `ref` value is prefixed with `refs/heads/`.
As of 2.3.0, Nix will not prefix `refs/heads/` if `ref` starts with `refs/` or
if `ref` looks like a commit hash for backwards compatibility with CppNix 2.3.
- `submodules` (default: `false`)
A Boolean parameter that specifies whether submodules should be checked out.
- `shallow` (default: `false`)
A Boolean parameter that specifies whether fetching from a shallow remote repository is allowed.
This still performs a full clone of what is available on the remote.
- `allRefs`
Whether to fetch all references of the repository.
With this argument being true, it's possible to load a `rev` from *any* `ref`
(by default only `rev`s from the specified `ref` are supported).
Here are some examples of how to use `fetchGit`.
- To fetch a private repository over SSH:
```nix
builtins.fetchGit {
url = "git@github.com:my-secret/repository.git";
ref = "master";
rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
}
```
- To fetch an arbitrary reference:
```nix
builtins.fetchGit {
url = "https://github.com/NixOS/nix.git";
ref = "refs/heads/0.5-release";
}
```
- If the revision you're looking for is in the default branch of
the git repository you don't strictly need to specify the branch
name in the `ref` attribute.
However, if the revision you're looking for is in a future
branch for the non-default branch you will need to specify the
the `ref` attribute as well.
```nix
builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
ref = "1.11-maintenance";
}
```
> **Note**
>
> It is nice to always specify the branch which a revision
> belongs to. Without the branch being specified, the fetcher
> might fail if the default branch changes. Additionally, it can
> be confusing to try a commit from a non-default branch and see
> the fetch fail. If the branch is specified the fault is much
> more obvious.
- If the revision you're looking for is in the default branch of
the git repository you may omit the `ref` attribute.
```nix
builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
}
```
- To fetch a specific tag:
```nix
builtins.fetchGit {
url = "https://github.com/nixos/nix.git";
ref = "refs/tags/1.9";
}
```
- To fetch the latest version of a remote branch:
```nix
builtins.fetchGit {
url = "ssh://git@github.com/nixos/nix.git";
ref = "master";
}
```
Nix will refetch the branch according to the [`tarball-ttl`](@docroot@/command-ref/conf-file.md#conf-tarball-ttl) setting.
This behavior is disabled in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
- To fetch the content of a checked-out work directory:
```nix
builtins.fetchGit ./work-dir
```
If the URL points to a local directory, and no `ref` or `rev` is
given, `fetchGit` will use the current content of the checked-out
files, even if they are not committed or added to Git's index. It will
only consider files added to the Git repository, as listed by `git ls-files`.

42
src/libexpr/builtins/fetchTarball.md Normal file
View file

@ -0,0 +1,42 @@
---
name: fetchTarball
args: [args]
renameInGlobalScope: false
---
Download the specified URL, unpack it and return the path of the
unpacked tree. The file must be a tape archive (`.tar`) compressed
with `gzip`, `bzip2` or `xz`. The top-level path component of the
files in the tarball is removed, so it is best if the tarball
contains a single directory at top level. The typical use of the
function is to obtain external Nix expression dependencies, such as
a particular version of Nixpkgs, e.g.
```nix
with import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz") {};
stdenv.mkDerivation { … }
```
The fetched tarball is cached for a certain amount of time (1
hour by default) in `~/.cache/nix/tarballs/`. You can change the
cache timeout either on the command line with `--tarball-ttl`
*number-of-seconds* or in the Nix configuration file by adding
the line `tarball-ttl = ` *number-of-seconds*.
Note that when obtaining the hash with `nix-prefetch-url` the
option `--unpack` is required.
This function can also verify the contents against a hash. In that
case, the function takes a set instead of a URL. The set requires
the attribute `url` and the attribute `sha256`, e.g.
```nix
with import (fetchTarball {
url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz";
sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
}) {};
stdenv.mkDerivation { … }
```
Not available in [restricted evaluation mode](@docroot@/command-ref/conf-file.md#conf-restrict-eval).

7
src/libexpr/builtins/fetchurl.md Normal file
View file

@ -0,0 +1,7 @@
---
name: fetchurl
args: [url]
---
Download the specified URL and return the path of the downloaded file.
Not available in [restricted evaluation mode](@docroot@/command-ref/conf-file.md#conf-restrict-eval).

6
src/libexpr/builtins/filter.md Normal file
View file

@ -0,0 +1,6 @@
---
name: filter
args: [f, list]
---
Return a list consisting of the elements of *list* for which the
function *f* returns `true`.

51
src/libexpr/builtins/filterSource.md Normal file
View file

@ -0,0 +1,51 @@
---
name: filterSource
args: [e1, e2]
---
> **Warning**
>
> `filterSource` should not be used to filter store paths. Since
> `filterSource` uses the name of the input directory while naming
> the output directory, doing so will produce a directory name in
> the form of `<hash2>-<hash>-<name>`, where `<hash>-<name>` is
> the name of the input directory. Since `<hash>` depends on the
> unfiltered directory, the name of the output directory will
> indirectly depend on files that are filtered out by the
> function. This will trigger a rebuild even when a filtered out
> file is changed. Use `builtins.path` instead, which allows
> specifying the name of the output directory.
This function allows you to copy sources into the Nix store while
filtering certain files. For instance, suppose that you want to use
the directory `source-dir` as an input to a Nix expression, e.g.
```nix
stdenv.mkDerivation {
...
src = ./source-dir;
}
```
However, if `source-dir` is a Subversion working copy, then all
those annoying `.svn` subdirectories will also be copied to the
store. Worse, the contents of those directories may change a lot,
causing lots of spurious rebuilds. With `filterSource` you can
filter out the `.svn` directories:
```nix
src = builtins.filterSource
(path: type: type != "directory" || baseNameOf path != ".svn")
./source-dir;
```
Thus, the first argument *e1* must be a predicate function that is
called for each regular file, directory or symlink in the source
tree *e2*. If the function returns `true`, the file is copied to the
Nix store, otherwise it is omitted. The function is called with two
arguments. The first is the full path of the file. The second is a
string that identifies the type of the file, which is either
`"regular"`, `"directory"`, `"symlink"` or `"unknown"` (for other
kinds of files such as device nodes or fifos — but note that those
cannot be copied to the Nix store, so if the predicate returns
`true` for them, the copy will fail). If you exclude a directory,
the entire corresponding subtree of *e2* will be excluded.

45
src/libexpr/builtins/findFile.md Normal file
View file

@ -0,0 +1,45 @@
---
name: findFile
args: ['search path', 'lookup path']
---
Look up the given path with the given search path.
A search path is represented list of [attribute sets](./values.md#attribute-set) with two attributes, `prefix`, and `path`.
`prefix` is a relative path.
`path` denotes a file system location; the exact syntax depends on the command line interface.
Examples of search path attribute sets:
- ```
{
prefix = "nixos-config";
path = "/etc/nixos/configuration.nix";
}
```
- ```
{
prefix = "";
path = "/nix/var/nix/profiles/per-user/root/channels";
}
```
The lookup algorithm checks each entry until a match is found, returning a [path value](@docroot@/language/values.html#type-path) of the match.
This is the process for each entry:
If the lookup path matches `prefix`, then the remainder of the lookup path (the "suffix") is searched for within the directory denoted by `patch`.
Note that the `path` may need to be downloaded at this point to look inside.
If the suffix is found inside that directory, then the entry is a match;
the combined absolute path of the directory (now downloaded if need be) and the suffix is returned.
The syntax
```nix
<nixpkgs>
```
is equivalent to:
```nix
builtins.findFile builtins.nixPath "nixpkgs"
```

21
src/libexpr/builtins/flakeRefToString.md Normal file
View file

@ -0,0 +1,21 @@
---
name: flakeRefToString
implementation: flake::prim_flakeRefToString
args: [attrs]
experimentalFeature: flakes
---
Convert a flake reference from attribute set format to URL format.
For example:
```nix
builtins.flakeRefToString {
dir = "lib"; owner = "NixOS"; ref = "23.05"; repo = "nixpkgs"; type = "github";
}
```
evaluates to
```nix
"github:NixOS/nixpkgs/23.05?dir=lib"
```

9
src/libexpr/builtins/floor.md Normal file
View file

@ -0,0 +1,9 @@
---
name: floor
args: [double]
---
Converts an IEEE-754 double-precision floating-point number (*double*) to
the next lower integer.
If the datatype is neither an integer nor a "float", an evaluation error will be
thrown.

10
src/libexpr/builtins/foldlStrict.md Normal file
View file

@ -0,0 +1,10 @@
---
name: foldl'
implementation: prim_foldlStrict
args: [op, nul, list]
---
Reduce a list by applying a binary operator, from left to right,
e.g. `foldl' op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2)
...`. For example, `foldl' (x: y: x + y) 0 [1 2 3]` evaluates to 6.
The return value of each application of `op` is evaluated immediately,
even for intermediate values.

11
src/libexpr/builtins/fromJSON.md Normal file
View file

@ -0,0 +1,11 @@
---
name: fromJSON
args: [e]
---
Convert a JSON string to a Nix value. For example,
```nix
builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
```
returns the value `{ x = [ 1 2 3 ]; y = null; }`.

17
src/libexpr/builtins/fromTOML.md Normal file
View file

@ -0,0 +1,17 @@
---
name: fromTOML
args: [e]
renameInGlobalScope: false
---
Convert a TOML string to a Nix value. For example,
```nix
builtins.fromTOML ''
x=1
s="a"
[table]
y=2
''
```
returns the value `{ s = "a"; table = { y = 2; }; x = 1; }`.

13
src/libexpr/builtins/functionArgs.md Normal file
View file

@ -0,0 +1,13 @@
---
name: functionArgs
args: [f]
---
Return a set containing the names of the formal arguments expected
by the function *f*. The value of each attribute is a Boolean
denoting whether the corresponding argument has a default value. For
instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y =
true; }`.
"Formal argument" here refers to the attributes pattern-matched by
the function. Plain lambdas are not included, e.g. `functionArgs (x:
...) = { }`.

12
src/libexpr/builtins/genList.md Normal file
View file

@ -0,0 +1,12 @@
---
name: genList
args: [generator, length]
---
Generate list of size *length*, with each element *i* equal to the
value returned by *generator* `i`. For example,
```nix
builtins.genList (x: x * x) 5
```
returns the list `[ 0 1 4 9 16 ]`.

28
src/libexpr/builtins/genericClosure.md Normal file
View file

@ -0,0 +1,28 @@
---
name: genericClosure
args: [attrset]
---
Take an *attrset* with values named `startSet` and `operator` in order to
return a *list of attrsets* by starting with the `startSet` and recursively
applying the `operator` function to each `item`. The *attrsets* in the
`startSet` and the *attrsets* produced by `operator` must contain a value
named `key` which is comparable. The result is produced by calling `operator`
for each `item` with a value for `key` that has not been called yet including
newly produced `item`s. The function terminates when no new `item`s are
produced. The resulting *list of attrsets* contains only *attrsets* with a
unique key. For example,
```
builtins.genericClosure {
startSet = [ {key = 5;} ];
operator = item: [{
key = if (item.key / 2 ) * 2 == item.key
then item.key / 2
else 3 * item.key + 1;
}];
}
```
evaluates to
```
[ { key = 5; } { key = 16; } { key = 8; } { key = 4; } { key = 2; } { key = 1; } ]
```

8
src/libexpr/builtins/getAttr.md Normal file
View file

@ -0,0 +1,8 @@
---
name: getAttr
args: [s, set]
---
`getAttr` returns the attribute named *s* from *set*. Evaluation
aborts if the attribute doesn’t exist. This is a dynamic version of
the `.` operator, since *s* is an expression rather than an
identifier.

21
src/libexpr/builtins/getContext.md Normal file
View file

@ -0,0 +1,21 @@
---
name: getContext
args: [s]
---
Return the string context of *s*.
The string context tracks references to derivations within a string.
It is represented as an attribute set of [store derivation](@docroot@/glossary.md#gloss-store-derivation) paths mapping to output names.
Using [string interpolation](@docroot@/language/string-interpolation.md) on a derivation will add that derivation to the string context.
For example,
```nix
builtins.getContext "${derivation { name = "a"; builder = "b"; system = "c"; }}"
```
evaluates to
```
{ "/nix/store/arhvjaf6zmlyn8vh8fgn55rpwnxq0n7l-a.drv" = { outputs = [ "out" ]; }; }
```

14
src/libexpr/builtins/getEnv.md Normal file
View file

@ -0,0 +1,14 @@
---
name: getEnv
args: [s]
---
`getEnv` returns the value of the environment variable *s*, or an
empty string if the variable doesn't exist. This function should be
used with care, as it can introduce all sorts of nasty environment
dependencies in your Nix expression.
`getEnv` is used in nixpkgs for evil impurities such as locating the file
`~/.config/nixpkgs/config.nix` which contains user-local settings for nixpkgs.
(That is, it does a `getEnv "HOME"` to locate the user's home directory.)
When in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval), this function always returns an empty string.

19
src/libexpr/builtins/getFlake.md Normal file
View file

@ -0,0 +1,19 @@
---
name: getFlake
implementation: flake::prim_getFlake
args: [args]
experimentalFeature: flakes
---
Fetch a flake from a flake reference, and return its output attributes and some metadata. For example:
```nix
(builtins.getFlake "nix/55bc52401966fbffa525c574c14f67b00bc4fb3a").packages.x86_64-linux.nix
```
Unless impure evaluation is allowed (`--impure`), the flake reference
must be "locked", e.g. contain a Git revision or content hash. An
example of an unlocked usage is:
```nix
(builtins.getFlake "github:edolstra/dwarffs").rev
```

20
src/libexpr/builtins/groupBy.md Normal file
View file

@ -0,0 +1,20 @@
---
name: groupBy
args: [f, list]
---
Groups elements of *list* together by the string returned from the
function *f* called on each element. It returns an attribute set
where each attribute value contains the elements of *list* that are
mapped to the same corresponding attribute name returned by *f*.
For example,
```nix
builtins.groupBy (builtins.substring 0 1) ["foo" "bar" "baz"]
```
evaluates to
```nix
{ b = [ "bar" "baz" ]; f = [ "foo" ]; }
```

7
src/libexpr/builtins/hasAttr.md Normal file
View file

@ -0,0 +1,7 @@
---
name: hasAttr
args: [s, set]
---
`hasAttr` returns `true` if *set* has an attribute named *s*, and
`false` otherwise. This is a dynamic version of the `?` operator,
since *s* is an expression rather than an identifier.

20
src/libexpr/builtins/hasContext.md Normal file
View file

@ -0,0 +1,20 @@
---
name: hasContext
args: [s]
---
Return `true` if string *s* has a non-empty context.
The context can be obtained with
[`getContext`](#builtins-getContext).
> **Example**
>
> Many operations require a string context to be empty because they are intended only to work with "regular" strings, and also to help users avoid unintentionally losing track of string context elements.
> `builtins.hasContext` can help create better domain-specific errors in those case.
>
> ```nix
> name: meta:
>
> if builtins.hasContext name
> then throw "package name cannot contain string context"
> else { ${name} = meta; }
> ```

7
src/libexpr/builtins/hashFile.md Normal file
View file

@ -0,0 +1,7 @@
---
name: hashFile
args: [type, p]
---
Return a base-16 representation of the cryptographic hash of the
file at path *p*. The hash algorithm specified by *type* must be one
of `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`.

7
src/libexpr/builtins/hashString.md Normal file
View file

@ -0,0 +1,7 @@
---
name: hashString
args: [type, s]
---
Return a base-16 representation of the cryptographic hash of string
*s*. The hash algorithm specified by *type* must be one of `"md5"`,
`"sha1"`, `"sha256"` or `"sha512"`.

7
src/libexpr/builtins/head.md Normal file
View file

@ -0,0 +1,7 @@
---
name: head
args: [list]
---
Return the first element of a list; abort evaluation if the argument
isn’t a list or is an empty list. You can test whether a list is
empty by comparing it with `[]`.

63
src/libexpr/builtins/import.md Normal file
View file

@ -0,0 +1,63 @@
---
name: import
args: [path]
renameInGlobalScope: false
---
Load, parse and return the Nix expression in the file *path*.
The value *path* can be a path, a string, or an attribute set with an
`__toString` attribute or a `outPath` attribute (as derivations or flake
inputs typically have).
If *path* is a directory, the file `default.nix` in that directory
is loaded.
Evaluation aborts if the file doesn’t exist or contains
an incorrect Nix expression. `import` implements Nix’s module
system: you can put any Nix expression (such as a set or a
function) in a separate file, and use it from Nix expressions in
other files.
> **Note**
>
> Unlike some languages, `import` is a regular function in Nix.
> Paths using the angle bracket syntax (e.g., `import` *\<foo\>*)
> are normal [path values](@docroot@/language/values.md#type-path).
A Nix expression loaded by `import` must not contain any *free
variables* (identifiers that are not defined in the Nix expression
itself and are not built-in). Therefore, it cannot refer to
variables that are in scope at the call site. For instance, if you
have a calling expression
```nix
rec {
x = 123;
y = import ./foo.nix;
}
```
then the following `foo.nix` will give an error:
```nix
x + 456
```
since `x` is not in scope in `foo.nix`. If you want `x` to be
available in `foo.nix`, you should pass it as a function argument:
```nix
rec {
x = 123;
y = import ./foo.nix x;
}
```
and
```nix
x: x + 456
```
(The function argument doesn’t have to be called `x` in `foo.nix`;
any name would work.)

8
src/libexpr/builtins/intersectAttrs.md Normal file
View file

@ -0,0 +1,8 @@
---
name: intersectAttrs
args: [e1, e2]
---
Return a set consisting of the attributes in the set *e2* which have the
same name as some attribute in *e1*.
Performs in O(*n* log *m*) where *n* is the size of the smaller set and *m* the larger set's size.

5
src/libexpr/builtins/isAttrs.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isAttrs
args: [e]
---
Return `true` if *e* evaluates to a set, and `false` otherwise.

5
src/libexpr/builtins/isBool.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isBool
args: [e]
---
Return `true` if *e* evaluates to a bool, and `false` otherwise.

5
src/libexpr/builtins/isFloat.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isFloat
args: [e]
---
Return `true` if *e* evaluates to a float, and `false` otherwise.

5
src/libexpr/builtins/isFunction.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isFunction
args: [e]
---
Return `true` if *e* evaluates to a function, and `false` otherwise.

5
src/libexpr/builtins/isInt.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isInt
args: [e]
---
Return `true` if *e* evaluates to an integer, and `false` otherwise.

5
src/libexpr/builtins/isList.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isList
args: [e]
---
Return `true` if *e* evaluates to a list, and `false` otherwise.

8
src/libexpr/builtins/isNull.md Normal file
View file

@ -0,0 +1,8 @@
---
name: isNull
args: [e]
renameInGlobalScope: false
---
Return `true` if *e* evaluates to `null`, and `false` otherwise.
This is equivalent to `e == null`.

5
src/libexpr/builtins/isPath.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isPath
args: [e]
---
Return `true` if *e* evaluates to a path, and `false` otherwise.

5
src/libexpr/builtins/isString.md Normal file
View file

@ -0,0 +1,5 @@
---
name: isString
args: [e]
---
Return `true` if *e* evaluates to a string, and `false` otherwise.

5
src/libexpr/builtins/length.md Normal file
View file

@ -0,0 +1,5 @@
---
name: length
args: [e]
---
Return the length of the list *e*.

7
src/libexpr/builtins/lessThan.md Normal file
View file

@ -0,0 +1,7 @@
---
name: lessThan
args: [e1, e2]
---
Return `true` if the number *e1* is less than the number *e2*, and
`false` otherwise. Evaluation aborts if either *e1* or *e2* does not
evaluate to a number.

27
src/libexpr/builtins/listToAttrs.md Normal file
View file

@ -0,0 +1,27 @@
---
name: listToAttrs
args: [e]
---
Construct a set from a list specifying the names and values of each
attribute. Each element of the list should be a set consisting of a
string-valued attribute `name` specifying the name of the attribute,
and an attribute `value` specifying its value.
In case of duplicate occurrences of the same name, the first
takes precedence.
Example:
```nix
builtins.listToAttrs
[ { name = "foo"; value = 123; }
{ name = "bar"; value = 456; }
{ name = "bar"; value = 420; }
]
```
evaluates to
```nix
{ foo = 123; bar = 456; }
```

13
src/libexpr/builtins/map.md Normal file
View file

@ -0,0 +1,13 @@
---
name: map
args: [f, list]
renameInGlobalScope: false
---
Apply the function *f* to each element in the list *list*. For
example,
```nix
map (x: "foo" + x) [ "bar" "bla" "abc" ]
```
evaluates to `[ "foobar" "foobla" "fooabc" ]`.

11
src/libexpr/builtins/mapAttrs.md Normal file
View file

@ -0,0 +1,11 @@
---
name: mapAttrs
args: [f, attrset]
---
Apply function *f* to every element of *attrset*. For example,
```nix
builtins.mapAttrs (name: value: value * 10) { a = 1; b = 2; }
```
evaluates to `{ a = 10; b = 20; }`.

32
src/libexpr/builtins/match.md Normal file
View file

@ -0,0 +1,32 @@
---
name: match
args: [regex, str]
---
Returns a list if the [extended POSIX regular
expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
*regex* matches *str* precisely, otherwise returns `null`. Each item
in the list is a regex group.
```nix
builtins.match "ab" "abc"
```
Evaluates to `null`.
```nix
builtins.match "abc" "abc"
```
Evaluates to `[ ]`.
```nix
builtins.match "a(b)(c)" "abc"
```
Evaluates to `[ "b" "c" ]`.
```nix
builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO "
```
Evaluates to `[ "FOO" ]`.

5
src/libexpr/builtins/mul.md Normal file
View file

@ -0,0 +1,5 @@
---
name: mul
args: [e1, e2]
---
Return the product of the numbers *e1* and *e2*.

23
src/libexpr/builtins/outputOf.md Normal file
View file

@ -0,0 +1,23 @@
---
name: outputOf
args: [derivation-reference, output-name]
experimentalFeature: dynamic-derivations
---
Return the output path of a derivation, literally or using a placeholder if needed.
If the derivation has a statically-known output path (i.e. the derivation output is input-addressed, or fixed content-addresed), the output path will just be returned.
But if the derivation is content-addressed or if the derivation is itself not-statically produced (i.e. is the output of another derivation), a placeholder will be returned instead.
*`derivation reference`* must be a string that may contain a regular store path to a derivation, or may be a placeholder reference. If the derivation is produced by a derivation, you must explicitly select `drv.outPath`.
This primop can be chained arbitrarily deeply.
For instance,
```nix
builtins.outputOf
(builtins.outputOf myDrv "out)
"out"
```
will return a placeholder for the output of the output of `myDrv`.
This primop corresponds to the `^` sigil for derivable paths, e.g. as part of installable syntax on the command line.

10
src/libexpr/builtins/parseDrvName.md Normal file
View file

@ -0,0 +1,10 @@
---
name: parseDrvName
args: [s]
---
Split the string *s* into a package name and version. The package
name is everything up to but not including the first dash not followed
by a letter, and the version is everything following that dash. The
result is returned in a set `{ name, version }`. Thus,
`builtins.parseDrvName "nix-0.12pre12876"` returns `{ name =
"nix"; version = "0.12pre12876"; }`.

19
src/libexpr/builtins/parseFlakeRef.md Normal file
View file

@ -0,0 +1,19 @@
---
name: parseFlakeRef
implementation: flake::prim_parseFlakeRef
args: [flake-ref]
experimentalFeature: flakes
---
Parse a flake reference, and return its exploded form.
For example:
```nix
builtins.parseFlakeRef "github:NixOS/nixpkgs/23.05?dir=lib"
```
evaluates to:
```nix
{ dir = "lib"; owner = "NixOS"; ref = "23.05"; repo = "nixpkgs"; type = "github"; }
```

19
src/libexpr/builtins/partition.md Normal file
View file

@ -0,0 +1,19 @@
---
name: partition
args: [pred, list]
---
Given a predicate function *pred*, this function returns an
attrset containing a list named `right`, containing the elements
in *list* for which *pred* returned `true`, and a list named
`wrong`, containing the elements for which it returned
`false`. For example,
```nix
builtins.partition (x: x > 10) [1 23 9 3 42]
```
evaluates to
```nix
{ right = [ 23 42 ]; wrong = [ 1 9 3 ]; }
```

31
src/libexpr/builtins/path.md Normal file
View file

@ -0,0 +1,31 @@
---
name: path
args: [args]
---
An enrichment of the built-in path type, based on the attributes
present in *args*. All are optional except `path`:
- path\
The underlying path.
- name\
The name of the path when added to the store. This can used to
reference paths that have nix-illegal characters in their names,
like `@`.
- filter\
A function of the type expected by `builtins.filterSource`,
with the same semantics.
- recursive\
When `false`, when `path` is added to the store it is with a
flat hash, rather than a hash of the NAR serialization of the
file. Thus, `path` must refer to a regular file, not a
directory. This allows similar behavior to `fetchurl`. Defaults
to `true`.
- sha256\
When provided, this is the expected hash of the file at the
path. Evaluation will fail if the hash is incorrect, and
providing a hash allows `builtins.path` to be used even when the
`pure-eval` nix config option is on.

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