diff --git a/default.nix b/default.nix
index 2cccff28d51..6466507b714 100644
--- a/default.nix
+++ b/default.nix
@@ -1,10 +1,9 @@
-(import
- (
- let lock = builtins.fromJSON (builtins.readFile ./flake.lock); in
- fetchTarball {
- url = "https://github.com/edolstra/flake-compat/archive/${lock.nodes.flake-compat.locked.rev}.tar.gz";
- sha256 = lock.nodes.flake-compat.locked.narHash;
- }
- )
- { src = ./.; }
-).defaultNix
+(import (
+ let
+ lock = builtins.fromJSON (builtins.readFile ./flake.lock);
+ in
+ fetchTarball {
+ url = "https://github.com/edolstra/flake-compat/archive/${lock.nodes.flake-compat.locked.rev}.tar.gz";
+ sha256 = lock.nodes.flake-compat.locked.narHash;
+ }
+) { src = ./.; }).defaultNix
diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix
index 37ed12a4330..3649560f7c6 100644
--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@@ -5,7 +5,15 @@ in
builtinsInfo:
let
- showBuiltin = name: { doc, type ? null, args ? [ ], experimental-feature ? null, impure-only ? false }:
+ showBuiltin =
+ name:
+ {
+ doc,
+ type ? null,
+ args ? [ ],
+ experimental-feature ? null,
+ impure-only ? false,
+ }:
let
type' = optionalString (type != null) " (${type})";
diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 791bfd2c756..31e74e17d26 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -32,7 +32,13 @@ let
commandInfo = fromJSON commandDump;
- showCommand = { command, details, filename, toplevel }:
+ showCommand =
+ {
+ command,
+ details,
+ filename,
+ toplevel,
+ }:
let
result = ''
@@ -56,26 +62,27 @@ let
${maybeOptions}
'';
- showSynopsis = command: args:
+ showSynopsis =
+ command: args:
let
- showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
+ showArgument = arg: "*${arg.label}*" + optionalString (!arg ? arity) "...";
arguments = concatStringsSep " " (map showArgument args);
- in ''
+ in
+ ''
`${command}` [*option*...] ${arguments}
'';
- maybeSubcommands = optionalString (details ? commands && details.commands != {})
- ''
- where *subcommand* is one of the following:
+ maybeSubcommands = optionalString (details ? commands && details.commands != { }) ''
+ where *subcommand* is one of the following:
- ${subcommands}
- '';
+ ${subcommands}
+ '';
- subcommands = if length categories > 1
- then listCategories
- else listSubcommands details.commands;
+ subcommands = if length categories > 1 then listCategories else listSubcommands details.commands;
- categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands)));
+ categories = sort (x: y: x.id < y.id) (
+ unique (map (cmd: cmd.category) (attrValues details.commands))
+ );
listCategories = concatStrings (map showCategory categories);
@@ -99,38 +106,39 @@ let
${allStores}
'';
- index = replaceStrings
- [ "@store-types@" "./local-store.md" "./local-daemon-store.md" ]
- [ storesOverview "#local-store" "#local-daemon-store" ]
- details.doc;
+ index =
+ replaceStrings
+ [ "@store-types@" "./local-store.md" "./local-daemon-store.md" ]
+ [ storesOverview "#local-store" "#local-daemon-store" ]
+ details.doc;
storesOverview =
let
- showEntry = store:
- "- [${store.name}](#${store.slug})";
+ showEntry = store: "- [${store.name}](#${store.slug})";
in
concatStringsSep "\n" (map showEntry storesList) + "\n";
allStores = concatStringsSep "\n" (attrValues storePages);
- storePages = listToAttrs
- (map (s: { name = s.filename; value = s.page; }) storesList);
+ storePages = listToAttrs (
+ map (s: {
+ name = s.filename;
+ value = s.page;
+ }) storesList
+ );
storesList = showStoreDocs {
storeInfo = commandInfo.stores;
inherit inlineHTML;
};
- hasInfix = infix: content:
+ hasInfix =
+ infix: content:
builtins.stringLength content != builtins.stringLength (replaceStrings [ infix ] [ "" ] content);
in
optionalString (details ? doc) (
# An alternate implementation with builtins.match stack overflowed on some systems.
- if hasInfix "@store-types@" details.doc
- then help-stores
- else details.doc
+ if hasInfix "@store-types@" details.doc then help-stores else details.doc
);
maybeOptions =
let
- allVisibleOptions = filterAttrs
- (_: o: ! o.hiddenCategory)
- (details.flags // toplevel.flags);
+ allVisibleOptions = filterAttrs (_: o: !o.hiddenCategory) (details.flags // toplevel.flags);
in
optionalString (allVisibleOptions != { }) ''
# Options
@@ -142,55 +150,73 @@ let
> See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.
'';
- showOptions = inlineHTML: allOptions:
+ showOptions =
+ inlineHTML: allOptions:
let
showCategory = cat: opts: ''
${optionalString (cat != "") "## ${cat}"}
${concatStringsSep "\n" (attrValues (mapAttrs showOption opts))}
'';
- showOption = name: option:
+ showOption =
+ name: option:
let
result = trim ''
- ${item}
${option.description}
'';
- item = if inlineHTML
- then ''[`--${name}`](#opt-${name}) ${shortName} ${labels}''
- else "`--${name}` ${shortName} ${labels}";
- shortName = optionalString
- (option ? shortName)
- ("/ `-${option.shortName}`");
- labels = optionalString
- (option ? labels)
- (concatStringsSep " " (map (s: "*${s}*") option.labels));
- in result;
- categories = mapAttrs
- # Convert each group from a list of key-value pairs back to an attrset
- (_: listToAttrs)
- (groupBy
- (cmd: cmd.value.category)
- (attrsToList allOptions));
- in concatStrings (attrValues (mapAttrs showCategory categories));
- in squash result;
+ item =
+ if inlineHTML then
+ ''[`--${name}`](#opt-${name}) ${shortName} ${labels}''
+ else
+ "`--${name}` ${shortName} ${labels}";
+ shortName = optionalString (option ? shortName) ("/ `-${option.shortName}`");
+ labels = optionalString (option ? labels) (concatStringsSep " " (map (s: "*${s}*") option.labels));
+ in
+ result;
+ categories =
+ mapAttrs
+ # Convert each group from a list of key-value pairs back to an attrset
+ (_: listToAttrs)
+ (groupBy (cmd: cmd.value.category) (attrsToList allOptions));
+ in
+ concatStrings (attrValues (mapAttrs showCategory categories));
+ in
+ squash result;
appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
- processCommand = { command, details, filename, toplevel }:
+ processCommand =
+ {
+ command,
+ details,
+ filename,
+ toplevel,
+ }:
let
cmd = {
inherit command;
name = filename + ".md";
- value = showCommand { inherit command details filename toplevel; };
- };
- subcommand = subCmd: processCommand {
- command = command + " " + subCmd;
- details = details.commands.${subCmd};
- filename = appendName filename subCmd;
- inherit toplevel;
+ value = showCommand {
+ inherit
+ command
+ details
+ filename
+ toplevel
+ ;
+ };
};
- in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
+ subcommand =
+ subCmd:
+ processCommand {
+ command = command + " " + subCmd;
+ details = details.commands.${subCmd};
+ filename = appendName filename subCmd;
+ inherit toplevel;
+ };
+ in
+ [ cmd ] ++ concatMap subcommand (attrNames details.commands or { });
manpages = processCommand {
command = "nix";
@@ -199,9 +225,11 @@ let
toplevel = commandInfo.args;
};
- tableOfContents = let
- showEntry = page:
- " - [${page.command}](command-ref/new-cli/${page.name})";
- in concatStringsSep "\n" (map showEntry manpages) + "\n";
+ tableOfContents =
+ let
+ showEntry = page: " - [${page.command}](command-ref/new-cli/${page.name})";
+ in
+ concatStringsSep "\n" (map showEntry manpages) + "\n";
-in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
+in
+(listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
index 93a8e093e48..35ae73e5d1f 100644
--- a/doc/manual/generate-settings.nix
+++ b/doc/manual/generate-settings.nix
@@ -1,67 +1,99 @@
let
- inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
- inherit (import ) concatStrings indent optionalString squash;
+ inherit (builtins)
+ attrValues
+ concatStringsSep
+ isAttrs
+ isBool
+ mapAttrs
+ ;
+ inherit (import )
+ concatStrings
+ indent
+ optionalString
+ squash
+ ;
in
# `inlineHTML` is a hack to accommodate inconsistent output from `lowdown`
-{ prefix, inlineHTML ? true }: settingsInfo:
+{
+ prefix,
+ inlineHTML ? true,
+}:
+settingsInfo:
let
- showSetting = prefix: setting: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
+ showSetting =
+ prefix: setting:
+ {
+ description,
+ documentDefault,
+ defaultValue,
+ aliases,
+ value,
+ experimentalFeature,
+ }:
let
result = squash ''
- - ${item}
+ - ${item}
- ${indent " " body}
- '';
- item = if inlineHTML
- then ''[`${setting}`](#${prefix}-${setting})''
- else "`${setting}`";
+ ${indent " " body}
+ '';
+ item =
+ if inlineHTML then
+ ''[`${setting}`](#${prefix}-${setting})''
+ else
+ "`${setting}`";
# separate body to cleanly handle indentation
body = ''
- ${experimentalFeatureNote}
+ ${experimentalFeatureNote}
- ${description}
+ ${description}
- **Default:** ${showDefault documentDefault defaultValue}
+ **Default:** ${showDefault documentDefault defaultValue}
- ${showAliases aliases}
- '';
+ ${showAliases aliases}
+ '';
experimentalFeatureNote = optionalString (experimentalFeature != null) ''
- > **Warning**
- >
- > This setting is part of an
- > [experimental feature](@docroot@/development/experimental-features.md).
- >
- > To change this setting, make sure the
- > [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
- > is enabled.
- > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
- >
- > ```
- > extra-experimental-features = ${experimentalFeature}
- > ${setting} = ...
- > ```
- '';
+ > **Warning**
+ >
+ > This setting is part of an
+ > [experimental feature](@docroot@/development/experimental-features.md).
+ >
+ > To change this setting, make sure the
+ > [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
+ > is enabled.
+ > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
+ >
+ > ```
+ > extra-experimental-features = ${experimentalFeature}
+ > ${setting} = ...
+ > ```
+ '';
- showDefault = documentDefault: defaultValue:
+ showDefault =
+ documentDefault: defaultValue:
if documentDefault then
# a StringMap value type is specified as a string, but
# this shows the value type. The empty stringmap is `null` in
# JSON, but that converts to `{ }` here.
- if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
- then "*empty*"
- else if isBool defaultValue then
- if defaultValue then "`true`" else "`false`"
- else "`${toString defaultValue}`"
- else "*machine-specific*";
+ if defaultValue == "" || defaultValue == [ ] || isAttrs defaultValue then
+ "*empty*"
+ else if isBool defaultValue then
+ if defaultValue then "`true`" else "`false`"
+ else
+ "`${toString defaultValue}`"
+ else
+ "*machine-specific*";
- showAliases = aliases:
- optionalString (aliases != [])
- "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
+ showAliases =
+ aliases:
+ optionalString (aliases != [ ])
+ "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
- in result;
+ in
+ result;
-in concatStrings (attrValues (mapAttrs (showSetting prefix) settingsInfo))
+in
+concatStrings (attrValues (mapAttrs (showSetting prefix) settingsInfo))
diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
index cc370412414..e8b7377dafd 100644
--- a/doc/manual/generate-store-info.nix
+++ b/doc/manual/generate-store-info.nix
@@ -1,6 +1,20 @@
let
- inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
- inherit (import ) optionalString filterAttrs trim squash toLower unique indent;
+ inherit (builtins)
+ attrNames
+ listToAttrs
+ concatStringsSep
+ readFile
+ replaceStrings
+ ;
+ inherit (import )
+ optionalString
+ filterAttrs
+ trim
+ squash
+ toLower
+ unique
+ indent
+ ;
showSettings = import ;
in
@@ -14,7 +28,13 @@ in
let
- showStore = { name, slug }: { settings, doc, experimentalFeature }:
+ showStore =
+ { name, slug }:
+ {
+ settings,
+ doc,
+ experimentalFeature,
+ }:
let
result = squash ''
# ${name}
@@ -25,7 +45,10 @@ let
## Settings
- ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
+ ${showSettings {
+ prefix = "store-${slug}";
+ inherit inlineHTML;
+ } settings}
'';
experimentalFeatureNote = optionalString (experimentalFeature != null) ''
@@ -43,15 +66,15 @@ let
> extra-experimental-features = ${experimentalFeature}
> ```
'';
- in result;
-
- storesList = map
- (name: rec {
- inherit name;
- slug = replaceStrings [ " " ] [ "-" ] (toLower name);
- filename = "${slug}.md";
- page = showStore { inherit name slug; } storeInfo.${name};
- })
- (attrNames storeInfo);
-
-in storesList
+ in
+ result;
+
+ storesList = map (name: rec {
+ inherit name;
+ slug = replaceStrings [ " " ] [ "-" ] (toLower name);
+ filename = "${slug}.md";
+ page = showStore { inherit name slug; } storeInfo.${name};
+ }) (attrNames storeInfo);
+
+in
+storesList
diff --git a/doc/manual/generate-store-types.nix b/doc/manual/generate-store-types.nix
index 46179abc5bf..a03d3d6216e 100644
--- a/doc/manual/generate-store-types.nix
+++ b/doc/manual/generate-store-types.nix
@@ -1,5 +1,11 @@
let
- inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
+ inherit (builtins)
+ attrNames
+ listToAttrs
+ concatStringsSep
+ readFile
+ replaceStrings
+ ;
showSettings = import ;
showStoreDocs = import ;
in
@@ -14,26 +20,28 @@ let
index =
let
- showEntry = store:
- "- [${store.name}](./${store.filename})";
+ showEntry = store: "- [${store.name}](./${store.filename})";
in
concatStringsSep "\n" (map showEntry storesList);
- "index.md" = replaceStrings
- [ "@store-types@" ] [ index ]
- (readFile ./source/store/types/index.md.in);
+ "index.md" =
+ replaceStrings [ "@store-types@" ] [ index ]
+ (readFile ./source/store/types/index.md.in);
tableOfContents =
let
- showEntry = store:
- " - [${store.name}](store/types/${store.filename})";
+ showEntry = store: " - [${store.name}](store/types/${store.filename})";
in
concatStringsSep "\n" (map showEntry storesList) + "\n";
"SUMMARY.md" = tableOfContents;
- storePages = listToAttrs
- (map (s: { name = s.filename; value = s.page; }) storesList);
+ storePages = listToAttrs (
+ map (s: {
+ name = s.filename;
+ value = s.page;
+ }) storesList
+ );
in
storePages // { inherit "index.md" "SUMMARY.md"; }
diff --git a/doc/manual/generate-xp-features-shortlist.nix b/doc/manual/generate-xp-features-shortlist.nix
index eb735ba5f7a..1520fc2f815 100644
--- a/doc/manual/generate-xp-features-shortlist.nix
+++ b/doc/manual/generate-xp-features-shortlist.nix
@@ -2,8 +2,8 @@ with builtins;
with import ;
let
- showExperimentalFeature = name: doc:
- ''
- - [`${name}`](@docroot@/development/experimental-features.md#xp-feature-${name})
- '';
-in xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
+ showExperimentalFeature = name: doc: ''
+ - [`${name}`](@docroot@/development/experimental-features.md#xp-feature-${name})
+ '';
+in
+xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
diff --git a/doc/manual/generate-xp-features.nix b/doc/manual/generate-xp-features.nix
index 0eec0e1da23..468d253bafd 100644
--- a/doc/manual/generate-xp-features.nix
+++ b/doc/manual/generate-xp-features.nix
@@ -2,7 +2,8 @@ with builtins;
with import ;
let
- showExperimentalFeature = name: doc:
+ showExperimentalFeature =
+ name: doc:
squash ''
## [`${name}`]{#xp-feature-${name}}
diff --git a/doc/manual/package.nix b/doc/manual/package.nix
index f8133f2e1dd..8f5d0dfe137 100644
--- a/doc/manual/package.nix
+++ b/doc/manual/package.nix
@@ -1,19 +1,20 @@
-{ lib
-, mkMesonDerivation
+{
+ lib,
+ mkMesonDerivation,
-, meson
-, ninja
-, lowdown-unsandboxed
-, mdbook
-, mdbook-linkcheck
-, jq
-, python3
-, rsync
-, nix-cli
+ meson,
+ ninja,
+ lowdown-unsandboxed,
+ mdbook,
+ mdbook-linkcheck,
+ jq,
+ python3,
+ rsync,
+ nix-cli,
-# Configuration Options
+ # Configuration Options
-, version
+ version,
}:
let
@@ -25,18 +26,22 @@ mkMesonDerivation (finalAttrs: {
inherit version;
workDir = ./.;
- fileset = fileset.difference
- (fileset.unions [
- ../../.version
- # Too many different types of files to filter for now
- ../../doc/manual
- ./.
- ])
- # Do a blacklist instead
- ../../doc/manual/package.nix;
+ fileset =
+ fileset.difference
+ (fileset.unions [
+ ../../.version
+ # Too many different types of files to filter for now
+ ../../doc/manual
+ ./.
+ ])
+ # Do a blacklist instead
+ ../../doc/manual/package.nix;
# TODO the man pages should probably be separate
- outputs = [ "out" "man" ];
+ outputs = [
+ "out"
+ "man"
+ ];
# Hack for sake of the dev shell
passthru.externalNativeBuildInputs = [
@@ -54,11 +59,10 @@ mkMesonDerivation (finalAttrs: {
nix-cli
];
- preConfigure =
- ''
- chmod u+w ./.version
- echo ${finalAttrs.version} > ./.version
- '';
+ preConfigure = ''
+ chmod u+w ./.version
+ echo ${finalAttrs.version} > ./.version
+ '';
postInstall = ''
mkdir -p ''$out/nix-support
diff --git a/doc/manual/redirects.js b/doc/manual/redirects.js
index dea141391df..17fb66f2870 100644
--- a/doc/manual/redirects.js
+++ b/doc/manual/redirects.js
@@ -346,6 +346,9 @@ const redirects = {
"scoping-rules": "scoping.html",
"string-literal": "string-literals.html",
},
+ "language/derivations.md": {
+ "builder-execution": "store/drv/building.md#builder-execution",
+ },
"installation/installing-binary.html": {
"linux": "uninstall.html#linux",
"macos": "uninstall.html#macos",
@@ -372,6 +375,7 @@ const redirects = {
"glossary.html": {
"gloss-local-store": "store/types/local-store.html",
"gloss-chroot-store": "store/types/local-store.html",
+ "gloss-content-addressed-derivation": "#gloss-content-addressing-derivation",
},
};
diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in
index 69dbd841904..e7427232825 100644
--- a/doc/manual/source/SUMMARY.md.in
+++ b/doc/manual/source/SUMMARY.md.in
@@ -22,6 +22,8 @@
- [Store Object](store/store-object.md)
- [Content-Addressing Store Objects](store/store-object/content-address.md)
- [Store Path](store/store-path.md)
+ - [Store Derivation and Deriving Path](store/drv.md)
+ - [Building](store/building.md)
- [Store Types](store/types/index.md)
{{#include ./store/types/SUMMARY.md}}
- [Nix Language](language/index.md)
diff --git a/doc/manual/source/architecture/architecture.md b/doc/manual/source/architecture/architecture.md
index 867a9c992d3..cbc469355f8 100644
--- a/doc/manual/source/architecture/architecture.md
+++ b/doc/manual/source/architecture/architecture.md
@@ -69,7 +69,7 @@ It can also execute build plans to produce new data, which are made available to
A build plan itself is a series of *build tasks*, together with their build inputs.
> **Important**
-> A build task in Nix is called [derivation](@docroot@/glossary.md#gloss-derivation).
+> A build task in Nix is called [store derivation](@docroot@/glossary.md#gloss-store-derivation).
Each build task has a special build input executed as *build instructions* in order to perform the build.
The result of a build task can be input to another build task.
diff --git a/doc/manual/source/command-ref/nix-env/install.md b/doc/manual/source/command-ref/nix-env/install.md
index aa5c2fbba83..527fd8f90d8 100644
--- a/doc/manual/source/command-ref/nix-env/install.md
+++ b/doc/manual/source/command-ref/nix-env/install.md
@@ -22,11 +22,11 @@ It is based on the current generation of the active [profile](@docroot@/command-
The arguments *args* map to store paths in a number of possible ways:
-- By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression].
+- By default, *args* is a set of names denoting derivations in the [default Nix expression].
These are [realised], and the resulting output paths are installed.
Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
- [derivation]: @docroot@/glossary.md#gloss-derivation
+ [derivation expression]: @docroot@/glossary.md#gloss-derivation-expression
[default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
[realised]: @docroot@/glossary.md#gloss-realise
@@ -66,11 +66,11 @@ The arguments *args* map to store paths in a number of possible ways:
This can be used to override the priority of the derivations being installed.
This is useful if *args* are [store paths], which don't have any priority information.
-- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
+- If *args* are [store paths] that point to [store derivations][store derivation], then those store derivations are [realised], and the resulting output paths are installed.
-- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
+- If *args* are [store paths] that do not point to store derivations, then these are [realised] and installed.
-- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
+- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [store derivation].
This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
Example:
@@ -122,6 +122,8 @@ The arguments *args* map to store paths in a number of possible ways:
manifest.nix
```
+[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+
# Options
- `--prebuilt-only` / `-b`
diff --git a/doc/manual/source/command-ref/nix-env/query.md b/doc/manual/source/command-ref/nix-env/query.md
index c67794ed58e..bde9b38202c 100644
--- a/doc/manual/source/command-ref/nix-env/query.md
+++ b/doc/manual/source/command-ref/nix-env/query.md
@@ -125,7 +125,10 @@ derivation is shown unless `--no-name` is specified.
- `--drv-path`
- Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
+ Print the [store path] to the [store derivation].
+
+ [store path]: @docroot@/glossary.md#gloss-store-path
+ [store derivation]: @docroot@/glossary.md#gloss-derivation
- `--out-path`
diff --git a/doc/manual/source/command-ref/nix-hash.md b/doc/manual/source/command-ref/nix-hash.md
index f249c2b84d6..0860f312d94 100644
--- a/doc/manual/source/command-ref/nix-hash.md
+++ b/doc/manual/source/command-ref/nix-hash.md
@@ -67,7 +67,7 @@ md5sum`.
- `--type` *hashAlgo*
Use the specified cryptographic hash algorithm, which can be one of
- `md5`, `sha1`, `sha256`, and `sha512`.
+ `blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
- `--to-base16`
diff --git a/doc/manual/source/command-ref/nix-instantiate.md b/doc/manual/source/command-ref/nix-instantiate.md
index 487ef8f102f..38454515d57 100644
--- a/doc/manual/source/command-ref/nix-instantiate.md
+++ b/doc/manual/source/command-ref/nix-instantiate.md
@@ -42,8 +42,8 @@ standard input.
- `--eval`
Just parse and evaluate the input files, and print the resulting
- values on standard output. No instantiation of store derivations
- takes place.
+ values on standard output.
+ Store derivations are not serialized and written to the store, but instead just hashed and discarded.
> **Warning**
>
diff --git a/doc/manual/source/command-ref/nix-prefetch-url.md b/doc/manual/source/command-ref/nix-prefetch-url.md
index ffab94b8afa..19322ec8e04 100644
--- a/doc/manual/source/command-ref/nix-prefetch-url.md
+++ b/doc/manual/source/command-ref/nix-prefetch-url.md
@@ -42,7 +42,7 @@ the path of the downloaded file in the Nix store is also printed.
- `--type` *hashAlgo*
Use the specified cryptographic hash algorithm,
- which can be one of `md5`, `sha1`, `sha256`, and `sha512`.
+ which can be one of `blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
The default is `sha256`.
- `--print-path`
diff --git a/doc/manual/source/command-ref/nix-store/realise.md b/doc/manual/source/command-ref/nix-store/realise.md
index a899758dfab..240685ce5c7 100644
--- a/doc/manual/source/command-ref/nix-store/realise.md
+++ b/doc/manual/source/command-ref/nix-store/realise.md
@@ -15,7 +15,7 @@ Each of *paths* is processed as follows:
1. If it is not [valid], substitute the store derivation file itself.
2. Realise its [output paths]:
- Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure].
- - With [content-addressed derivations] (experimental):
+ - With [content-addressing derivations] (experimental):
Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database].
- For any store paths that cannot be substituted, produce the required store objects:
1. Realise all outputs of the derivation's dependencies
@@ -32,7 +32,7 @@ If no substitutes are available and no store derivation is given, realisation fa
[store objects]: @docroot@/store/store-object.md
[closure]: @docroot@/glossary.md#gloss-closure
[substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
-[content-addressed derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
+[content-addressing derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
[Nix database]: @docroot@/glossary.md#gloss-nix-database
The resulting paths are printed on standard output.
diff --git a/doc/manual/source/development/building.md b/doc/manual/source/development/building.md
index 409294682e9..c5a173dc744 100644
--- a/doc/manual/source/development/building.md
+++ b/doc/manual/source/development/building.md
@@ -79,7 +79,7 @@ This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` im
To get a shell with one of the other [supported compilation environments](#compilation-environments):
```console
-$ nix develop .#native-clangStdenvPackages
+$ nix develop .#native-clangStdenv
```
> **Note**
@@ -167,24 +167,18 @@ It is useful to perform multiple cross and native builds on the same source tree
for example to ensure that better support for one platform doesn't break the build for another.
Meson thankfully makes this very easy by confining all build products to the build directory --- one simple shares the source directory between multiple build directories, each of which contains the build for Nix to a different platform.
-Nixpkgs's `configurePhase` always chooses `build` in the current directory as the name and location of the build.
-This makes having multiple build directories slightly more inconvenient.
-The good news is that Meson/Ninja seem to cope well with relocating the build directory after it is created.
+Here's how to do that:
-Here's how to do that
-
-1. Configure as usual
+1. Instruct Nixpkgs's infra where we want Meson to put its build directory
```bash
- configurePhase
+ mesonBuildDir=build-my-variant-name
```
-2. Rename the build directory
+1. Configure as usual
```bash
- cd .. # since `configurePhase` cd'd inside
- mv build build-linux # or whatever name we want
- cd build-linux
+ configurePhase
```
3. Build as usual
@@ -193,10 +187,6 @@ Here's how to do that
buildPhase
```
-> **N.B.**
-> [`nixpkgs#335818`](https://github.com/NixOS/nixpkgs/issues/335818) tracks giving `mesonConfigurePhase` proper support for custom build directories.
-> When it is fixed, we can simplify these instructions and then remove this notice.
-
## System type
Nix uses a string with the following format to identify the *system type* or *platform* it runs on:
@@ -261,7 +251,8 @@ See [supported compilation environments](#compilation-environments) and instruct
To use the LSP with your editor, you will want a `compile_commands.json` file telling `clangd` how we are compiling the code.
Meson's configure always produces this inside the build directory.
-Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages` shell. You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
+Configure your editor to use the `clangd` from the `.#native-clangStdenv` shell.
+You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
> **Note**
>
@@ -277,6 +268,8 @@ You may run the formatters as a one-off using:
./maintainers/format.sh
```
+### Pre-commit hooks
+
If you'd like to run the formatters before every commit, install the hooks:
```
@@ -291,3 +284,30 @@ If it fails, run `git add --patch` to approve the suggestions _and commit again_
To refresh pre-commit hook's config file, do the following:
1. Exit the development shell and start it again by running `nix develop`.
2. If you also use the pre-commit hook, also run `pre-commit-hooks-install` again.
+
+### VSCode
+
+Insert the following json into your `.vscode/settings.json` file to configure `nixfmt`.
+This will be picked up by the _Format Document_ command, `"editor.formatOnSave"`, etc.
+
+```json
+{
+ "nix.formatterPath": "nixfmt",
+ "nix.serverSettings": {
+ "nixd": {
+ "formatting": {
+ "command": [
+ "nixfmt"
+ ],
+ },
+ },
+ "nil": {
+ "formatting": {
+ "command": [
+ "nixfmt"
+ ],
+ },
+ },
+ },
+}
+```
diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md
index ce623110b36..98456841af1 100644
--- a/doc/manual/source/development/debugging.md
+++ b/doc/manual/source/development/debugging.md
@@ -2,6 +2,8 @@
This section shows how to build and debug Nix with debug symbols enabled.
+Additionally, see [Testing Nix](./testing.md) for further instructions on how to debug Nix in the context of a unit test or functional test.
+
## Building Nix with Debug Symbols
In the development shell, set the `mesonBuildType` environment variable to `debug` before configuring the build:
@@ -13,6 +15,15 @@ In the development shell, set the `mesonBuildType` environment variable to `debu
Then, proceed to build Nix as described in [Building Nix](./building.md).
This will build Nix with debug symbols, which are essential for effective debugging.
+It is also possible to build without debugging for faster build:
+
+```console
+[nix-shell]$ NIX_HARDENING_ENABLE=$(printLines $NIX_HARDENING_ENABLE | grep -v fortify)
+[nix-shell]$ export mesonBuildType=debug
+```
+
+(The first line is needed because `fortify` hardening requires at least some optimization.)
+
## Debugging the Nix Binary
Obtain your preferred debugger within the development shell:
diff --git a/doc/manual/source/development/testing.md b/doc/manual/source/development/testing.md
index d582ce4b413..d0c3a1c784e 100644
--- a/doc/manual/source/development/testing.md
+++ b/doc/manual/source/development/testing.md
@@ -87,7 +87,11 @@ A environment variables that Google Test accepts are also worth knowing:
This is used to avoid logging passing tests.
-Putting the two together, one might run
+3. [`GTEST_BREAK_ON_FAILURE`](https://google.github.io/googletest/advanced.html#turning-assertion-failures-into-break-points)
+
+ This is used to create a debugger breakpoint when an assertion failure occurs.
+
+Putting the first two together, one might run
```bash
GTEST_BRIEF=1 GTEST_FILTER='ErrorTraceTest.*' meson test nix-expr-tests -v
@@ -95,6 +99,22 @@ GTEST_BRIEF=1 GTEST_FILTER='ErrorTraceTest.*' meson test nix-expr-tests -v
for short but comprensive output.
+### Debugging tests
+
+For debugging, it is useful to combine the third option above with Meson's [`--gdb`](https://mesonbuild.com/Unit-tests.html#other-test-options) flag:
+
+```bash
+GTEST_BRIEF=1 GTEST_FILTER='Group.my-failing-test' meson test nix-expr-tests --gdb
+```
+
+This will:
+
+1. Run the unit test with GDB
+
+2. Run just `Group.my-failing-test`
+
+3. Stop the program when the test fails, allowing the user to then issue arbitrary commands to GDB.
+
### Characterisation testing { #characaterisation-testing-unit }
See [functional characterisation testing](#characterisation-testing-functional) for a broader discussion of characterisation testing.
@@ -144,7 +164,7 @@ $ checkPhase
Sometimes it is useful to group related tests so they can be easily run together without running the entire test suite.
Each test group is in a subdirectory of `tests`.
-For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressed derivation outputs.
+For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressing derivation outputs.
That test group can be run like this:
@@ -213,10 +233,10 @@ edit it like so:
bar
```
-Then, running the test with `./mk/debug-test.sh` will drop you into GDB once the script reaches that point:
+Then, running the test with [`--interactive`](https://mesonbuild.com/Unit-tests.html#other-test-options) will prevent Meson from hijacking the terminal so you can drop you into GDB once the script reaches that point:
```shell-session
-$ ./mk/debug-test.sh tests/functional/${testName}.sh
+$ meson test ${testName} --interactive
...
+ gdb blash blub
GNU gdb (GDB) 12.1
diff --git a/doc/manual/source/glossary.md b/doc/manual/source/glossary.md
index fa357ece3d6..a1964070588 100644
--- a/doc/manual/source/glossary.md
+++ b/doc/manual/source/glossary.md
@@ -13,37 +13,41 @@
- [Content-Addressing File System Objects](@docroot@/store/file-system-object/content-address.md)
- [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md)
- - [content-addressed derivation](#gloss-content-addressed-derivation)
+ - [content-addressing derivation](#gloss-content-addressing-derivation)
Software Heritage's writing on [*Intrinsic and Extrinsic identifiers*](https://www.softwareheritage.org/2020/07/09/intrinsic-vs-extrinsic-identifiers) is also a good introduction to the value of content-addressing over other referencing schemes.
Besides content addressing, the Nix store also uses [input addressing](#gloss-input-addressed-store-object).
-- [derivation]{#gloss-derivation}
+- [store derivation]{#gloss-store-derivation}
- A description of a build task. The result of a derivation is a
- store object. Derivations declared in Nix expressions are specified
- using the [`derivation` primitive](./language/derivations.md). These are
- translated into low-level *store derivations* (implicitly by
- `nix-build`, or explicitly by `nix-instantiate`).
+ A single build task.
+ See [Store Derivation](@docroot@/store/drv.md#store-derivation) for details.
- [derivation]: #gloss-derivation
+ [store derivation]: #gloss-store-derivation
-- [store derivation]{#gloss-store-derivation}
+- [derivation path]{#gloss-derivation-path}
- A [derivation] represented as a `.drv` file in the [store].
- It has a [store path], like any [store object].
- It is the [instantiated][instantiate] form of a derivation.
+ A [store path] which uniquely identifies a [store derivation].
- Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
+ See [Referencing Store Derivations](@docroot@/store/drv.md#derivation-path) for details.
- See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations.
+ Not to be confused with [deriving path].
- [store derivation]: #gloss-store-derivation
+ [derivation path]: #gloss-derivation-path
+
+- [derivation expression]{#gloss-derivation-expression}
+
+ A description of a [store derivation] in the Nix language.
+ The output(s) of a derivation are store objects.
+ Derivations are typically specified in Nix expressions using the [`derivation` primitive](./language/derivations.md).
+ These are translated into store layer *derivations* (implicitly by `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
+
+ [derivation expression]: #gloss-derivation-expression
- [instantiate]{#gloss-instantiate}, instantiation
- Save an evaluated [derivation] as a [store derivation] in the Nix [store].
+ Translate a [derivation expression] into a [store derivation].
See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation.
@@ -55,7 +59,7 @@
This can be achieved by:
- Fetching a pre-built [store object] from a [substituter]
- - Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation]
+ - Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [store derivation]
- Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs
@@ -65,7 +69,7 @@
[realise]: #gloss-realise
-- [content-addressed derivation]{#gloss-content-addressed-derivation}
+- [content-addressing derivation]{#gloss-content-addressing-derivation}
A derivation which has the
[`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
@@ -73,7 +77,7 @@
- [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD)
- A [derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
+ A [store derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
- [store]{#gloss-store}
@@ -130,7 +134,7 @@
- [input-addressed store object]{#gloss-input-addressed-store-object}
A store object produced by building a
- non-[content-addressed](#gloss-content-addressed-derivation),
+ non-[content-addressed](#gloss-content-addressing-derivation),
non-[fixed-output](#gloss-fixed-output-derivation)
derivation.
@@ -138,7 +142,7 @@
A [store object] which is [content-addressed](#gloss-content-address),
i.e. whose [store path] is determined by its contents.
- This includes derivations, the outputs of [content-addressed derivations](#gloss-content-addressed-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
+ This includes derivations, the outputs of [content-addressing derivations](#gloss-content-addressing-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
See [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md) for details.
@@ -188,7 +192,7 @@
>
> The contents of a `.nix` file form a Nix expression.
- Nix expressions specify [derivations][derivation], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
+ Nix expressions specify [derivation expressions][derivation expression], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
These derivations can then be [realised][realise] to produce [outputs][output].
> **Example**
@@ -230,14 +234,14 @@
- [output]{#gloss-output}
- A [store object] produced by a [derivation].
+ A [store object] produced by a [store derivation].
See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details.
[output]: #gloss-output
- [output path]{#gloss-output-path}
- The [store path] to the [output] of a [derivation].
+ The [store path] to the [output] of a [store derivation].
[output path]: #gloss-output-path
@@ -246,14 +250,11 @@
- [deriving path]{#gloss-deriving-path}
- Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
- This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
- There are two forms:
+ Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
- - *constant*: just a [store path]
- It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
+ See [Deriving Path](./store/drv.md#deriving-path) for details.
- - *output*: a pair of a [store path] to a [derivation] and an [output] name.
+ Not to be confused with [derivation path].
- [deriver]{#gloss-deriver}
diff --git a/doc/manual/source/language/advanced-attributes.md b/doc/manual/source/language/advanced-attributes.md
index 51b83fc8acc..c384e956af6 100644
--- a/doc/manual/source/language/advanced-attributes.md
+++ b/doc/manual/source/language/advanced-attributes.md
@@ -192,7 +192,7 @@ Derivations can declare some infrequently used optional attributes.
The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings, and the [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
- It can currently be `"sha1"`, `"sha256"`, `"sha512"`, or `null`.
+ It can currently be `"blake3", "sha1"`, `"sha256"`, `"sha512"`, or `null`.
`outputHashAlgo` can only be `null` when `outputHash` follows the SRI format.
The `outputHashMode` attribute determines how the hash is computed.
diff --git a/doc/manual/source/language/derivations.md b/doc/manual/source/language/derivations.md
index 771b2bd9130..0f9284e9844 100644
--- a/doc/manual/source/language/derivations.md
+++ b/doc/manual/source/language/derivations.md
@@ -1,9 +1,10 @@
# Derivations
-The most important built-in function is `derivation`, which is used to describe a single derivation:
-a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths.
+The most important built-in function is `derivation`, which is used to describe a single store-layer [store derivation].
+Consult the [store chapter](@docroot@/store/drv.md) for what a store derivation is;
+this section just concerns how to create one from the Nix language.
-It takes as input an attribute set, the attributes of which specify the inputs to the process.
+This builtin function takes as input an attribute set, the attributes of which specify the inputs to the process.
It outputs an attribute set, and produces a [store derivation] as a side effect of evaluation.
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
@@ -15,7 +16,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
- [`name`]{#attr-name} ([String](@docroot@/language/types.md#type-string))
A symbolic name for the derivation.
- It is added to the [store path] of the corresponding [store derivation] as well as to its [output paths](@docroot@/glossary.md#gloss-output-path).
+ See [derivation outputs](@docroot@/store/drv.md#outputs) for what this is affects.
[store path]: @docroot@/store/store-path.md
@@ -28,17 +29,12 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
> }
> ```
>
- > The store derivation's path will be `/nix/store/-hello.drv`.
+ > The derivation's path will be `/nix/store/-hello.drv`.
> The [output](#attr-outputs) paths will be of the form `/nix/store/-hello[-