Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: merge builtin-constants into builtins #11059

Merged
merged 1 commit into from
Jul 8, 2024
Merged

docs: merge builtin-constants into builtins #11059

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 0 additions & 31 deletions doc/manual/generate-builtin-constants.nix
View file
Open in desktop

This file was deleted.

16 changes: 13 additions & 3 deletions doc/manual/generate-builtins.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,10 @@ in

builtinsInfo:
let
showBuiltin = name: { doc, args, arity, experimental-feature }:
showBuiltin = name: { doc, type ? null, args ? [ ], experimental-feature ? null, impure-only ? false }:
let
type' = optionalString (type != null) " (${type})";

experimentalNotice = optionalString (experimental-feature != null) ''
> **Note**
>
Expand All @@ -18,18 +20,26 @@ let
> extra-experimental-features = ${experimental-feature}
> ```
'';

impureNotice = optionalString impure-only ''
> **Note**
>
> Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
'';
in
squash ''
<dt id="builtins-${name}">
<a href="#builtins-${name}"><code>${name} ${listArgs args}</code></a>
<a href="#builtins-${name}"><code>${name}${listArgs args}</code></a>${type'}
</dt>
<dd>

${experimentalNotice}

${doc}

${impureNotice}
</dd>
'';
listArgs = args: concatStringsSep " " (map (s: "<var>${s}</var>") args);
listArgs = args: concatStringsSep "" (map (s: " <var>${s}</var>") args);
in
concatStringsSep "\n" (attrValues (mapAttrs showBuiltin builtinsInfo))
10 changes: 2 additions & 8 deletions doc/manual/local.mk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,16 +140,10 @@ $(d)/xp-features.json: $(doc_nix)

$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(doc_nix)
@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@.tmp;
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
@mv $@.tmp $@

$(d)/src/language/builtin-constants.md: $(d)/language.json $(d)/generate-builtin-constants.nix $(d)/src/language/builtin-constants-prefix.md $(doc_nix)
@cat doc/manual/src/language/builtin-constants-prefix.md > $@.tmp
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@.tmp;
@cat doc/manual/src/language/builtin-constants-suffix.md >> $@.tmp
@mv $@.tmp $@

$(d)/language.json: $(doc_nix)
$(trace-gen) $(dummy-env) $(doc_nix) __dump-language > $@.tmp
@mv $@.tmp $@
Expand Down Expand Up @@ -217,7 +211,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
# `@docroot@` is to be preserved for documenting the mechanism
# FIXME: maybe contributing guides should live right next to the code
# instead of in the manual
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
$(trace-gen) \
tmp="$$(mktemp -d)"; \
cp -r doc/manual "$$tmp"; \
Expand Down
9 changes: 4 additions & 5 deletions doc/manual/src/SUMMARY.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,10 @@
- [String interpolation](language/string-interpolation.md)
- [Lookup path](language/constructs/lookup-path.md)
- [Operators](language/operators.md)
- [Derivations](language/derivations.md)
- [Advanced Attributes](language/advanced-attributes.md)
- [Import From Derivation](language/import-from-derivation.md)
- [Built-in Constants](language/builtin-constants.md)
- [Built-in Functions](language/builtins.md)
- [Built-ins](language/builtins.md)
- [Derivations](language/derivations.md)
- [Advanced Attributes](language/advanced-attributes.md)
- [Import From Derivation](language/import-from-derivation.md)
- [Package Management](package-management/index.md)
- [Profiles](package-management/profiles.md)
- [Garbage Collection](package-management/garbage-collection.md)
Expand Down
1 change: 1 addition & 0 deletions doc/manual/src/_redirects
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
/expressions/* /language/:splat 301!
/language/values /language/types 301!
/language/constructs /language/syntax 301!
/language/builtin-constants /language/builtins 301!

/installation/installation /installation 301!

Expand Down
5 changes: 0 additions & 5 deletions doc/manual/src/language/builtin-constants-prefix.md
View file
Open in desktop

This file was deleted.

1 change: 0 additions & 1 deletion doc/manual/src/language/builtin-constants-suffix.md
View file
Open in desktop

This file was deleted.

10 changes: 6 additions & 4 deletions doc/manual/src/language/builtins-prefix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# Built-in Functions
# Built-ins

This section lists the functions built into the Nix language evaluator.
All built-in functions are available through the global [`builtins`](./builtin-constants.md#builtins-builtins) constant.
This section lists the values and functions built into the Nix language evaluator.
All built-ins are available through the global [`builtins`](#builtins-builtins) constant.

For convenience, some built-ins can be accessed directly:
Some built-ins are also exposed directly in the global scope:

<!-- TODO(@rhendric, #10970): this list is incomplete -->

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is on purpose, since most of them probably shouldn't be used unqualified and rather than making a manual list, this just provides the important ones. A complete list should be generated automatically and probably tucked away in a details tag.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can filter out anything that's deprecated or not yet ready for use, but I think it's important to have a complete description of the standard global scope in the language reference. Automated or manual is fine with me, but either way we should do the work of enumerating the set of builtins that ‘should’ be used unqualified, and this is not yet that set. (Is that set defined anywhere in code that I could reference? It's not obvious to me whether, say, map is in it.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current implementation special cases the __ in a number of hacky ways. It would be nice to replace that with a boolean in the metadata structs, which we can leverage in the implementation (what goes in just builtins vs also at the top level) and also the documentation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that might be an orthogonal concern? The __ identifiers are only in the global scope, not on builtins. A boolean for that condition wouldn't express whether an identifier that is on builtins should be (documented as) available in the global scope also.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding is that if there is that __foo at the top level corresponds to builtins.foo, and bar at the top level corresponds to builtins.bar; in other words, that the top-level name is authoritative. But maybe there are more degrees of freedom!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I think you're right about that. But my impression—@fricklerhandwerk correct me if I'm wrong—is that he would not want us to list all twenty-ish not-__ documented top-level identifiers because it's better practice to reference some of them from builtins. As a guess, isNull strikes me as a likely candidate for this; none of the other is* functions are available globally, so probably we should leave it in for backwards compatibility but not mention its availability outside of builtins in the language reference, sort of like the old let { ... } syntax.

But I don't know which other names should be in or out. builtins, false, null, true are obviously in. map, as I mentioned, is something I would lean toward including but I don't know how you all feel about it. break, removeAttrs, and toString are similar. Others I don't know what to think about; I would have erred on the side of including all of them (except for entirely undocumented functions like derivationStrict), but I'm happy to do whatever you all think is best.

Copy link
Member

@Ericson2314 Ericson2314 Jul 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rhendric Yeah so concretely I'm thinking something like this:

  1. Replace internal __ hacks with a bool
  2. Replace bool with a 3-way enum to disambiguate those we like at the top level vs don't like at the top level (or whatever other info we want)
  3. Use the richer information when generating the docs

Step 1 is a nice thing we can get started on right away.

- [`derivation`](#builtins-derivation)
- [`import`](#builtins-import)
Expand Down
2 changes: 1 addition & 1 deletion doc/manual/src/language/constructs/lookup-path.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

A lookup path is an identifier with an optional path suffix that resolves to a [path value](@docroot@/language/types.md#type-path) if the identifier matches a search path entry.

The value of a lookup path is determined by [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath).
The value of a lookup path is determined by [`builtins.nixPath`](@docroot@/language/builtins.md#builtins-nixPath).

See [`builtins.findFile`](@docroot@/language/builtins.md#builtins-findFile) for details on lookup path resolution.

Expand Down
2 changes: 1 addition & 1 deletion doc/manual/src/language/derivations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
> }
> ```
>
> [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem) has the value of the [`system` configuration option], and defaults to the system type of the current Nix installation.
> [`builtins.currentSystem`](@docroot@/language/builtins.md#builtins-currentSystem) has the value of the [`system` configuration option], and defaults to the system type of the current Nix installation.

- [`builder`]{#attr-builder} ([Path](@docroot@/language/types.md#type-path) | [String](@docroot@/language/types.md#type-string))

Expand Down
4 changes: 2 additions & 2 deletions doc/manual/src/language/types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ A _boolean_ in the Nix language is one of _true_ or _false_.

<!-- TODO: mention the top-level environment -->

These values are available as attributes of [`builtins`](builtin-constants.md#builtins-builtins) as [`builtins.true`](builtin-constants.md#builtins-true) and [`builtins.false`](builtin-constants.md#builtins-false).
These values are available as attributes of [`builtins`](builtins.md#builtins-builtins) as [`builtins.true`](builtins.md#builtins-true) and [`builtins.false`](builtins.md#builtins-false).
The function [`builtins.isBool`](builtins.md#builtins-isBool) can be used to determine if a value is a boolean.

### String {#type-string}
Expand All @@ -60,7 +60,7 @@ There is a single value of type _null_ in the Nix language.

<!-- TODO: mention the top-level environment -->

This value is available as an attribute on the [`builtins`](builtin-constants.md#builtins-builtins) attribute set as [`builtins.null`](builtin-constants.md#builtins-null).
This value is available as an attribute on the [`builtins`](builtins.md#builtins-builtins) attribute set as [`builtins.null`](builtins.md#builtins-null).

## Compound values

Expand Down
14 changes: 7 additions & 7 deletions src/libexpr/eval-settings.hh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ struct EvalSettings : Config
R"(
List of search paths to use for [lookup path](@docroot@/language/constructs/lookup-path.md) resolution.
This setting determines the value of
[`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath) and can be used with [`builtins.findFile`](@docroot@/language/builtin-constants.md#builtins-findFile).
[`builtins.nixPath`](@docroot@/language/builtins.md#builtins-nixPath) and can be used with [`builtins.findFile`](@docroot@/language/builtins.md#builtins-findFile).

The default value is

Expand All @@ -95,7 +95,7 @@ struct EvalSettings : Config
this, "", "eval-system",
R"(
This option defines
[`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem)
[`builtins.currentSystem`](@docroot@/language/builtins.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)
Expand All @@ -116,7 +116,7 @@ struct EvalSettings : Config
R"(
If set to `true`, the Nix evaluator will not allow access to any
files outside of
[`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath),
[`builtins.nixPath`](@docroot@/language/builtins.md#builtins-nixPath),
or to URIs outside of
[`allowed-uris`](@docroot@/command-ref/conf-file.md#conf-allowed-uris).
)"};
Expand All @@ -127,10 +127,10 @@ struct EvalSettings : Config

- Restrict file system and network access to files specified by cryptographic hash
- Disable impure constants:
- [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem)
- [`builtins.currentTime`](@docroot@/language/builtin-constants.md#builtins-currentTime)
- [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath)
- [`builtins.storePath`](@docroot@/language/builtin-constants.md#builtins-storePath)
- [`builtins.currentSystem`](@docroot@/language/builtins.md#builtins-currentSystem)
- [`builtins.currentTime`](@docroot@/language/builtins.md#builtins-currentTime)
- [`builtins.nixPath`](@docroot@/language/builtins.md#builtins-nixPath)
- [`builtins.storePath`](@docroot@/language/builtins.md#builtins-storePath)
)"
};

Expand Down
4 changes: 2 additions & 2 deletions src/libexpr/primops.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1872,7 +1872,7 @@ static RegisterPrimOp primop_findFile(PrimOp {
- 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.

[Lookup path](@docroot@/language/constructs/lookup-path.md) expressions are [desugared](https://en.wikipedia.org/wiki/Syntactic_sugar) using this and [`builtins.nixPath`](@docroot@/language/builtin-constants.md#builtins-nixPath):
[Lookup path](@docroot@/language/constructs/lookup-path.md) expressions are [desugared](https://en.wikipedia.org/wiki/Syntactic_sugar) using this and [`builtins.nixPath`](#builtins-nixPath):

```nix
<nixpkgs>
Expand Down Expand Up @@ -4519,7 +4519,7 @@ void EvalState::createBaseEnv()
addConstant("builtins", v, {
.type = nAttrs,
.doc = R"(
Contains all the [built-in functions](@docroot@/language/builtins.md) and values.
Contains all the built-in functions 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:

Expand Down
2 changes: 1 addition & 1 deletion src/libstore/globals.hh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,7 @@ public:
While you can force Nix to run a Darwin-specific `builder` executable on a Linux machine, the result would obviously be wrong.

This value is available in the Nix language as
[`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem)
[`builtins.currentSystem`](@docroot@/language/builtins.md#builtins-currentSystem)
if the
[`eval-system`](#conf-eval-system)
configuration option is set as the empty string.
Expand Down
2 changes: 1 addition & 1 deletion src/libutil/experimental-features.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ constexpr std::array<ExperimentalFeatureDetails, numXpFeatures> xpFeatureDetails
an impure derivation cannot also be
[content-addressed](#xp-feature-ca-derivations).

This is a more explicit alternative to using [`builtins.currentTime`](@docroot@/language/builtin-constants.md#builtins-currentTime).
This is a more explicit alternative to using [`builtins.currentTime`](@docroot@/language/builtins.md#builtins-currentTime).
)",
.trackingUrl = "https://github.com/NixOS/nix/milestone/42",
},
Expand Down
49 changes: 21 additions & 28 deletions src/nix/main.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -419,35 +419,28 @@ void mainWrapped(int argc, char * * argv)
};
evalSettings.pureEval = false;
EvalState state({}, openStore("dummy://"), evalSettings);
auto res = nlohmann::json::object();
res["builtins"] = ({
auto builtinsJson = nlohmann::json::object();
for (auto & builtin : *state.baseEnv.values[0]->attrs()) {
auto b = nlohmann::json::object();
if (!builtin.value->isPrimOp()) continue;
auto primOp = builtin.value->primOp();
if (!primOp->doc) continue;
b["arity"] = primOp->arity;
b["args"] = primOp->args;
b["doc"] = trim(stripIndentation(primOp->doc));
auto builtinsJson = nlohmann::json::object();
for (auto & builtin : *state.baseEnv.values[0]->attrs()) {
auto b = nlohmann::json::object();
if (!builtin.value->isPrimOp()) continue;
auto primOp = builtin.value->primOp();
if (!primOp->doc) continue;
b["args"] = primOp->args;
b["doc"] = trim(stripIndentation(primOp->doc));
if (primOp->experimentalFeature)
b["experimental-feature"] = primOp->experimentalFeature;
builtinsJson[state.symbols[builtin.name]] = std::move(b);
}
std::move(builtinsJson);
});
res["constants"] = ({
auto constantsJson = nlohmann::json::object();
for (auto & [name, info] : state.constantInfos) {
auto c = nlohmann::json::object();
if (!info.doc) continue;
c["doc"] = trim(stripIndentation(info.doc));
c["type"] = showType(info.type, false);
c["impure-only"] = info.impureOnly;
constantsJson[name] = std::move(c);
}
std::move(constantsJson);
});
logger->cout("%s", res);
builtinsJson[state.symbols[builtin.name]] = std::move(b);
}
for (auto & [name, info] : state.constantInfos) {
auto b = nlohmann::json::object();
if (!info.doc) continue;
b["doc"] = trim(stripIndentation(info.doc));
b["type"] = showType(info.type, false);
if (info.impureOnly)
b["impure-only"] = true;
builtinsJson[name] = std::move(b);
}
logger->cout("%s", builtinsJson);
return;
}

Expand Down
Loading