diff --git a/.clang-tidy b/.clang-tidy
deleted file mode 100644
index 0887b867087a..000000000000
--- a/.clang-tidy
+++ /dev/null
@@ -1,3 +0,0 @@
-# We use pointers to aggregates in a couple of places, intentionally.
-# void * would look weird.
-Checks: '-bugprone-sizeof-expression'
diff --git a/.clang-tidy b/.clang-tidy
new file mode 120000
index 000000000000..871c4b83d57d
--- /dev/null
+++ b/.clang-tidy
@@ -0,0 +1 @@
+nix-meson-build-support/common/clang-tidy/.clang-tidy
\ No newline at end of file
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 5ace4600a1f2..1880a89da556 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -4,3 +4,11 @@ updates:
directory: "/"
schedule:
interval: "weekly"
+ - package-ecosystem: "nix"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+ groups:
+ flake-inputs:
+ patterns:
+ - "*"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 96f0c44671e6..133d19c2173c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -157,7 +157,7 @@ jobs:
run: mkdir -p ./artifacts
- name: Fetch artifacts
- uses: actions/download-artifact@v7
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
with:
path: downloaded
- name: Move downloaded artifacts to artifacts directory
diff --git a/.gitignore b/.gitignore
index 96c134335232..c0d09b7e189c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,23 +2,8 @@
/build
# Meson creates this file too
src/.wraplock
-
-# /tests/functional/
-/tests/functional/common/subst-vars.sh
-/tests/functional/restricted-innocent
-/tests/functional/debugger-test-out
-/tests/functional/test-libstoreconsumer/test-libstoreconsumer
-/tests/functional/nix-shell
-
-# /tests/functional/lang/
-/tests/functional/lang/*.out
-/tests/functional/lang/*.out.xml
-/tests/functional/lang/*.err
-/tests/functional/lang/*.ast
-
-# /tests/functional/cli-characterisation/
-/tests/functional/cli-characterisation/*.out
-/tests/functional/cli-characterisation/*.err
+# Python bytecode (clang-tidy runner scripts)
+__pycache__/
/outputs
diff --git a/.version b/.version
index fb61f64bad1e..d07233cc933c 100644
--- a/.version
+++ b/.version
@@ -1 +1 @@
-2.34.8
+2.35.1
diff --git a/ci/gha/tests/default.nix b/ci/gha/tests/default.nix
index 7d206750fcfe..94327adc9f0d 100644
--- a/ci/gha/tests/default.nix
+++ b/ci/gha/tests/default.nix
@@ -57,8 +57,6 @@ rec {
nix-expr = prev.nix-expr.override { enableGC = !withSanitizers; };
mesonComponentOverrides = lib.composeManyExtensions componentOverrides;
- # Unclear how to make Perl bindings work with a dynamically linked ASAN.
- nix-perl-bindings = if withSanitizers then null else prev.nix-perl-bindings;
}
);
@@ -78,6 +76,7 @@ rec {
installerScriptForGHA = hydraJobs.installerScriptForGHA.${system};
nixpkgsLibTests = hydraJobs.tests.nixpkgsLibTests.${system};
nixpkgsLibTestsLazy = hydraJobs.tests.nixpkgsLibTestsLazy.${system};
+ filetransfer-retry-backoff = hydraJobs.tests.filetransfer-retry-backoff.${system};
rl-next = pkgs.buildPackages.runCommand "test-rl-next-release-notes" { } ''
LANG=C.UTF-8 ${pkgs.changelog-d}/bin/changelog-d ${../../../doc/manual/rl-next} >$out
'';
diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
index e66611affe08..a58d4f79e132 100644
--- a/doc/manual/generate-store-info.nix
+++ b/doc/manual/generate-store-info.nix
@@ -46,10 +46,12 @@ let
## Settings
- ${showSettings {
- prefix = "store-${slug}";
- inherit inlineHTML;
- } settings}
+ ${replaceStrings [ "@store-slug@" ] [ "store-${slug}" ] (
+ showSettings {
+ prefix = "store-${slug}";
+ inherit inlineHTML;
+ } settings
+ )}
'';
experimentalFeatureNote = optionalString (experimentalFeature != null) ''
diff --git a/doc/manual/meson.build b/doc/manual/meson.build
index d842fe30ea0a..1edf11afc1f4 100644
--- a/doc/manual/meson.build
+++ b/doc/manual/meson.build
@@ -1,7 +1,7 @@
project(
'nix-manual',
version : files('.version'),
- meson_version : '>= 1.1',
+ meson_version : '>= 1.8',
license : 'LGPL-2.1-or-later',
)
@@ -231,7 +231,9 @@ foreach command : nix_nested_manpages
meson.current_source_dir() / 'source',
meson.current_build_dir() / 'source',
doc_url,
- meson.current_source_dir() / 'source/command-ref' / command[0] / (page + '.md'),
+ meson.current_source_dir() / 'source/command-ref' / command[0] / (
+ page + '.md'
+ ),
'@OUTPUT0@',
],
input : [
@@ -320,8 +322,6 @@ nix3_manpages = [
'nix3-provenance-show',
'nix3-provenance-verify',
'nix3-ps',
- 'nix3-realisation',
- 'nix3-realisation-info',
'nix3-registry',
'nix3-registry-add',
'nix3-registry-list',
@@ -336,6 +336,8 @@ nix3_manpages = [
'nix3-store-add',
'nix3-store-add-file',
'nix3-store-add-path',
+ 'nix3-store-build-trace-info',
+ 'nix3-store-build-trace',
'nix3-store-cat',
'nix3-store-copy-log',
'nix3-store-copy-sigs',
diff --git a/doc/manual/package.nix b/doc/manual/package.nix
index 9e69156ac0ca..c66163e285e3 100644
--- a/doc/manual/package.nix
+++ b/doc/manual/package.nix
@@ -145,6 +145,21 @@ mkMesonDerivation (finalAttrs: {
# Exclude undocumented builtins
".*/language/builtins\\.html#builtins-addErrorContext"
".*/language/builtins\\.html#builtins-appendContext"
+ # `print.html` aggregates content from all pages, including
+ # the JSON schema pages and builtins pages excluded above,
+ # so it inherits the same broken fragment links.
+ ".*/print\\.html#algorithm"
+ ".*/print\\.html#root"
+ ".*/print\\.html#builtins-addErrorContext"
+ ".*/print\\.html#builtins-appendContext"
+ ".*/print\\.html#derivations_pattern1_structuredAttrs_additionalProperties"
+ ".*/print\\.html#structuredAttrs_additionalProperties"
+ ];
+ # `404.html` uses `` so that absolute links
+ # work on the deployed site. Lychee cannot resolve `/` against
+ # a local file path, so skip the file entirely.
+ exclude_path = [
+ ".*/404\\.html"
];
};
};
diff --git a/doc/manual/redirects.json b/doc/manual/redirects.json
index 07a6f36627ff..76ce242178f3 100644
--- a/doc/manual/redirects.json
+++ b/doc/manual/redirects.json
@@ -283,7 +283,7 @@
"string-literal": "string-literals.html"
},
"language/derivations.html": {
- "builder-execution": "../store/building.html#builder-execution"
+ "builder-execution": "../store/building.html"
},
"installation/installing-binary.html": {
"uninstalling": "uninstall.html"
@@ -297,7 +297,6 @@
"debugging-failing-functional-tests": "testing.html#debugging-failing-functional-tests",
"integration-tests": "testing.html#integration-tests",
"installer-tests": "testing.html#installer-tests",
- "one-time-setup": "testing.html#one-time-setup",
"using-the-ci-generated-installer-for-manual-testing":
"testing.html#using-the-ci-generated-installer-for-manual-testing",
"characterization-testing": "testing.html#characterisation-testing-unit",
@@ -307,6 +306,9 @@
"reverting": "contributing.html#reverting",
"branches": "contributing.html#branches"
},
+ "store/store-path.html": {
+ "store-directory": "#store-directory-path"
+ },
"glossary.html": {
"gloss-local-store": "store/types/local-store.html",
"package-attribute-set": "#package",
diff --git a/doc/manual/remove_before_wrapper.py b/doc/manual/remove_before_wrapper.py
index 6da4c19b0ce7..a0fcb6a55776 100644
--- a/doc/manual/remove_before_wrapper.py
+++ b/doc/manual/remove_before_wrapper.py
@@ -22,7 +22,7 @@ def main():
shutil.rmtree(output, ignore_errors=True)
shutil.rmtree(output_temp, ignore_errors=True)
- # Execute nix command with `--write-to` tempary output
+ # Execute nix command with `--write-to` temporary output
nix_command_write_to = nix_command + ['--write-to', output_temp]
subprocess.run(nix_command_write_to, check=True)
diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in
index 7b5bf0a8b0cf..e808ca66b887 100644
--- a/doc/manual/source/SUMMARY.md.in
+++ b/doc/manual/source/SUMMARY.md.in
@@ -14,9 +14,10 @@
- [Nix Store](store/index.md)
- [File System Object](store/file-system-object.md)
- [Content-Addressing File System Objects](store/file-system-object/content-address.md)
+ - [Exposing in OS File Systems](store/file-system-object/os-file-system.md)
- [Store Object](store/store-object.md)
- [Content-Addressing Store Objects](store/store-object/content-address.md)
- - [Store Path](store/store-path.md)
+ - [Store Path and Store Directory](store/store-path.md)
- [Store Derivation and Deriving Path](store/derivation/index.md)
- [Derivation Outputs and Types of Derivations](store/derivation/outputs/index.md)
- [Content-addressing derivation outputs](store/derivation/outputs/content-address.md)
@@ -118,8 +119,10 @@
- [Hash](protocols/json/hash.md)
- [Content Address](protocols/json/content-address.md)
- [Store Path](protocols/json/store-path.md)
+ - [Signature](protocols/json/signature.md)
- [Store Object Info](protocols/json/store-object-info.md)
- [Derivation](protocols/json/derivation/index.md)
+ - [Resolved Derivation](protocols/json/derivation/resolved.md)
- [Derivation Options](protocols/json/derivation/options.md)
- [Deriving Path](protocols/json/deriving-path.md)
- [Build Trace Entry](protocols/json/build-trace-entry.md)
@@ -128,7 +131,9 @@
- [Serving Tarball Flakes](protocols/tarball-fetcher.md)
- [Store Path Specification](protocols/store-path.md)
- [Nix Archive (NAR) Format](protocols/nix-archive/index.md)
- - [Nix Cache Info Format](protocols/nix-cache-info.md)
+ - [Binary Cache](protocols/binary-cache/index.md)
+ - [`nix-cache-info` Format](protocols/binary-cache/nix-cache-info.md)
+ - [`.narinfo` Format](protocols/binary-cache/narinfo.md)
- [Derivation "ATerm" file format](protocols/derivation-aterm.md)
- [Nix32 Encoding](protocols/nix32.md)
- [`builtins.wasm` Host Interface](protocols/wasm.md)
@@ -142,8 +147,9 @@
- [Debugging](development/debugging.md)
- [Documentation](development/documentation.md)
- [CLI guideline](development/cli-guideline.md)
- - [JSON guideline](development/json-guideline.md)
+ - [Data Modeling Guidelines](development/data-modeling.md)
- [C++ style guide](development/cxx.md)
+ - [Static Analysis](development/static-analysis.md)
- [Experimental Features](development/experimental-features.md)
- [Contributing](development/contributing.md)
- [Determinate Nix Release Notes](release-notes-determinate/index.md)
@@ -211,6 +217,7 @@
- [Release 3.0.0 (2025-03-04)](release-notes-determinate/rl-3.0.0.md)
- [Nix Release Notes](release-notes/index.md)
{{#include ./SUMMARY-rl-next.md}}
+ - [Release 2.35 (2026-06-22)](release-notes/rl-2.35.md)
- [Release 2.34 (2026-02-27)](release-notes/rl-2.34.md)
- [Release 2.33 (2025-12-09)](release-notes/rl-2.33.md)
- [Release 2.32 (2025-10-06)](release-notes/rl-2.32.md)
diff --git a/doc/manual/source/_redirects b/doc/manual/source/_redirects
index 07b3130f9ce9..74815df282c8 100644
--- a/doc/manual/source/_redirects
+++ b/doc/manual/source/_redirects
@@ -27,7 +27,8 @@
/contributing/documentation /development/documentation 301!
/contributing/experimental-features /development/experimental-features 301!
/contributing/cli-guideline /development/cli-guideline 301!
-/contributing/json-guideline /development/json-guideline 301!
+/contributing/json-guideline /development/data-modeling 301!
+/development/json-guideline /development/data-modeling 301!
/contributing/cxx /development/cxx 301!
/expressions/expression-language /language/ 301!
@@ -36,6 +37,7 @@
/expressions/language-values /language/values 301!
/expressions/* /language/:splat 301!
/language/values /language/types 301!
+/language/values.html /language/types 301!
/language/constructs /language/syntax 301!
/language/builtin-constants /language/builtins 301!
@@ -46,6 +48,7 @@
/package-management/package-management /package-management 301!
/package-management/s3-substituter /store/types/s3-binary-cache-store 301!
+/protocols/nix-cache-info /protocols/binary-cache/nix-cache-info 301!
/protocols/protocols /protocols 301!
/json/* /protocols/json/:splat 301!
diff --git a/doc/manual/source/command-ref/conf-file-prefix.md b/doc/manual/source/command-ref/conf-file-prefix.md
index 627806cfbda8..53a3761fd4b1 100644
--- a/doc/manual/source/command-ref/conf-file-prefix.md
+++ b/doc/manual/source/command-ref/conf-file-prefix.md
@@ -8,19 +8,26 @@ Nix supports a variety of configuration settings, which are read from configurat
## Configuration file
-By default Nix reads settings from the following places, in that order:
+By default Nix reads settings from each of the following places.
+Settings are applied on top of one another, so later settings overwrite earlier entries.
-1. The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set.
+1. The system-wide configuration file `nix.conf` in the configuration directory.
+
+ The configuration directory defaults to `${sysconfdir}/nix` (i.e. `/etc/nix` on most Unix systems) or `%PROGRAMDATA%\nix\conf` on Windows, and can be overridden with [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR).
Values loaded in this file are not forwarded to the Nix daemon.
The client assumes that the daemon has already loaded them.
-1. If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order.
+1. If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path in the list will be loaded in reverse order.
+ The list separator is `:` on Unix and `;` on Windows.
+
+ Otherwise it will look for `nix.conf` in:
- Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and [`XDG_CONFIG_HOME`](./env-common.md#env-XDG_CONFIG_HOME).
- If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+ - The [user configuration directory](./env-common.md#user-conf-dir)
+ - On Unix additionally, `nix/nix.conf` under each directory in [`XDG_CONFIG_DIRS`](./env-common.md#env-XDG_CONFIG_DIRS)
1. If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file.
+ In particular, settings are separated by newlines, just as in the configuration file.
### File format
diff --git a/doc/manual/source/command-ref/env-common.md b/doc/manual/source/command-ref/env-common.md
index 35d682949ba8..cc7fe77eae56 100644
--- a/doc/manual/source/command-ref/env-common.md
+++ b/doc/manual/source/command-ref/env-common.md
@@ -1,34 +1,25 @@
# Common Environment Variables
-Most Nix commands interpret the following environment variables:
+Most Nix commands interpret the following environment variables.
-- [`IN_NIX_SHELL`](#env-IN_NIX_SHELL)
+## Configuration environment variables
- Indicator that tells if the current environment was set up by
- `nix-shell`. It can have the values `pure` or `impure`.
+The following environment variables affect how Nix loads its configuration.
+See the [configuration file](@docroot@/command-ref/conf-file.md#configuration-file) documentation for full details.
-- [`NIX_PATH`](#env-NIX_PATH)
+- [`NIX_CONF_DIR`](#env-NIX_CONF_DIR)
- A colon-separated list of search path entries used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
+ Overrides the system configuration directory.
- This environment variable overrides the value of the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path).
+- [`NIX_USER_CONF_FILES`](#env-NIX_USER_CONF_FILES)
- It can be extended using the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
+ Overrides the user configuration file locations.
- > **Example**
- >
- > ```bash
- > $ export NIX_PATH=`/home/eelco/Dev:nixos-config=/etc/nixos
- > ```
+- [`NIX_CONFIG`](#env-NIX_CONFIG)
- If `NIX_PATH` is set to an empty string, resolving search paths will always fail.
+ Provides configuration settings inline.
- > **Example**
- >
- > ```bash
- > $ NIX_PATH= nix-instantiate --eval ''
- > error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)
- > ```
+## Store setting environment variables
- [`NIX_IGNORE_SYMLINK_STORE`](#env-NIX_IGNORE_SYMLINK_STORE)
@@ -55,37 +46,34 @@ Most Nix commands interpret the following environment variables:
- [`NIX_STORE_DIR`](#env-NIX_STORE_DIR)
- Overrides the location of the Nix store (default `prefix/store`).
+ Overrides the location of the Nix store.
+ On Unix, the default is `/nix/store`, set at compile time by the `libstore:store-dir` build option.
+ On Windows, there is no compile-time setting; the default is `%PROGRAMDATA%\nix\store`, determined at runtime using the [`%PROGRAMDATA%` Known Folder](#known-folders).
-- [`NIX_LOG_DIR`](#env-NIX_LOG_DIR)
-
- Overrides the location of the Nix log directory (default
- `prefix/var/log/nix`).
+ See the [Store Types] chapter; each store has a `store` setting linking back to this as its default.
-- [`NIX_STATE_DIR`](#env-NIX_STATE_DIR)
-
- Overrides the location of the Nix state directory (default
- `prefix/var/nix`).
+- [`NIX_LOG_DIR`](#env-NIX_LOG_DIR)
-- [`NIX_CONF_DIR`](#env-NIX_CONF_DIR)
+ Overrides the location of the Nix log directory.
+ On Unix, the default is `/nix/var/log/nix`, set at compile time by the `log-dir` build option.
+ On Windows, there is no compile-time setting; the default is `%PROGRAMDATA%\nix\log`, determined at runtime using the [`%PROGRAMDATA%` Known Folder](#known-folders).
- Overrides the location of the system Nix configuration directory
- (default `sysconfdir/nix`, i.e. `/etc/nix` on most systems).
+ The [Local Store], [Local Daemon Store], and [Experimental SSH Store with filesystem mounted] have per-store settings that override this.
-- [`NIX_CONFIG`](#env-NIX_CONFIG)
+- [`NIX_STATE_DIR`](#env-NIX_STATE_DIR)
- Applies settings from Nix configuration from the environment.
- The content is treated as if it was read from a Nix configuration file.
- Settings are separated by the newline character.
+ Overrides the location of the Nix state directory.
+ On Unix, the default is `${localstatedir}/nix`, where `localstatedir` is a compile-time build option defaulting to `/nix/var`.
+ On Windows, there is no compile-time setting; the default is `%PROGRAMDATA%\nix\state`, determined at runtime using the [`%PROGRAMDATA%` Known Folder](#known-folders).
-- [`NIX_USER_CONF_FILES`](#env-NIX_USER_CONF_FILES)
+ The [Local Store], [Local Daemon Store], and [Experimental SSH Store with filesystem mounted] have per-store settings that override this.
- Overrides the location of the Nix user configuration files to load from.
+- [`NIX_DAEMON_SOCKET_PATH`](#env-NIX_DAEMON_SOCKET_PATH)
- The default are the locations according to the [XDG Base Directory Specification].
- See the [XDG Base Directories](#xdg-base-directories) sub-section for details.
+ Overrides the path to the Unix domain socket used to communicate with the Nix daemon.
+ Defaults to `daemon-socket/socket` within the state directory (see [`NIX_STATE_DIR`](#env-NIX_STATE_DIR)).
- The variable is treated as a list separated by the `:` token.
+ See the [Local Daemon Store] documentation for details on how the socket path is resolved.
- [`TMPDIR`](#env-TMPDIR)
@@ -95,12 +83,15 @@ Most Nix commands interpret the following environment variables:
- [`NIX_REMOTE`](#env-NIX_REMOTE)
- This variable should be set to `daemon` if you want to use the Nix
- daemon to execute Nix operations. This is necessary in [multi-user
- Nix installations](@docroot@/installation/nix-security.md#multi-user-model). If the Nix
- daemon's Unix socket is at some non-standard path, this variable
- should be set to `unix://path/to/socket`. Otherwise, it should be
- left unset.
+ Overrides the [`store`](@docroot@/command-ref/conf-file.md#conf-store) setting.
+
+[Store Types]: @docroot@/store/types/index.md
+[store URL format]: @docroot@/store/types/index.md#store-url-format
+[Local Store]: @docroot@/store/types/local-store.md
+[Local Daemon Store]: @docroot@/store/types/local-daemon-store.md
+[Experimental SSH Store with filesystem mounted]: @docroot@/store/types/experimental-ssh-store-with-filesystem-mounted.md
+
+## Nix language evaluator settings
- [`NIX_SHOW_STATS`](#env-NIX_SHOW_STATS)
@@ -120,32 +111,87 @@ Most Nix commands interpret the following environment variables:
384 MiB. Setting it to a low value reduces memory consumption, but
will increase runtime due to the overhead of garbage collection.
-## XDG Base Directories
+- [`NIX_PATH`](#env-NIX_PATH)
-Nix follows the [XDG Base Directory Specification].
+ A colon-separated list of search path entries used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
-For backwards compatibility, Nix commands will follow the standard only when [`use-xdg-base-directories`] is enabled.
-[New Nix commands](@docroot@/command-ref/new-cli/nix.md) (experimental) conform to the standard by default.
+ This environment variable overrides the value of the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path).
-The following environment variables are used to determine locations of various state and configuration files:
+ It can be extended using the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
-- [`XDG_CONFIG_HOME`]{#env-XDG_CONFIG_HOME} (default `~/.config`)
-- [`XDG_STATE_HOME`]{#env-XDG_STATE_HOME} (default `~/.local/state`)
-- [`XDG_CACHE_HOME`]{#env-XDG_CACHE_HOME} (default `~/.cache`)
+ > **Example**
+ >
+ > ```bash
+ > $ export NIX_PATH=/home/eelco/Dev:nixos-config=/etc/nixos
+ > ```
-[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
-[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
+ If `NIX_PATH` is set to an empty string, resolving search paths will always fail.
+
+ > **Example**
+ >
+ > ```bash
+ > $ NIX_PATH= nix-instantiate --eval ''
+ > error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)
+ > ```
+
+## User Directories
+
+Nix supports per-user **configuration**, **state**, and **cache** directories.
+The following environment variables override the locations for these directories:
+
+- [user configuration directory]{#user-conf-dir}: [`NIX_CONFIG_HOME`]{#env-NIX_CONFIG_HOME}
+- user state directory: [`NIX_STATE_HOME`]{#env-NIX_STATE_HOME}
+- user cache directory: [`NIX_CACHE_HOME`]{#env-NIX_CACHE_HOME}
-In addition, setting the following environment variables overrides the XDG base directories:
+When these are not set, the defaults depend on the platform:
-- [`NIX_CONFIG_HOME`]{#env-NIX_CONFIG_HOME} (default `$XDG_CONFIG_HOME/nix`)
-- [`NIX_STATE_HOME`]{#env-NIX_STATE_HOME} (default `$XDG_STATE_HOME/nix`)
-- [`NIX_CACHE_HOME`]{#env-NIX_CACHE_HOME} (default `$XDG_CACHE_HOME/nix`)
+- On Unix, the [XDG base directories](#xdg-base-directories): `$XDG_CONFIG_HOME/nix`, `$XDG_STATE_HOME/nix`, `$XDG_CACHE_HOME/nix`
+- On Windows, the [Windows Known Folders](#known-folders): `%APPDATA%\nix\config`, `%LOCALAPPDATA%\nix\state`, `%LOCALAPPDATA%\nix\cache`
-When [`use-xdg-base-directories`] is enabled, the configuration directory is:
+[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
+
+For backwards compatibility, legacy Nix commands (e.g. `nix-env`, `nix-channel`) use dotfiles in `$HOME` instead of these directories unless [`use-xdg-base-directories`] is enabled.
+[New Nix commands](@docroot@/command-ref/new-cli/nix.md) (experimental) use the proper directories by default.
+
+When [`use-xdg-base-directories`] is enabled, the configuration directory is resolved as:
1. `$NIX_CONFIG_HOME`, if it is defined
-2. Otherwise, `$XDG_CONFIG_HOME/nix`, if `XDG_CONFIG_HOME` is defined
-3. Otherwise, `~/.config/nix`.
+2. Otherwise, the platform default (e.g. `$XDG_CONFIG_HOME/nix` on Unix)
Likewise for the state and cache directories.
+
+## Miscellaneous environment variables
+
+- [`IN_NIX_SHELL`](#env-IN_NIX_SHELL)
+
+ Indicator that tells if the current environment was set up by
+ `nix-shell`. It can have the values `pure` or `impure`.
+
+## Appendix: OS-specific conventions
+
+This information is not Nix-specific, but is referenced above.
+
+### Unix: XDG Base Directories {#xdg-base-directories}
+
+The [XDG Base Directory Specification] defines standard locations for user-specific configuration, state, and cache files on Unix systems.
+
+[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+The following environment variables are used:
+
+- [`XDG_CONFIG_HOME`]{#env-XDG_CONFIG_HOME} (default `~/.config`)
+- [`XDG_STATE_HOME`]{#env-XDG_STATE_HOME} (default `~/.local/state`)
+- [`XDG_CACHE_HOME`]{#env-XDG_CACHE_HOME} (default `~/.cache`)
+- [`XDG_CONFIG_DIRS`]{#env-XDG_CONFIG_DIRS} (default `/etc/xdg`) — colon-separated list of additional configuration base directories, searched after `XDG_CONFIG_HOME`
+
+### Windows: Known Folders {#known-folders}
+
+On Windows, [Known Folders][windows-known-folders] provide standard locations for application data on Windows.
+
+[windows-known-folders]: https://learn.microsoft.com/en-us/windows/win32/shell/known-folders
+
+The relevant folders are:
+
+- [`%APPDATA%`]{#env-APPDATA} — per-user roaming application data
+- [`%LOCALAPPDATA%`]{#env-LOCALAPPDATA} — per-user local application data
+- [`%PROGRAMDATA%`]{#env-PROGRAMDATA} — system-wide application data
diff --git a/doc/manual/source/command-ref/nix-collect-garbage.md b/doc/manual/source/command-ref/nix-collect-garbage.md
index 763179b8ee18..07229255e7cd 100644
--- a/doc/manual/source/command-ref/nix-collect-garbage.md
+++ b/doc/manual/source/command-ref/nix-collect-garbage.md
@@ -62,9 +62,9 @@ These options are for deleting old [profiles] prior to deleting unreachable [sto
This is the equivalent of invoking [`nix-env --delete-generations `](@docroot@/command-ref/nix-env/delete-generations.md#generations-time) on each found profile.
See the documentation of that command for additional information about the *period* argument.
- - [`--max-freed`](#opt-max-freed) *bytes*
+- [`--max-freed`](#opt-max-freed) *bytes*
-
+
Keep deleting paths until at least *bytes* bytes have been deleted,
then stop. The argument *bytes* can be followed by the
diff --git a/doc/manual/source/command-ref/nix-hash.md b/doc/manual/source/command-ref/nix-hash.md
index 7c17ce9095b4..c1a4251b0973 100644
--- a/doc/manual/source/command-ref/nix-hash.md
+++ b/doc/manual/source/command-ref/nix-hash.md
@@ -45,20 +45,20 @@ md5sum`.
- `--base32`
- Print the hash in a base-32 representation rather than hexadecimal.
- This base-32 representation is more compact and can be used in Nix
+ Print the hash in [Nix32](@docroot@/protocols/nix32.md) representation rather than hexadecimal.
+ This representation is more compact and can be used in Nix
expressions (such as in calls to `fetchurl`).
- `--base64`
- Similar to --base32, but print the hash in a base-64 representation,
- which is more compact than the base-32 one.
+ Similar to `--base32`, but print the hash in a [Base64](https://en.wikipedia.org/wiki/Base64) representation,
+ which is more compact than the Nix32 one.
- `--sri`
- Print the hash in SRI format with base-64 encoding.
+ Print the hash in [SRI](@docroot@/glossary.md#gloss-sri) format with Base64 encoding.
The type of hash algorithm will be prepended to the hash string,
- followed by a hyphen (-) and the base-64 hash body.
+ followed by a hyphen (-) and the Base64 hash body.
- `--truncate`
@@ -71,18 +71,18 @@ md5sum`.
- `--to-base16`
- Don’t hash anything, but convert the base-32 hash representation
+ Don’t hash anything, but convert the [Nix32](@docroot@/protocols/nix32.md) hash representation
*hash* to hexadecimal.
- `--to-base32`
Don’t hash anything, but convert the hexadecimal hash representation
- *hash* to base-32.
+ *hash* to [Nix32](@docroot@/protocols/nix32.md).
- `--to-base64`
Don’t hash anything, but convert the hexadecimal hash representation
- *hash* to base-64.
+ *hash* to Base64.
- `--to-sri`
@@ -134,7 +134,7 @@ $ nix-hash --type sha256 --flat test/world
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
```
-Converting between hexadecimal, base-32, base-64, and SRI:
+Converting between hexadecimal, Nix32, Base64, and SRI:
```console
$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
diff --git a/doc/manual/source/command-ref/nix-prefetch-url.md b/doc/manual/source/command-ref/nix-prefetch-url.md
index 8451778ad46d..86c20b9e1de4 100644
--- a/doc/manual/source/command-ref/nix-prefetch-url.md
+++ b/doc/manual/source/command-ref/nix-prefetch-url.md
@@ -32,7 +32,7 @@ Otherwise, the file is downloaded, and an error is signaled if the
actual hash of the file does not match the specified hash.
This command prints the hash on standard output.
-The hash is printed using base-32 unless `--type md5` is specified,
+The hash is printed using [Nix32](@docroot@/protocols/nix32.md) unless `--type md5` is specified,
in which case it's printed using base-16.
Additionally, if the option `--print-path` is used,
the path of the downloaded file in the Nix store is also printed.
diff --git a/doc/manual/source/development/json-guideline.md b/doc/manual/source/development/data-modeling.md
similarity index 86%
rename from doc/manual/source/development/json-guideline.md
rename to doc/manual/source/development/data-modeling.md
index 309b4b3a06e4..a9d131147588 100644
--- a/doc/manual/source/development/json-guideline.md
+++ b/doc/manual/source/development/data-modeling.md
@@ -1,7 +1,12 @@
-# JSON guideline
+# Data Modeling Guidelines
-Nix consumes and produces JSON in a variety of contexts.
-These guidelines ensure consistent practices for all our JSON interfaces, for ease of use, and so that experience in one part carries over to another.
+Nix consumes and produces JSON and attribute sets in a variety of contexts.
+These guidelines ensure consistent practices for our interfaces, for ease of use, and so that experience in one part carries over to another.
+
+For these guidelines, we will use JSON terminology, but they apply equally well to new attribute set interfaces (primops, etc.).
+Note that these are guidelines first and foremost. Exceptions include:
+- Feature testing: e.g., it is OK to do `builtins?frobnicate`.
+- Compatibility: we generally do not change stable interfaces just to make them comply. New replacements can be added with care.
## Extensibility
diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md
index 6578632d991a..35e4c71ec388 100644
--- a/doc/manual/source/development/debugging.md
+++ b/doc/manual/source/development/debugging.md
@@ -26,7 +26,6 @@ or GCC. This is useful when debugging memory corruption issues.
```console
[nix-shell]$ export mesonBuildType=debugoptimized
[nix-shell]$ appendToVar mesonFlags "-Dlibexpr:gc=disabled" # Disable Boehm
-[nix-shell]$ appendToVar mesonFlags "-Dbindings=false" # Disable nix-perl
[nix-shell]$ appendToVar mesonFlags "-Db_sanitize=address,undefined"
```
diff --git a/doc/manual/source/development/static-analysis.md b/doc/manual/source/development/static-analysis.md
new file mode 100644
index 000000000000..6bdf875befde
--- /dev/null
+++ b/doc/manual/source/development/static-analysis.md
@@ -0,0 +1,87 @@
+# Static Analysis
+
+Nix uses [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) for static analysis of C++ code.
+This helps catch bugs, enforce coding standards, and maintain code quality.
+
+## Running clang-tidy locally
+
+To run clang-tidy on the entire codebase in the development shell:
+
+```console
+$ nix develop .#native-clangStdenv
+$ configurePhase
+$ meson compile -C build clang-tidy
+```
+
+This will analyze all C++ source files and report any warnings.
+
+To automatically apply fixes for certain warnings:
+
+```console
+$ meson compile -C build clang-tidy-fix
+```
+
+> **Warning**
+>
+> Review the changes before committing, as automatic fixes may not always be correct.
+
+## CI integration
+
+clang-tidy runs automatically on every pull request via GitHub Actions.
+The CI job builds `.#hydraJobs.clangTidy.x86_64-linux` which:
+
+1. Builds all components with debug mode (for faster compilation)
+2. Runs clang-tidy on each component
+3. Fails if any warnings are found (warnings are treated as errors)
+
+## Configuration
+
+The clang-tidy configuration is in `.clang-tidy` at the repository root (symlinked from `nix-meson-build-support/common/clang-tidy/.clang-tidy`).
+
+### Suppressing warnings
+
+If a warning is a false positive, you can suppress it in several ways:
+
+1. **Inline suppression** (preferred for specific cases):
+ ```cpp
+ // NOLINTBEGIN(bugprone-some-check)
+ ... code ...
+ // NOLINTEND(bugprone-some-check)
+ ```
+ Or for a single line:
+ ```cpp
+ int x = something(); // NOLINT(bugprone-some-check)
+ ```
+
+2. **Configuration file** (for project-wide suppression):
+ Add the check to the disabled list in `.clang-tidy`:
+ ```yaml
+ Checks:
+ - -bugprone-some-check # Reason for disabling
+ ```
+
+3. **Check options** (for configuring check behavior):
+ ```yaml
+ CheckOptions:
+ bugprone-reserved-identifier.AllowedIdentifiers: '__some_identifier'
+ ```
+
+### Adding new checks
+
+To enable additional checks:
+
+1. Edit `nix-meson-build-support/common/clang-tidy/.clang-tidy`
+2. Add the check to the `Checks` list
+3. Run clang-tidy locally to see the impact
+4. Fix any new warnings or disable specific sub-checks if needed
+
+## Custom clang-tidy plugin
+
+The Nix project includes infrastructure for custom clang-tidy checks in `src/clang-tidy-plugin/`.
+These checks can enforce Nix-specific coding patterns that aren't covered by standard clang-tidy checks.
+
+To add a new custom check:
+
+1. Add the check implementation in `src/clang-tidy-plugin/`
+2. Register it in `nix-clang-tidy-checks.cc`
+3. Enable it in `.clang-tidy` with the `nix-` prefix
diff --git a/doc/manual/source/development/testing.md b/doc/manual/source/development/testing.md
index 35654d163935..6ea1a233a4aa 100644
--- a/doc/manual/source/development/testing.md
+++ b/doc/manual/source/development/testing.md
@@ -9,7 +9,7 @@ You can build it yourself:
```
# nix build .#hydraJobs.coverage
-# xdg-open ./result/coverage/index.html
+# xdg-open ./result/index.html
```
[Extensive records of build metrics](https://hydra.nixos.org/job/nix/master/coverage#tabs-charts), such as test coverage over time, are also available online.
@@ -34,31 +34,28 @@ The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
> │ ├── value/context.cc
> │ …
> │
-> ├── tests
-> │ │
+> ├── libutil-tests
+> │ ├── meson.build
> │ …
-> │ ├── libutil-tests
-> │ │ ├── meson.build
-> │ │ …
-> │ │ └── data
-> │ │ ├── git/tree.txt
-> │ │ …
-> │ │
-> │ ├── libexpr-test-support
+> │ ├── data
+> │ │ ├── git/tree.txt
+> │ …
+> │
+> ├── libexpr-test-support
+> │ ├── meson.build
+> │ ├── include/nix/expr
> │ │ ├── meson.build
-> │ │ ├── include/nix/expr
-> │ │ │ ├── meson.build
-> │ │ │ └── tests
-> │ │ │ ├── value/context.hh
-> │ │ │ …
> │ │ └── tests
-> │ │ ├── value/context.cc
+> │ │ ├── value/context.hh
> │ │ …
-> │ │
-> │ ├── libexpr-tests
-> │ … ├── meson.build
+> │ ├── tests
> │ ├── value/context.cc
> │ …
+> │
+> ├── libexpr-tests
+> │ ├── meson.build
+> │ ├── value/context.cc
+> │ …
> …
> ```
@@ -80,7 +77,7 @@ there is no risk of any build-system wildcards for the library accidentally pick
### Running tests
You can run the whole testsuite with `meson test` from the Meson build directory, or the tests for a specific component with `meson test nix-store-tests`.
-A environment variables that Google Test accepts are also worth knowing:
+The environment variables that Google Test accepts are also worth knowing:
1. [`GTEST_FILTER`](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests)
@@ -257,15 +254,6 @@ GNU gdb (GDB) 12.1
One can debug the Nix invocation in all the usual ways.
For example, enter `run` to start the Nix invocation.
-### Troubleshooting
-
-Sometimes running tests in the development shell may leave artefacts in the local repository.
-To remove any traces of that:
-
-```console
-git clean -x --force tests
-```
-
### Characterisation testing { #characterisation-testing-functional }
Occasionally, Nix utilizes a technique called [Characterisation Testing](https://en.wikipedia.org/wiki/Characterization_test) as part of the functional tests.
@@ -311,77 +299,34 @@ Generally, this build is sufficient, but in nightly or CI we also test the attri
The integration tests are defined in the Nix flake under the `hydraJobs.tests` attribute.
These tests include everything that needs to interact with external services or run Nix in a non-trivial distributed setup.
-Because these tests are expensive and require more than what the standard github-actions setup provides, they only run on the master branch (on ).
+Because these tests are expensive and require more than what the standard github-actions setup provides, most of them only run on the master branch (on ).
You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}`.
## Installer tests
-After a one-time setup, the Nix repository's GitHub Actions continuous integration (CI) workflow can test the installer each time you push to a branch.
-
-Creating a Cachix cache for your installer tests and adding its authorisation token to GitHub enables [two installer-specific jobs in the CI workflow](https://github.com/NixOS/nix/blob/88a45d6149c0e304f6eb2efcc2d7a4d0d569f8af/.github/workflows/ci.yml#L50-L91):
+GitHub Actions CI in the Nix repository also tests the installer on PRs. It does not require additional setup and utilises [GHA Artifacts](https://docs.github.com/en/actions/tutorials/store-and-share-data) and can be run in any Nix repository fork.
-- The `installer` job generates installers for the platforms below and uploads them to your Cachix cache:
+- The `tests` job generates installers for the platforms below and uploads them as an artifact:
- `x86_64-linux`
- - `armv6l-linux`
- - `armv7l-linux`
-
-- The `installer_test` job (which runs on `ubuntu-24.04` and `macos-14`) will try to install Nix with the cached installer and run a trivial Nix command.
+ - `aarch64-darwin`
-### One-time setup
+- The `installer_test` job (which runs on Linux and macOS) will try to install Nix with the cached installer and run a trivial Nix command.
+- Both the scripted installer and the [standalone Rust-based installer](https://github.com/NixOS/nix-installer) are tested.
-1. Have a GitHub account with a fork of the [Nix repository](https://github.com/NixOS/nix).
-2. At cachix.org:
- - Create or log in to an account.
- - Create a Cachix cache using the format `-nix-install-tests`.
- - Navigate to the new cache > Settings > Auth Tokens.
- - Generate a new Cachix auth token and copy the generated value.
-3. At github.com:
- - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret.
- - Name the secret `CACHIX_AUTH_TOKEN`.
- - Paste the copied value of the Cachix cache auth token.
+You can generate the installer tarball and script manually by running `nix build .#hydraJobs.installerScriptForGHA.`.
## Working on documentation
### Using the CI-generated installer for manual testing
-After the CI run completes, you can check the output to extract the installer URL:
+After the CI run completes, you can check the output to extract the installer artifact:
1. Click into the detailed view of the CI run.
-2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them).
-3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`)
-4. Copy the value of `install_url`
-5. To generate an install command, plug this `install_url` and your GitHub username into this template:
+2. Scroll down to `Artifacts` section.
+3. Download the corresponding installer artifact (`installer-darwin` for `aarch64-darwin` and `installer-linux` for `x86_64-linux`).
+4. Unpack the downloaded `.zip` artifact.
+5. To generate an install command, plug the path to the unpacked artifact into this template:
```console
- curl -L | sh -s -- --tarball-url-prefix https://-nix-install-tests.cachix.org/serve
+ sh /install --tarball-url-prefix file://
```
-
-
-
diff --git a/doc/manual/source/glossary.md b/doc/manual/source/glossary.md
index 64ca1cf5e167..c7b8931509a8 100644
--- a/doc/manual/source/glossary.md
+++ b/doc/manual/source/glossary.md
@@ -1,5 +1,32 @@
# Glossary
+- [base directory]{#gloss-base-directory}
+
+ The location from which relative paths are resolved.
+
+ - For expressions in a file, the base directory is the directory containing that file.
+ This is analogous to the directory of a [base URL](https://datatracker.ietf.org/doc/html/rfc1808#section-3.3).
+
+
+
+ - For expressions written in command line arguments with [`--expr`](@docroot@/command-ref/opt-common.html#opt-expr), the base directory is the current working directory.
+
+ [base directory]: #gloss-base-directory
+
+- [binary cache]{#gloss-binary-cache}
+
+ A *binary cache* is a Nix store which uses a different format: its
+ metadata and signatures are kept in `.narinfo` files rather than in a
+ [Nix database]. This different format simplifies serving store objects
+ over the network, but cannot host builds. Examples of binary caches
+ include S3 buckets and the [NixOS binary cache](https://cache.nixos.org).
+
- [build system]{#gloss-build-system}
Generic term for software that facilitates the building of software by automating the invocation of compilers, linkers, and other tools.
@@ -8,6 +35,26 @@
It has no knowledge of any particular programming language or toolchain.
These details are specified in [derivation expressions](#gloss-derivation-expression).
+- [closure]{#gloss-closure}
+
+ The closure of a store path is the set of store paths that are
+ directly or indirectly “reachable” from that store path; that is,
+ it’s the closure of the path under the *references* relation. For
+ a package, the closure of its derivation is equivalent to the
+ build-time dependencies, while the closure of its [output path] is
+ equivalent to its runtime dependencies. For correct deployment it
+ is necessary to deploy whole closures, since otherwise at runtime
+ files could be missing. The command `nix-store --query --requisites ` prints out
+ closures of store paths.
+
+ As an example, if the [store object] at path `P` contains a [reference]
+ to a store object at path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
+ references `R` then `R` is also in the closure of `P`.
+
+ See [References](@docroot@/store/store-object.md#references) for details.
+
+ [closure]: #gloss-closure
+
- [content address]{#gloss-content-address}
A
@@ -31,32 +78,37 @@
The industry term for storage and retrieval systems using [content addressing](#gloss-content-address). A Nix store also has [input addressing](#gloss-input-addressed-store-object), and metadata.
+- [content-addressed store object]{#gloss-content-addressed-store-object}
+
+ 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-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.
+
+- [content-addressing derivation]{#gloss-content-addressing-derivation}
+
+ A derivation which has the
+ [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
+ attribute set to `true`.
+
- [derivation]{#gloss-derivation}
A derivation can be thought of as a [pure function](https://en.wikipedia.org/wiki/Pure_function) that produces new [store objects][store object] from existing store objects.
- Derivations are implemented as [operating system processes that run in a sandbox](@docroot@/store/building.md#builder-execution).
+ Derivations are implemented as [operating system processes that run in a sandbox](@docroot@/store/building.md).
This sandbox by default only allows reading from store objects specified as inputs, and only allows writing to designated [outputs][output] to be [captured as store objects](@docroot@/store/building.md#processing-outputs).
A derivation is typically specified as a [derivation expression] in the [Nix language], and [instantiated][instantiate] to a [store derivation].
- There are multiple ways of obtaining store objects from store derivatons, collectively called [realisation][realise].
+ There are multiple ways of obtaining store objects from store derivations, collectively called [realisation][realise].
[derivation]: #gloss-derivation
-- [store derivation]{#gloss-store-derivation}
-
- A [derivation] represented as a [store object].
-
- See [Store Derivation](@docroot@/store/derivation/index.md#store-derivation) for details.
-
- [store derivation]: #gloss-store-derivation
-
-- [directed acyclic graph]{#gloss-directed-acyclic-graph}
+- [derivation expression]{#gloss-derivation-expression}
- A [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) is graph whose edges are given a direction ("a to b" is not the same edge as "b to a"), and for which no possible path (created by joining together edges) forms a cycle.
+ A description of a [store derivation] using the [`derivation` primitive](./language/derivations.md) in the [Nix language].
- DAGs are very important to Nix.
- In particular, the non-self-[references][reference] of [store object][store object] form a cycle.
+ [derivation expression]: #gloss-derivation-expression
- [derivation path]{#gloss-derivation-path}
@@ -68,79 +120,34 @@
[derivation path]: #gloss-derivation-path
-- [derivation expression]{#gloss-derivation-expression}
-
- A description of a [store derivation] using the [`derivation` primitive](./language/derivations.md) in the [Nix language].
-
- [derivation expression]: #gloss-derivation-expression
-
-- [instantiate]{#gloss-instantiate}, instantiation
-
- 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.
-
- [instantiate]: #gloss-instantiate
-
-- [realise]{#gloss-realise}, realisation
-
- Ensure a [store path] is [valid][validity].
-
- This can be achieved by:
- - Fetching a pre-built [store object] from a [substituter]
- - [Building](@docroot@/store/building.md) the corresponding [store derivation]
- - Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs
-
- See [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md) for a detailed description of the algorithm.
-
- See also [`nix-build`](./command-ref/nix-build.md) and [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental).
-
- [realise]: #gloss-realise
-
-- [content-addressing derivation]{#gloss-content-addressing-derivation}
-
- A derivation which has the
- [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
- attribute set to `true`.
-
-- [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD)
-
- 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.
+- [deriver]{#gloss-deriver}
-- [store]{#gloss-store}
+ The [store derivation] that produced an [output path].
- A collection of [store objects][store object], with operations to manipulate that collection.
- See [Nix Store](./store/index.md) for details.
+ The deriver for an output path can be queried with the `--deriver` option to
+ [`nix-store --query`](@docroot@/command-ref/nix-store/query.md).
- There are many types of stores, see [Store Types](./store/types/index.md) for details.
+- [deriving path]{#gloss-deriving-path}
- [store]: #gloss-store
+ Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
-- [Nix instance]{#gloss-nix-instance}
-
- 1. An installation of Nix, which includes the presence of a [store], and the Nix package manager which operates on that store.
- A local Nix installation and a [remote builder](@docroot@/advanced-topics/distributed-builds.md) are two examples of Nix instances.
- 2. A running Nix process, such as the `nix` command.
+ See [Deriving Path](./store/derivation/index.md#deriving-path) for details.
-- [binary cache]{#gloss-binary-cache}
+ Not to be confused with [derivation path].
- A *binary cache* is a Nix store which uses a different format: its
- metadata and signatures are kept in `.narinfo` files rather than in a
- [Nix database]. This different format simplifies serving store objects
- over the network, but cannot host builds. Examples of binary caches
- include S3 buckets and the [NixOS binary cache](https://cache.nixos.org).
+- [directed acyclic graph]{#gloss-directed-acyclic-graph}
-- [store path]{#gloss-store-path}
+ A [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) is graph whose edges are given a direction ("a to b" is not the same edge as "b to a"), and for which no possible path (created by joining together edges) forms a cycle.
- The location of a [store object] in the file system, i.e., an immediate child of the Nix store directory.
+ DAGs are very important to Nix.
+ In particular, the non-self-[references][reference] of [store object][store object] form a cycle.
- > **Example**
- >
- > `/nix/store/jf6gn2dzna4nmsfbdxsd7kwhsk6gnnlr-git-2.38.1`
+- [experimental feature]{#gloss-experimental-feature}
- See [Store Path](@docroot@/store/store-path.md) for details.
+ Not yet stabilized functionality guarded by named experimental feature flags.
+ These flags are enabled or disabled with the [`experimental-features`](./command-ref/conf-file.html#conf-experimental-features) setting.
- [store path]: #gloss-store-path
+ See the contribution guide on the [purpose and lifecycle of experimental feaures](@docroot@/development/experimental-features.md).
- [file system object]{#gloss-file-system-object}
@@ -150,21 +157,19 @@
[file system object]: #gloss-file-system-object
-- [store object]{#gloss-store-object}
-
- Part of the contents of a [store].
-
- A store object consists of a [file system object], [references][reference] to other store objects, and other metadata.
- It can be referred to by a [store path].
-
- See [Store Object](@docroot@/store/store-object.md) for details.
+- [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD)
- [store object]: #gloss-store-object
+ 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.
- [IFD]{#gloss-ifd}
[Import From Derivation](./language/import-from-derivation.md)
+- [impure derivation]{#gloss-impure-derivation}
+
+ [An experimental feature](@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
+ so that they are always rebuilt, and their outputs not reused by subsequent calls to realise them.
+
- [input-addressed store object]{#gloss-input-addressed-store-object}
A store object produced by building a
@@ -174,42 +179,28 @@
See [input-addressing derivation outputs](store/derivation/outputs/input-address.md) for details.
-- [content-addressed store object]{#gloss-content-addressed-store-object}
-
- 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-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.
-
-- [substitute]{#gloss-substitute}
+- [installable]{#gloss-installable}
- A substitute is a command invocation stored in the [Nix database] that
- describes how to build a store object, bypassing the normal build
- mechanism (i.e., derivations). Typically, the substitute builds the
- store object by downloading a pre-built version of the store object
- from some server.
+ Something that can be realised in the Nix store.
-- [substituter]{#gloss-substituter}
+ See [installables](./command-ref/new-cli/nix.md#installables) for [`nix` commands](./command-ref/new-cli/nix.md) (experimental) for details.
- An additional [store]{#gloss-store} from which Nix can obtain store objects instead of building them.
- Often the substituter is a [binary cache](#gloss-binary-cache), but any store can serve as substituter.
+- [instantiate]{#gloss-instantiate}, instantiation
- See the [`substituters` configuration option](./command-ref/conf-file.md#conf-substituters) for details.
+ Translate a [derivation expression] into a [store derivation].
- [substituter]: #gloss-substituter
+ See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation.
-- [purity]{#gloss-purity}
+ [instantiate]: #gloss-instantiate
- The assumption that equal Nix derivations when run always produce
- the same output. This cannot be guaranteed in general (e.g., a
- builder can rely on external inputs such as the network or the
- system time) but the Nix model assumes it.
+- [Nix Archive (NAR)]{#gloss-nar}
-- [impure derivation]{#gloss-impure-derivation}
+ A *N*ix *AR*chive. This is a serialisation of a path in the Nix
+ store. It can contain regular files, directories and symbolic
+ links. NARs are generated and unpacked using `nix-store --dump`
+ and `nix-store --restore`.
- [An experimental feature](@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
- so that they are always rebuilt, and their outputs not reused by subsequent calls to realise them.
+ See [Nix Archive](store/file-system-object/content-address.html#serial-nix-archive) for details.
- [Nix database]{#gloss-nix-database}
@@ -235,137 +226,136 @@
>
> Building and deploying software using Nix entails writing Nix expressions to describe [packages][package] and compositions thereof.
-- [reference]{#gloss-reference}
+- [Nix instance]{#gloss-nix-instance}
+
+ 1. An installation of Nix, which includes the presence of a [store], and the Nix package manager which operates on that store.
+ A local Nix installation and a [remote builder](@docroot@/advanced-topics/distributed-builds.md) are two examples of Nix instances.
+ 2. A running Nix process, such as the `nix` command.
- An edge from one [store object] to another.
+- [output]{#gloss-output}
- See [References](@docroot@/store/store-object.md#references) for details.
+ A [store object] produced by a [store derivation].
+ See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details.
- [reference]: #gloss-reference
+ [output]: #gloss-output
- See [References](@docroot@/store/store-object.md#references) for details.
+- [output closure]{#gloss-output-closure}\
+ The [closure] of an [output path]. It only contains what is [reachable] from the output.
-- [reachable]{#gloss-reachable}
+- [output path]{#gloss-output-path}
- A store path `Q` is reachable from another store path `P` if `Q`
- is in the *closure* of the *references* relation.
+ The [store path] to the [output] of a [store derivation].
- See [References](@docroot@/store/store-object.md#references) for details.
+ [output path]: #gloss-output-path
-- [closure]{#gloss-closure}
+- [package]{#package}
- The closure of a store path is the set of store paths that are
- directly or indirectly “reachable” from that store path; that is,
- it’s the closure of the path under the *references* relation. For
- a package, the closure of its derivation is equivalent to the
- build-time dependencies, while the closure of its [output path] is
- equivalent to its runtime dependencies. For correct deployment it
- is necessary to deploy whole closures, since otherwise at runtime
- files could be missing. The command `nix-store --query --requisites ` prints out
- closures of store paths.
+ A software package; files that belong together for a particular purpose, and metadata.
- As an example, if the [store object] at path `P` contains a [reference]
- to a store object at path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
- references `R` then `R` is also in the closure of `P`.
+ Nix represents files as [file system objects][file system object], and how they belong together is encoded as [references][reference] between [store objects][store object] that contain these file system objects.
- See [References](@docroot@/store/store-object.md#references) for details.
+ The [Nix language] allows denoting packages in terms of [attribute sets](@docroot@/language/types.md#type-attrs) containing:
+ - attributes that refer to the files of a package, typically in the form of [derivation outputs](#gloss-output),
+ - attributes with metadata, such as information about how the package is supposed to be used.
- [closure]: #gloss-closure
+ The exact shape of these attribute sets is up to convention.
-- [requisite]{#gloss-requisite}
+ [package]: #package
- A store object [reachable] by a path (chain of references) from a given [store object].
- The [closure] is the set of requisites.
+- [profile]{#gloss-profile}
- See [References](@docroot@/store/store-object.md#references) for details.
+ A symlink to the current *user environment* of a user, e.g.,
+ `/nix/var/nix/profiles/default`.
-- [referrer]{#gloss-referrer}
+- [purity]{#gloss-purity}
- A reversed edge from one [store object] to another.
+ The assumption that equal Nix derivations when run always produce
+ the same output. This cannot be guaranteed in general (e.g., a
+ builder can rely on external inputs such as the network or the
+ system time) but the Nix model assumes it.
-- [output]{#gloss-output}
+- [reachable]{#gloss-reachable}
- A [store object] produced by a [store derivation].
- See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details.
+ A store path `Q` is reachable from another store path `P` if `Q`
+ is in the *closure* of the *references* relation.
- [output]: #gloss-output
+ See [References](@docroot@/store/store-object.md#references) for details.
-- [output path]{#gloss-output-path}
+- [realise]{#gloss-realise}, realisation
- The [store path] to the [output] of a [store derivation].
+ Ensure a [store path] is [valid][validity].
- [output path]: #gloss-output-path
+ This can be achieved by:
+ - Fetching a pre-built [store object] from a [substituter]
+ - [Building](@docroot@/store/building.md) the corresponding [store derivation]
+ - Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs
-- [output closure]{#gloss-output-closure}\
- The [closure] of an [output path]. It only contains what is [reachable] from the output.
+ See [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md) for a detailed description of the algorithm.
-- [deriving path]{#gloss-deriving-path}
+ See also [`nix-build`](./command-ref/nix-build.md) and [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental).
- Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
+ [realise]: #gloss-realise
- See [Deriving Path](./store/derivation/index.md#deriving-path) for details.
+- [reference]{#gloss-reference}
- Not to be confused with [derivation path].
+ An edge from one [store object] to another.
-- [deriver]{#gloss-deriver}
+ See [References](@docroot@/store/store-object.md#references) for details.
- The [store derivation] that produced an [output path].
+ [reference]: #gloss-reference
- The deriver for an output path can be queried with the `--deriver` option to
- [`nix-store --query`](@docroot@/command-ref/nix-store/query.md).
+ See [References](@docroot@/store/store-object.md#references) for details.
-- [validity]{#gloss-validity}
+- [referrer]{#gloss-referrer}
- A store path is valid if all [store object]s in its [closure] can be read from the [store].
+ A reversed edge from one [store object] to another.
- For a [local store], this means:
- - The store path leads to an existing [store object] in that [store].
- - The store path is listed in the [Nix database] as being valid.
- - All paths in the store path's [closure] are valid.
+- [requisite]{#gloss-requisite}
- [validity]: #gloss-validity
- [local store]: @docroot@/store/types/local-store.md
+ A store object [reachable] by a path (chain of references) from a given [store object].
+ The [closure] is the set of requisites.
-- [user environment]{#gloss-user-env}
+ See [References](@docroot@/store/store-object.md#references) for details.
- An automatically generated store object that consists of a set of
- symlinks to “active” applications, i.e., other store paths. These
- are generated automatically by
- [`nix-env`](./command-ref/nix-env.md). See *profiles*.
+- [store]{#gloss-store}
-- [profile]{#gloss-profile}
+ A collection of [store objects][store object], with operations to manipulate that collection.
+ See [Nix Store](./store/index.md) for details.
- A symlink to the current *user environment* of a user, e.g.,
- `/nix/var/nix/profiles/default`.
+ There are many types of stores, see [Store Types](./store/types/index.md) for details.
-- [installable]{#gloss-installable}
+ [store]: #gloss-store
- Something that can be realised in the Nix store.
+- [store derivation]{#gloss-store-derivation}
- See [installables](./command-ref/new-cli/nix.md#installables) for [`nix` commands](./command-ref/new-cli/nix.md) (experimental) for details.
+ A [derivation] represented as a [store object].
-- [Nix Archive (NAR)]{#gloss-nar}
+ See [Store Derivation](@docroot@/store/derivation/index.md#store-derivation) for details.
- A *N*ix *AR*chive. This is a serialisation of a path in the Nix
- store. It can contain regular files, directories and symbolic
- links. NARs are generated and unpacked using `nix-store --dump`
- and `nix-store --restore`.
+ [store derivation]: #gloss-store-derivation
- See [Nix Archive](store/file-system-object/content-address.html#serial-nix-archive) for details.
+- [store object]{#gloss-store-object}
-- [package]{#package}
+ Part of the contents of a [store].
- A software package; files that belong together for a particular purpose, and metadata.
+ A store object consists of a [file system object], [references][reference] to other store objects, and other metadata.
+ It can be referred to by a [store path].
- Nix represents files as [file system objects][file system object], and how they belong together is encoded as [references][reference] between [store objects][store object] that contain these file system objects.
+ See [Store Object](@docroot@/store/store-object.md) for details.
- The [Nix language] allows denoting packages in terms of [attribute sets](@docroot@/language/types.md#type-attrs) containing:
- - attributes that refer to the files of a package, typically in the form of [derivation outputs](#gloss-output),
- - attributes with metadata, such as information about how the package is supposed to be used.
+ [store object]: #gloss-store-object
- The exact shape of these attribute sets is up to convention.
+- [store path]{#gloss-store-path}
- [package]: #package
+ The location of a [store object] in the file system, i.e., an immediate child of the Nix store directory.
+
+ > **Example**
+ >
+ > `/nix/store/jf6gn2dzna4nmsfbdxsd7kwhsk6gnnlr-git-2.38.1`
+
+ See [Store Path](@docroot@/store/store-path.md) for details.
+
+ [store path]: #gloss-store-path
- [string interpolation]{#gloss-string-interpolation}
@@ -377,31 +367,47 @@
[path]: ./language/types.md#type-path
[attribute name]: ./language/types.md#type-attrs
-- [base directory]{#gloss-base-directory}
+- [SRI]{#gloss-sri}
- The location from which relative paths are resolved.
+ [Subresource Integrity](https://www.w3.org/TR/SRI/) (SRI) is a [W3C specification](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) for integrity metadata.
+ Nix uses the SRI hash format (`-`) to specify content hashes in a way that is self-describing, since the hash algorithm is part of the format.
- - For expressions in a file, the base directory is the directory containing that file.
- This is analogous to the directory of a [base URL](https://datatracker.ietf.org/doc/html/rfc1808#section-3.3).
-
+ [SRI]: #gloss-sri
-
- - For expressions written in command line arguments with [`--expr`](@docroot@/command-ref/opt-common.html#opt-expr), the base directory is the current working directory.
+- [substitute]{#gloss-substitute}
- [base directory]: #gloss-base-directory
+ A substitute is a command invocation stored in the [Nix database] that
+ describes how to build a store object, bypassing the normal build
+ mechanism (i.e., derivations). Typically, the substitute builds the
+ store object by downloading a pre-built version of the store object
+ from some server.
-- [experimental feature]{#gloss-experimental-feature}
+- [substituter]{#gloss-substituter}
- Not yet stabilized functionality guarded by named experimental feature flags.
- These flags are enabled or disabled with the [`experimental-features`](./command-ref/conf-file.html#conf-experimental-features) setting.
+ An additional [store]{#gloss-store} from which Nix can obtain store objects instead of building them.
+ Often the substituter is a [binary cache](#gloss-binary-cache), but any store can serve as substituter.
- See the contribution guide on the [purpose and lifecycle of experimental feaures](@docroot@/development/experimental-features.md).
+ See the [`substituters` configuration option](./command-ref/conf-file.md#conf-substituters) for details.
+
+ [substituter]: #gloss-substituter
+
+- [user environment]{#gloss-user-env}
+
+ An automatically generated store object that consists of a set of
+ symlinks to “active” applications, i.e., other store paths. These
+ are generated automatically by
+ [`nix-env`](./command-ref/nix-env.md). See *profiles*.
+
+- [validity]{#gloss-validity}
+ A store path is valid if all [store object]s in its [closure] can be read from the [store].
+
+ For a [local store], this means:
+ - The store path leads to an existing [store object] in that [store].
+ - The store path is listed in the [Nix database] as being valid.
+ - All paths in the store path's [closure] are valid.
+
+ [validity]: #gloss-validity
+ [local store]: @docroot@/store/types/local-store.md
[Nix language]: ./language/index.md
diff --git a/doc/manual/source/installation/prerequisites-source.md b/doc/manual/source/installation/prerequisites-source.md
index 057fd444349e..e98067348ee6 100644
--- a/doc/manual/source/installation/prerequisites-source.md
+++ b/doc/manual/source/installation/prerequisites-source.md
@@ -1,80 +1,52 @@
# Prerequisites
- - GNU Autoconf () and the
- autoconf-archive macro collection
- (). These are
- needed to run the bootstrap script.
-
- - GNU Make.
-
- - Bash Shell. The `./configure` script relies on bashisms, so Bash is
- required.
-
- - A version of GCC or Clang that supports C++23.
-
- - `pkg-config` to locate dependencies. If your distribution does not
- provide it, you can get it from
- .
-
- - The OpenSSL library to calculate cryptographic hashes. If your
- distribution does not provide it, you can get it from
- .
-
- - The `libbrotlienc` and `libbrotlidec` libraries to provide
- implementation of the Brotli compression algorithm. They are
- available for download from the official repository
- .
-
- - cURL and its library. If your distribution does not provide it, you
- can get it from .
-
- - The SQLite embedded database library, version 3.6.19 or higher. If
- your distribution does not provide it, please install it from
- .
-
- - The [Boehm garbage collector (`bdw-gc`)](http://www.hboehm.info/gc/) to reduce
- the evaluator’s memory consumption (optional).
-
- To enable it, install
- `pkgconfig` and the Boehm garbage collector, and pass the flag
- `--enable-gc` to `configure`.
-
- - The `boost` library of version 1.66.0 or higher. It can be obtained
- from the official web site .
-
- - The `editline` library of version 1.14.0 or higher. It can be
- obtained from the its repository
- .
-
- - The `libsodium` library for verifying cryptographic signatures
- of contents fetched from binary caches.
- It can be obtained from the official web site
- .
-
- - Recent versions of Bison and Flex to build the parser. (This is
- because Nix needs GLR support in Bison and reentrancy support in
- Flex.) For Bison, you need version 2.6, which can be obtained from
- the [GNU FTP server](ftp://alpha.gnu.org/pub/gnu/bison). For Flex,
- you need version 2.5.35, which is available on
- [SourceForge](http://lex.sourceforge.net/). Slightly older versions
- may also work, but ancient versions like the ubiquitous 2.5.4a
- won't.
-
- - The `libseccomp` is used to provide syscall filtering on Linux. This
- is an optional dependency and can be disabled passing a
- `--disable-seccomp-sandboxing` option to the `configure` script (Not
- recommended unless your system doesn't support `libseccomp`). To get
- the library, visit .
-
- - On 64-bit x86 machines only, `libcpuid` library
- is used to determine which microarchitecture levels are supported
+ This list and lower version bounds are maintained on best-effort basis. When in doubt, check the `meson.build` files.
+
+ - Meson build system ().
+
+ - Ninja ().
+
+ - A version of GCC or Clang that supports C++23 (anything newer than Clang 19 or GCC 14 is likely to work).
+
+ - `pkg-config` to locate dependencies.
+ If your distribution does not provide it, you can get it from .
+
+ - The OpenSSL library to calculate cryptographic hashes.
+ If your distribution does not provide it, you can get it from .
+
+ - The `libbrotlienc` and `libbrotlidec` libraries to provide implementation of the Brotli compression algorithm.
+ They are available for download from the official repository .
+
+ - cURL library.
+ If your distribution does not provide it, you can get it from .
+
+ - The SQLite embedded database library, version 3.6.19 or higher.
+ If your distribution does not provide it, please install it from .
+
+ - The [Boehm garbage collector (`bdw-gc`)](http://www.hboehm.info/gc/) to reduce the evaluator’s memory consumption (optional).
+ To enable it, install `pkgconfig` and the Boehm garbage collector, and pass the option `-Dlibexpr:gc=enabled` to `meson setup`.
+
+ - The `boost` library of version 1.87.0 or higher.
+ It can be obtained from the official web site .
+
+ - The `editline` library of version 1.14.0 or higher.
+ It can be obtained from the its repository .
+
+ - The `libsodium` library for verifying cryptographic signatures of contents fetched from binary caches.
+ It can be obtained from the official web site .
+
+ - Recent versions of Bison and Flex to build the parser.
+ (This is because Nix needs C++ template support in Bison and reentrancy support in Flex.)
+
+ - The `libseccomp` is used to provide syscall filtering on Linux.
+ This is an optional dependency and can be disabled passing a `-Dlibstore:seccomp-sandboxing=disabled` option to the `meson setup` command
+ (Not recommended unless your system doesn't support `libseccomp`).
+ To get the library, visit .
+
+ - On 64-bit x86 machines only, `libcpuid` library is used to determine which microarchitecture levels are supported
(e.g., as whether to have `x86_64-v2-linux` among additional system types).
- The library is available from its homepage
- .
- This is an optional dependency and can be disabled
- by providing a `--disable-cpuid` to the `configure` script.
-
- - Unless `./configure --disable-unit-tests` is specified, GoogleTest (GTest) and
- RapidCheck are required, which are available at
- and
- respectively.
+ The library is available from its homepage .
+ This is an optional dependency and can be disabled by providing a `-Dlibutil:cpuid=disabled` option to `meson setup` script.
+
+ - Unless `meson setup build -Dunit-tests=false` is specified, GoogleTest (GTest) and RapidCheck are required, which are available at
+ and respectively.
diff --git a/doc/manual/source/introduction.md b/doc/manual/source/introduction.md
index 039ad6f30b1c..06518598aa10 100644
--- a/doc/manual/source/introduction.md
+++ b/doc/manual/source/introduction.md
@@ -25,7 +25,7 @@ as
/nix/store/q06x3jll2yfzckz2bzqak089p43ixkkq-firefox-33.1/
-where `b6gvzjyb2pg0…` is a unique identifier for the package that
+where `q06x3jll2yfz…` is a unique identifier for the package that
captures all its dependencies (it’s a cryptographic hash of the
package’s build dependency graph). This enables many powerful
features.
@@ -64,7 +64,7 @@ builds correctly on your system, this is because you specified the
dependency explicitly. This takes care of the build-time dependencies.
Once a package is built, runtime dependencies are found by scanning
-binaries for the hash parts of Nix store paths (such as `r8vvq9kq…`).
+binaries for the [hash parts](@docroot@/store/store-path.md#digest) of Nix store paths (such as `r8vvq9kq…`).
This sounds risky, but it works extremely well.
## Multi-user support
@@ -189,7 +189,7 @@ the package:
## Portability
-Nix runs on Linux and macOS.
+Nix runs on Linux, macOS and FreeBSD.
## NixOS
diff --git a/doc/manual/source/language/advanced-attributes.md b/doc/manual/source/language/advanced-attributes.md
index 67612029c8a4..cc2743dc5ca9 100644
--- a/doc/manual/source/language/advanced-attributes.md
+++ b/doc/manual/source/language/advanced-attributes.md
@@ -337,8 +337,8 @@ Here is more information on the `output*` attributes, and what values they may b
This will specify the output hash of the single output of a [fixed-output derivation].
- The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
- The ["nix32" encoding](@docroot@/protocols/nix32.md) is Nix's variant of base-32 encoding.
+ The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](@docroot@/glossary.md#gloss-sri).
+ The ["nix32" encoding](@docroot@/protocols/nix32.md) is Nix's variant of Base32 encoding.
> **Note**
>
diff --git a/doc/manual/source/language/derivations.md b/doc/manual/source/language/derivations.md
index 2403183fc2d2..50aa525acbf4 100644
--- a/doc/manual/source/language/derivations.md
+++ b/doc/manual/source/language/derivations.md
@@ -165,7 +165,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
>
> for an Autoconf-style package.
- The name of an output is combined with the name of the derivation to create the name part of the output's store path, unless it is `out`, in which case just the name of the derivation is used.
+ The name of an output is combined with the name of the derivation to create the [name part](@docroot@/store/store-path.md#name) of the output's store path, unless it is `out`, in which case just the name of the derivation is used.
> **Example**
>
diff --git a/doc/manual/source/package-management/binary-cache-substituter.md b/doc/manual/source/package-management/binary-cache-substituter.md
index e6a772213d6d..bc2cdfb27ab2 100644
--- a/doc/manual/source/package-management/binary-cache-substituter.md
+++ b/doc/manual/source/package-management/binary-cache-substituter.md
@@ -19,7 +19,7 @@ whatever port you like:
$ nix-serve -p 8080
```
-To check whether it works, try fetching the [`nix-cache-info`](@docroot@/protocols/nix-cache-info.md) file on the client:
+To check whether it works, try fetching the [`nix-cache-info`](@docroot@/protocols/binary-cache/nix-cache-info.md) file on the client:
```console
$ curl http://avalon:8080/nix-cache-info
@@ -28,7 +28,7 @@ WantMassQuery: 1
Priority: 30
```
-When writing to a binary cache (e.g., with [`nix copy`](@docroot@/command-ref/new-cli/nix3-copy.md)), Nix creates [`nix-cache-info`](@docroot@/protocols/nix-cache-info.md) automatically if it doesn't exist.
+When writing to a binary cache (e.g., with [`nix copy`](@docroot@/command-ref/new-cli/nix3-copy.md)), Nix creates [`nix-cache-info`](@docroot@/protocols/binary-cache/nix-cache-info.md) automatically if it doesn't exist.
On the client side, you can tell Nix to use your binary cache using
`--substituters`, e.g.:
diff --git a/doc/manual/source/package-management/profiles.md b/doc/manual/source/package-management/profiles.md
index 1d9e672a8def..53cf5061f834 100644
--- a/doc/manual/source/package-management/profiles.md
+++ b/doc/manual/source/package-management/profiles.md
@@ -11,8 +11,7 @@ in a directory
another version might be stored in
`/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long
strings prefixed to the directory names are cryptographic hashes (to be
-precise, 160-bit truncations of SHA-256 hashes encoded in a base-32
-notation) of *all* inputs involved in building the package — sources,
+precise, 160-bit truncations of SHA-256 hashes encoded in [Nix32](@docroot@/protocols/nix32.md)) of *all* inputs involved in building the package — sources,
dependencies, compiler flags, and so on. So if two packages differ in
any way, they end up in different locations in the file system, so they
don’t interfere with each other. Here is what a part of a typical Nix
diff --git a/doc/manual/source/protocols/binary-cache/index.md b/doc/manual/source/protocols/binary-cache/index.md
new file mode 100644
index 000000000000..d86d307ad9ee
--- /dev/null
+++ b/doc/manual/source/protocols/binary-cache/index.md
@@ -0,0 +1,19 @@
+# Binary Cache
+
+The binary cache format is an interface designed for exposing a store over HTTP.
+
+A binary cache consists of:
+
+- A [`nix-cache-info`](./nix-cache-info.md) file at the root with remote-side configuration.
+- For each [store object](@docroot@/store/store-object.md):
+ - A [`.narinfo`](./narinfo.md) file containing the object's [metadata](@docroot@/store/store-object.md#metadata) and a (usually relative) URL to the corresponding compressed NAR.
+ - A possibly-compressed [Nix Archive](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) containing the store object's file system data.
+- For every entry in the [build trace](@docroot@/store/build-trace.md), a JSON file at `build-trace-v2//.doi`:
+ - the path encodes the [key](@docroot@/protocols/json/build-trace-entry.md#key)
+ - the contents are the [value](@docroot@/protocols/json/build-trace-entry.md#value).
+
+The following [store types](@docroot@/store/types/index.md) use the binary cache format:
+
+- [HTTP Binary Cache Store](@docroot@/store/types/http-binary-cache-store.md) — served over HTTP(S)
+- [Local Binary Cache Store](@docroot@/store/types/local-binary-cache-store.md) — stored on the file system
+- [S3 Binary Cache Store](@docroot@/store/types/s3-binary-cache-store.md) — stored in an AWS S3 bucket
diff --git a/doc/manual/source/protocols/binary-cache/narinfo.md b/doc/manual/source/protocols/binary-cache/narinfo.md
new file mode 100644
index 000000000000..e2e2efac0eeb
--- /dev/null
+++ b/doc/manual/source/protocols/binary-cache/narinfo.md
@@ -0,0 +1,42 @@
+# `.narinfo` Format
+
+A `.narinfo` file contains the [metadata of a store object](@docroot@/store/store-object.md#metadata) in the [binary cache](@docroot@/protocols/binary-cache/index.md) format.
+It is a simple line-oriented format where each line is a `Key: Value` pair.
+Some keys (e.g. `Sig`) may appear multiple times.
+
+The file is named `.narinfo`, where `` is the [hash part](@docroot@/store/store-path.md#digest) of the store object's [store path](@docroot@/store/store-path.md).
+
+The fields correspond to those documented in the [store object info](@docroot@/protocols/json/store-object-info.md) JSON format:
+
+| `.narinfo` field | JSON field | Differences |
+|---|---|---|
+| `StorePath` | [`path`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_path) | Full [store path](@docroot@/store/store-path.md) rather than [store path base name](@docroot@/store/store-path.md#base-name) |
+| `URL` | [`url`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_url) | |
+| `Compression` | [`compression`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_compression) | Defaults to `bzip2` if omitted |
+| `FileHash` | [`downloadHash`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_downloadHash) | String-encoded hash rather than structured |
+| `FileSize` | [`downloadSize`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_downloadSize) | |
+| `NarHash` | [`narHash`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_narHash) | String-encoded hash rather than structured |
+| `NarSize` | [`narSize`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_narSize) | |
+| `References` | [`references`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_references) | Space-separated [store path base names](@docroot@/store/store-path.md#base-name) rather than a JSON array |
+| `Deriver` | [`deriver`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_deriver) | [Store path base name](@docroot@/store/store-path.md#base-name); `unknown-deriver` instead of `null` |
+| `Sig` | [`signatures`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_signatures) | May appear multiple times rather than using an array |
+| `CA` | [`ca`](@docroot@/protocols/json/store-object-info.md#oneOf_i2_ca) | String-encoded [content address](@docroot@/store/store-object/content-address.md) rather than structured |
+
+## Example
+
+
+
+```
+StorePath: /nix/store/n5wkd9frr45pa74if5gpz9j7mifg27fh-foo
+URL: nar/1w1fff338fvdw53sqgamddn1b2xgds473pv6y13gizdbqjv4i5p3.nar.xz?sha256=1w1fff338fvdw53sqgamddn1b2xgds473pv6y13gizdbqjv4i5p3
+Compression: xz
+FileHash: sha256:09ymwqf5i9q7d4dm7x4pjjcqqj0qrcp5lnznbh42gfsci5hcbqqm
+FileSize: 4029176
+NarHash: sha256:09ymwqf5i9q7d4dm7x4pjjcqqj0qrcp5lnznbh42gfsci5hcbqqm
+NarSize: 34878
+References: g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar n5wkd9frr45pa74if5gpz9j7mifg27fh-foo
+Deriver: g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar.drv
+Sig: asdf:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==
+Sig: qwer:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==
+CA: fixed:r:sha256:1lr187v6dck1rjh2j6svpikcfz53wyl3qrlcbb405zlh13x0khhh
+```
diff --git a/doc/manual/source/protocols/nix-cache-info.md b/doc/manual/source/protocols/binary-cache/nix-cache-info.md
similarity index 90%
rename from doc/manual/source/protocols/nix-cache-info.md
rename to doc/manual/source/protocols/binary-cache/nix-cache-info.md
index e8351e1cebe8..3859b2a10ac4 100644
--- a/doc/manual/source/protocols/nix-cache-info.md
+++ b/doc/manual/source/protocols/binary-cache/nix-cache-info.md
@@ -1,6 +1,6 @@
-# Nix Cache Info Format
+# `nix-cache-info` Format
-The `nix-cache-info` file is a metadata file at the root of a [binary cache](@docroot@/package-management/binary-cache-substituter.md) (e.g., `https://cache.example.com/nix-cache-info`).
+The `nix-cache-info` file is a metadata file at the root of a [binary cache](@docroot@/protocols/binary-cache/index.md) (e.g., `https://cache.example.com/nix-cache-info`).
MIME type: `text/x-nix-cache-info`
diff --git a/doc/manual/source/protocols/derivation-aterm.md b/doc/manual/source/protocols/derivation-aterm.md
index 523678e663e3..778614eb1602 100644
--- a/doc/manual/source/protocols/derivation-aterm.md
+++ b/doc/manual/source/protocols/derivation-aterm.md
@@ -26,7 +26,7 @@ Derivations are serialised in one of the following formats:
When derivation is encoded to a [store object] we make the following choices:
-- The store path name is the derivation name with `.drv` suffixed at the end
+- The store path [name](@docroot@/store/store-path.md#name) is the derivation name with `.drv` suffixed at the end
Indeed, the ATerm format above does *not* contain the name of the derivation, on the assumption that a store path will also be provided out-of-band.
diff --git a/doc/manual/source/protocols/json/build-trace-entry.md b/doc/manual/source/protocols/json/build-trace-entry.md
index 9eea93712601..d4a3a96edb64 100644
--- a/doc/manual/source/protocols/json/build-trace-entry.md
+++ b/doc/manual/source/protocols/json/build-trace-entry.md
@@ -1,21 +1,21 @@
-{{#include build-trace-entry-v2-fixed.md}}
+{{#include build-trace-entry-v3-fixed.md}}
## Examples
### Simple build trace entry
```json
-{{#include schema/build-trace-entry-v2/simple.json}}
+{{#include schema/build-trace-entry-v3/simple.json}}
```
### Build trace entry with signature
```json
-{{#include schema/build-trace-entry-v2/with-signature.json}}
+{{#include schema/build-trace-entry-v3/with-signature.json}}
```
diff --git a/doc/manual/source/protocols/json/derivation/resolved.md b/doc/manual/source/protocols/json/derivation/resolved.md
new file mode 100644
index 000000000000..45e18d9af047
--- /dev/null
+++ b/doc/manual/source/protocols/json/derivation/resolved.md
@@ -0,0 +1 @@
+{{#include ../derivation-resolved-v4-fixed.md}}
diff --git a/doc/manual/source/protocols/json/fixup-json-schema-generated-doc.sed b/doc/manual/source/protocols/json/fixup-json-schema-generated-doc.sed
index 96b6f1801a57..0162036d420b 100644
--- a/doc/manual/source/protocols/json/fixup-json-schema-generated-doc.sed
+++ b/doc/manual/source/protocols/json/fixup-json-schema-generated-doc.sed
@@ -16,3 +16,6 @@ s^\(./hash-v1.yaml\)\?#/$defs/algorithm^[JSON format for `Hash`](@docroot@/proto
s^\(./hash-v1.yaml\)^[JSON format for `Hash`](@docroot@/protocols/json/hash.html)^g
s^\(./content-address-v1.yaml\)\?#/$defs/method^[JSON format for `ContentAddress`](@docroot@/protocols/json/content-address.html#method)^g
s^\(./content-address-v1.yaml\)^[JSON format for `ContentAddress`](@docroot@/protocols/json/content-address.html)^g
+s^\(./store-path-v1.yaml\)^[JSON format for `StorePath`](@docroot@/protocols/json/store-path.html)^g
+s^\(./derivation-v4.yaml\)\?#/\$defs/common/properties/[a-zA-Z]*^[JSON format for `Derivation`](@docroot@/protocols/json/derivation/index.html)^g
+s^\(./derivation-v4.yaml\)^[JSON format for `Derivation`](@docroot@/protocols/json/derivation/index.html)^g
diff --git a/doc/manual/source/protocols/json/meson.build b/doc/manual/source/protocols/json/meson.build
index c7c48c4ed6e2..9fcacb20387f 100644
--- a/doc/manual/source/protocols/json/meson.build
+++ b/doc/manual/source/protocols/json/meson.build
@@ -13,11 +13,13 @@ schemas = [
'hash-v1',
'content-address-v1',
'store-path-v1',
- 'store-object-info-v2',
+ 'signature-v2',
+ 'store-object-info-v3',
'derivation-v4',
+ 'derivation-resolved-v4',
'derivation-options-v1',
'deriving-path-v1',
- 'build-trace-entry-v2',
+ 'build-trace-entry-v3',
'build-result-v1',
'store-v1',
]
diff --git a/doc/manual/source/protocols/json/schema/build-result-v1.yaml b/doc/manual/source/protocols/json/schema/build-result-v1.yaml
index 55e55d3e5cbe..d0d8d8a0c742 100644
--- a/doc/manual/source/protocols/json/schema/build-result-v1.yaml
+++ b/doc/manual/source/protocols/json/schema/build-result-v1.yaml
@@ -83,7 +83,7 @@ properties:
description: |
A mapping from output names to their build trace entries.
additionalProperties:
- "$ref": "build-trace-entry-v2.yaml"
+ "$ref": "build-trace-entry-v3.yaml#/$defs/value"
failure:
type: object
diff --git a/doc/manual/source/protocols/json/schema/build-trace-entry-v2.yaml b/doc/manual/source/protocols/json/schema/build-trace-entry-v2.yaml
deleted file mode 100644
index 4340f82388c2..000000000000
--- a/doc/manual/source/protocols/json/schema/build-trace-entry-v2.yaml
+++ /dev/null
@@ -1,95 +0,0 @@
-"$schema": "http://json-schema.org/draft-04/schema"
-"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/build-trace-entry-v2.json"
-title: Build Trace Entry
-description: |
- A record of a successful build outcome for a specific derivation output.
-
- This schema describes the JSON representation of a [build trace entry](@docroot@/store/build-trace.md).
-
- > **Warning**
- >
- > This JSON format is currently
- > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-ca-derivations)
- > and subject to change.
-
- Verision history:
-
- - Version 1: Original format
-
- - Version 2: Remove `dependentRealisations`
-
-type: object
-required:
- - id
- - outPath
- - signatures
-allOf:
- - "$ref": "#/$defs/key"
- - "$ref": "#/$defs/value"
-properties:
- id: {}
- outPath: {}
- signatures: {}
-additionalProperties:
- dependentRealisations:
- description: deprecated field
- type: object
-
-"$defs":
- key:
- title: Build Trace Key
- description: |
- A [build trace entry](@docroot@/store/build-trace.md) is a key-value pair.
- This is the "key" part, refering to a derivation and output.
- type: object
- required:
- - id
- properties:
- id:
- type: string
- title: Derivation Output ID
- pattern: "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$"
- description: |
- Unique identifier for the derivation output that was built.
-
- Format: `{hash-quotient-drv}!{output-name}`
-
- - **hash-quotient-drv**: SHA-256 [hash of the quotient derivation](@docroot@/store/derivation/outputs/input-address.md#hash-quotient-drv).
- Begins with `sha256:`.
-
- - **output-name**: Name of the specific output (e.g., "out", "dev", "doc")
-
- Example: `"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad!foo"`
-
- value:
- title: Build Trace Value
- description: |
- A [build trace entry](@docroot@/store/build-trace.md) is a key-value pair.
- This is the "value" part, describing an output.
- type: object
- required:
- - outPath
- - signatures
- properties:
- outPath:
- "$ref": "store-path-v1.yaml"
- title: Output Store Path
- description: |
- The path to the store object that resulted from building this derivation for the given output name.
-
- patternProperties:
- "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$":
- "$ref": "store-path-v1.yaml"
- title: Dependent Store Path
- description: Store path that this dependency resolved to during the build
- additionalProperties: false
-
- signatures:
- type: array
- title: Build Signatures
- description: |
- A set of cryptographic signatures attesting to the authenticity of this build trace entry.
- items:
- type: string
- title: Signature
- description: A single cryptographic signature
diff --git a/doc/manual/source/protocols/json/schema/build-trace-entry-v2 b/doc/manual/source/protocols/json/schema/build-trace-entry-v3
similarity index 100%
rename from doc/manual/source/protocols/json/schema/build-trace-entry-v2
rename to doc/manual/source/protocols/json/schema/build-trace-entry-v3
diff --git a/doc/manual/source/protocols/json/schema/build-trace-entry-v3.yaml b/doc/manual/source/protocols/json/schema/build-trace-entry-v3.yaml
new file mode 100644
index 000000000000..2e825af6fb8a
--- /dev/null
+++ b/doc/manual/source/protocols/json/schema/build-trace-entry-v3.yaml
@@ -0,0 +1,83 @@
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/build-trace-entry-v3.json"
+title: Build Trace Entry
+description: |
+ A record of a successful build outcome for a specific derivation output.
+
+ This schema describes the JSON representation of an [entry](@docroot@/store/build-trace.md#entry) in a [build trace](@docroot@/store/build-trace.md).
+
+ > **Warning**
+ >
+ > This JSON format is currently
+ > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-ca-derivations)
+ > and subject to change.
+
+ ## Version History
+
+ - Version 1: Original format
+
+ - Version 2:
+ - Remove `dependentRealisations`
+
+ - Version 3:
+ - Use `drvPath` not `drvHash` to refer to derivation in a more conventional way.
+ - Separate into `key` and `value`
+ - Use 2nd version of signatures format (objects, not strings)
+
+type: object
+required:
+ - key
+ - value
+properties:
+ key:
+ "$ref": "#/$defs/key"
+ value:
+ "$ref": "#/$defs/value"
+additionalProperties: false
+
+"$defs":
+ key:
+ title: Build Trace Key
+ description: |
+ A [build trace entry](@docroot@/store/build-trace.md#entry) is a key-value pair.
+ This is the "key" part, referring to a derivation and output.
+ type: object
+ required:
+ - drvPath
+ - outputName
+ properties:
+ drvPath:
+ "$ref": "store-path-v1.yaml"
+ title: Derivation Path
+ description: |
+ The store path of the derivation that was built.
+ outputName:
+ type: string
+ title: Output Name
+ description: |
+ Name of the specific output (e.g., "out", "dev", "doc")
+ additionalProperties: false
+
+ value:
+ title: Build Trace Value
+ description: |
+ A [build trace entry](@docroot@/store/build-trace.md#entry) is a key-value pair.
+ This is the "value" part, describing an output.
+ type: object
+ required:
+ - outPath
+ - signatures
+ properties:
+ outPath:
+ "$ref": "store-path-v1.yaml"
+ title: Output Store Path
+ description: |
+ The path to the store object that resulted from building this derivation for the given output name.
+
+ signatures:
+ type: array
+ title: Build Signatures
+ description: |
+ A set of cryptographic signatures attesting to the authenticity of this build trace entry.
+ items:
+ "$ref": "signature-v2.yaml"
diff --git a/doc/manual/source/protocols/json/schema/derivation-resolved-v4.yaml b/doc/manual/source/protocols/json/schema/derivation-resolved-v4.yaml
new file mode 100644
index 000000000000..705156eb8451
--- /dev/null
+++ b/doc/manual/source/protocols/json/schema/derivation-resolved-v4.yaml
@@ -0,0 +1,52 @@
+"$schema": "http://json-schema.org/draft-04/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/derivation-resolved-v4.json"
+title: Resolved Derivation
+description: |
+ Experimental JSON representation of a resolved Nix derivation (version 4).
+
+ This schema describes the JSON representation of Nix's `BasicDerivation` type,
+ which is a derivation with all input derivation dependencies resolved to store paths.
+ This is the result of `Derivation::tryResolve`.
+
+ This is called "version 4" because we wish to keep it in sync with the
+ [primary (not necessarily resolved) JSON schema](@docroot@/protocols/json/derivation/index.md),
+ but actually it is the first version for this format.
+
+type: object
+required:
+ - name
+ - version
+ - outputs
+ - inputs
+ - system
+ - builder
+ - args
+ - env
+properties:
+ name: { "$ref": "derivation-v4.yaml#/$defs/common/properties/name" }
+ version: { "$ref": "derivation-v4.yaml#/$defs/common/properties/version" }
+ outputs: { "$ref": "derivation-v4.yaml#/$defs/common/properties/outputs" }
+ system: { "$ref": "derivation-v4.yaml#/$defs/common/properties/system" }
+ builder: { "$ref": "derivation-v4.yaml#/$defs/common/properties/builder" }
+ args: { "$ref": "derivation-v4.yaml#/$defs/common/properties/args" }
+ env: { "$ref": "derivation-v4.yaml#/$defs/common/properties/env" }
+ structuredAttrs: { "$ref": "derivation-v4.yaml#/$defs/common/properties/structuredAttrs" }
+
+ inputs:
+ type: array
+ title: Input source paths
+ description: |
+ List of store paths on which this resolved derivation depends.
+ Since all derivation inputs have been resolved, only source paths remain.
+
+ > **Example**
+ >
+ > ```json
+ > "inputs": [
+ > "b8nwz167km1yciqpwzjj24f8jcy8pq1h-separate-debug-info.sh",
+ > "f1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-dep1-out"
+ > ]
+ > ```
+ items:
+ $ref: "store-path-v1.yaml"
+additionalProperties: false
diff --git a/doc/manual/source/protocols/json/schema/derivation-v4.yaml b/doc/manual/source/protocols/json/schema/derivation-v4.yaml
index c1884769671e..fa443d982c25 100644
--- a/doc/manual/source/protocols/json/schema/derivation-v4.yaml
+++ b/doc/manual/source/protocols/json/schema/derivation-v4.yaml
@@ -23,57 +23,14 @@ required:
- args
- env
properties:
- name:
- type: string
- title: Derivation name
- description: |
- The name of the derivation.
- Used when calculating store paths for the derivation’s outputs.
-
- version:
- const: 4
- title: Format version (must be 4)
- description: |
- Must be `4`.
- This is a guard that allows us to continue evolving this format.
- The choice of `3` is fairly arbitrary, but corresponds to this informal version:
-
- - Version 0: ATerm format
-
- - Version 1: Original JSON format, with ugly `"r:sha256"` inherited from ATerm format.
-
- - Version 2: Separate `method` and `hashAlgo` fields in output specs
-
- - Version 3: Drop store dir from store paths, just include base name.
-
- - Version 4: Two cleanups, batched together to lesson churn:
-
- - Reorganize inputs into nested structure (`inputs.srcs` and `inputs.drvs`)
-
- - Use canonical content address JSON format for floating content addressed derivation outputs.
-
- Note that while this format is experimental, the maintenance of versions is best-effort, and not promised to identify every change.
-
- outputs:
- type: object
- title: Output specifications
- description: |
- Information about the output paths of the derivation.
- This is a JSON object with one member per output, where the key is the output name and the value is a JSON object as described.
-
- > **Example**
- >
- > ```json
- > "outputs": {
- > "out": {
- > "method": "nar",
- > "hashAlgo": "sha256",
- > "hash": "6fc80dcc62179dbc12fc0b5881275898f93444833d21b89dfe5f7fbcbb1d0d62"
- > }
- > }
- > ```
- additionalProperties:
- "$ref": "#/$defs/output/overall"
+ name: { "$ref": "#/$defs/common/properties/name" }
+ version: { "$ref": "#/$defs/common/properties/version" }
+ outputs: { "$ref": "#/$defs/common/properties/outputs" }
+ system: { "$ref": "#/$defs/common/properties/system" }
+ builder: { "$ref": "#/$defs/common/properties/builder" }
+ args: { "$ref": "#/$defs/common/properties/args" }
+ env: { "$ref": "#/$defs/common/properties/env" }
+ structuredAttrs: { "$ref": "#/$defs/common/properties/structuredAttrs" }
inputs:
type: object
@@ -126,47 +83,105 @@ properties:
- "$ref": "#/$defs/dynamicOutputs"
additionalProperties: false
additionalProperties: false
+additionalProperties: false
- system:
- type: string
- title: Build system type
+"$defs":
+ common:
+ title: Common Derivation Fields
description: |
- The system type on which this derivation is to be built
- (e.g. `x86_64-linux`).
+ Fields shared between `Derivation` and `BasicDerivation`.
+ properties:
+ name:
+ type: string
+ title: Derivation name
+ description: |
+ The name of the derivation.
+ Used when calculating store paths for the derivation's outputs.
- builder:
- type: string
- title: Build program path
- description: |
- Absolute path of the program used to perform the build.
- Typically this is the `bash` shell
- (e.g. `/nix/store/p4xlj4imjbnm4v0x5jf4qysvyjjlgq1d-bash-4.4-p23/bin/bash`).
+ version:
+ const: 4
+ title: Format version (must be 4)
+ description: |
+ Must be `4`.
+ This is a guard that allows us to continue evolving this format.
+ The choice of `3` is fairly arbitrary, but corresponds to this informal version:
- args:
- type: array
- title: Builder arguments
- description: |
- Command-line arguments passed to the `builder`.
- items:
- type: string
+ - Version 0: ATerm format
- env:
- type: object
- title: Environment variables
- description: |
- Environment variables passed to the `builder`.
- additionalProperties:
- type: string
+ - Version 1: Original JSON format, with ugly `"r:sha256"` inherited from ATerm format.
- structuredAttrs:
- title: Structured attributes
- description: |
- [Structured Attributes](@docroot@/store/derivation/index.md#structured-attrs), only defined if the derivation contains them.
- Structured attributes are JSON, and thus embedded as-is.
- type: object
- additionalProperties: true
+ - Version 2: Separate `method` and `hashAlgo` fields in output specs
+
+ - Version 3: Drop store dir from store paths, just include base name.
+
+ - Version 4: Two cleanups, batched together to lesson churn:
+
+ - Reorganize inputs into nested structure (`inputs.srcs` and `inputs.drvs`)
+
+ - Use canonical content address JSON format for floating content addressed derivation outputs.
+
+ Note that while this format is experimental, the maintenance of versions is best-effort, and not promised to identify every change.
+
+ outputs:
+ type: object
+ title: Output specifications
+ description: |
+ Information about the output paths of the derivation.
+ This is a JSON object with one member per output, where the key is the output name and the value is a JSON object as described.
+
+ > **Example**
+ >
+ > ```json
+ > "outputs": {
+ > "out": {
+ > "method": "nar",
+ > "hashAlgo": "sha256",
+ > "hash": "6fc80dcc62179dbc12fc0b5881275898f93444833d21b89dfe5f7fbcbb1d0d62"
+ > }
+ > }
+ > ```
+ additionalProperties:
+ "$ref": "#/$defs/output/overall"
+
+ system:
+ type: string
+ title: Build system type
+ description: |
+ The system type on which this derivation is to be built
+ (e.g. `x86_64-linux`).
+
+ builder:
+ type: string
+ title: Build program path
+ description: |
+ Absolute path of the program used to perform the build.
+ Typically this is the `bash` shell
+ (e.g. `/nix/store/p4xlj4imjbnm4v0x5jf4qysvyjjlgq1d-bash-4.4-p23/bin/bash`).
+
+ args:
+ type: array
+ title: Builder arguments
+ description: |
+ Command-line arguments passed to the `builder`.
+ items:
+ type: string
+
+ env:
+ type: object
+ title: Environment variables
+ description: |
+ Environment variables passed to the `builder`.
+ additionalProperties:
+ type: string
+
+ structuredAttrs:
+ title: Structured attributes
+ description: |
+ [Structured Attributes](@docroot@/store/derivation/index.md#structured-attrs), only defined if the derivation contains them.
+ Structured attributes are JSON, and thus embedded as-is.
+ type: object
+ additionalProperties: true
-"$defs":
output:
overall:
title: Derivation Output
diff --git a/doc/manual/source/protocols/json/schema/nar-info-v3 b/doc/manual/source/protocols/json/schema/nar-info-v3
new file mode 120000
index 000000000000..378215b4156b
--- /dev/null
+++ b/doc/manual/source/protocols/json/schema/nar-info-v3
@@ -0,0 +1 @@
+../../../../../../src/libstore-tests/data/nar-info/json-3
\ No newline at end of file
diff --git a/doc/manual/source/protocols/json/schema/signature-v2.yaml b/doc/manual/source/protocols/json/schema/signature-v2.yaml
new file mode 100644
index 000000000000..d94798902f47
--- /dev/null
+++ b/doc/manual/source/protocols/json/schema/signature-v2.yaml
@@ -0,0 +1,27 @@
+"$schema": "http://json-schema.org/draft-07/schema"
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/signature-v2.json"
+title: Signature
+description: |
+ A cryptographic signature along with the name of the key that produced it.
+
+ This schema describes the JSON representation of signatures as used in various Nix JSON APIs.
+
+ ## Version History
+
+ - Version 1: Colon-separated string in the format `:`
+
+ - Version 2: Structured object with `keyName` and `sig` fields
+
+type: object
+required:
+ - keyName
+ - sig
+properties:
+ keyName:
+ type: string
+ title: Key Name
+ description: The name of the key used to produce this signature
+ sig:
+ type: string
+ title: Signature Data
+ description: The raw signature bytes, Base64-encoded
diff --git a/doc/manual/source/protocols/json/schema/signature-v2/simple.json b/doc/manual/source/protocols/json/schema/signature-v2/simple.json
new file mode 100644
index 000000000000..abf69dfa0f92
--- /dev/null
+++ b/doc/manual/source/protocols/json/schema/signature-v2/simple.json
@@ -0,0 +1,4 @@
+{
+ "keyName": "cache.nixos.org-1",
+ "sig": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+}
diff --git a/doc/manual/source/protocols/json/schema/store-object-info-v2 b/doc/manual/source/protocols/json/schema/store-object-info-v2
deleted file mode 120000
index 36ca7f13db94..000000000000
--- a/doc/manual/source/protocols/json/schema/store-object-info-v2
+++ /dev/null
@@ -1 +0,0 @@
-../../../../../../src/libstore-tests/data/path-info/json-2
\ No newline at end of file
diff --git a/doc/manual/source/protocols/json/schema/store-object-info-v3 b/doc/manual/source/protocols/json/schema/store-object-info-v3
new file mode 120000
index 000000000000..d5dae48fcf69
--- /dev/null
+++ b/doc/manual/source/protocols/json/schema/store-object-info-v3
@@ -0,0 +1 @@
+../../../../../../src/libstore-tests/data/path-info/json-3
\ No newline at end of file
diff --git a/doc/manual/source/protocols/json/schema/store-object-info-v2.yaml b/doc/manual/source/protocols/json/schema/store-object-info-v3.yaml
similarity index 96%
rename from doc/manual/source/protocols/json/schema/store-object-info-v2.yaml
rename to doc/manual/source/protocols/json/schema/store-object-info-v3.yaml
index 582b5e9eb476..bf4e4dafe144 100644
--- a/doc/manual/source/protocols/json/schema/store-object-info-v2.yaml
+++ b/doc/manual/source/protocols/json/schema/store-object-info-v3.yaml
@@ -1,6 +1,6 @@
"$schema": "http://json-schema.org/draft-04/schema"
-"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/store-object-info-v2.json"
-title: Store Object Info v2
+"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/store-object-info-v3.json"
+title: Store Object Info v3
description: |
Information about a [store object](@docroot@/store/store-object.md).
@@ -44,10 +44,10 @@ $defs:
properties:
version:
type: integer
- const: 2
- title: Format version (must be 2)
+ const: 3
+ title: Format version (must be 3)
description: |
- Must be `2`.
+ Must be `3`.
This is a guard that allows us to continue evolving this format.
Here is the rough version history:
@@ -57,6 +57,8 @@ $defs:
- Version 2: Use structured JSON type for `ca`
+ - Version 3: Use structured JSON type for `signatures`
+
path:
"$ref": "./store-path-v1.yaml"
title: Store Path
@@ -101,7 +103,7 @@ $defs:
type: string
title: Store Directory
description: |
- The [store directory](@docroot@/store/store-path.md#store-directory) this store object belongs to (e.g. `/nix/store`).
+ The [path to the store directory](@docroot@/store/store-path.md#store-directory-path) this store object belongs within (e.g. `/nix/store`).
additionalProperties: false
impure:
@@ -168,7 +170,7 @@ $defs:
> This is an "impure" field that may not be included in certain contexts.
items:
- type: string
+ "$ref": "./signature-v2.yaml"
# Computed closure fields
closureSize:
diff --git a/doc/manual/source/protocols/json/schema/store-path-v1.yaml b/doc/manual/source/protocols/json/schema/store-path-v1.yaml
index 3cd7c56fcf79..31760c64a617 100644
--- a/doc/manual/source/protocols/json/schema/store-path-v1.yaml
+++ b/doc/manual/source/protocols/json/schema/store-path-v1.yaml
@@ -18,7 +18,7 @@ description: |
The format follows this pattern: `${digest}-${name}`
- - **hash**: Digest rendered in [Nix32](@docroot@/protocols/nix32.md), a variant of base-32 (20 hash bytes become 32 ASCII characters)
+ - **hash**: Digest rendered in [Nix32](@docroot@/protocols/nix32.md) (20 hash bytes become 32 ASCII characters)
- **name**: The package name and optional version/suffix information
type: string
diff --git a/doc/manual/source/protocols/json/schema/store-v1.yaml b/doc/manual/source/protocols/json/schema/store-v1.yaml
index e3e09c699621..eaf5c624b0be 100644
--- a/doc/manual/source/protocols/json/schema/store-v1.yaml
+++ b/doc/manual/source/protocols/json/schema/store-v1.yaml
@@ -37,7 +37,7 @@ properties:
- contents
properties:
info:
- "$ref": "./store-object-info-v2.yaml#/$defs/impure"
+ "$ref": "./store-object-info-v3.yaml#/$defs/impure"
title: Store Object Info
description: |
Metadata about the [store object](@docroot@/store/store-object.md) including hash, size, references, etc.
@@ -70,7 +70,7 @@ properties:
"^[A-Za-z0-9+/]{43}=$":
type: object
additionalProperties:
- "$ref": "./build-trace-entry-v2.yaml#/$defs/value"
+ "$ref": "./build-trace-entry-v3.yaml#/$defs/value"
additionalProperties: false
"$defs":
diff --git a/doc/manual/source/protocols/json/signature.md b/doc/manual/source/protocols/json/signature.md
new file mode 100644
index 000000000000..363b4ef11e0a
--- /dev/null
+++ b/doc/manual/source/protocols/json/signature.md
@@ -0,0 +1,9 @@
+{{#include signature-v2-fixed.md}}
+
+## Examples
+
+### Simple signature
+
+```json
+{{#include schema/signature-v2/simple.json}}
+```
diff --git a/doc/manual/source/protocols/json/store-object-info.md b/doc/manual/source/protocols/json/store-object-info.md
index 4ad83de00b3f..ea1cc3a9d223 100644
--- a/doc/manual/source/protocols/json/store-object-info.md
+++ b/doc/manual/source/protocols/json/store-object-info.md
@@ -1,45 +1,45 @@
-{{#include store-object-info-v2-fixed.md}}
+{{#include store-object-info-v3-fixed.md}}
## Examples
### Minimal store object (content-addressed)
```json
-{{#include schema/store-object-info-v2/pure.json}}
+{{#include schema/store-object-info-v3/pure.json}}
```
### Store object with impure fields
```json
-{{#include schema/store-object-info-v2/impure.json}}
+{{#include schema/store-object-info-v3/impure.json}}
```
### Minimal store object (empty)
```json
-{{#include schema/store-object-info-v2/empty_pure.json}}
+{{#include schema/store-object-info-v3/empty_pure.json}}
```
### Store object with all impure fields
```json
-{{#include schema/store-object-info-v2/empty_impure.json}}
+{{#include schema/store-object-info-v3/empty_impure.json}}
```
### NAR info (minimal)
```json
-{{#include schema/nar-info-v2/pure.json}}
+{{#include schema/nar-info-v3/pure.json}}
```
### NAR info (with binary cache fields)
```json
-{{#include schema/nar-info-v2/impure.json}}
+{{#include schema/nar-info-v3/impure.json}}
```
diff --git a/doc/manual/source/protocols/nix32.md b/doc/manual/source/protocols/nix32.md
index 72afe893ea24..d8da1e9952cf 100644
--- a/doc/manual/source/protocols/nix32.md
+++ b/doc/manual/source/protocols/nix32.md
@@ -1,6 +1,6 @@
# Nix32 Encoding
-Nix32 is Nix's variant of base-32 encoding, used for [store path digests](@docroot@/protocols/store-path.md), hash output via [`nix hash`](@docroot@/command-ref/new-cli/nix3-hash.md), and the [`outputHash`](@docroot@/language/advanced-attributes.md#adv-attr-outputHash) derivation attribute.
+Nix32 is Nix's variant of [Base32](https://en.wikipedia.org/wiki/Base32) encoding, used for [store path digests](@docroot@/protocols/store-path.md), hash output via [`nix hash`](@docroot@/command-ref/new-cli/nix3-hash.md), and the [`outputHash`](@docroot@/language/advanced-attributes.md#adv-attr-outputHash) derivation attribute.
## Alphabet
diff --git a/doc/manual/source/protocols/store-path.md b/doc/manual/source/protocols/store-path.md
index 1aa79615d1c8..bdce19d1d62c 100644
--- a/doc/manual/source/protocols/store-path.md
+++ b/doc/manual/source/protocols/store-path.md
@@ -18,11 +18,9 @@ where
- `name` = the name of the store object.
-- `store-dir` = the [store directory](@docroot@/store/store-path.md#store-directory)
+- `store-dir` = the [path of the store directory](@docroot@/store/store-path.md#store-directory-path)
-- `digest` = base-32 representation of the compressed to 160 bits [SHA-256] hash of `fingerprint`.
-
- Nix uses a custom base-32 encoding called [Nix32](@docroot@/protocols/nix32.md).
+- `digest` = [Nix32](@docroot@/protocols/nix32.md) representation of the compressed to 160 bits [SHA-256] hash of `fingerprint`.
For the definition of the hash compression algorithm, please refer to section 5.1 of the [Nix thesis](https://edolstra.github.io/pubs/phd-thesis.pdf).
diff --git a/doc/manual/source/release-notes/rl-2.23.md b/doc/manual/source/release-notes/rl-2.23.md
index b358a0fdc3c3..92e5f4599440 100644
--- a/doc/manual/source/release-notes/rl-2.23.md
+++ b/doc/manual/source/release-notes/rl-2.23.md
@@ -14,7 +14,7 @@
- Modify `nix derivation {add,show}` JSON format [#9866](https://github.com/NixOS/nix/issues/9866) [#10722](https://github.com/NixOS/nix/pull/10722)
- The JSON format for derivations has been slightly revised to better conform to our [JSON guidelines](@docroot@/development/json-guideline.md).
+ The JSON format for derivations has been slightly revised to better conform to our [data modeling guidelines](@docroot@/development/data-modeling.md).
In particular, the hash algorithm and content addressing method of content-addressed derivation outputs are now separated into two fields `hashAlgo` and `method`,
rather than one field with an arcane `:`-separated format.
@@ -89,7 +89,7 @@
This makes records of this sort more self-describing, and easier to consume programmatically.
We will follow this design principle going forward;
- the [JSON guidelines](@docroot@/development/json-guideline.md) in the contributing section have been updated accordingly.
+ the [data modeling guidelines](@docroot@/development/data-modeling.md) in the contributing section have been updated accordingly.
- Large path warnings [#10661](https://github.com/NixOS/nix/pull/10661)
diff --git a/doc/manual/source/release-notes/rl-2.30.md b/doc/manual/source/release-notes/rl-2.30.md
index 34d3e5bab4c6..5a65ed99af29 100644
--- a/doc/manual/source/release-notes/rl-2.30.md
+++ b/doc/manual/source/release-notes/rl-2.30.md
@@ -13,7 +13,7 @@
- Deprecate manually making structured attrs using the `__json` attribute [#13220](https://github.com/NixOS/nix/pull/13220)
The proper way to create a derivation using [structured attrs] in the Nix language is by using `__structuredAttrs = true` with [`builtins.derivation`].
- However, by exploiting how structured attrs are implementated, it has also been possible to create them by setting the `__json` environment variable to a serialized JSON string.
+ However, by exploiting how structured attrs are implemented, it has also been possible to create them by setting the `__json` environment variable to a serialized JSON string.
This sneaky alternative method is now deprecated, and may be disallowed in future versions of Nix.
[structured attrs]: @docroot@/language/advanced-attributes.md#adv-attr-structuredAttrs
diff --git a/doc/manual/source/release-notes/rl-2.32.md b/doc/manual/source/release-notes/rl-2.32.md
index 5d90da0c9ebd..c59ecd6c2456 100644
--- a/doc/manual/source/release-notes/rl-2.32.md
+++ b/doc/manual/source/release-notes/rl-2.32.md
@@ -8,7 +8,7 @@
- Derivation JSON format now uses store path basenames only [#13570](https://github.com/NixOS/nix/issues/13570) [#13980](https://github.com/NixOS/nix/pull/13980)
- Experience with many JSON frameworks (e.g. nlohmann/json in C++, Serde in Rust, and Aeson in Haskell) has shown that the use of the store directory in JSON formats is an impediment to systematic JSON formats, because it requires the serializer/deserializer to take an extra paramater (the store directory).
+ Experience with many JSON frameworks (e.g. nlohmann/json in C++, Serde in Rust, and Aeson in Haskell) has shown that the use of the store directory in JSON formats is an impediment to systematic JSON formats, because it requires the serializer/deserializer to take an extra parameter (the store directory).
We ultimately want to rectify this issue with all JSON formats to the extent allowed by our stability promises. To start with, we are changing the JSON format for derivations because the `nix derivation` commands are — in addition to being formally unstable — less widely used than other unstable commands.
diff --git a/doc/manual/source/release-notes/rl-2.33.md b/doc/manual/source/release-notes/rl-2.33.md
index 810dcad00b15..0849f097cd0e 100644
--- a/doc/manual/source/release-notes/rl-2.33.md
+++ b/doc/manual/source/release-notes/rl-2.33.md
@@ -135,7 +135,7 @@ This is the legacy format, preserved for backwards compatibility:
### Version 2 (`--json-format 2`)
-The new structured format follows the [JSON guidelines](@docroot@/development/json-guideline.md) with the following changes:
+The new structured format follows the [data modeling guidelines](@docroot@/development/data-modeling.md) with the following changes:
- **Nested structure with top-level metadata**:
@@ -149,9 +149,9 @@ The new structured format follows the [JSON guidelines](@docroot@/development/js
}
```
- The map from store path base names to store object info is nested under the `info` field.
+ The map from [store path base names](@docroot@/store/store-path.md#base-name) to store object info is nested under the `info` field.
-- **Store path base names instead of full paths**:
+- **[Store path base names](@docroot@/store/store-path.md#base-name) instead of full paths**:
Map keys and references use store path base names (e.g., `"abc...-foo"`) instead of full absolute store paths.
Combined with `storeDir`, the full path can be reconstructed.
diff --git a/doc/manual/source/release-notes/rl-2.34.md b/doc/manual/source/release-notes/rl-2.34.md
index 89017f1767cf..91ee4ad5e9af 100644
--- a/doc/manual/source/release-notes/rl-2.34.md
+++ b/doc/manual/source/release-notes/rl-2.34.md
@@ -119,7 +119,7 @@
New command [`nix store roots-daemon`](@docroot@/command-ref/new-cli/nix3-store-roots-daemon.md) runs a daemon that serves garbage collector roots over a Unix domain socket.
It enables the garbage collector to discover runtime roots when the main Nix daemon doesn't have `CAP_SYS_PTRACE` capability and therefore cannot scan `/proc`.
- The garbage collector can be configured to use this daemon via the [`use-roots-daemon`](@docroot@/store/types/local-store.md#store-experimental-option-use-roots-daemon) store setting.
+ The garbage collector can be configured to use this daemon via the [`use-roots-daemon`](@docroot@/store/types/local-store.md#store-local-store-use-roots-daemon) store setting.
This feature requires the [`local-overlay-store` experimental feature](@docroot@/development/experimental-features.md#xp-feature-local-overlay-store).
diff --git a/doc/manual/source/release-notes/rl-2.35.md b/doc/manual/source/release-notes/rl-2.35.md
new file mode 100644
index 000000000000..a712b6385627
--- /dev/null
+++ b/doc/manual/source/release-notes/rl-2.35.md
@@ -0,0 +1,414 @@
+# Release 2.35.0 (2026-06-22)
+
+## Highlights
+
+- Sources are copied to the store more lazily [#3121](https://github.com/NixOS/nix/issues/3121) [#15711](https://github.com/NixOS/nix/pull/15711) [#15920](https://github.com/NixOS/nix/pull/15920)
+
+ Historically, flakes source trees have been eagerly fetched to and evaluated from the Nix store to ensure deterministic and hermetic evaluation, even if the resulting store object is not used as a derivation input. This made the implementation simpler, yet made flakes unusable in large repositories and performed unnecessary writes to the store on each change to the source tree.
+
+ Since Nix 2.32, all I/O (excluding `path:` and `hg+:`-style inputs) for reading sources during evaluation has been funneled to their original filesystem location (or to the `~/.cache/nix/tarball-cache-v2` bare git repository for tarball-based inputs). However, the source tree was still fetched to the store -- primarily for computing the resulting content-addressed store path. In most cases, (such as importing the `nixpkgs` package set) this is not necessary.
+
+ Touching (and hashing the NAR serialisation of) the whole source tree is unavoidable, since:
+
+ - In case of flake inputs, `narHash` integrity must be checked eagerly.
+ - The `outPath` attribute of a flake must be known in advance, and for backwards compatibility must be a content-addressed store path string with [constant string context](@docroot@/language/string-context.md#string-context-constant) representing the flake source tree.
+
+ Even within the constraints imposed by backwards compatibility requirements, there are several improvements that are achievable. To reduce the number of copies performed, Nix now hashes the input without copying first, assuming that the `.outPath` will not end up in a derivation attribute and thus would never have to be actually fetched to the store. This comes at the slight cost of doing more work in case the assumption is wrong, but results in less work in typical use cases. The evaluator continues to behave as if the copy was performed:
+
+ - Flakes are still evaluated from the store, from the evaluator's point of view.
+ - `toString ./.` continues to produce a content-addressed store path string without context.
+ - Path resolution crossing trees located in the filesystem and in Nix's view of it (with "virtual" overlays on top) continues to work. For example, the flake source tree can contain a relative symlink pointing outside its corresponding store object (though such usage is discouraged and makes further improvements to laziness intractable).
+ - Reading files from the flake's `outPath` continues to work. For example, such code is well-formed and is not considered [IFD](@docroot@/language/import-from-derivation.md):
+
+ ```nix
+ builtins.readFile ( /. + (builtins.unsafeDiscardStringContext self.outPath) + "/flake.nix" )
+ ```
+
+ Similar treatment has been applied to `builtins.fetchTarball`, which no longer eagerly copies paths to the store.
+ `builtins.storePath` now also short-circuits on "lazy-ish" store paths and doesn't substitute unless necessary.
+
+ This change is expected to significantly reduce disk usage required for typical evaluations and results in ~2x speedup for fetching and unpacking a nixpkgs tarball (either via `fetchTree`/flakes or via `fetchTarball`).
+
+- Support FreeBSD `libjail` based sandboxing, add `x86_64-freebsd` to installer [#9968](https://github.com/NixOS/nix/pull/9968) [#13281](https://github.com/NixOS/nix/pull/13281) [#15673](https://github.com/NixOS/nix/pull/15673)
+
+ The FreeBSD build of Nix now supports build sandboxing via FreeBSD jails and is enabled by default.
+ A FreeBSD build has been added to the traditional installer script. The beta rust-based installer is not yet supported.
+ FreeBSD support is not as well-tested as Linux or macOS, but is fully capable of building packages and performing other tasks expected of Nix on Linux.
+
+## Improvements
+
+- HTTP/3 (QUIC) support [#15961](https://github.com/NixOS/nix/pull/15961)
+
+ Nix can now fetch from binary caches and other HTTP(S) sources over HTTP/3 (QUIC), controlled by a new [`http3`](@docroot@/command-ref/conf-file.md#conf-http3) setting (disabled by default).
+ When enabled, Nix requests HTTP/3 and transparently falls back to HTTP/2 or HTTP/1.1 for servers that do not advertise QUIC.
+ The setting only takes effect when linked against a `libcurl` built with HTTP/3 support, otherwise it is ignored and Nix keeps using HTTP/2 without warning or error.
+
+ Enable it with:
+
+ ```
+ nix.conf: http3 = true
+ CLI: --http3
+ ```
+
+ Or disable with:
+
+ ```
+ nix.conf: http3 = false
+ CLI: --no-http3
+ ```
+
+- Link mimalloc for faster evaluation [#15596](https://github.com/NixOS/nix/pull/15596)
+
+ The `nix` binary now links [mimalloc](https://github.com/microsoft/mimalloc) by default, replacing glibc's malloc for all non-GC allocations.
+ This yields a **5–12% wall-clock improvement** on evaluation workloads, ranging from `nix-instantiate hello` to `nix-env -qa` and full NixOS configurations.
+ The allocator can be disabled at build time with `-Dmimalloc=disabled`.
+
+- The `revCount` attribute of the Git fetchers is now lazily computed and passed-through as-is when explicitly specified [#15772](https://github.com/NixOS/nix/pull/15772) [#14596](https://github.com/NixOS/nix/pull/14596)
+
+ `revCount` and `lastModified` attributes passed to the Git fetcher are no longer eagerly validated when explicitly specified.
+
+ When not explicitly specified, `revCount` is now also a thunk value and not computed eagerly. This delays this (potentially) expensive computation until the value is actually required.
+
+- Configurable file-transfer retry backoff with full jitter and `Retry-After` support [#15023](https://github.com/NixOS/nix/issues/15023) [#15419](https://github.com/NixOS/nix/issues/15419) [#15449](https://github.com/NixOS/nix/pull/15449)
+
+ File transfer retries (downloads and uploads) now use AWS-style "full jitter" exponential backoff, treat HTTP 503 as rate-limited (same longer delay as 429),
+ and honor the `Retry-After` response header.
+
+ Retry timing is configurable via new `nix.conf` settings:
+
+ - [`filetransfer-retry-delay`](@docroot@/command-ref/conf-file.md#conf-filetransfer-retry-delay): base delay for transient errors
+ - [`filetransfer-retry-delay-rate-limited`](@docroot@/command-ref/conf-file.md#conf-filetransfer-retry-delay-rate-limited): base delay for 429/503
+ - [`filetransfer-retry-max-delay`](@docroot@/command-ref/conf-file.md#conf-filetransfer-retry-max-delay): per-attempt delay ceiling
+ - [`filetransfer-retry-jitter`](@docroot@/command-ref/conf-file.md#conf-filetransfer-retry-jitter): enable full jitter
+
+ The existing `download-attempts` setting has been renamed to [`filetransfer-retry-attempts`](@docroot@/command-ref/conf-file.md#conf-filetransfer-retry-attempts) to reflect that it applies to uploads as well as downloads.
+ The old name remains as an alias for backwards compatibility.
+
+ Per-substituter overrides are available as store reference parameters ([`retry-delay`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-retry-delay), [`retry-delay-rate-limited`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-retry-delay-rate-limited), [`retry-max-delay`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-retry-max-delay), [`retry-attempts`](@docroot@/store/types/http-binary-cache-store.md#store-http-binary-cache-store-retry-attempts)), e.g. `s3://my-cache?retry-attempts=8`.
+
+- Improve daemon socket path logic for chroot stores [#15190](https://github.com/NixOS/nix/pull/15190)
+
+ The default daemon socket path now uses the per-store [`state`](@docroot@/store/types/local-store.md#store-local-store-state) directory whenever one is defined, rather than always using the global [`NIX_STATE_DIR`](@docroot@/command-ref/env-common.md#env-NIX_STATE_DIR).
+ This means [local chroot stores](@docroot@/store/types/local-store.md#chroot) each get their own socket path automatically.
+
+ Example:
+
+ ```bash
+ nix-daemon --store /foo/bar
+ ```
+
+ will now use a socket at:
+ ```
+ /foo/bar/nix/var/nix/daemon-socket/socket
+ ```
+ instead of
+ ```
+ $NIX_STATE_DIR/daemon-socket/socket
+ ```
+
+ Users who wish to serve or connect to a chroot store at the old location will have to force the socket location:
+
+ - When serving (running a daemon), use the new [`--socket-path`](@docroot@/command-ref/new-cli/nix3-daemon.md#opt-socket-path) flag:
+
+ ```bash
+ nix daemon --socket-path "$NIX_STATE_DIR/daemon-socket/socket"
+ ```
+
+ - When connecting as a client, put the path in the [store URL](@docroot@/store/types/local-daemon-store.md):
+
+ ```
+ unix://$NIX_STATE_DIR/daemon-socket/socket
+ ```
+
+- Linux sandbox: also block `listxattr` syscalls [#15743](https://github.com/NixOS/nix/pull/15743)
+
+ The Linux sandbox now also returns `ENOTSUP` for `listxattr`, `llistxattr` and `flistxattr`, matching the existing treatment of `getxattr`/`setxattr`/`removexattr`.
+ This prevents host xattrs (e.g. `security.selinux`) from leaking into builds and fixes tools such as `mkfs.ubifs` that probe xattr support via `listxattr`.
+
+- Support SCP-like URLs in fetchGit and type = "git" flake inputs [#14852](https://github.com/NixOS/nix/issues/14852) [#14867](https://github.com/NixOS/nix/issues/14867) [#14863](https://github.com/NixOS/nix/pull/14863)
+
+ Nix now (once again) recognizes [SCP-like syntax for Git URLs](https://git-scm.com/docs/git-clone#_git_urls). This partially
+ restores compatibility with Nix 2.3 for `fetchGit`. The following syntax is once again supported:
+
+ ```nix
+ builtins.fetchGit "host:/absolute/path/to/repo"
+ ```
+
+ Nix also passes through the tilde (for home directories) verbatim:
+
+ ```nix
+ builtins.fetchGit "host:~/relative/to/home"
+ ```
+
+ IPv6 addresses also supported when bracketed:
+
+ ```nix
+ builtins.fetchGit "user@[::1]:~/relative/to/home"
+ ```
+
+ `builtins.fetchTree` also supports this syntax now:
+
+ ```nix
+ builtins.fetchTree { type = "git"; url = "host:/path/to/repo"; }
+ ```
+
+- `nix flake check` now supports `--print-out-paths` [#13470](https://github.com/NixOS/nix/issues/13470) [#15476](https://github.com/NixOS/nix/pull/15476) and `--out-link` [#13470](https://github.com/NixOS/nix/issues/13470) [#15476](https://github.com/NixOS/nix/pull/15476) defaulting to not creating out links if the flag is not specified.
+
+- Added `--skip-alive` (and `--skip-live` alias for compatibility with Lix users) option to `nix store delete` for collecting garbage within a closure [#7239](https://github.com/NixOS/nix/issues/7239) [#15236](https://github.com/NixOS/nix/pull/15236) [#15727](https://github.com/NixOS/nix/pull/15727)
+
+ `nix store delete --recursive --skip-alive` can be used to collect garbage within a closure, in which case it will only collect the dead paths that are part of the closure of its arguments.
+ The additional option `--also-referrers` is added to support this mode, which allows referrers of paths in the closure to also be deleted.
+
+- `builtins.getFlake` now supports path values [#15290](https://github.com/NixOS/nix/pull/15290)
+
+ `builtins.getFlake` now accepts path values in addition to flakerefs. This improves the usability of relative flakes, allowing you to write `builtins.getFlake ./subflake`.
+ This change does not allow specifying paths that are not already in the store (though they do not have valid store objects, i.e. this will not force a copy if the flake has only been hashed -- and not copied to the store). This may change in a future release.
+
+- `nix-profile.fish` and `nix-profile-daemon.fish` now use `$NIX_LINK` for computing the value of `NIX_PROFILE` instead of `$HOME/.nix-profile` [#14293](https://github.com/NixOS/nix/pull/14293)
+
+- `nix` binary now exports symbols from C bindings [#15696](https://github.com/NixOS/nix/pull/15696)
+
+ This allows Nix plugins written against the C API to look up symbols dynamically without linking to corresponding `libnix*c.so` libraries.
+
+- The computed Git LFS endpoint URLs have been fixed to follow the spec [#15891](https://github.com/NixOS/nix/pull/15891) and memory usage of LFS fetches has been decreased [#15912](https://github.com/NixOS/nix/pull/15912)
+
+- We now verify that fetched Git LFS objects have the same OID as requested [#15845](https://github.com/NixOS/nix/pull/15845)
+
+- Primop documentation now includes time complexity information [#14554](https://github.com/NixOS/nix/pull/14554)
+
+- Improved documentation on store paths and derivation building [#14699](https://github.com/NixOS/nix/pull/14699)
+
+- The [build hook](@docroot@/command-ref/conf-file.md#conf-build-hook) is now killed with `SIGTERM` instead of `SIGKILL` [#15105](https://github.com/NixOS/nix/pull/15105)
+
+- Download/upload logs strip `userinfo` URL components [#15715](https://github.com/NixOS/nix/pull/15715)
+
+## Content-addressed derivations changes
+
+ The experimental content-addressed (CA) derivation feature has undergone a significant change to how build traces (formerly called "realisations") are identified.
+ This changes the binary cache endpoints for realisations and the daemon/nix-serve protocol (gated behind a daemon protocol feature flag).
+
+- Realisations keyed by store path instead of hash modulo [#11897](https://github.com/NixOS/nix/issues/11897) [#12464](https://github.com/NixOS/nix/pull/12464)
+
+ Previously, a build trace entry (realisation) was keyed by the hash modulo of the derivation. In simpler terms, derivations transitively depending on distinct fixed-output derivations with the same `outPath` would share a realisation.
+
+ Now, build trace entries are keyed by the regular derivation store path (`.drvPath`) plus the output name. For example, instead of:
+
+ ```
+ sha256:ba7816bf8f01...!out
+ ```
+
+ The key is now:
+
+ ```
+ /nix/store/abc...-foo.drv^out
+ ```
+
+- Removed support for "deep" realisations [#15289](https://github.com/NixOS/nix/pull/15289)
+
+ Previously the build trace (set of "realisations") contained entries for both unresolved and [resolved](@docroot@/store/resolution.md) derivations.
+ Now, it contains entries exclusively for resolved derivations.
+ For now, unresolved derivations will be resolved from these underlying build trace entries.
+ This is slower, but has the benefit of making build trace entries stateless and self-describing --- making sharing realisations easier between stores.
+
+ This change necessitates changes to the binary cache format:
+
+ - The directory for build traces moved from `realisations/` to `build-trace-v2/`.
+ - File paths changed from `realisations/!