Reword the experimental feature description.

Co-Authored-By: Robert Hensing <robert@roberthensing.nl>

.clang-format

@@ -15,7 +15,7 @@ SpaceAfterCStyleCast: true
 SpaceAfterTemplateKeyword: false
 AccessModifierOffset: -4
 AlignAfterOpenBracket: AlwaysBreak
-AlignEscapedNewlines: Left
+AlignEscapedNewlines: DontAlign
 ColumnLimit: 120
 BreakStringLiterals: false
 BitFieldColonSpacing: None
@@ -28,7 +28,3 @@ EmptyLineBeforeAccessModifier: Leave
 #PackConstructorInitializers: BinPack
 BreakBeforeBinaryOperators: NonAssignment
 AlwaysBreakBeforeMultilineStrings: true
-IndentPPDirectives: AfterHash
-PPIndentWidth: 2
-BinPackArguments: false
-BinPackParameters: false

.github/CODEOWNERS

@@ -11,16 +11,7 @@
 .github/CODEOWNERS @edolstra
 
 # Documentation of built-in functions
-src/libexpr/primops.cc @roberth @fricklerhandwerk
-
-# Documentation of settings
-src/libexpr/eval-settings.hh @fricklerhandwerk
-src/libstore/globals.hh @fricklerhandwerk
-
-# Documentation
-doc/manual @fricklerhandwerk
-maintainers/*.md @fricklerhandwerk
-src/**/*.md @fricklerhandwerk
+src/libexpr/primops.cc @roberth
 
 # Libstore layer
-/src/libstore @thufschmitt @ericson2314
+/src/libstore @thufschmitt

.github/labeler.yml

@@ -1,19 +1,6 @@
-"c api":
-  - changed-files:
-    - any-glob-to-any-file: "src/lib*-c/**/*"
-    - any-glob-to-any-file: "test/unit/**/nix_api_*"
-    - any-glob-to-any-file: "doc/external-api/**/*"
-
-"contributor-experience":
-  - changed-files:
-    - any-glob-to-any-file: "CONTRIBUTING.md"
-    - any-glob-to-any-file: ".github/ISSUE_TEMPLATE/*"
-    - any-glob-to-any-file: ".github/PULL_REQUEST_TEMPLATE.md"
-    - any-glob-to-any-file: "doc/manual/src/contributing/**"
-
 "documentation":
   - changed-files:
-    - any-glob-to-any-file: "doc/manual/**/*"
+    - any-glob-to-any-file: "doc/manual/*"
     - any-glob-to-any-file: "src/nix/**/*.md"
 
 "store":
@@ -40,4 +27,4 @@
     - any-glob-to-any-file: "src/*/tests/**/*"
     # Functional and integration tests
     - any-glob-to-any-file: "tests/functional/**/*"
-
+    

.github/workflows/backport.yml

@@ -21,7 +21,7 @@ jobs:
           fetch-depth: 0
       - name: Create backport PRs
         # should be kept in sync with `version`
-        uses: zeebe-io/backport-action@v3.0.2
+        uses: zeebe-io/backport-action@v2.4.1
         with:
           # Config README: https://github.com/zeebe-io/backport-action#backport-action
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -20,12 +20,12 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: cachix/install-nix-action@V27
+    - uses: cachix/install-nix-action@v25
       with:
         # The sandbox would otherwise be disabled by default on Darwin
         extra_nix_config: "sandbox = true"
     - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
-    - uses: cachix/cachix-action@v15
+    - uses: cachix/cachix-action@v14
       if: needs.check_secrets.outputs.cachix == 'true'
       with:
         name: '${{ env.CACHIX_NAME }}'
@@ -62,10 +62,10 @@ jobs:
       with:
         fetch-depth: 0
     - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
-    - uses: cachix/install-nix-action@V27
+    - uses: cachix/install-nix-action@v25
       with:
-        install_url: https://releases.nixos.org/nix/nix-2.20.3/install
-    - uses: cachix/cachix-action@v15
+        install_url: https://releases.nixos.org/nix/nix-2.13.3/install
+    - uses: cachix/cachix-action@v14
       with:
         name: '${{ env.CACHIX_NAME }}'
         signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
@@ -84,7 +84,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
-    - uses: cachix/install-nix-action@V27
+    - uses: cachix/install-nix-action@v25
       with:
         install_url: '${{needs.installer.outputs.installerURL}}'
         install_options: "--tarball-url-prefix https://${{ env.CACHIX_NAME }}.cachix.org/serve"
@@ -114,12 +114,12 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: cachix/install-nix-action@V27
+    - uses: cachix/install-nix-action@v25
       with:
-        install_url: https://releases.nixos.org/nix/nix-2.20.3/install
+        install_url: https://releases.nixos.org/nix/nix-2.13.3/install
     - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
     - run: echo NIX_VERSION="$(nix --experimental-features 'nix-command flakes' eval .\#default.version | tr -d \")" >> $GITHUB_ENV
-    - uses: cachix/cachix-action@v15
+    - uses: cachix/cachix-action@v14
       if: needs.check_secrets.outputs.cachix == 'true'
       with:
         name: '${{ env.CACHIX_NAME }}'
@@ -153,17 +153,6 @@ jobs:
         IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
 
         docker tag nix:$NIX_VERSION $IMAGE_ID:$NIX_VERSION
-        docker tag nix:$NIX_VERSION $IMAGE_ID:latest
-        docker push $IMAGE_ID:$NIX_VERSION
-        docker push $IMAGE_ID:latest
-        # deprecated 2024-02-24
         docker tag nix:$NIX_VERSION $IMAGE_ID:master
+        docker push $IMAGE_ID:$NIX_VERSION
         docker push $IMAGE_ID:master
-
-  vm_tests:
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v4
-      - uses: DeterminateSystems/nix-installer-action@main
-      - uses: DeterminateSystems/magic-nix-cache-action@main
-      - run: nix build -L .#hydraJobs.tests.githubFlakes .#hydraJobs.tests.tarballFlakes

.gitignore

@@ -10,7 +10,6 @@ perl/Makefile.config
 /stamp-h1
 /svn-revision
 /libtool
-/config/config.*
 
 # /doc/manual/
 /doc/manual/*.1
@@ -46,19 +45,13 @@ perl/Makefile.config
 /src/libexpr/parser-tab.hh
 /src/libexpr/parser-tab.output
 /src/libexpr/nix.tbl
-/src/libexpr/tests
 /tests/unit/libexpr/libnixexpr-tests
 
-# /src/libfetchers
-/tests/unit/libfetchers/libnixfetchers-tests
-
 # /src/libstore/
 *.gen.*
-/src/libstore/tests
 /tests/unit/libstore/libnixstore-tests
 
 # /src/libutil/
-/src/libutil/tests
 /tests/unit/libutil/libnixutil-tests
 
 /src/nix/nix
@@ -92,7 +85,7 @@ perl/Makefile.config
 
 # /tests/functional/
 /tests/functional/test-tmp
-/tests/functional/common/subst-vars.sh
+/tests/functional/common/vars-and-functions.sh
 /tests/functional/result*
 /tests/functional/restricted-innocent
 /tests/functional/shell
@@ -115,9 +108,14 @@ perl/Makefile.config
 
 /misc/systemd/nix-daemon.service
 /misc/systemd/nix-daemon.socket
+/misc/systemd/nix-gc-trace.service
+/misc/systemd/nix-gc-trace.socket
+
 /misc/systemd/nix-daemon.conf
 /misc/upstart/nix-daemon.conf
 
+/src/resolve-system-dependencies/resolve-system-dependencies
+
 outputs/
 
 *.a
@@ -143,7 +141,6 @@ GTAGS
 
 # auto-generated compilation database
 compile_commands.json
-*.compile_commands.json
 
 nix-rust/target
 
@@ -154,8 +151,6 @@ result-*
 .vscode/
 .idea/
 
-.pre-commit-config.yaml
-
 # clangd and possibly more
 .cache/
 

.shellcheckrc

@@ -1,2 +0,0 @@
-external-sources=true
-source-path=SCRIPTDIR

.version

@@ -1 +1 @@
-2.23.1
+2.21.0

CITATION.cff

@@ -1,42 +0,0 @@
-cff-version: 1.2.0
-title: Nix
-message: >-
-  If you use this software, please cite it using the
-  metadata from this file.
-type: software
-authors:
-  - given-names: Eelco
-    family-names: Dolstra
-    email: edolstra@gmail.com
-  - name: The Nix contributors
-    website: 'https://github.com/NixOS/nix'
-references:
-  - title: The Purely Functional Software Deployment Model
-    authors:
-    - family-names: Dolstra
-      given-names: Eelco
-    year: 2006
-    type: thesis
-    thesis-type: PhD thesis
-    isbn: 90-393-4130-3
-    url: https://dspace.library.uu.nl/handle/1874/7540
-    database-provider: Utrecht University Repository
-    institution:
-      name: Utrecht University
-    keywords:
-    - configuration management
-    - software deployment
-    - purely functional
-    - component-based software engineering
-repository-code: 'https://github.com/NixOS/nix'
-url: 'https://nixos.org/'
-abstract: >-
-  Nix, a purely functional package manager, is a powerful
-  package manager for Linux and other Unix systems that
-  makes package management reliable and reproducible.
-keywords:
-  - reproducibility
-  - open-source
-  - c++
-  - functional
-license: LGPL-2.1

CONTRIBUTING.md

@@ -27,8 +27,6 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
 1. Search for related issues that cover what you're going to work on.
    It could help to mention there that you will work on the issue.
 
-   We strongly recommend first-time contributors not to propose new features but rather fix tightly-scoped problems in order to build trust and a working relationship with maintainers.
-
    Issues labeled [good first issue](https://github.com/NixOS/nix/labels/good%20first%20issue) should be relatively easy to fix and are likely to get merged quickly.
    Pull requests addressing issues labeled [idea approved](https://github.com/NixOS/nix/labels/idea%20approved) or [RFC](https://github.com/NixOS/nix/labels/RFC) are especially welcomed by maintainers and will receive prioritised review.
 
@@ -69,7 +67,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
    - [ ] API documentation in header files
    - [ ] Code and comments are self-explanatory
    - [ ] Commit message explains **why** the change was made
-   - [ ] New feature or incompatible change: [add a release note](https://nixos.org/manual/nix/stable/contributing/hacking#add-a-release-note)
+   - [ ] New feature or incompatible change: updated [release notes](./doc/manual/src/release-notes/rl-next.md)
 
 7. If you need additional feedback or help to getting pull request into shape, ask other contributors using [@mentions](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams).
 

Makefile

@@ -7,27 +7,20 @@ clean-files += $(buildprefix)Makefile.config
 
 # List makefiles
 
-include mk/platform.mk
-
 ifeq ($(ENABLE_BUILD), yes)
 makefiles = \
   mk/precompiled-headers.mk \
   local.mk \
   src/libutil/local.mk \
+  src/nix-find-roots/local.mk \
   src/libstore/local.mk \
   src/libfetchers/local.mk \
   src/libmain/local.mk \
   src/libexpr/local.mk \
   src/libcmd/local.mk \
   src/nix/local.mk \
-  src/libutil-c/local.mk \
-  src/libstore-c/local.mk \
-  src/libexpr-c/local.mk
-
-ifdef HOST_UNIX
-makefiles += \
+  src/resolve-system-dependencies/local.mk \
   scripts/local.mk \
-  maintainers/local.mk \
   misc/bash/local.mk \
   misc/fish/local.mk \
   misc/zsh/local.mk \
@@ -35,7 +28,6 @@ makefiles += \
   misc/launchd/local.mk \
   misc/upstart/local.mk
 endif
-endif
 
 ifeq ($(ENABLE_UNIT_TESTS), yes)
 makefiles += \
@@ -43,23 +35,19 @@ makefiles += \
   tests/unit/libutil-support/local.mk \
   tests/unit/libstore/local.mk \
   tests/unit/libstore-support/local.mk \
-  tests/unit/libfetchers/local.mk \
   tests/unit/libexpr/local.mk \
   tests/unit/libexpr-support/local.mk
 endif
 
 ifeq ($(ENABLE_FUNCTIONAL_TESTS), yes)
-ifdef HOST_UNIX
 makefiles += \
   tests/functional/local.mk \
+  tests/functional/gc-external-daemon/local.mk \
   tests/functional/ca/local.mk \
-  tests/functional/git-hashing/local.mk \
   tests/functional/dyn-drv/local.mk \
-  tests/functional/local-overlay-store/local.mk \
   tests/functional/test-libstoreconsumer/local.mk \
   tests/functional/plugins/local.mk
 endif
-endif
 
 # Some makefiles require access to built programs and must be included late.
 makefiles-late =
@@ -72,10 +60,6 @@ ifeq ($(ENABLE_INTERNAL_API_DOCS), yes)
 makefiles-late += doc/internal-api/local.mk
 endif
 
-ifeq ($(ENABLE_EXTERNAL_API_DOCS), yes)
-makefiles-late += doc/external-api/local.mk
-endif
-
 # Miscellaneous global Flags
 
 OPTIMIZE = 1
@@ -85,9 +69,10 @@ ifeq ($(OPTIMIZE), 1)
   GLOBAL_LDFLAGS += $(CXXLTO)
 else
   GLOBAL_CXXFLAGS += -O0 -U_FORTIFY_SOURCE
-  unexport NIX_HARDENING_ENABLE
 endif
 
+include mk/platform.mk
+
 ifdef HOST_WINDOWS
   # Windows DLLs are stricter about symbol visibility than Unix shared
   # objects --- see https://gcc.gnu.org/wiki/Visibility for details.
@@ -98,7 +83,7 @@ ifdef HOST_WINDOWS
   GLOBAL_LDFLAGS += -Wl,--export-all-symbols
 endif
 
-GLOBAL_CXXFLAGS += -g -Wall -Wdeprecated-copy -Wignored-qualifiers -Wimplicit-fallthrough -include $(buildprefix)config.h -std=c++2a -I src
+GLOBAL_CXXFLAGS += -g -Wall -include $(buildprefix)config.h -std=c++2a -I src
 
 # Include the main lib, causing rules to be defined
 
@@ -138,10 +123,3 @@ internal-api-html:
 	@echo "Internal API docs are disabled. Configure with '--enable-internal-api-docs', or avoid calling 'make internal-api-html'."
 	@exit 1
 endif
-
-ifneq ($(ENABLE_EXTERNAL_API_DOCS), yes)
-.PHONY: external-api-html
-external-api-html:
-	@echo "External API docs are disabled. Configure with '--enable-external-api-docs', or avoid calling 'make external-api-html'."
-	@exit 1
-endif

Makefile.config.in

@@ -12,7 +12,6 @@ ENABLE_BUILD = @ENABLE_BUILD@
 ENABLE_DOC_GEN = @ENABLE_DOC_GEN@
 ENABLE_FUNCTIONAL_TESTS = @ENABLE_FUNCTIONAL_TESTS@
 ENABLE_INTERNAL_API_DOCS = @ENABLE_INTERNAL_API_DOCS@
-ENABLE_EXTERNAL_API_DOCS = @ENABLE_EXTERNAL_API_DOCS@
 ENABLE_S3 = @ENABLE_S3@
 ENABLE_UNIT_TESTS = @ENABLE_UNIT_TESTS@
 GTEST_LIBS = @GTEST_LIBS@

build/hydra.nix

@@ -1,186 +0,0 @@
-{ inputs
-, binaryTarball
-, forAllCrossSystems
-, forAllSystems
-, lib
-, linux64BitSystems
-, nixpkgsFor
-, self
-}:
-let
-  inherit (inputs) nixpkgs nixpkgs-regression;
-  inherit (lib) fileset;
-
-  installScriptFor = tarballs:
-    nixpkgsFor.x86_64-linux.native.callPackage ../scripts/installer.nix {
-      inherit tarballs;
-    };
-
-  testNixVersions = pkgs: client: daemon:
-    pkgs.callPackage ../package.nix {
-      pname =
-        "nix-tests"
-        + lib.optionalString
-          (lib.versionAtLeast daemon.version "2.4pre20211005" &&
-           lib.versionAtLeast client.version "2.4pre20211005")
-          "-${client.version}-against-${daemon.version}";
-
-      inherit fileset;
-
-      test-client = client;
-      test-daemon = daemon;
-
-      doBuild = false;
-    };
-in
-{
-  # Binary package for various platforms.
-  build = forAllSystems (system: self.packages.${system}.nix);
-
-  shellInputs = forAllSystems (system: self.devShells.${system}.default.inputDerivation);
-
-  buildStatic = lib.genAttrs linux64BitSystems (system: self.packages.${system}.nix-static);
-
-  buildCross = forAllCrossSystems (crossSystem:
-    lib.genAttrs [ "x86_64-linux" ] (system: self.packages.${system}."nix-${crossSystem}"));
-
-  buildNoGc = forAllSystems (system:
-    self.packages.${system}.nix.override { enableGC = false; }
-  );
-
-  buildNoTests = forAllSystems (system:
-    self.packages.${system}.nix.override {
-      doCheck = false;
-      doInstallCheck = false;
-      installUnitTests = false;
-    }
-  );
-
-  # Toggles some settings for better coverage. Windows needs these
-  # library combinations, and Debian build Nix with GNU readline too.
-  buildReadlineNoMarkdown = forAllSystems (system:
-    self.packages.${system}.nix.override {
-      enableMarkdown = false;
-      readlineFlavor = "readline";
-    }
-  );
-
-  # Perl bindings for various platforms.
-  perlBindings = forAllSystems (system: nixpkgsFor.${system}.native.nix.perl-bindings);
-
-  # Binary tarball for various platforms, containing a Nix store
-  # with the closure of 'nix' package, and the second half of
-  # the installation script.
-  binaryTarball = forAllSystems (system: binaryTarball nixpkgsFor.${system}.native.nix nixpkgsFor.${system}.native);
-
-  binaryTarballCross = lib.genAttrs [ "x86_64-linux" ] (system:
-    forAllCrossSystems (crossSystem:
-      binaryTarball
-        self.packages.${system}."nix-${crossSystem}"
-        nixpkgsFor.${system}.cross.${crossSystem}));
-
-  # The first half of the installation script. This is uploaded
-  # to https://nixos.org/nix/install. It downloads the binary
-  # tarball for the user's system and calls the second half of the
-  # installation script.
-  installerScript = installScriptFor [
-    # Native
-    self.hydraJobs.binaryTarball."x86_64-linux"
-    self.hydraJobs.binaryTarball."i686-linux"
-    self.hydraJobs.binaryTarball."aarch64-linux"
-    self.hydraJobs.binaryTarball."x86_64-darwin"
-    self.hydraJobs.binaryTarball."aarch64-darwin"
-    # Cross
-    self.hydraJobs.binaryTarballCross."x86_64-linux"."armv6l-unknown-linux-gnueabihf"
-    self.hydraJobs.binaryTarballCross."x86_64-linux"."armv7l-unknown-linux-gnueabihf"
-    self.hydraJobs.binaryTarballCross."x86_64-linux"."riscv64-unknown-linux-gnu"
-  ];
-  installerScriptForGHA = installScriptFor [
-    # Native
-    self.hydraJobs.binaryTarball."x86_64-linux"
-    self.hydraJobs.binaryTarball."x86_64-darwin"
-    # Cross
-    self.hydraJobs.binaryTarballCross."x86_64-linux"."armv6l-unknown-linux-gnueabihf"
-    self.hydraJobs.binaryTarballCross."x86_64-linux"."armv7l-unknown-linux-gnueabihf"
-    self.hydraJobs.binaryTarballCross."x86_64-linux"."riscv64-unknown-linux-gnu"
-  ];
-
-  # docker image with Nix inside
-  dockerImage = lib.genAttrs linux64BitSystems (system: self.packages.${system}.dockerImage);
-
-  # Line coverage analysis.
-  coverage = nixpkgsFor.x86_64-linux.native.nix.override {
-    pname = "nix-coverage";
-    withCoverageChecks = true;
-  };
-
-  # API docs for Nix's unstable internal C++ interfaces.
-  internal-api-docs = nixpkgsFor.x86_64-linux.native.callPackage ../package.nix {
-    inherit fileset;
-    doBuild = false;
-    enableInternalAPIDocs = true;
-  };
-
-  # API docs for Nix's C bindings.
-  external-api-docs = nixpkgsFor.x86_64-linux.native.callPackage ../package.nix {
-    inherit fileset;
-    doBuild = false;
-    enableExternalAPIDocs = true;
-  };
-
-  # System tests.
-  tests = import ../tests/nixos { inherit lib nixpkgs nixpkgsFor; } // {
-
-    # Make sure that nix-env still produces the exact same result
-    # on a particular version of Nixpkgs.
-    evalNixpkgs =
-      let
-        inherit (nixpkgsFor.x86_64-linux.native) runCommand nix;
-      in
-      runCommand "eval-nixos" { buildInputs = [ nix ]; }
-        ''
-          type -p nix-env
-          # Note: we're filtering out nixos-install-tools because https://github.com/NixOS/nixpkgs/pull/153594#issuecomment-1020530593.
-          (
-            set -x
-            time nix-env --store dummy:// -f ${nixpkgs-regression} -qaP --drv-path | sort | grep -v nixos-install-tools > packages
-            [[ $(sha1sum < packages | cut -c1-40) = e01b031fc9785a572a38be6bc473957e3b6faad7 ]]
-          )
-          mkdir $out
-        '';
-
-    nixpkgsLibTests =
-      forAllSystems (system:
-        import (nixpkgs + "/lib/tests/release.nix")
-          {
-            pkgs = nixpkgsFor.${system}.native;
-            nixVersions = [ self.packages.${system}.nix ];
-          }
-      );
-  };
-
-  metrics.nixpkgs = import "${nixpkgs-regression}/pkgs/top-level/metrics.nix" {
-    pkgs = nixpkgsFor.x86_64-linux.native;
-    nixpkgs = nixpkgs-regression;
-  };
-
-  installTests = forAllSystems (system:
-    let pkgs = nixpkgsFor.${system}.native; in
-    pkgs.runCommand "install-tests"
-      {
-        againstSelf = testNixVersions pkgs pkgs.nix pkgs.pkgs.nix;
-        againstCurrentUnstable =
-          # FIXME: temporarily disable this on macOS because of #3605.
-          if system == "x86_64-linux"
-          then testNixVersions pkgs pkgs.nix pkgs.nixUnstable
-          else null;
-        # Disabled because the latest stable version doesn't handle
-        # `NIX_DAEMON_SOCKET_PATH` which is required for the tests to work
-        # againstLatestStable = testNixVersions pkgs pkgs.nix pkgs.nixStable;
-      } "touch $out");
-
-  installerTests = import ../tests/installer {
-    binaryTarballs = self.hydraJobs.binaryTarball;
-    inherit nixpkgsFor;
-  };
-}

configure.ac

@@ -63,6 +63,7 @@ AC_SYS_LARGEFILE
 
 
 # Solaris-specific stuff.
+AC_STRUCT_DIRENT_D_TYPE
 case "$host_os" in
   solaris*)
     # Solaris requires -lsocket -lnsl for network functions
@@ -149,11 +150,6 @@ AC_ARG_ENABLE(unit-tests, AS_HELP_STRING([--disable-unit-tests],[Do not build th
   ENABLE_UNIT_TESTS=$enableval, ENABLE_UNIT_TESTS=$ENABLE_BUILD)
 AC_SUBST(ENABLE_UNIT_TESTS)
 
-# Build external API docs by default
-AC_ARG_ENABLE(external_api_docs, AS_HELP_STRING([--enable-external-api-docs],[Build API docs for Nix's C interface]),
-  external_api_docs=$enableval, external_api_docs=yes)
-AC_SUBST(external_api_docs)
-
 AS_IF(
   [test "$ENABLE_BUILD" == "no" && test "$ENABLE_UNIT_TESTS" == "yes"],
   [AC_MSG_ERROR([Cannot enable unit tests when building overall is disabled. Please do not pass '--enable-unit-tests' or do not pass '--disable-build'.])])
@@ -176,10 +172,6 @@ AC_ARG_ENABLE(internal-api-docs, AS_HELP_STRING([--enable-internal-api-docs],[Bu
   ENABLE_INTERNAL_API_DOCS=$enableval, ENABLE_INTERNAL_API_DOCS=no)
 AC_SUBST(ENABLE_INTERNAL_API_DOCS)
 
-AC_ARG_ENABLE(external-api-docs, AS_HELP_STRING([--enable-external-api-docs],[Build API docs for Nix's external unstable C interfaces]),
-  ENABLE_EXTERNAL_API_DOCS=$enableval, ENABLE_EXTERNAL_API_DOCS=no)
-AC_SUBST(ENABLE_EXTERNAL_API_DOCS)
-
 AS_IF(
   [test "$ENABLE_FUNCTIONAL_TESTS" == "yes" || test "$ENABLE_DOC_GEN" == "yes"],
   [NEED_PROG(jq, jq)])
@@ -313,20 +305,9 @@ case "$host_os" in
                                 ]))
     if test "x$enable_seccomp_sandboxing" != "xno"; then
       PKG_CHECK_MODULES([LIBSECCOMP], [libseccomp],
-                        [CXXFLAGS="$LIBSECCOMP_CFLAGS $CXXFLAGS" CFLAGS="$LIBSECCOMP_CFLAGS $CFLAGS"])
+                        [CXXFLAGS="$LIBSECCOMP_CFLAGS $CXXFLAGS"])
       have_seccomp=1
       AC_DEFINE([HAVE_SECCOMP], [1], [Whether seccomp is available and should be used for sandboxing.])
-      AC_COMPILE_IFELSE([
-        AC_LANG_SOURCE([[
-          #include <seccomp.h>
-          #ifndef __SNR_fchmodat2
-          # error "Missing support for fchmodat2"
-          #endif
-        ]])
-      ], [], [
-        echo "libseccomp is missing __SNR_fchmodat2. Please provide libseccomp 2.5.5 or later"
-        exit 1
-      ])
     else
       have_seccomp=
     fi

doc/external-api/.gitignore

@@ -1,3 +0,0 @@
-/doxygen.cfg
-/html
-/latex

doc/external-api/README.md

@@ -1,121 +0,0 @@
-# Getting started
-
-> **Warning** These bindings are **experimental**, which means they can change
-> at any time or be removed outright; nevertheless the plan is to provide a
-> stable external C API to the Nix language and the Nix store.
-
-The language library allows evaluating Nix expressions and interacting with Nix
-language values. The Nix store API is still rudimentary, and only allows
-initialising and connecting to a store for the Nix language evaluator to
-interact with.
-
-Currently there are two ways to interface with the Nix language evaluator
-programmatically:
-
-1. Embedding the evaluator
-2. Writing language plug-ins
-
-Embedding means you link the Nix C libraries in your program and use them from
-there. Adding a plug-in means you make a library that gets loaded by the Nix
-language evaluator, specified through a configuration option.
-
-Many of the components and mechanisms involved are not yet documented, therefore
-please refer to the [Nix source code](https://github.com/NixOS/nix/) for
-details. Additions to in-code documentation and the reference manual are highly
-appreciated.
-
-The following examples, for simplicity, don't include error handling. See the
-[Handling errors](@ref errors) section for more information.
-
-# Embedding the Nix Evaluator{#nix_evaluator_example}
-
-In this example we programmatically start the Nix language evaluator with a
-dummy store (that has no store paths and cannot be written to), and evaluate the
-Nix expression `builtins.nixVersion`.
-
-**main.c:**
-
-```C
-#include <nix_api_util.h>
-#include <nix_api_expr.h>
-#include <nix_api_value.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-
-// NOTE: This example lacks all error handling. Production code must check for
-// errors, as some return values will be undefined.
-
-void my_get_string_cb(const char * start, unsigned int n, void * user_data)
-{
-    *((char **) user_data) = strdup(start);
-}
-
-int main()
-{
-    nix_libexpr_init(NULL);
-
-    Store * store = nix_store_open(NULL, "dummy://", NULL);
-    EvalState * state = nix_state_create(NULL, NULL, store); // empty search path (NIX_PATH)
-    Value * value = nix_alloc_value(NULL, state);
-
-    nix_expr_eval_from_string(NULL, state, "builtins.nixVersion", ".", value);
-    nix_value_force(NULL, state, value);
-
-    char * version;
-    nix_get_string(NULL, value, my_get_string_cb, &version);
-    printf("Nix version: %s\n", version);
-
-    free(version);
-    nix_gc_decref(NULL, value);
-    nix_state_free(state);
-    nix_store_free(store);
-    return 0;
-}
-```
-
-**Usage:**
-
-```ShellSession
-$ gcc main.c $(pkg-config nix-expr-c --libs --cflags) -o main
-$ ./main
-Nix version: 2.17
-```
-
-# Writing a Nix language plug-in
-
-In this example we add a custom primitive operation (_primop_) to `builtins`. It
-will increment the argument if it is an integer and throw an error otherwise.
-
-**plugin.c:**
-
-```C
-#include <nix_api_util.h>
-#include <nix_api_expr.h>
-#include <nix_api_value.h>
-
-void increment(void* user_data, nix_c_context* ctx, EvalState* state, Value** args, Value* v) {
-    nix_value_force(NULL, state, args[0]);
-    if (nix_get_type(NULL, args[0]) == NIX_TYPE_INT) {
-      nix_init_int(NULL, v, nix_get_int(NULL, args[0]) + 1);
-    } else {
-      nix_set_err_msg(ctx, NIX_ERR_UNKNOWN, "First argument should be an integer.");
-    }
-}
-
-void nix_plugin_entry() {
-  const char* args[] = {"n", NULL};
-  PrimOp *p = nix_alloc_primop(NULL, increment, 1, "increment", args, "Example custom built-in function: increments an integer", NULL);
-  nix_register_primop(NULL, p);
-  nix_gc_decref(NULL, p);
-}
-```
-
-**Usage:**
-
-```ShellSession
-$ gcc plugin.c $(pkg-config nix-expr-c --libs --cflags) -shared -o plugin.so
-$ nix --plugin-files ./plugin.so repl
-nix-repl> builtins.increment 1
-2
-```

doc/external-api/doxygen.cfg.in

@@ -1,57 +0,0 @@
-# Doxyfile 1.9.5
-
-# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
-# double-quotes, unless you are using Doxywizard) that should identify the
-# project for which the documentation is generated. This name is used in the
-# title of most generated pages and in a few other places.
-# The default value is: My Project.
-
-PROJECT_NAME           = "Nix"
-
-# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
-# could be handy for archiving the generated documentation or if some version
-# control system is used.
-
-PROJECT_NUMBER         = @PACKAGE_VERSION@
-
-# Using the PROJECT_BRIEF tag one can provide an optional one line description
-# for a project that appears at the top of each page and should give viewer a
-# quick idea about the purpose of the project. Keep the description short.
-
-PROJECT_BRIEF          = "Nix, the purely functional package manager: C API (experimental)"
-
-# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
-# The default value is: YES.
-
-GENERATE_LATEX         = NO
-
-# The INPUT tag is used to specify the files and/or directories that contain
-# documented source files. You may enter file names like myfile.cpp or
-# directories like /usr/src/myproject. Separate the files or directories with
-# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
-# Note: If this tag is empty the current directory is searched.
-
-# FIXME Make this list more maintainable somehow. We could maybe generate this
-# in the Makefile, but we would need to change how `.in` files are preprocessed
-# so they can expand variables despite configure variables.
-
-INPUT                  = \
-  src/libutil-c \
-  src/libexpr-c \
-  src/libstore-c \
-  doc/external-api/README.md
-
-FILE_PATTERNS = nix_api_*.h *.md
-
-# The INCLUDE_PATH tag can be used to specify one or more directories that
-# contain include files that are not input files but should be processed by the
-# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of
-# RECURSIVE has no effect here.
-# This tag requires that the tag SEARCH_INCLUDES is set to YES.
-
-INCLUDE_PATH           = @RAPIDCHECK_HEADERS@
-EXCLUDE_PATTERNS = *_internal.h
-GENERATE_TREEVIEW = YES
-OPTIMIZE_OUTPUT_FOR_C  = YES
-
-USE_MDFILE_AS_MAINPAGE = doc/external-api/README.md

doc/external-api/local.mk

@@ -1,7 +0,0 @@
-$(docdir)/external-api/html/index.html $(docdir)/external-api/latex: $(d)/doxygen.cfg src/lib*-c/*.h
-	mkdir -p $(docdir)/external-api
-	{ cat $< ; echo "OUTPUT_DIRECTORY=$(docdir)/external-api" ; } | doxygen -
-
-# Generate the HTML API docs for Nix's unstable C bindings
-.PHONY: external-api-html
-external-api-html: $(docdir)/external-api/html/index.html

doc/internal-api/local.mk

@@ -1,4 +1,4 @@
-$(docdir)/internal-api/html/index.html $(docdir)/internal-api/latex: $(d)/doxygen.cfg src/**/*.hh
+$(docdir)/internal-api/html/index.html $(docdir)/internal-api/latex: $(d)/doxygen.cfg
 	mkdir -p $(docdir)/internal-api
 	{ cat $< ; echo "OUTPUT_DIRECTORY=$(docdir)/internal-api" ; } | doxygen -
 

doc/manual/book.toml

@@ -6,6 +6,8 @@ additional-css = ["custom.css"]
 additional-js = ["redirects.js"]
 edit-url-template = "https://github.com/NixOS/nix/tree/master/doc/manual/{path}"
 git-repository-url = "https://github.com/NixOS/nix"
+fold.enable = true
+fold.level = 1
 
 [preprocessor.anchors]
 renderers = ["html"]

doc/manual/custom.css

@@ -1,25 +1,3 @@
-:root {
-    --sidebar-width: 23em;
-}
-
-h1.menu-title::before {
-  content: "";
-  background-image: url("./favicon.svg");
-  padding: 1.25em;
-  background-position: center center;
-  background-size: 2em;
-  background-repeat: no-repeat;
-}
-
-
-h1.menu-title {
-  padding: 0.5em;
-}
-
-.sidebar .sidebar-scrollbox {
-  padding: 1em;
-}
-
 h1:not(:first-of-type) {
     margin-top: 1.3em;
 }

doc/manual/local.mk

@@ -175,16 +175,6 @@ $(d)/src/SUMMARY-rl-next.md: $(d)/src/release-notes/rl-next.md
 # Generate the HTML manual.
 .PHONY: manual-html
 manual-html: $(docdir)/manual/index.html
-
-# Open the built HTML manual in the default browser.
-manual-html-open: $(docdir)/manual/index.html
-	@echo "  OPEN  " $<; \
-	  xdg-open $< \
-		  || open $< \
-			|| { \
-		echo "Could not open the manual in a browser. Please open '$<'" >&2; \
-		false; \
-		}
 install: $(docdir)/manual/index.html
 
 # Generate 'nix' manpages.
@@ -217,7 +207,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 # `@docroot@` is to be preserved for documenting the mechanism
 # FIXME: maybe contributing guides should live right next to the code
 # instead of in the manual
-$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
+$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md
 	$(trace-gen) \
 		tmp="$$(mktemp -d)"; \
 		cp -r doc/manual "$$tmp"; \

doc/manual/redirects.js

@@ -14,7 +14,7 @@
 
 const redirects = {
  "index.html": {
-    "part-advanced-topics": "advanced-topics/index.html",
+    "part-advanced-topics": "advanced-topics/advanced-topics.html",
     "chap-tuning-cores-and-jobs": "advanced-topics/cores-vs-jobs.html",
     "chap-diff-hook": "advanced-topics/diff-hook.html",
     "check-dirs-are-unregistered": "advanced-topics/diff-hook.html#check-dirs-are-unregistered",
@@ -22,7 +22,7 @@ const redirects = {
     "chap-post-build-hook": "advanced-topics/post-build-hook.html",
     "chap-post-build-hook-caveats": "advanced-topics/post-build-hook.html#implementation-caveats",
     "chap-writing-nix-expressions": "language/index.html",
-    "part-command-ref": "command-ref/index.html",
+    "part-command-ref": "command-ref/command-ref.html",
     "conf-allow-import-from-derivation": "command-ref/conf-file.html#conf-allow-import-from-derivation",
     "conf-allow-new-privileges": "command-ref/conf-file.html#conf-allow-new-privileges",
     "conf-allowed-uris": "command-ref/conf-file.html#conf-allowed-uris",
@@ -261,7 +261,7 @@ const redirects = {
     "sec-installer-proxy-settings": "installation/env-variables.html#proxy-environment-variables",
     "sec-nix-ssl-cert-file": "installation/env-variables.html#nix_ssl_cert_file",
     "sec-nix-ssl-cert-file-with-nix-daemon-and-macos": "installation/env-variables.html#nix_ssl_cert_file-with-macos-and-the-nix-daemon",
-    "chap-installation": "installation/index.html",
+    "chap-installation": "installation/installation.html",
     "ch-installing-binary": "installation/installing-binary.html",
     "sect-macos-installation": "installation/installing-binary.html#macos-installation",
     "sect-macos-installation-change-store-prefix": "installation/installing-binary.html#macos-installation",
@@ -285,19 +285,19 @@ const redirects = {
     "ch-basic-package-mgmt": "package-management/basic-package-mgmt.html",
     "ssec-binary-cache-substituter": "package-management/binary-cache-substituter.html",
     "sec-channels": "command-ref/nix-channel.html",
-    "ssec-copy-closure": "command-ref/nix-copy-closure.html",
+    "ssec-copy-closure": "package-management/copy-closure.html",
     "sec-garbage-collection": "package-management/garbage-collection.html",
     "ssec-gc-roots": "package-management/garbage-collector-roots.html",
-    "chap-package-management": "package-management/index.html",
+    "chap-package-management": "package-management/package-management.html",
     "sec-profiles": "package-management/profiles.html",
-    "ssec-s3-substituter": "store/types/s3-substituter.html",
-    "ssec-s3-substituter-anonymous-reads": "store/types/s3-substituter.html#anonymous-reads-to-your-s3-compatible-binary-cache",
-    "ssec-s3-substituter-authenticated-reads": "store/types/s3-substituter.html#authenticated-reads-to-your-s3-binary-cache",
-    "ssec-s3-substituter-authenticated-writes": "store/types/s3-substituter.html#authenticated-writes-to-your-s3-compatible-binary-cache",
+    "ssec-s3-substituter": "package-management/s3-substituter.html",
+    "ssec-s3-substituter-anonymous-reads": "package-management/s3-substituter.html#anonymous-reads-to-your-s3-compatible-binary-cache",
+    "ssec-s3-substituter-authenticated-reads": "package-management/s3-substituter.html#authenticated-reads-to-your-s3-binary-cache",
+    "ssec-s3-substituter-authenticated-writes": "package-management/s3-substituter.html#authenticated-writes-to-your-s3-compatible-binary-cache",
     "sec-sharing-packages": "package-management/sharing-packages.html",
     "ssec-ssh-substituter": "package-management/ssh-substituter.html",
     "chap-quick-start": "quick-start.html",
-    "sec-relnotes": "release-notes/index.html",
+    "sec-relnotes": "release-notes/release-notes.html",
     "ch-relnotes-0.10.1": "release-notes/rl-0.10.1.html",
     "ch-relnotes-0.10": "release-notes/rl-0.10.html",
     "ssec-relnotes-0.11": "release-notes/rl-0.11.html",

doc/manual/rl-next/better-errors-in-nix-repl.md

@@ -0,0 +1,40 @@
+---
+synopsis: Concise error printing in `nix repl`
+prs: 9928
+---
+
+Previously, if an element of a list or attribute set threw an error while
+evaluating, `nix repl` would print the entire error (including source location
+information) inline. This output was clumsy and difficult to parse:
+
+```
+nix-repl> { err = builtins.throw "uh oh!"; }
+{ err = «error:
+       … while calling the 'throw' builtin
+         at «string»:1:9:
+            1| { err = builtins.throw "uh oh!"; }
+             |         ^
+
+       error: uh oh!»; }
+```
+
+Now, only the error message is displayed, making the output much more readable.
+```
+nix-repl> { err = builtins.throw "uh oh!"; }
+{ err = «error: uh oh!»; }
+```
+
+However, if the whole expression being evaluated throws an error, source
+locations and (if applicable) a stack trace are printed, just like you'd expect:
+
+```
+nix-repl> builtins.throw "uh oh!"
+error:
+       … while calling the 'throw' builtin
+         at «string»:1:1:
+            1| builtins.throw "uh oh!"
+             | ^
+
+       error: uh oh!
+```
+

doc/manual/rl-next/debugger-locals-for-let-expressions.md

@@ -0,0 +1,9 @@
+---
+synopsis: "`--debugger` can now access bindings from `let` expressions"
+prs: 9918
+issues: 8827.
+---
+
+Breakpoints and errors in the bindings of a `let` expression can now access
+those bindings in the debugger. Previously, only the body of `let` expressions
+could access those bindings.

doc/manual/rl-next/debugger-on-trace.md

@@ -0,0 +1,9 @@
+---
+synopsis: Enter the `--debugger` when `builtins.trace` is called if `debugger-on-trace` is set
+prs: 9914
+---
+
+If the `debugger-on-trace` option is set and `--debugger` is given,
+`builtins.trace` calls will behave similarly to `builtins.break` and will enter
+the debug REPL. This is useful for determining where warnings are being emitted
+from.

doc/manual/rl-next/debugger-positions.md

@@ -0,0 +1,25 @@
+---
+synopsis: Debugger prints source position information
+prs: 9913
+---
+
+The `--debugger` now prints source location information, instead of the
+pointers of source location information. Before:
+
+```
+nix-repl> :bt
+0: while evaluating the attribute 'python311.pythonForBuild.pkgs'
+0x600001522598
+```
+
+After:
+
+```
+0: while evaluating the attribute 'python311.pythonForBuild.pkgs'
+/nix/store/hg65h51xnp74ikahns9hyf3py5mlbbqq-source/overrides/default.nix:132:27
+
+   131|
+   132|       bootstrappingBase = pkgs.${self.python.pythonAttr}.pythonForBuild.pkgs;
+      |                           ^
+   133|     in
+```

doc/manual/rl-next/enter-debugger-more-reliably-in-let-and-calls.md

@@ -0,0 +1,25 @@
+---
+synopsis: The `--debugger` will start more reliably in `let` expressions and function calls
+prs: 9917
+issues: 6649
+---
+
+Previously, if you attempted to evaluate this file with the debugger:
+
+```nix
+let
+  a = builtins.trace "before inner break" (
+    builtins.break "hello"
+  );
+  b = builtins.trace "before outer break" (
+    builtins.break a
+  );
+in
+  b
+```
+
+Nix would correctly enter the debugger at `builtins.break a`, but if you asked
+it to `:continue`, it would skip over the `builtins.break "hello"` expression
+entirely.
+
+Now, Nix will correctly enter the debugger at both breakpoints.

doc/manual/rl-next/harden-user-sandboxing.md

@@ -1,8 +0,0 @@
----
-synopsis: Harden the user sandboxing
-significance: significant
-issues:
-prs: <only provided once merged>
----
-
-The build directory has been hardened against interference with the outside world by nesting it inside another directory owned by (and only readable by) the daemon user.

doc/manual/rl-next/lambda-printing.md

@@ -0,0 +1,50 @@
+---
+synopsis: Functions are printed with more detail
+prs: 9606
+issues: 7145
+---
+
+Functions and `builtins` are printed with more detail in `nix repl`, `nix
+eval`, `builtins.trace`, and most other places values are printed.
+
+Before:
+
+```
+$ nix repl nixpkgs
+nix-repl> builtins.map
+«primop»
+
+nix-repl> builtins.map lib.id
+«primop-app»
+
+nix-repl> builtins.trace lib.id "my-value"
+trace: <LAMBDA>
+"my-value"
+
+$ nix eval --file functions.nix
+{ id = <LAMBDA>; primop = <PRIMOP>; primop-app = <PRIMOP-APP>; }
+```
+
+After:
+
+```
+$ nix repl nixpkgs
+nix-repl> builtins.map
+«primop map»
+
+nix-repl> builtins.map lib.id
+«partially applied primop map»
+
+nix-repl> builtins.trace lib.id "my-value"
+trace: «lambda id @ /nix/store/8rrzq23h2zq7sv5l2vhw44kls5w0f654-source/lib/trivial.nix:26:5»
+"my-value"
+
+$ nix eval --file functions.nix
+{ id = «lambda id @ /Users/wiggles/nix/functions.nix:2:8»; primop = «primop map»; primop-app = «partially applied primop map»; }
+```
+
+This was actually released in Nix 2.20, but wasn't added to the release notes
+so we're announcing it here. The historical release notes have been updated as well.
+
+[type-error]: https://github.com/NixOS/nix/pull/9753
+[coercion-error]: https://github.com/NixOS/nix/pull/9754

doc/manual/rl-next/leading-period.md

@@ -0,0 +1,10 @@
+---
+synopsis: Store paths are allowed to start with `.`
+issues: 912
+prs: 9867 9091 9095 9120 9121 9122 9130 9219 9224
+---
+
+Leading periods were allowed by accident in Nix 2.4. The Nix team has considered this to be a bug, but this behavior has since been relied on by users, leading to unnecessary difficulties.
+From now on, leading periods are officially, definitively supported. The names `.` and `..` are disallowed, as well as those starting with `.-` or `..-`.
+
+Nix versions that denied leading periods are documented [in the issue](https://github.com/NixOS/nix/issues/912#issuecomment-1919583286).

doc/manual/rl-next/more-commands-respect-ctrl-c.md

@@ -0,0 +1,13 @@
+---
+synopsis: Nix commands respect Ctrl-C
+prs: 9687 6995
+issues: 7245
+---
+
+Previously, many Nix commands would hang indefinitely if Ctrl-C was pressed
+while performing various operations (including `nix develop`, `nix flake
+update`, and so on). With several fixes to Nix's signal handlers, Nix commands
+will now exit quickly after Ctrl-C is pressed.
+
+This was actually released in Nix 2.20, but wasn't added to the release notes
+so we're announcing it here. The historical release notes have been updated as well.

doc/manual/rl-next/pretty-print-in-nix-repl.md

@@ -0,0 +1,24 @@
+---
+synopsis: "`nix repl` pretty-prints values"
+prs: 9931
+---
+
+`nix repl` will now pretty-print values:
+
+```
+{
+  attrs = {
+    a = {
+      b = {
+        c = { };
+      };
+    };
+  };
+  list = [ 1 ];
+  list' = [
+    1
+    2
+    3
+  ];
+}
+```

doc/manual/rl-next/reduce-debugger-clutter.md

@@ -0,0 +1,37 @@
+---
+synopsis: "Visual clutter in `--debugger` is reduced"
+prs: 9919
+---
+
+Before:
+```
+info: breakpoint reached
+
+
+Starting REPL to allow you to inspect the current state of the evaluator.
+
+Welcome to Nix 2.20.0pre20231222_dirty. Type :? for help.
+
+nix-repl> :continue
+error: uh oh
+
+
+Starting REPL to allow you to inspect the current state of the evaluator.
+
+Welcome to Nix 2.20.0pre20231222_dirty. Type :? for help.
+
+nix-repl>
+```
+
+After:
+
+```
+info: breakpoint reached
+
+Nix 2.20.0pre20231222_dirty debugger
+Type :? for help.
+nix-repl> :continue
+error: uh oh
+
+nix-repl>
+```

doc/manual/rl-next/repl-ctrl-c-while-printing.md

@@ -0,0 +1,8 @@
+---
+synopsis: "`nix repl` now respects Ctrl-C while printing values"
+prs: 9927
+---
+
+`nix repl` will now halt immediately when Ctrl-C is pressed while it's printing
+a value. This is useful if you got curious about what would happen if you
+printed all of Nixpkgs.

doc/manual/rl-next/repl-cycle-detection.md

@@ -0,0 +1,22 @@
+---
+synopsis: Cycle detection in `nix repl` is simpler and more reliable
+prs: 9926
+issues: 8672
+---
+
+The cycle detection in `nix repl`, `nix eval`, `builtins.trace`, and everywhere
+else values are printed is now simpler and matches the cycle detection in
+`nix-instantiate --eval` output.
+
+Before:
+
+```
+nix eval --expr 'let self = { inherit self; }; in self'
+{ self = { self = «repeated»; }; }
+```
+
+After:
+
+```
+{ self = «repeated»; }
+```

doc/manual/rl-next/stack-size-macos.md

@@ -0,0 +1,9 @@
+---
+synopsis: Stack size is increased on macOS
+prs: 9860
+---
+
+Previously, Nix would set the stack size to 64MiB on Linux, but would leave the
+stack size set to the default (approximately 8KiB) on macOS. Now, the stack
+size is correctly set to 64MiB on macOS as well, which should reduce stack
+overflow segfaults in deeply-recursive Nix expressions.

doc/manual/src/SUMMARY.md.in

@@ -18,9 +18,7 @@
   - [Uninstalling Nix](installation/uninstall.md)
 - [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)
   - [Store Object](store/store-object.md)
-    - [Content-Addressing Store Objects](store/store-object/content-address.md)
   - [Store Path](store/store-path.md)
   - [Store Types](store/types/index.md)
 {{#include ./store/types/SUMMARY.md}}
@@ -29,7 +27,6 @@
   - [Language Constructs](language/constructs.md)
     - [String interpolation](language/string-interpolation.md)
     - [Lookup path](language/constructs/lookup-path.md)
-    - [String context](language/string-context.md)
   - [Operators](language/operators.md)
   - [Derivations](language/derivations.md)
     - [Advanced Attributes](language/advanced-attributes.md)
@@ -43,7 +40,9 @@
 - [Advanced Topics](advanced-topics/index.md)
   - [Sharing Packages Between Machines](package-management/sharing-packages.md)
     - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md)
+    - [Copying Closures via SSH](package-management/copy-closure.md)
     - [Serving a Nix store via SSH](package-management/ssh-substituter.md)
+    - [Serving a Nix store via S3](package-management/s3-substituter.md)
   - [Remote Builds](advanced-topics/distributed-builds.md)
   - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)
   - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
@@ -111,9 +110,7 @@
     - [Derivation](protocols/json/derivation.md)
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
   - [Store Path Specification](protocols/store-path.md)
-  - [Nix Archive (NAR) Format](protocols/nix-archive.md)
   - [Derivation "ATerm" file format](protocols/derivation-aterm.md)
-- [C API](c-api.md)
 - [Glossary](glossary.md)
 - [Contributing](contributing/index.md)
   - [Hacking](contributing/hacking.md)
@@ -121,13 +118,9 @@
   - [Documentation](contributing/documentation.md)
   - [Experimental Features](contributing/experimental-features.md)
   - [CLI guideline](contributing/cli-guideline.md)
-  - [JSON guideline](contributing/json-guideline.md)
   - [C++ style guide](contributing/cxx.md)
-- [Releases](release-notes/index.md)
+- [Release Notes](release-notes/index.md)
 {{#include ./SUMMARY-rl-next.md}}
-  - [Release 2.23 (2024-06-03)](release-notes/rl-2.23.md)
-  - [Release 2.22 (2024-04-23)](release-notes/rl-2.22.md)
-  - [Release 2.21 (2024-03-11)](release-notes/rl-2.21.md)
   - [Release 2.20 (2024-01-29)](release-notes/rl-2.20.md)
   - [Release 2.19 (2023-11-17)](release-notes/rl-2.19.md)
   - [Release 2.18 (2023-09-20)](release-notes/rl-2.18.md)

doc/manual/src/_redirects

@@ -39,5 +39,3 @@
 /json/* /protocols/json/:splat 301!
 
 /release-notes/release-notes /release-notes 301!
-
-/package-management/copy-closure /command-ref/nix-copy-closure 301!

doc/manual/src/advanced-topics/distributed-builds.md

@@ -12,14 +12,14 @@ machine is accessible via SSH and that it has Nix installed. You can
 test whether connecting to the remote Nix instance works, e.g.
 
 ```console
-$ nix store ping --store ssh://mac
+$ nix store info --store ssh://mac
 ```
 
 will try to connect to the machine named `mac`. It is possible to
 specify an SSH identity file as part of the remote store URI, e.g.
 
 ```console
-$ nix store ping --store ssh://mac?ssh-key=/home/alice/my-key
+$ nix store info --store ssh://mac?ssh-key=/home/alice/my-key
 ```
 
 Since builds should be non-interactive, the key should not have a

doc/manual/src/architecture/architecture.md

@@ -69,7 +69,7 @@ It can also execute build plans to produce new data, which are made available to
 A build plan itself is a series of *build tasks*, together with their build inputs.
 
 > **Important**
-> A build task in Nix is called [derivation](@docroot@/glossary.md#gloss-derivation).
+> A build task in Nix is called [derivation](../glossary.md#gloss-derivation).
 
 Each build task has a special build input executed as *build instructions* in order to perform the build.
 The result of a build task can be input to another build task.

doc/manual/src/c-api.md

@@ -1,16 +0,0 @@
-# C API
-
-Nix provides a C API with the intent of [_becoming_](https://github.com/NixOS/nix/milestone/52) a stable API, which it is currently not.
-It is in development.
-
-See:
-- C API documentation for a recent build of master
-  - [Getting Started]
-  - [Index]
-- [Matrix Room *Nix Bindings*](https://matrix.to/#/#nix-bindings:nixos.org) for discussion and questions.
-- [Stabilisation Milestone](https://github.com/NixOS/nix/milestone/52)
-- [Other C API PRs and issues](https://github.com/NixOS/nix/labels/c%20api)
-- [Contributing C API Documentation](contributing/documentation.md#c-api-documentation), including how to build it locally.
-
-[Getting Started]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs
-[Index]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs/globals.html

doc/manual/src/command-ref/conf-file-prefix.md

@@ -66,12 +66,5 @@ Configuration options can be set on the command line, overriding the values set
 
 The `extra-` prefix is supported for settings that take a list of items (e.g. `--extra-trusted users alice` or `--option extra-trusted-users alice`).
 
-## Integer settings
-
-Settings that have an integer type support the suffixes `K`, `M`, `G`
-and `T`. These cause the specified value to be multiplied by 2^10,
-2^20, 2^30 and 2^40, respectively. For instance, `--min-free 1M` is
-equivalent to `--min-free 1048576`.
-
 # Available settings
 

doc/manual/src/command-ref/nix-build.md

@@ -41,7 +41,7 @@ expression to a low-level [store derivation]) and [`nix-store
 --realise`](@docroot@/command-ref/nix-store/realise.md) (to build the store
 derivation).
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[store derivation]: ../glossary.md#gloss-store-derivation
 
 > **Warning**
 >

doc/manual/src/command-ref/nix-collect-garbage.md

@@ -74,4 +74,4 @@ $ nix-collect-garbage -d
 ```
 
 [profiles]: @docroot@/command-ref/files/profiles.md
-[store objects]: @docroot@/store/store-object.md
+[store objects]: @docroot@/glossary.md#gloss-store-object

doc/manual/src/command-ref/nix-copy-closure.md

@@ -1,91 +1,91 @@
 # Name
 
-`nix-copy-closure` - copy store objects to or from a remote machine via SSH
+`nix-copy-closure` - copy a closure to or from a remote machine via SSH
 
 # Synopsis
 
 `nix-copy-closure`
-  [`--to` | `--from` ]
+  [`--to` | `--from`]
   [`--gzip`]
   [`--include-outputs`]
   [`--use-substitutes` | `-s`]
   [`-v`]
-  [_user_@]_machine_[:_port_] _paths_
+  _user@machine_ _paths_
 
 # Description
 
-Given _paths_ from one machine, `nix-copy-closure` computes the [closure](@docroot@/glossary.md#gloss-closure) of those paths (i.e. all their dependencies in the Nix store), and copies [store objects](@docroot@/glossary.md#gloss-store-object) in that closure to another machine via SSH.
-It doesn’t copy store objects that are already present on the other machine.
+`nix-copy-closure` gives you an easy and efficient way to exchange
+software between machines.  Given one or more Nix store _paths_ on the
+local machine, `nix-copy-closure` computes the closure of those paths
+(i.e. all their dependencies in the Nix store), and copies all paths
+in the closure to the remote machine via the `ssh` (Secure Shell)
+command.  With the `--from` option, the direction is reversed: the
+closure of _paths_ on a remote machine is copied to the Nix store on
+the local machine.
 
-> **Note**
->
-> While the Nix store to use on the local machine can be specified on the command line with the [`--store`](@docroot@/command-ref/conf-file.md#conf-store) option, the Nix store to be accessed on the remote machine can only be [configured statically](@docroot@/command-ref/conf-file.md#configuration-file) on that remote machine.
+This command is efficient because it only sends the store paths
+that are missing on the target machine.
 
-Since `nix-copy-closure` calls `ssh`, you may need to authenticate with the remote machine.
-In fact, you may be asked for authentication _twice_ because `nix-copy-closure` currently connects twice to the remote machine: first to get the set of paths missing on the target machine, and second to send the dump of those paths.
-When using public key authentication, you can avoid typing the passphrase with `ssh-agent`.
+Since `nix-copy-closure` calls `ssh`, you may be asked to type in the
+appropriate password or passphrase.  In fact, you may be asked _twice_
+because `nix-copy-closure` currently connects twice to the remote
+machine, first to get the set of paths missing on the target machine,
+and second to send the dump of those paths.  When using public key
+authentication, you can avoid typing the passphrase with `ssh-agent`.
 
 # Options
 
-  - `--to`
+  - `--to`\
+    Copy the closure of _paths_ from the local Nix store to the Nix
+    store on _machine_. This is the default.
 
-    Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_.
-    This is the default behavior.
-
-  - `--from`
-
-    Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified Nix store.
-
-  - `--gzip`
+  - `--from`\
+    Copy the closure of _paths_ from the Nix store on _machine_ to the
+    local Nix store.
 
+  - `--gzip`\
     Enable compression of the SSH connection.
 
-  - `--include-outputs`
-
+  - `--include-outputs`\
     Also copy the outputs of [store derivation]s included in the closure.
 
-    [store derivation]: @docroot@/glossary.md#gloss-store-derivation
+    [store derivation]: ../glossary.md#gloss-store-derivation
 
-  - `--use-substitutes` / `-s`
+  - `--use-substitutes` / `-s`\
+    Attempt to download missing paths on the target machine using Nix’s
+    substitute mechanism.  Any paths that cannot be substituted on the
+    target are still copied normally from the source.  This is useful,
+    for instance, if the connection between the source and target
+    machine is slow, but the connection between the target machine and
+    `nixos.org` (the default binary cache server) is
+    fast.
 
-    Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters).
-    Any store objects that cannot be substituted on the target are still copied normally from the source.
-    This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast.
+  - `-v`\
+    Show verbose output.
 
 {{#include ./opt-common.md}}
 
 # Environment variables
 
-  - `NIX_SSHOPTS`
-
-    Additional options to be passed to `ssh` on the command line.
+  - `NIX_SSHOPTS`\
+    Additional options to be passed to `ssh` on the command
+    line.
 
 {{#include ./env-common.md}}
 
 # Examples
 
-> **Example**
->
-> Copy GNU Hello with all its dependencies to a remote machine:
->
-> ```shell-session
-> $ storePath="$(nix-build '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello --no-out-link)"
-> $ nix-copy-closure --to alice@itchy.example.org "$storePath"
-> copying 5 paths...
-> copying path '/nix/store/nrwkk6ak3rgkrxbqhsscb01jpzmslf2r-xgcc-13.2.0-libgcc' to 'ssh://alice@itchy.example.org'...
-> copying path '/nix/store/gm61h1y42pqyl6178g90x8zm22n6pyy5-libunistring-1.1' to 'ssh://alice@itchy.example.org'...
-> copying path '/nix/store/ddfzjdykw67s20c35i7a6624by3iz5jv-libidn2-2.3.7' to 'ssh://alice@itchy.example.org'...
-> copying path '/nix/store/apab5i73dqa09wx0q27b6fbhd1r18ihl-glibc-2.39-31' to 'ssh://alice@itchy.example.org'...
-> copying path '/nix/store/g1n2vryg06amvcc1avb2mcq36faly0mh-hello-2.12.1' to 'ssh://alice@itchy.example.org'...
-> ```
+Copy Firefox with all its dependencies to a remote machine:
 
-> **Example**
->
-> Copy GNU Hello from a remote machine using a known store path, and run it:
->
-> ```shell-session
-> $ storePath="$(nix-instantiate --eval '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello.outPath | tr -d '"')"
-> $ nix-copy-closure --from alice@itchy.example.org "$storePath"
-> $ "$storePath"/bin/hello
-> Hello, world!
-> ```
+```console
+$ nix-copy-closure --to alice@itchy.labs $(type -tP firefox)
+```
+
+Copy Subversion from a remote machine and then install it into a user
+environment:
+
+```console
+$ nix-copy-closure --from alice@itchy.labs \
+    /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4
+$ nix-env --install /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4
+```

doc/manual/src/command-ref/nix-env.md

@@ -47,83 +47,39 @@ These pages can be viewed offline:
 
   Example: `nix-env --help --install`
 
-# Package sources
-
-`nix-env` can obtain packages from multiple sources:
-
-- An attribute set of derivations from:
-  - The [default Nix expression](@docroot@/command-ref/files/default-nix-expression.md) (by default)
-  - A Nix file, specified via `--file`
-  - A [profile](@docroot@/command-ref/files/profiles.md), specified via `--from-profile`
-  - A Nix expression that is a function which takes default expression as argument, specified via `--from-expression`
-- A [store path](@docroot@/store/store-path.md)
-
 # Selectors
 
-Several operations, such as [`nix-env --query`](./nix-env/query.md) and [`nix-env --install`](./nix-env/install.md), take a list of *arguments* that specify the packages on which to operate.
+Several commands, such as `nix-env --query ` and `nix-env --install `, take a list of
+arguments that specify the packages on which to operate. These are
+extended regular expressions that must match the entire name of the
+package. (For details on regular expressions, see **regex**(7).) The match is
+case-sensitive. The regular expression can optionally be followed by a
+dash and a version number; if omitted, any version of the package will
+match. Here are some examples:
 
-Packages are identified based on a `name` part and a `version` part of a [symbolic derivation name](@docroot@/language/derivations.md#attr-names):
+  - `firefox`\
+    Matches the package name `firefox` and any version.
 
-- `name`: Everything up to but not including the first dash (`-`) that is *not* followed by a letter.
-- `version`: The rest, excluding the separating dash.
+  - `firefox-32.0`\
+    Matches the package name `firefox` and version `32.0`.
 
-> **Example**
->
-> `nix-env` parses the symbolic derivation name `apache-httpd-2.0.48` as:
->
-> ```json
-> {
->   "name": "apache-httpd",
->   "version": "2.0.48"
-> }
-> ```
+  - `gtk\\+`\
+    Matches the package name `gtk+`. The `+` character must be escaped
+    using a backslash to prevent it from being interpreted as a
+    quantifier, and the backslash must be escaped in turn with another
+    backslash to ensure that the shell passes it on.
 
-> **Example**
->
-> `nix-env` parses the symbolic derivation name `firefox.*` as:
->
-> ```json
-> {
->   "name": "firefox.*",
->   "version": ""
-> }
-> ```
+  - `.\*`\
+    Matches any package name. This is the default for most commands.
 
-The `name` parts of the *arguments* to `nix-env` are treated as extended regular expressions and matched against the `name` parts of derivation names in the package source.
-The match is case-sensitive.
-The regular expression can optionally be followed by a dash (`-`) and a version number; if omitted, any version of the package will match.
-For details on regular expressions, see [**regex**(7)](https://linux.die.net/man/7/regex).
+  - `'.*zip.*'`\
+    Matches any package name containing the string `zip`. Note the dots:
+    `'*zip*'` does not work, because in a regular expression, the
+    character `*` is interpreted as a quantifier.
 
-> **Example**
->
-> Common patterns for finding package names with `nix-env`:
->
-> - `firefox`
->
->   Matches the package name `firefox` and any version.
->
-> - `firefox-32.0`
->
->   Matches the package name `firefox` and version `32.0`.
->
-> - `gtk\\+`
->
->   Matches the package name `gtk+`.
->   The `+` character must be escaped using a backslash (`\`) to prevent it from being interpreted as a quantifier, and the backslash must be escaped in turn with another backslash to ensure that the shell passes it on.
->
-> - `.\*`
->
->   Matches any package name.
->   This is the default for most commands.
->
-> - `'.*zip.*'`
->
->   Matches any package name containing the string `zip`.
->   Note the dots: `'*zip*'` does not work, because in a regular expression, the character `*` is interpreted as a quantifier.
->
-> - `'.*(firefox|chromium).*'`
->
->   Matches any package name containing the strings `firefox` or `chromium`.
+  - `'.*(firefox|chromium).*'`\
+    Matches any package name containing the strings `firefox` or
+    `chromium`.
 
 # Files
 

doc/manual/src/command-ref/nix-env/delete-generations.md

@@ -49,7 +49,7 @@ Periodically deleting old generations is important to make garbage collection
 effective.
 The is because profiles are also garbage collection roots — any [store object] reachable from a profile is "alive" and ineligible for deletion.
 
-[store object]: @docroot@/store/store-object.md
+[store object]: @docroot@/glossary.md#gloss-store-object
 
 {{#include ./opt-common.md}}
 

doc/manual/src/command-ref/nix-env/install.md

@@ -14,13 +14,14 @@
 
 # Description
 
-The `--install` operation creates a new user environment.
+The install operation creates a new user environment.
 It is based on the current generation of the active [profile](@docroot@/command-ref/files/profiles.md), to which a set of [store paths] described by *args* is added.
 
-[store paths]: @docroot@/store/store-path.md
+[store paths]: @docroot@/glossary.md#gloss-store-path
 
 The arguments *args* map to store paths in a number of possible ways:
 
+
   - By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression].
     These are [realised], and the resulting output paths are installed.
     Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
@@ -49,7 +50,7 @@ The arguments *args* map to store paths in a number of possible ways:
     Show the attribute paths of available packages with [`nix-env --query`](./query.md):
 
     ```console
-    nix-env --query --available --attr-path
+    nix-env --query --available --attr-path`
     ```
 
   - If `--from-profile` *path* is given, *args* is a set of names

doc/manual/src/command-ref/nix-hash.md

@@ -20,21 +20,16 @@ an example.
 The hash is computed over a *serialisation* of each path: a dump of
 the file system tree rooted at the path. This allows directories and
 symlinks to be hashed as well as regular files. The dump is in the
-*[Nix Archive (NAR)][Nix Archive] format* produced by [`nix-store
+*NAR format* produced by [`nix-store
 --dump`](@docroot@/command-ref/nix-store/dump.md).  Thus, `nix-hash path`
 yields the same cryptographic hash as `nix-store --dump path |
 md5sum`.
 
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
-
 # Options
 
   - `--flat`\
-    Print the cryptographic hash of the contents of each regular file *path*.
-    That is, instead of computing
-    the hash of the [Nix Archive (NAR)](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) of *path*,
-    just [directly hash]((@docroot@/store/file-system-object/content-address.md#serial-flat) *path* as is.
-    This requires *path* to resolve to a regular file rather than directory.
+    Print the cryptographic hash of the contents of each regular file
+    *path*. That is, do not compute the hash over the dump of *path*.
     The result is identical to that produced by the GNU commands
     `md5sum` and `sha1sum`.
 

doc/manual/src/command-ref/nix-instantiate.md

@@ -23,7 +23,7 @@ It evaluates the Nix expressions in each of *files* (which defaults to
 derivation, a list of derivations, or a set of derivations. The paths
 of the resulting store derivations are printed on standard output.
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[store derivation]: ../glossary.md#gloss-store-derivation
 
 If *files* is the character `-`, then a Nix expression will be read from
 standard input.

doc/manual/src/command-ref/nix-shell.md

@@ -202,14 +202,14 @@ For example, here is a Python script that depends on Python and the
 
 ```python
 #! /usr/bin/env nix-shell
-#! nix-shell -i python3 --packages python3 python3Packages.prettytable
+#! nix-shell -i python --packages python pythonPackages.prettytable
 
 import prettytable
 
 # Print a simple table.
 t = prettytable.PrettyTable(["N", "N^2"])
 for n in range(1, 10): t.add_row([n, n * n])
-print(t)
+print t
 ```
 
 Similarly, the following is a Perl script that specifies that it

doc/manual/src/command-ref/nix-store/dump.md

@@ -1,6 +1,6 @@
 # Name
 
-`nix-store --dump` - write a single path to a [Nix Archive]
+`nix-store --dump` - write a single path to a Nix Archive
 
 ## Synopsis
 
@@ -8,7 +8,7 @@
 
 ## Description
 
-The operation `--dump` produces a [Nix archive](@docroot@/glossary.md#gloss-nar) (NAR) file containing the
+The operation `--dump` produces a NAR (Nix ARchive) file containing the
 contents of the file system tree rooted at *path*. The archive is
 written to standard output.
 
@@ -30,9 +30,8 @@ NAR archives support filenames of unlimited length and 64-bit file
 sizes. They can contain regular files, directories, and symbolic links,
 but not other types of files (such as device nodes).
 
-A Nix archive can be unpacked using [`nix-store --restore`](@docroot@/command-ref/nix-store/restore.md).
-
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
+A Nix archive can be unpacked using `nix-store
+--restore`.
 
 {{#include ./opt-common.md}}
 

doc/manual/src/command-ref/nix-store/export.md

@@ -1,6 +1,6 @@
 # Name
 
-`nix-store --export` - export store paths to a [Nix Archive]
+`nix-store --export` - export store paths to a Nix Archive
 
 ## Synopsis
 
@@ -8,22 +8,16 @@
 
 ## Description
 
-The operation `--export` writes a serialisation of the given [store objects](@docroot@/glossary.md#gloss-store-object) to standard output in a format that can be imported into another [Nix store](@docroot@/store/index.md) with [`nix-store --import`](./import.md).
+The operation `--export` writes a serialisation of the specified store
+paths to standard output in a format that can be imported into another
+Nix store with `nix-store --import`. This is like `nix-store
+--dump`, except that the NAR archive produced by that command doesn’t
+contain the necessary meta-information to allow it to be imported into
+another Nix store (namely, the set of references of the path).
 
-> **Warning**
->
-> This command *does not* produce a [closure](@docroot@/glossary.md#gloss-closure) of the specified store paths.
-> Trying to import a store object that refers to store paths not available in the target Nix store will fail.
->
-> Use [`nix-store --query`](@docroot@/command-ref/nix-store/query.md) to obtain the closure of a store path.
-
-This command is different from [`nix-store --dump`](./dump.md), which produces a [Nix archive](@docroot@/glossary.md#gloss-nar) that *does not* contain the set of [references](@docroot@/glossary.md#gloss-reference) of a given store path.
-
-> **Note**
->
-> For efficient transfer of closures to remote machines over SSH, use [`nix-copy-closure`](@docroot@/command-ref/nix-copy-closure.md).
-
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
+This command does not produce a *closure* of the specified paths, so if
+a store path references other store paths that are missing in the target
+Nix store, the import will fail.
 
 {{#include ./opt-common.md}}
 
@@ -33,21 +27,15 @@ This command is different from [`nix-store --dump`](./dump.md), which produces a
 
 # Examples
 
-> **Example**
->
-> Deploy GNU Hello to an airgapped machine via USB stick.
->
-> Write the closure to the block device on a machine with internet connection:
->
-> ```shell-session
-> [alice@itchy]$ storePath=$(nix-build '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello --no-out-link)
-> [alice@itchy]$ nix-store --export $(nix-store --query --requisites $storePath) | sudo dd of=/dev/usb
-> ```
->
-> Read the closure from the block device on the machine without internet connection:
->
-> ```shell-session
-> [bob@scratchy]$ hello=$(sudo dd if=/dev/usb | nix-store --import | tail -1)
-> [bob@scratchy]$ $hello/bin/hello
-> Hello, world!
-> ```
+To copy a whole closure, do something
+like:
+
+```console
+$ nix-store --export $(nix-store --query --requisites paths) > out
+```
+
+To import the whole closure again, run:
+
+```console
+$ nix-store --import < out
+```

doc/manual/src/command-ref/nix-store/import.md

@@ -1,8 +1,6 @@
 # Name
 
-`nix-store --import` - import [Nix Archive] into the store
-
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
+`nix-store --import` - import Nix Archive into the store
 
 # Synopsis
 
@@ -10,34 +8,14 @@
 
 # Description
 
-The operation `--import` reads a serialisation of a set of [store objects](@docroot@/glossary.md#gloss-store-object) produced by [`nix-store --export`](./export.md) from standard input, and adds those store objects to the specified [Nix store](@docroot@/store/index.md).
-Paths that already exist in the target Nix store are ignored.
-If a path [refers](@docroot@/glossary.md#gloss-reference) to another path that doesn’t exist in the target Nix store, the import fails.
-
-> **Note**
->
-> For efficient transfer of closures to remote machines over SSH, use [`nix-copy-closure`](@docroot@/command-ref/nix-copy-closure.md).
+The operation `--import` reads a serialisation of a set of store paths
+produced by `nix-store --export` from standard input and adds those
+store paths to the Nix store. Paths that already exist in the Nix store
+are ignored. If a path refers to another path that doesn’t exist in the
+Nix store, the import fails.
 
 {{#include ./opt-common.md}}
 
 {{#include ../opt-common.md}}
 
 {{#include ../env-common.md}}
-
-# Examples
-
-> **Example**
->
-> Given a closure of GNU Hello as a file:
->
-> ```shell-session
-> $ storePath="$(nix-build '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello --no-out-link)"
-> $ nix-store --export $(nix-store --query --requisites $storePath) > hello.closure
-> ```
->
-> Import the closure into a [remote SSH store](@docroot@/store/types/ssh-store.md) using the [`--store`](@docroot@/command-ref/conf-file.md#conf-store) option:
->
-> ```console
-> $ nix-store --import --store ssh://alice@itchy.example.org < hello.closure
-> ```
-

doc/manual/src/command-ref/nix-store/optimise.md

@@ -12,7 +12,7 @@ The operation `--optimise` reduces Nix store disk space usage by finding
 identical files in the store and hard-linking them to each other. It
 typically reduces the size of the store by something like 25-35%. Only
 regular files and symlinks are hard-linked in this manner. Files are
-considered identical when they have the same [Nix Archive (NAR)][Nix Archive] serialisation:
+considered identical when they have the same NAR archive serialisation:
 that is, regular files must have the same contents and permission
 (executable or non-executable), and symlinks must have the same
 contents.
@@ -38,4 +38,3 @@ hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1'
 there are 114486 files with equal contents out of 215894 files in total
 ```
 
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive

doc/manual/src/command-ref/nix-store/query.md

@@ -40,12 +40,12 @@ symlink.
     derivations *paths*. These are the paths that will be produced when
     the derivation is built.
 
-    [output paths]: @docroot@/glossary.md#gloss-output-path
+    [output paths]: ../../glossary.md#gloss-output-path
 
   - `--requisites`; `-R`\
     Prints out the [closure] of the store path *paths*.
 
-    [closure]: @docroot@/glossary.md#gloss-closure
+    [closure]: ../../glossary.md#gloss-closure
 
     This query has one option:
 
@@ -66,7 +66,7 @@ symlink.
     *paths*, that is, their immediate dependencies. (For *all*
     dependencies, use `--requisites`.)
 
-    [references]: @docroot@/glossary.md#gloss-reference
+    [references]: ../../glossary.md#gloss-reference
 
   - `--referrers`\
     Prints the set of *referrers* of the store paths *paths*, that is,
@@ -90,7 +90,7 @@ symlink.
     example when *paths* were substituted from a binary cache.
     Use `--valid-derivers` instead to obtain valid paths only.
 
-    [deriver]: @docroot@/glossary.md#gloss-deriver
+    [deriver]: ../../glossary.md#gloss-deriver
 
   - `--valid-derivers`\
     Prints a set of derivation files (`.drv`) which are supposed produce

doc/manual/src/command-ref/nix-store/realise.md

@@ -25,11 +25,11 @@ Each of *paths* is processed as follows:
 
 If no substitutes are available and no store derivation is given, realisation fails.
 
-[store paths]: @docroot@/store/store-path.md
+[store paths]: @docroot@/glossary.md#gloss-store-path
 [valid]: @docroot@/glossary.md#gloss-validity
 [store derivation]: @docroot@/glossary.md#gloss-store-derivation
 [output paths]: @docroot@/glossary.md#gloss-output-path
-[store objects]: @docroot@/store/store-object.md
+[store objects]: @docroot@/glossary.md#gloss-store-object
 [closure]: @docroot@/glossary.md#gloss-closure
 [substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
 [content-addressed derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations

doc/manual/src/command-ref/nix-store/restore.md

@@ -8,11 +8,9 @@
 
 ## Description
 
-The operation `--restore` unpacks a [Nix Archive (NAR)][Nix Archive] to *path*, which must
+The operation `--restore` unpacks a NAR archive to *path*, which must
 not already exist. The archive is read from standard input.
 
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
-
 {{#include ./opt-common.md}}
 
 {{#include ../opt-common.md}}

doc/manual/src/contributing/cli-guideline.md

@@ -389,6 +389,88 @@ colors, no emojis and using ASCII instead of Unicode symbols). The same should
 happen when TTY is not detected on STDERR. We should not display progress /
 status section, but only print warnings and errors.
 
+## Returning future proof JSON
+
+The schema of JSON output should allow for backwards compatible extension. This section explains how to achieve this.
+
+Two definitions are helpful here, because while JSON only defines one "key-value"
+object type, we use it to cover two use cases:
+
+ - **dictionary**: a map from names to value that all have the same type. In
+   C++ this would be a `std::map` with string keys.
+ - **record**: a fixed set of attributes each with their own type. In C++, this
+   would be represented by a `struct`.
+
+It is best not to mix these use cases, as that may lead to incompatibilities when the schema changes. For example, adding a record field to a dictionary breaks consumers that assume all JSON object fields to have the same meaning and type.
+
+This leads to the following guidelines:
+
+ - The top-level (root) value must be a record.
+
+   Otherwise, one can not change the structure of a command's output.
+
+ - The value of a dictionary item must be a record.
+
+   Otherwise, the item type can not be extended.
+
+ - List items should be records.
+
+   Otherwise, one can not change the structure of the list items.
+
+   If the order of the items does not matter, and each item has a unique key that is a string, consider representing the list as a dictionary instead. If the order of the items needs to be preserved, return a list of records.
+
+ - Streaming JSON should return records.
+
+   An example of a streaming JSON format is [JSON lines](https://jsonlines.org/), where each line represents a JSON value. These JSON values can be considered top-level values or list items, and they must be records.
+
+### Examples
+
+
+This is bad, because all keys must be assumed to be store types:
+
+```json
+{
+  "local": { ... },
+  "remote": { ... },
+  "http": { ... }
+}
+```
+
+This is good, because the it is extensible at the root, and is somewhat self-documenting:
+
+```json
+{
+  "storeTypes": { "local": { ... }, ... },
+  "pluginSupport": true
+}
+```
+
+While the dictionary of store types seems like a very complete response at first, a use case may arise that warrants returning additional information.
+For example, the presence of plugin support may be crucial information for a client to proceed when their desired store type is missing.
+
+
+
+The following representation is bad because it is not extensible:
+
+```json
+{ "outputs": [ "out" "bin" ] }
+```
+
+However, simply converting everything to records is not enough, because the order of outputs must be preserved:
+
+```json
+{ "outputs": { "bin": {}, "out": {} } }
+```
+
+The first item is the default output. Deriving this information from the outputs ordering is not great, but this is how Nix currently happens to work.
+While it is possible for a JSON parser to preserve the order of fields, we can not rely on this capability to be present in all JSON libraries.
+
+This representation is extensible and preserves the ordering:
+
+```json
+{ "outputs": [ { "outputName": "out" }, { "outputName": "bin" } ] }
+```
+
 ## Dialog with the user
 
 CLIs don't always make it clear when an action has taken place. For every

doc/manual/src/contributing/documentation.md

@@ -27,9 +27,11 @@ and open `./result-doc/share/doc/nix/manual/index.html`.
 To build the manual incrementally, [enter the development shell](./hacking.md) and run:
 
 ```console
-make manual-html-open -j $NIX_BUILD_CORES
+make manual-html -j $NIX_BUILD_CORES
 ```
 
+and open `./outputs/out/share/doc/nix/manual/language/index.html`.
+
 In order to reflect changes to the [Makefile for the manual], clear all generated files before re-building:
 
 [Makefile for the manual]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
@@ -147,7 +149,7 @@ Please observe these guidelines to ease reviews:
   ```
   A [store object] contains a [file system object] and [references] to other store objects.
 
-  [store object]: @docroot@/store/store-object.md
+  [store object]: @docroot@/glossary.md#gloss-store-object
   [file system object]: @docroot@/architecture/file-system-object.md
   [references]: @docroot@/glossary.md#gloss-reference
   ```
@@ -206,23 +208,3 @@ or inside `nix-shell` or `nix develop`:
 # make internal-api-html
 # xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html
 ```
-
-## C API documentation
-
-Note that the C API is not yet stable.
-[C API documentation] is available online.
-You can also build and view it yourself:
-
-[C API documentation]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs
-
-```console
-# nix build .#hydraJobs.external-api-docs
-# xdg-open ./result/share/doc/nix/external-api/html/index.html
-```
-
-or inside `nix-shell` or `nix develop`:
-
-```
-# make external-api-html
-# xdg-open ./outputs/doc/share/doc/nix/external-api/html/index.html
-```

doc/manual/src/contributing/hacking.md

@@ -144,7 +144,6 @@ Nix can be built for various platforms, as specified in [`flake.nix`]:
 - `aarch64-darwin`
 - `armv6l-linux`
 - `armv7l-linux`
-- `riscv64-linux`
 
 In order to build Nix for a different platform than the one you're currently
 on, you need a way for your current Nix installation to build code for that
@@ -167,10 +166,7 @@ or for Nix with the [`flakes`] and [`nix-command`] experimental features enabled
 $ nix build .#packages.aarch64-linux.default
 ```
 
-Cross-compiled builds are available for:
-- `armv6l-linux`
-- `armv7l-linux`
-- `riscv64-linux`
+Cross-compiled builds are available for ARMv6 (`armv6l-linux`) and ARMv7 (`armv7l-linux`).
 Add more [system types](#system-type) to `crossSystems` in `flake.nix` to bootstrap Nix on unsupported platforms.
 
 ### Building for multiple platforms at once
@@ -200,7 +196,7 @@ In order to facilitate this, Nix has some support for being built out of tree
 
 ## System type
 
-Nix uses a string with the following format to identify the *system type* or *platform* it runs on:
+Nix uses a string with he following format to identify the *system type* or *platform* it runs on:
 
 ```
 <cpu>-<os>[-<abi>]
@@ -262,10 +258,10 @@ See [supported compilation environments](#compilation-environments) and instruct
 To use the LSP with your editor, you first need to [set up `clangd`](https://clangd.llvm.org/installation#project-setup) by running:
 
 ```console
-make compile_commands.json
+make clean && bear -- make -j$NIX_BUILD_CORES default check install
 ```
 
-Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages` shell. You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
+Configure your editor to use the `clangd` from the shell, either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
 
 > **Note**
 >
@@ -273,29 +269,6 @@ Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages
 > Some other editors (e.g. Emacs, Vim) need a plugin to support LSP servers in general (e.g. [lsp-mode](https://github.com/emacs-lsp/lsp-mode) for Emacs and [vim-lsp](https://github.com/prabirshrestha/vim-lsp) for vim).
 > Editor-specific setup is typically opinionated, so we will not cover it here in more detail.
 
-## Formatting and pre-commit hooks
-
-You may run the formatters as a one-off using:
-
-```console
-make format
-```
-
-If you'd like to run the formatters before every commit, install the hooks:
-
-```
-pre-commit-hooks-install
-```
-
-This installs [pre-commit](https://pre-commit.com) using [cachix/git-hooks.nix](https://github.com/cachix/git-hooks.nix).
-
-When making a commit, pay attention to the console output.
-If it fails, run `git add --patch` to approve the suggestions _and commit again_.
-
-To refresh pre-commit hook's config file, do the following:
-1. Exit the development shell and start it again by running `nix develop`.
-2. If you also use the pre-commit hook, also run `pre-commit-hooks-install` again.
-
 ## Add a release note
 
 `doc/manual/rl-next` contains release notes entries for all unreleased changes.

doc/manual/src/contributing/json-guideline.md

@@ -1,128 +0,0 @@
-# JSON guideline
-
-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.
-
-## Extensibility
-
-The schema of JSON input and output should allow for backwards compatible extension.
-This section explains how to achieve this.
-
-Two definitions are helpful here, because while JSON only defines one "key-value" object type, we use it to cover two use cases:
-
- - **dictionary**: a map from names to value that all have the same type.
-   In C++ this would be a `std::map` with string keys.
-
- - **record**: a fixed set of attributes each with their own type.
-   In C++, this would be represented by a `struct`.
-
-It is best not to mix these use cases, as that may lead to incompatibilities when the schema changes.
-For example, adding a record field to a dictionary breaks consumers that assume all JSON object fields to have the same meaning and type, and dictionary items with a colliding name can not be represented anymore.
-
-This leads to the following guidelines:
-
- - The top-level (root) value must be a record.
-
-   Otherwise, one can not change the structure of a command's output.
-
- - The value of a dictionary item must be a record.
-
-   Otherwise, the item type can not be extended.
-
- - List items should be records.
-
-   Otherwise, one can not change the structure of the list items.
-
-   If the order of the items does not matter, and each item has a unique key that is a string, consider representing the list as a dictionary instead.
-   If the order of the items needs to be preserved, return a list of records.
-
- - Streaming JSON should return records.
-
-   An example of a streaming JSON format is [JSON lines](https://jsonlines.org/), where each line represents a JSON value.
-   These JSON values can be considered top-level values or list items, and they must be records.
-
-### Examples
-
-This is bad, because all keys must be assumed to be store types:
-
-```json
-{
-  "local": { ... },
-  "remote": { ... },
-  "http": { ... }
-}
-```
-
-This is good, because the it is extensible at the root, and is somewhat self-documenting:
-
-```json
-{
-  "storeTypes": { "local": { ... }, ... },
-  "pluginSupport": true
-}
-```
-
-While the dictionary of store types seems like a very complete response at first, a use case may arise that warrants returning additional information.
-For example, the presence of plugin support may be crucial information for a client to proceed when their desired store type is missing.
-
-
-
-The following representation is bad because it is not extensible:
-
-```json
-{ "outputs": [ "out" "bin" ] }
-```
-
-However, simply converting everything to records is not enough, because the order of outputs must be preserved:
-
-```json
-{ "outputs": { "bin": {}, "out": {} } }
-```
-
-The first item is the default output. Deriving this information from the outputs ordering is not great, but this is how Nix currently happens to work.
-While it is possible for a JSON parser to preserve the order of fields, we can not rely on this capability to be present in all JSON libraries.
-
-This representation is extensible and preserves the ordering:
-
-```json
-{ "outputs": [ { "outputName": "out" }, { "outputName": "bin" } ] }
-```
-
-## Self-describing values
-
-As described in the previous section, it's crucial that schemas can be extended with with new fields without breaking compatibility.
-However, that should *not* mean we use the presence/absence of fields to indicate optional information *within* a version of the schema.
-Instead, always include the field, and use `null` to indicate the "nothing" case.
-
-### Examples
-
-Here are two JSON objects:
-
-```json
-{
-  "foo": {}
-}
-```
-```json
-{
-  "foo": {},
-  "bar": {}
-}
-```
-
-Since they differ in which fields they contain, they should *not* both be valid values of the same schema.
-At most, they can match two different schemas where the second (with `foo` and `bar`) is considered a newer version of the first (with just `foo`).
-Within each version, all fields are mandatory (always `foo`, and always `foo` and `bar`).
-Only *between* each version, `bar` gets added as a new mandatory field.
-
-Here are another two JSON objects:
-
-```json
-{ "foo": null }
-```
-```json
-{ "foo": { "bar": 1 } }
-```
-
-Since they both contain a `foo` field, they could be valid values of the same schema.
-The schema would have `foo` has an optional field, which is either `null` or an object where `bar` is an integer.

doc/manual/src/contributing/testing.md

@@ -60,7 +60,7 @@ The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
 > ```
 
 The tests for each Nix library (`libnixexpr`, `libnixstore`, etc..) live inside a directory `tests/unit/${library_name_without-nix}`.
-Given an interface (header) and implementation pair in the original library, say, `src/libexpr/value/context.{hh,cc}`, we write tests for it in `tests/unit/libexpr/tests/value/context.cc`, and (possibly) declare/define additional interfaces for testing purposes in `tests/unit/libexpr-support/tests/value/context.{hh,cc}`.
+Given a interface (header) and implementation pair in the original library, say, `src/libexpr/value/context.{hh,cc}`, we write tests for it in `tests/unit/libexpr/tests/value/context.cc`, and (possibly) declare/define additional interfaces for testing purposes in `tests/unit/libexpr-support/tests/value/context.{hh,cc}`.
 
 Data for unit tests is stored in a `data` subdir of the directory for each unit test executable.
 For example, `libnixstore` code is in `src/libstore`, and its test data is in `tests/unit/libstore/data`.
@@ -162,14 +162,14 @@ ran test tests/functional/${testName}.sh... [PASS]
 or without `make`:
 
 ```shell-session
-$ ./mk/run-test.sh tests/functional/${testName}.sh
+$ ./mk/run-test.sh tests/functional/${testName}.sh tests/functional/init.sh
 ran test tests/functional/${testName}.sh... [PASS]
 ```
 
 To see the complete output, one can also run:
 
 ```shell-session
-$ ./mk/debug-test.sh tests/functional/${testName}.sh
+$ ./mk/debug-test.sh tests/functional/${testName}.sh tests/functional/init.sh
 +(${testName}.sh:1) foo
 output from foo
 +(${testName}.sh:2) bar
@@ -204,7 +204,7 @@ edit it like so:
 Then, running the test with `./mk/debug-test.sh` will drop you into GDB once the script reaches that point:
 
 ```shell-session
-$ ./mk/debug-test.sh tests/functional/${testName}.sh
+$ ./mk/debug-test.sh tests/functional/${testName}.sh tests/functional/init.sh
 ...
 + gdb blash blub
 GNU gdb (GDB) 12.1

doc/manual/src/favicon.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="587.11" height="516.604" viewBox="0 0 550.416 484.317"><defs><linearGradient id="a"><stop offset="0" style="stop-color:#699ad7;stop-opacity:1"/><stop offset=".243" style="stop-color:#7eb1dd;stop-opacity:1"/><stop offset="1" style="stop-color:#7ebae4;stop-opacity:1"/></linearGradient><linearGradient id="b"><stop offset="0" style="stop-color:#415e9a;stop-opacity:1"/><stop offset=".232" style="stop-color:#4a6baf;stop-opacity:1"/><stop offset="1" style="stop-color:#5277c3;stop-opacity:1"/></linearGradient><linearGradient xlink:href="#a" id="c" x1="200.597" x2="290.087" y1="351.411" y2="506.188" gradientTransform="translate(70.65 -1055.151)" gradientUnits="userSpaceOnUse"/><linearGradient xlink:href="#b" id="e" x1="-584.199" x2="-496.297" y1="782.336" y2="937.714" gradientTransform="translate(864.696 -1491.34)" gradientUnits="userSpaceOnUse"/></defs><g style="display:inline;opacity:1" transform="translate(-132.651 958.04)"><path id="d" d="m309.549-710.388 122.197 211.675-56.157.527-32.624-56.87-32.856 56.566-27.903-.011-14.29-24.69 46.81-80.49-33.23-57.826z" style="opacity:1;fill:url(#c);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"/><use xlink:href="#d" width="100%" height="100%" transform="rotate(60 407.112 -715.787)"/><use xlink:href="#d" width="100%" height="100%" transform="rotate(-60 407.312 -715.7)"/><use xlink:href="#d" width="100%" height="100%" transform="rotate(180 407.419 -715.756)"/><path id="f" d="m309.549-710.388 122.197 211.675-56.157.527-32.624-56.87-32.856 56.566-27.903-.011-14.29-24.69 46.81-80.49-33.23-57.826z" style="color:#000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000;solid-opacity:1;fill:url(#e);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"/><use xlink:href="#f" width="100%" height="100%" style="display:inline" transform="rotate(120 407.34 -716.084)"/><use xlink:href="#f" width="100%" height="100%" style="display:inline" transform="rotate(-120 407.288 -715.87)"/></g></svg>

doc/manual/src/glossary.md

@@ -1,24 +1,5 @@
 # Glossary
 
-- [content address]{#gloss-content-address}
-
-  A
-  [*content address*](https://en.wikipedia.org/wiki/Content-addressable_storage)
-  is a secure way to reference immutable data.
-  The reference is calculated directly from the content of the data being referenced, which means the reference is
-  [*tamper proof*](https://en.wikipedia.org/wiki/Tamperproofing)
-  --- variations of the data should always calculate to distinct content addresses.
-
-  For how Nix uses content addresses, see:
-
-    - [Content-Addressing File System Objects](@docroot@/store/file-system-object/content-address.md)
-    - [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md)
-    - [content-addressed derivation](#gloss-content-addressed-derivation)
-
-  Software Heritage's writing on [*Intrinsic and Extrinsic identifiers*](https://www.softwareheritage.org/2020/07/09/intrinsic-vs-extrinsic-identifiers) is also a good introduction to the value of content-addressing over other referencing schemes.
-
-  Besides content addressing, the Nix store also uses [input addressing](#gloss-input-addressed-store-object).
-
 - [derivation]{#gloss-derivation}
 
   A description of a build task. The result of a derivation is a
@@ -105,7 +86,7 @@
 
   [store path]: #gloss-store-path
 
-- [file system object]{#gloss-file-system-object}
+- [file system object]{#gloss-store-object}
 
   The Nix data model for representing simplified file system data.
 
@@ -137,12 +118,9 @@
 
 - [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.
+  A [store object] whose [store path] is determined by its contents.
   This includes derivations, the outputs of [content-addressed derivations](#gloss-content-addressed-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
 
-  See [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md) for details.
-
 - [substitute]{#gloss-substitute}
 
   A substitute is a command invocation stored in the [Nix database] that
@@ -237,20 +215,6 @@
 
   [output path]: #gloss-output-path
 
-- [output closure]{#gloss-output-closure}\
-  The [closure] of an [output path]. It only contains what is [reachable] from the output.
-
-- [deriving path]{#gloss-deriving-path}
-
-  Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
-  This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
-  There are two forms:
-
-  - *constant*: just a [store path]
-    It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
-
-  - *output*: a pair of a [store path] to a [derivation] and an [output] name.
-
 - [deriver]{#gloss-deriver}
 
   The [store derivation] that produced an [output path].
@@ -288,15 +252,13 @@
 
   See [installables](./command-ref/new-cli/nix.md#installables) for [`nix` commands](./command-ref/new-cli/nix.md) (experimental) for details.
 
-- [Nix Archive (NAR)]{#gloss-nar}
+- [NAR]{#gloss-nar}
 
   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`.
 
-  See [Nix Archive](store/file-system-object/content-address.html#serial-nix-archive) for details.
-
 - [`∅`]{#gloss-emtpy-set}
 
   The empty set symbol. In the context of profile history, this denotes a package is not present in a particular version of the profile.
@@ -330,25 +292,6 @@
   [path]: ./language/values.md#type-path
   [attribute name]: ./language/values.md#attribute-set
 
-- [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).
-    <!-- which is sufficient for resolving non-empty URLs -->
-
-  <!--
-    The wording here may look awkward, but it's for these reasons:
-      * "with --expr": it's a flag, and not an option with an accompanying value
-      * "written in": the expression itself must be written as an argument,
-        whereas the more natural "passed as an argument" allows an interpretation
-        where the expression could be passed by file name.
-    -->
-  - 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
-
 - [experimental feature]{#gloss-experimental-feature}
 
   Not yet stabilized functionality guarded by named experimental feature flags.

doc/manual/src/installation/env-variables.md

@@ -53,8 +53,7 @@ ssl-cert-file = /etc/ssl/my-certificate-bundle.crt
 
 The Nix installer has special handling for these proxy-related
 environment variables: `http_proxy`, `https_proxy`, `ftp_proxy`,
-`all_proxy`, `no_proxy`, `HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`,
-`ALL_PROXY`, `NO_PROXY`.
+`no_proxy`, `HTTP_PROXY`, `HTTPS_PROXY`, `FTP_PROXY`, `NO_PROXY`.
 
 If any of these variables are set when running the Nix installer, then
 the installer will create an override file at

doc/manual/src/installation/installing-binary.md

@@ -50,7 +50,7 @@ Supported systems:
 To explicitly instruct the installer to perform a multi-user installation on your system:
 
 ```console
-$ bash <(curl -L https://nixos.org/nix/install) --daemon
+$ curl -L https://nixos.org/nix/install | sh -s -- --daemon
 ```
 
 You can run this under your usual user account or `root`.
@@ -61,7 +61,7 @@ The script will invoke `sudo` as needed.
 To explicitly select a single-user installation on your system:
 
 ```console
-$ bash <(curl -L https://nixos.org/nix/install) --no-daemon
+$ curl -L https://nixos.org/nix/install | sh -s -- --no-daemon
 ```
 
 In a single-user installation, `/nix` is owned by the invoking user.

doc/manual/src/installation/installing-rootless-daemon.md

@@ -0,0 +1,138 @@
+# Using Nix in multi-user mode with a non-root daemon
+
+> Experimental blurb
+
+It is experimentally possible to run Nix in multi-user mode without running the whole daemon as root.
+This is done by delegating the only part that requires root access to a separate daemon, with a much smaller attack surface.
+Because of the need for a second daemon, this makes the setup a bit more complex and isn't yet supported by the installer. It is however possible to set this up manually:
+
+1. Create a new user and group for the daemon:
+    ```sh
+    sudo groupadd nix-daemon
+    sudo useradd --gid nix-daemon --system -c "Nix daemon user" nix-daemon
+    ```
+2. Create `/nix` owned by that user:
+    ```sh
+    sudo mkdir -m 0755 /nix
+    sudo chown nix-daemon:nix-daemon /nix
+    ```
+3. Download a statically-compiled Nix version for bootstrapping
+    ```sh
+    curl -L https://hydra.nixos.org/job/nix/master/buildStatic.x86_64-linux/latest/download-by-type/file/binary-dist -o /tmp/nix-env
+    chmod +x /tmp/nix-env
+    ```
+4. Install a proper Nix and the tracing daemon in the store
+    ```sh
+    export DAEMON_HOME=$(sudo -u nix-daemon mktemp -d)
+    sudo -u nix-daemon HOME="$DAEMON_HOME" \
+        /tmp/nix-env \
+        -f https://github.com/nixos/nix/archive/rootless-daemon.tar.gz \
+        -iA default packages.x86_64-linux.nix-find-roots \
+        --option extra-substituters https://nixos-nix-install-tests.cachix.org \
+        --option extra-trusted-public-keys nixos-nix-install-tests.cachix.org-1:Le57vOUJjOcdzLlbwmZVBuLGoDC+Xg2rQDtmIzALgFU= \
+        --store / \
+        --profile /nix/var/nix/profiles/default
+    sudo -u nix-daemon mkdir -p /nix/var/nix/gc-socket
+    sudo -u nix-daemon rm -rf "$DAEMON_HOME"
+    ```
+5. Move the tracing daemon executable out of the store (as we don't want Nix
+   to own it)
+   ```sh
+   sudo cp /nix/var/nix/profiles/default/bin/nix-find-roots /usr/bin/
+   ```
+6. Install the systemd services for the daemon:
+    ```sh
+    cat <<EOF | sudo tee /etc/systemd/system/nix-daemon.service
+    [Unit]
+    Description=Nix Daemon
+    Documentation=man:nix-daemon https://nixos.org/manual
+    RequiresMountsFor=/nix/store
+    RequiresMountsFor=/nix/var
+    RequiresMountsFor=/nix/var/nix/db
+    ConditionPathIsReadWrite=/nix/var/nix/daemon-socket
+
+    [Service]
+    ExecStart=@/nix/var/nix/profiles/default/bin/nix-daemon nix-daemon --daemon
+    KillMode=process
+    LimitNOFILE=1048576
+    TasksMax=1048576
+    User=nix-daemon
+    Group=nix-daemon
+
+    [Install]
+    WantedBy=multi-user.target
+    EOF
+    ```
+    ```sh
+    cat <<EOF | sudo tee /etc/systemd/system/nix-daemon.socket
+    [Unit]
+    Description=Nix Daemon Socket
+    Before=multi-user.target
+    RequiresMountsFor=/nix/store
+    ConditionPathIsReadWrite=/nix/var/nix/daemon-socket
+
+    [Socket]
+    ListenStream=/nix/var/nix/daemon-socket/socket
+    SocketUser=nix-daemon
+
+    [Install]
+    WantedBy=sockets.target
+    EOF
+    ```
+7. Install the systemd services for the tracing daemon:
+    ```sh
+    cat <<EOF | sudo tee /etc/systemd/system/nix-find-roots.service
+    [Unit]
+    Description=Nix GC tracer daemon
+    RequiresMountsFor=/nix/store
+    RequiresMountsFor=/nix/var
+    ConditionPathIsReadWrite=/nix/var/nix/gc-socket
+    ProcSubset=pid
+
+    [Service]
+    ExecStart=@/usr/bin/nix-find-roots nix-find-roots
+    Type=simple
+    StandardError=journal
+    ProtectSystem=full
+    ReadWritePaths=/nix/var/nix/gc-socket
+    SystemCallFilter=@system-service
+    SystemCallErrorNumber=EPERM
+    PrivateNetwork=true
+    PrivateDevices=true
+    ProtectKernelTunables=true
+
+    [Install]
+    WantedBy=multi-user.target
+    EOF
+    ```
+    ```sh
+    cat <<EOF | sudo tee /etc/systemd/system/nix-find-roots.socket
+    [Unit]
+    Description=Nix Daemon Socket
+    Before=multi-user.target
+    RequiresMountsFor=/nix/store
+    ConditionPathIsReadWrite=/nix/var/nix/gc-socket
+
+    [Socket]
+    ListenStream=/nix/var/nix/gc-socket/socket
+    Accept=false
+
+    [Install]
+    WantedBy=sockets.target
+    EOF
+    ```
+8. Enable the required experimental Nix feature and basic configuration:
+    ```sh
+    sudo mkdir /etc/nix
+    cat <<EOF | sudo tee /etc/nix/nix.conf
+    experimental-features = external-gc-daemon
+    trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+    substituters = https://cache.nixos.org/
+    EOF
+    ```
+9. Start the systemd sockets:
+    ```sh
+    sudo systemctl start nix-daemon.socket
+    sudo systemctl start nix-find-roots.socket
+    ```
+10. Profit

doc/manual/src/installation/uninstall.md

@@ -1,8 +1,16 @@
 # Uninstalling Nix
 
+## Single User
+
+If you have a [single-user installation](./installing-binary.md#single-user-installation) of Nix, uninstall it by running:
+
+```console
+$ rm -rf /nix
+```
+
 ## Multi User
 
-Removing a [multi-user installation](./installing-binary.md#multi-user-installation) depends on the operating system.
+Removing a [multi-user installation](./installing-binary.md#multi-user-installation) of Nix is more involved, and depends on the operating system.
 
 ### Linux
 
@@ -43,15 +51,7 @@ which you may remove.
 
 ### macOS
 
-1. If system-wide shell initialisation files haven't been altered since installing Nix, use the backups made by the installer:
-
-   ```console
-   sudo mv /etc/zshrc.backup-before-nix /etc/zshrc
-   sudo mv /etc/bashrc.backup-before-nix /etc/bashrc
-   sudo mv /etc/bash.bashrc.backup-before-nix /etc/bash.bashrc
-   ```
-
-   Otherwise, edit `/etc/zshrc`, `/etc/bashrc`, and `/etc/bash.bashrc` to remove the lines sourcing `nix-daemon.sh`, which should look like this:
+1. Edit `/etc/zshrc`, `/etc/bashrc`, and `/etc/bash.bashrc` to remove the lines sourcing `nix-daemon.sh`, which should look like this:
 
    ```bash
    # Nix
@@ -61,6 +61,18 @@ which you may remove.
    # End Nix
    ```
 
+   If these files haven't been altered since installing Nix you can simply put
+   the backups back in place:
+
+   ```console
+   sudo mv /etc/zshrc.backup-before-nix /etc/zshrc
+   sudo mv /etc/bashrc.backup-before-nix /etc/bashrc
+   sudo mv /etc/bash.bashrc.backup-before-nix /etc/bash.bashrc
+   ```
+
+   This will stop shells from sourcing the file and bringing everything you
+   installed using Nix in scope.
+
 2. Stop and remove the Nix daemon services:
 
    ```console
@@ -70,7 +82,8 @@ which you may remove.
    sudo rm /Library/LaunchDaemons/org.nixos.darwin-store.plist
    ```
 
-   This stops the Nix daemon and prevents it from being started next time you boot the system.
+   This stops the Nix daemon and prevents it from being started next time you
+   boot the system.
 
 3. Remove the `nixbld` group and the `_nixbuildN` users:
 
@@ -81,42 +94,25 @@ which you may remove.
 
    This will remove all the build users that no longer serve a purpose.
 
-4. Edit fstab using `sudo vifs` to remove the line mounting the Nix Store volume on `/nix`, which looks like
+4. Edit fstab using `sudo vifs` to remove the line mounting the Nix Store
+   volume on `/nix`, which looks like
+   `UUID=<uuid> /nix apfs rw,noauto,nobrowse,suid,owners` or
+   `LABEL=Nix\040Store /nix apfs rw,nobrowse`. This will prevent automatic
+   mounting of the Nix Store volume.
 
-   ```
-   UUID=<uuid> /nix apfs rw,noauto,nobrowse,suid,owners
-   ```
-   or
+5. Edit `/etc/synthetic.conf` to remove the `nix` line. If this is the only
+   line in the file you can remove it entirely, `sudo rm /etc/synthetic.conf`.
+   This will prevent the creation of the empty `/nix` directory to provide a
+   mountpoint for the Nix Store volume.
 
-   ```
-   LABEL=Nix\040Store /nix apfs rw,nobrowse
-   ```
-
-   by setting the cursor on the respective line using the error keys, and pressing `dd`, and then `:wq` to save the file.
-
-   This will prevent automatic mounting of the Nix Store volume.
-
-5. Edit `/etc/synthetic.conf` to remove the `nix` line.
-   If this is the only line in the file you can remove it entirely:
-
-   ```bash
-   if [ -f /etc/synthetic.conf ]; then
-     if [ "$(cat /etc/synthetic.conf)" = "nix" ]; then
-       sudo rm /etc/synthetic.conf
-     else
-       sudo vi /etc/synthetic.conf
-     fi
-   fi
-   ```
-
-   This will prevent the creation of the empty `/nix` directory.
-
-6. Remove the files Nix added to your system, except for the store:
+6. Remove the files Nix added to your system:
 
    ```console
    sudo rm -rf /etc/nix /var/root/.nix-profile /var/root/.nix-defexpr /var/root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
    ```
 
+   This gets rid of any data Nix may have created except for the store which is
+   removed next.
 
 7. Remove the Nix Store volume:
 
@@ -124,32 +120,29 @@ which you may remove.
    sudo diskutil apfs deleteVolume /nix
    ```
 
-   This will remove the Nix Store volume and everything that was added to the store.
+   This will remove the Nix Store volume and everything that was added to the
+   store.
 
-   If the output indicates that the command couldn't remove the volume, you should make sure you don't have an _unmounted_ Nix Store volume.
-   Look for a "Nix Store" volume in the output of the following command:
+   If the output indicates that the command couldn't remove the volume, you should
+   make sure you don't have an _unmounted_ Nix Store volume. Look for a
+   "Nix Store" volume in the output of the following command:
 
    ```console
    diskutil list
    ```
 
-   If you _do_ find a "Nix Store" volume, delete it by running `diskutil deleteVolume` with the store volume's `diskXsY` identifier.
+   If you _do_ see a "Nix Store" volume, delete it by re-running the diskutil
+   deleteVolume command, but replace `/nix` with the store volume's `diskXsY`
+   identifier.
 
 > **Note**
 >
-> After you complete the steps here, you will still have an empty `/nix` directory.
-> This is an expected sign of a successful uninstall.
-> The empty `/nix` directory will disappear the next time you reboot.
+> After you complete the steps here, you will still have an empty `/nix`
+> directory. This is an expected sign of a successful uninstall. The empty
+> `/nix` directory will disappear the next time you reboot.
 >
-> You do not have to reboot to finish uninstalling Nix.
-> The uninstall is complete.
-> macOS (Catalina+) directly controls root directories, and its read-only root will prevent you from manually deleting the empty `/nix` mountpoint.
+> You do not have to reboot to finish uninstalling Nix. The uninstall is
+> complete. macOS (Catalina+) directly controls root directories and its
+> read-only root will prevent you from manually deleting the empty `/nix`
+> mountpoint.
 
-## Single User
-
-To remove a [single-user installation](./installing-binary.md#single-user-installation) of Nix, run:
-
-```console
-$ rm -rf /nix ~/.nix-channels ~/.nix-defexpr ~/.nix-profile
-```
-You might also want to manually remove references to Nix from your `~/.profile`.

doc/manual/src/installation/upgrading.md

@@ -28,7 +28,7 @@ $ sudo su
 ## macOS multi-user
 
 ```console
-$ sudo nix-env --install --file '<nixpkgs>' --attr nix cacert -I nixpkgs=channel:nixpkgs-unstable
+$ sudo nix-env --install --file '<nixpkgs>' --attr nix -I nixpkgs=channel:nixpkgs-unstable
 $ sudo launchctl remove org.nixos.nix-daemon
 $ sudo launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist
 ```

doc/manual/src/language/advanced-attributes.md

@@ -188,49 +188,38 @@ Derivations can declare some infrequently used optional attributes.
     }
     ```
 
-    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 is an adaptation of base-32 encoding.
-    The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings, and the [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
-
-    The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
-    It can currently be `"sha1"`, `"sha256"`, `"sha512"`, or `null`.
-    `outputHashAlgo` can only be `null` when `outputHash` follows the SRI format.
+    The `outputHashAlgo` attribute specifies the hash algorithm used to
+    compute the hash. It can currently be `"sha1"`, `"sha256"` or
+    `"sha512"`.
 
     The `outputHashMode` attribute determines how the hash is computed.
-    It must be one of the following values:
+    It must be one of the following two values:
 
-      - [`"flat"`](@docroot@/store/store-object/content-address.md#method-flat)
+      - `"flat"`\
+        The output must be a non-executable regular file. If it isn’t,
+        the build fails. The hash is simply computed over the contents
+        of that file (so it’s equal to what Unix commands like
+        `sha256sum` or `sha1sum` produce).
 
         This is the default.
 
-      - [`"recursive"` or `"nar"`](@docroot@/store/store-object/content-address.md#method-nix-archive)
+      - `"recursive"`\
+        The hash is computed over the NAR archive dump of the output
+        (i.e., the result of [`nix-store --dump`](@docroot@/command-ref/nix-store/dump.md)). In
+        this case, the output can be anything, including a directory
+        tree.
 
-        > **Compatibility**
-        >
-        > `"recursive"` is the traditional way of indicating this,
-        > and is supported since 2005 (virtually the entire history of Nix).
-        > `"nar"` is more clear, and consistent with other parts of Nix (such as the CLI),
-        > however support for it is only added in Nix version 2.21.
-
-      - [`"text"`](@docroot@/store/store-object/content-address.md#method-text)
-
-        > **Warning**
-        >
-        > The use of this method for derivation outputs is part of the [`dynamic-derivations`][xp-feature-dynamic-derivations] experimental feature.
-
-      - [`"git"`](@docroot@/store/store-object/content-address.md#method-git)
-
-        > **Warning**
-        >
-        > This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
+    The `outputHash` attribute, finally, must be a string containing
+    the hash in either hexadecimal or base-32 notation. (See the
+    [`nix-hash` command](../command-ref/nix-hash.md) for information
+    about converting to and from base-32 notation.)
 
   - [`__contentAddressed`]{#adv-attr-__contentAddressed}
-
     > **Warning**
     > This attribute is part of an [experimental feature](@docroot@/contributing/experimental-features.md).
     >
     > To use this attribute, you must enable the
-    > [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
+    > [`ca-derivations`](@docroot@/contributing/experimental-features.md#xp-feature-ca-derivations) experimental feature.
     > For example, in [nix.conf](../command-ref/conf-file.md) you could add:
     >
     > ```
@@ -310,7 +299,7 @@ Derivations can declare some infrequently used optional attributes.
     [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites),
     the following attributes are available:
 
-    - `maxSize` defines the maximum size of the resulting [store object](@docroot@/store/store-object.md).
+    - `maxSize` defines the maximum size of the resulting [store object](../glossary.md#gloss-store-object).
     - `maxClosureSize` defines the maximum size of the output's closure.
     - `ignoreSelfRefs` controls whether self-references should be considered when
       checking for allowed references/requisites.
@@ -362,7 +351,3 @@ Derivations can declare some infrequently used optional attributes.
   ```
 
   ensures that the derivation can only be built on a machine with the `kvm` feature.
-
-[xp-feature-ca-derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations
-[xp-feature-dynamic-derivations]: @docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations
-[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing

doc/manual/src/language/constructs.md

@@ -402,85 +402,7 @@ establishes the same scope as
 let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...
 ```
 
-Variables coming from outer `with` expressions *are* shadowed:
-
-```nix
-with { a = "outer"; };
-with { a = "inner"; };
-a
-```
-
-Does evaluate to `"inner"`.
-
 ## Comments
 
-- Inline comments start with `#` and run until the end of the line.
-
-  > **Example**
-  >
-  > ```nix
-  > # A number
-  > 2 # Equals 1 + 1
-  > ```
-  >
-  > ```console
-  > 2
-  > ```
-
-- Block comments start with `/*` and run until the next occurrence of `*/`.
-
-  > **Example**
-  >
-  > ```nix
-  > /*
-  > Block comments
-  > can span multiple lines.
-  > */ "hello"
-  > ```
-  >
-  > ```console
-  > "hello"
-  > ```
-
-  This means that block comments cannot be nested.
-
-  > **Example**
-  >
-  > ```nix
-  > /* /* nope */ */ 1
-  > ```
-  >
-  > ```console
-  > error: syntax error, unexpected '*'
-  >
-  >        at «string»:1:15:
-  >
-  >             1| /* /* nope */ *
-  >              |               ^
-  > ```
-
-  Consider escaping nested comments and unescaping them in post-processing.
-
-  > **Example**
-  >
-  > ```nix
-  > /* /* nested *\/ */ 1
-  > ```
-  >
-  > ```console
-  > 1
-  > ```
-
-## Scoping rules
-
-Nix is [statically scoped](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scope), but with multiple scopes and shadowing rules.
-
-* primary scope --- explicitly-bound variables
-  * [`let`](#let-expressions)
-  * [`inherit`](#inheriting-attributes)
-  * function arguments
-
-* secondary scope --- implicitly-bound variables
-  * [`with`](#with-expressions)
-Primary scope takes precedence over secondary scope.
-See [`with`](#with-expressions) for a detailed example.
+Comments can be single-line, started with a `#` character, or
+inline/multi-line, enclosed within `/* ... */`.

doc/manual/src/language/derivations.md

@@ -17,7 +17,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
   A symbolic name for the derivation.
   It is added to the [store path] of the corresponding [store derivation] as well as to its [output paths](@docroot@/glossary.md#gloss-output-path).
 
-  [store path]: @docroot@/store/store-path.md
+  [store path]: @docroot@/glossary.md#gloss-store-path
 
   > **Example**
   >
@@ -141,7 +141,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
 
   By default, a derivation produces a single output called `out`.
   However, derivations can produce multiple outputs.
-  This allows the associated [store objects](@docroot@/store/store-object.md) and their [closures](@docroot@/glossary.md#gloss-closure) to be copied or garbage-collected separately.
+  This allows the associated [store objects](@docroot@/glossary.md#gloss-store-object) and their [closures](@docroot@/glossary.md#gloss-closure) to be copied or garbage-collected separately.
 
   > **Example**
   >

doc/manual/src/language/import-from-derivation.md

@@ -2,9 +2,9 @@
 
 The value of a Nix expression can depend on the contents of a [store object].
 
-[store object]: @docroot@/store/store-object.md
+[store object]: @docroot@/glossary.md#gloss-store-object
 
-Passing an expression `expr` that evaluates to a [store path](@docroot@/store/store-path.md) to any built-in function which reads from the filesystem constitutes Import From Derivation (IFD):
+Passing an expression `expr` that evaluates to a [store path](@docroot@/glossary.md#gloss-store-path) to any built-in function which reads from the filesystem constitutes Import From Derivation (IFD):
 
 - [`import`](./builtins.md#builtins-import)` expr`
 - [`builtins.readFile`](./builtins.md#builtins-readFile)` expr`

doc/manual/src/language/index.md

@@ -1,13 +1,7 @@
 # Nix Language
 
 The Nix language is designed for conveniently creating and composing *derivations* – precise descriptions of how contents of existing files are used to derive new files.
-
-> **Tip**
->
-> These pages are written as a reference.
-> If you are learning Nix, nix.dev has a good [introduction to the Nix language](https://nix.dev/tutorials/nix-language).
-
-The language is:
+It is:
 
 - *domain-specific*
 
@@ -53,7 +47,7 @@ This is an incomplete overview of language features, by example.
   <td>
 
 
-   *Basic values ([primitives](@docroot@/language/values.md#primitives))*
+   *Basic values*
 
 
   </td>
@@ -71,7 +65,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [string](@docroot@/language/values.md#type-string)
+   A string
 
   </td>
  </tr>
@@ -94,18 +88,6 @@ This is an incomplete overview of language features, by example.
 
   </td>
  </tr>
- <tr>
-  <td>
-
-   `# Explanation`
-
-  </td>
-  <td>
-
-   A [comment](@docroot@/language/constructs.md#comments).
-
-  </td>
- </tr>
  <tr>
   <td>
 
@@ -118,7 +100,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [String interpolation](@docroot@/language/string-interpolation.md) (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
+   String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
 
   </td>
  </tr>
@@ -130,7 +112,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Booleans](@docroot@/language/values.md#type-boolean)
+   Booleans
 
   </td>
  </tr>
@@ -142,7 +124,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Null](@docroot@/language/values.md#type-null) value
+   Null value
 
   </td>
  </tr>
@@ -154,7 +136,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   An [integer](@docroot@/language/values.md#type-number)
+   An integer
 
   </td>
  </tr>
@@ -166,7 +148,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [floating point number](@docroot@/language/values.md#type-number)
+   A floating point number
 
   </td>
  </tr>
@@ -178,7 +160,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   An absolute [path](@docroot@/language/values.md#type-path)
+   An absolute path
 
   </td>
  </tr>
@@ -190,7 +172,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [path](@docroot@/language/values.md#type-path) relative to the file containing this Nix expression
+   A path relative to the file containing this Nix expression
 
   </td>
  </tr>
@@ -202,7 +184,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A home [path](@docroot@/language/values.md#type-path). Evaluates to the `"<user's home directory>/.config"`.
+   A home path. Evaluates to the `"<user's home directory>/.config"`.
 
   </td>
  </tr>
@@ -214,7 +196,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [lookup path](@docroot@/language/constructs/lookup-path.md) for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+   Search path for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
 
   </td>
  </tr>
@@ -238,7 +220,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   An [attribute set](@docroot@/language/values.md#attribute-set) with attributes named `x` and `y`
+   A set with attributes named `x` and `y`
 
   </td>
  </tr>
@@ -262,7 +244,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [recursive set](@docroot@/language/constructs.md#recursive-sets), equivalent to `{ x = "foo"; y = "foobar"; }`.
+   A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
 
   </td>
  </tr>
@@ -278,7 +260,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Lists](@docroot@/language/values.md#list) with three elements.
+   Lists with three elements.
 
   </td>
  </tr>
@@ -362,7 +344,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Attribute selection](@docroot@/language/values.md#attribute-set) (evaluates to `1`)
+   Attribute selection (evaluates to `1`)
 
   </td>
  </tr>
@@ -374,7 +356,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Attribute selection](@docroot@/language/values.md#attribute-set) with default (evaluates to `3`)
+   Attribute selection with default (evaluates to `3`)
 
   </td>
  </tr>
@@ -410,7 +392,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Conditional expression](@docroot@/language/constructs.md#conditionals).
+   Conditional expression
 
   </td>
  </tr>
@@ -422,7 +404,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   [Assertion](@docroot@/language/constructs.md#assertions) check (evaluates to `"yes!"`).
+   Assertion check (evaluates to `"yes!"`).
 
   </td>
  </tr>
@@ -434,7 +416,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Variable definition. See [`let`-expressions](@docroot@/language/constructs.md#let-expressions).
+   Variable definition
 
   </td>
  </tr>
@@ -446,44 +428,14 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Add all attributes from the given set to the scope (evaluates to `1`).
-
-   See [`with`-expressions](@docroot@/language/constructs.md#with-expressions) for details and shadowing caveats.
+   Add all attributes from the given set to the scope (evaluates to `1`)
 
   </td>
  </tr>
  <tr>
   <td>
 
-   `inherit pkgs src;`
-
-  </td>
-  <td>
-
-   Adds the variables to the current scope (attribute set or `let` binding).
-   Desugars to `pkgs = pkgs; src = src;`.
-   See [Inheriting attributes](@docroot@/language/constructs.md#inheriting-attributes).
-
-  </td>
- </tr>
- <tr>
-  <td>
-
-   `inherit (pkgs) lib stdenv;`
-
-  </td>
-  <td>
-
-   Adds the attributes, from the attribute set in parentheses, to the current scope (attribute set or `let` binding).
-   Desugars to `lib = pkgs.lib; stdenv = pkgs.stdenv;`.
-   See [Inheriting attributes](@docroot@/language/constructs.md#inheriting-attributes).
-
-  </td>
- </tr>
- <tr>
-  <td>
-
-   *[Functions](@docroot@/language/constructs.md#functions) (lambdas)*
+   *Functions (lambdas)*
 
   </td>
   <td>
@@ -500,7 +452,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [function](@docroot@/language/constructs.md#functions) that expects an integer and returns it increased by 1.
+   A function that expects an integer and returns it increased by 1
 
   </td>
  </tr>
@@ -512,7 +464,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Curried [function](@docroot@/language/constructs.md#functions), equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
+   Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
 
   </td>
  </tr>
@@ -524,7 +476,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [function](@docroot@/language/constructs.md#functions) call (evaluates to 101)
+   A function call (evaluates to 101)
 
   </td>
  </tr>
@@ -536,7 +488,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [function](@docroot@/language/constructs.md#functions) bound to a variable and subsequently called by name (evaluates to 103)
+   A function bound to a variable and subsequently called by name (evaluates to 103)
 
   </td>
  </tr>
@@ -548,7 +500,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y` and concatenates them
+   A function that expects a set with required attributes `x` and `y` and concatenates them
 
   </td>
  </tr>
@@ -560,7 +512,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
+   A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
 
   </td>
  </tr>
@@ -572,7 +524,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y` and ignores any other attributes
+   A function that expects a set with required attributes `x` and `y` and ignores any other attributes
 
   </td>
  </tr>
@@ -586,7 +538,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
+   A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
 
   </td>
  </tr>
@@ -610,8 +562,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Load and return Nix expression in given file.
-   See [import](@docroot@/language/builtins.md#builtins-import).
+   Load and return Nix expression in given file
 
   </td>
  </tr>
@@ -623,8 +574,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`).
-   See [`map`](@docroot@/language/builtins.md#builtins-map).
+   Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
 
   </td>
  </tr>

doc/manual/src/language/operators.md

@@ -128,8 +128,8 @@ The result is a string.
 > The file or directory at *path* must exist and is copied to the [store].
 > The path appears in the result as the corresponding [store path].
 
-[store path]: @docroot@/store/store-path.md
-[store]: @docroot@/glossary.md#gloss-store
+[store path]: ../glossary.md#gloss-store-path
+[store]: ../glossary.md#gloss-store
 
 [String and path concatenation]: #string-and-path-concatenation
 
@@ -141,7 +141,7 @@ The result is a string.
 
 Update [attribute set] *attrset1* with names and values from *attrset2*.
 
-The returned attribute set will have all of the attributes in *attrset1* and *attrset2*.
+The returned attribute set will have of all the attributes in *attrset1* and *attrset2*.
 If an attribute name is present in both, the attribute value from the latter is taken.
 
 [Update]: #update

doc/manual/src/language/string-context.md

@@ -1,134 +0,0 @@
-# String context
-
-> **Note**
->
-> This is an advanced topic.
-> The Nix language is designed to be used without the programmer consciously dealing with string contexts or even knowing what they are.
-
-A string in the Nix language is not just a sequence of characters like strings in other languages.
-It is actually a pair of a sequence of characters and a *string context*.
-The string context is an (unordered) set of *string context elements*.
-
-The purpose of string contexts is to collect non-string values attached to strings via
-[string concatenation](./operators.md#string-concatenation),
-[string interpolation](./string-interpolation.md),
-and similar operations.
-The idea is that a user can combine together values to create a build instructions for derivations without manually keeping track of where they come from.
-Then the Nix language implicitly does that bookkeeping to efficiently obtain the closure of derivation inputs.
-
-> **Note**
->
-> String contexts are *not* explicitly manipulated in idiomatic Nix language code.
-
-String context elements come in different forms:
-
-- [deriving path]{#string-context-element-derived-path}
-
-  A string context element of this type is a [deriving path](@docroot@/glossary.md#gloss-deriving-path).
-  They can be either of type [constant](#string-context-constant) or [output](#string-context-output), which correspond to the types of deriving paths.
-
-  - [Constant string context elements]{#string-context-constant}
-
-    > **Example**
-    >
-    > [`builtins.storePath`] creates a string with a single constant string context element:
-    >
-    > ```nix
-    > builtins.getContext (builtins.storePath "/nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10")
-    > ```
-    > evaluates to
-    > ```nix
-    > {
-    >   "/nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10" = {
-    >     path = true;
-    >   };
-    > }
-    > ```
-
-    [deriving path]: @docroot@/glossary.md#gloss-deriving-path
-    [store path]: @docroot@/glossary.md#gloss-store-path
-    [`builtins.storePath`]: ./builtins.md#builtins-storePath
-
-  - [Output string context elements]{#string-context-output}
-
-    > **Example**
-    >
-    > The behavior of string contexts are best demonstrated with a built-in function that is still experimental: [`builtins.outputOf`].
-    > This example will *not* work with stable Nix!
-    >
-    > ```nix
-    > builtins.getContext
-    >   (builtins.outputOf
-    >     (builtins.storePath "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv")
-    >     "out")
-    > ```
-    > evaluates to
-    > ```nix
-    > {
-    >   "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv" = {
-    >     outputs = [ "out" ];
-    >   };
-    > }
-    > ```
-
-    [`builtins.outputOf`]: ./builtins.md#builtins-outputOf
-
-- [*derivation deep*]{#string-context-element-derivation-deep}
-
-  *derivation deep* is an advanced feature intended to be used with the
-  [`exportReferencesGraph` derivation attribute](./advanced-attributes.html#adv-attr-exportReferencesGraph).
-  A *derivation deep* string context element is a derivation path, and refers to both its outputs and the entire build closure of that derivation:
-  all its outputs, all the other derivations the given derivation depends on, and all the outputs of those.
-
-  > **Example**
-  >
-  > The best way to illustrate *derivation deep* string contexts is with [`builtins.addDrvOutputDependencies`].
-  > Take a regular constant string context element pointing to a derivation, and transform it into a "Derivation deep" string context element.
-  >
-  > ```nix
-  > builtins.getContext
-  >   (builtins.addDrvOutputDependencies
-  >     (builtins.storePath "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv"))
-  > ```
-  > evaluates to
-  > ```nix
-  > {
-  >   "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv" = {
-  >     allOutputs = true;
-  >   };
-  > }
-  > ```
-
-  [`builtins.addDrvOutputDependencies`]: ./builtins.md#builtins-addDrvOutputDependencies
-  [`builtins.unsafeDiscardOutputDependency`]: ./builtins.md#builtins-unsafeDiscardOutputDependency
-
-## Inspecting string contexts
-
-Most basically, [`builtins.hasContext`] will tell whether a string has a non-empty context.
-
-When more granular information is needed, [`builtins.getContext`] can be used.
-It creates an [attribute set] representing the string context, which can be inspected as usual.
-
-[`builtins.hasContext`]: ./builtins.md#builtins-hasContext
-[`builtins.getContext`]: ./builtins.md#builtins-getContext
-[attribute set]: ./values.md#attribute-set
-
-## Clearing string contexts
-
-[`buitins.unsafeDiscardStringContext`](./builtins.md#builtins-unsafeDiscardStringContext) will make a copy of a string, but with an empty string context.
-The returned string can be used in more ways, e.g. by operators that require the string context to be empty.
-The requirement to explicitly discard the string context in such use cases helps ensure that string context elements are not lost by mistake.
-The "unsafe" marker is only there to remind that Nix normally guarantees that dependencies are tracked, whereas the returned string has lost them.
-
-## Constructing string contexts
-
-[`builtins.appendContext`] will create a copy of a string, but with additional string context elements.
-The context is specified explicitly by an [attribute set] in the format that [`builtins.hasContext`] produces.
-A string with arbitrary contexts can be made like this:
-
-1. Create a string with the desired string context elements.
-   (The contents of the string do not matter.)
-2. Dump its context with [`builtins.getContext`].
-3. Combine it with a base string and repeated [`builtins.appendContext`] calls.
-
-[`builtins.appendContext`]: ./builtins.md#builtins-appendContext

doc/manual/src/language/string-interpolation.md

@@ -20,7 +20,7 @@ Rather than writing
 
 (where `freetype` is a [derivation]), you can instead write
 
-[derivation]: @docroot@/glossary.md#gloss-derivation
+[derivation]: ../glossary.md#gloss-derivation
 
 ```nix
 "--with-freetype2-library=${freetype}/lib"
@@ -107,9 +107,9 @@ An expression that is interpolated must evaluate to one of the following:
 
 A string interpolates to itself.
 
-A path in an interpolated expression is first copied into the Nix store, and the resulting string is the [store path] of the newly created [store object](@docroot@/store/store-object.md).
+A path in an interpolated expression is first copied into the Nix store, and the resulting string is the [store path] of the newly created [store object](../glossary.md#gloss-store-object).
 
-[store path]: @docroot@/store/store-path.md
+[store path]: ../glossary.md#gloss-store-path
 
 > **Example**
 >

doc/manual/src/language/values.md

@@ -92,50 +92,39 @@
 
 - <a id="type-path" href="#type-path">Path</a>
 
-  *Paths* are distinct from strings and can be expressed by path literals such as `./builder.sh`.
+  *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
+  least one slash to be recognised as such. For instance, `builder.sh`
+  is not a path: it's parsed as an expression that selects the
+  attribute `sh` from the variable `builder`. If the file name is
+  relative, i.e., if it does not begin with a slash, it is made
+  absolute at parse time relative to the directory of the Nix
+  expression that contained it. For instance, if a Nix expression in
+  `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
+  is `/foo/xyzzy/fnord.nix`.
 
-  Paths are suitable for referring to local files, and are often preferable over strings.
-  - Path values do not contain trailing slashes, `.` and `..`, as they are resolved when evaluating a path literal.
-  - Path literals are automatically resolved relative to their [base directory](@docroot@/glossary.md#gloss-base-directory).
-  - The files referred to by path values are automatically copied into the Nix store when used in a string interpolation or concatenation.
-  - Tooling can recognize path literals and provide additional features, such as autocompletion, refactoring automation and jump-to-file.
+  If the first component of a path is a `~`, it is interpreted as if
+  the rest of the path were relative to the user's home directory.
+  e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
+  whose home directory is `/home/edolstra`.
 
-  A path literal must contain at least one slash to be recognised as such.
-  For instance, `builder.sh` is not a path:
-  it's parsed as an expression that selects the attribute `sh` from the variable `builder`.
+  For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
 
-  Path literals may also refer to absolute paths by starting with a slash.
-
-  > **Note**
-  >
-  > Absolute paths make expressions less portable.
-  > In the case where a function translates a path literal into an absolute path string for a configuration file, it is recommended to write a string literal instead.
-  > This avoids some confusion about whether files at that location will be used during evaluation.
-  > It also avoids unintentional situations where some function might try to copy everything at the location into the store.
-
-  If the first component of a path is a `~`, it is interpreted such that the rest of the path were relative to the user's home directory.
-  For example, `~/foo` would be equivalent to `/home/edolstra/foo` for a user whose home directory is `/home/edolstra`.
-  Path literals that start with `~` are not allowed in [pure](@docroot@/command-ref/conf-file.md#conf-pure-eval) evaluation.
-
-  Paths can be used in [string interpolation] and string concatenation.
-  For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` from the same directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
-
-  Note that the Nix language assumes that all input files will remain _unchanged_ while evaluating a Nix expression.
+  Note that the Nix language assumes that all input files will remain _unchanged_ while  evaluating a Nix expression.
   For example, assume you used a file path in an interpolated string during a `nix repl` session.
-  Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new [store path], since Nix might not re-read the file contents. Use `:r` to reset the repl as needed.
+  Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new [store path], since Nix might not re-read the file contents.
 
-  [store path]: @docroot@/store/store-path.md
+  [store path]: ../glossary.md#gloss-store-path
 
-  Path literals can also include [string interpolation], besides being [interpolated into other expressions].
+  Paths can include [string interpolation] and can themselves be [interpolated in other expressions].
 
-  [interpolated into other expressions]: ./string-interpolation.md#interpolated-expressions
+  [interpolated in other expressions]: ./string-interpolation.md#interpolated-expressions
 
   At least one slash (`/`) must appear *before* any interpolated expression for the result to be recognized as a path.
 
-  `a.${foo}/b.${bar}` is a syntactically valid number division operation.
+  `a.${foo}/b.${bar}` is a syntactically valid division operation.
   `./a.${foo}/b.${bar}` is a path.
 
-  [Lookup path](./constructs/lookup-path.md) literals such as `<nixpkgs>` also resolve to path values.
+  [Lookup paths](./constructs/lookup-path.md) such as `<nixpkgs>` resolve to path values.
 
 - <a id="type-boolean" href="#type-boolean">Boolean</a>
 

doc/manual/src/package-management/copy-closure.md

@@ -0,0 +1,34 @@
+# Copying Closures via SSH
+
+The command `nix-copy-closure` copies a Nix store path along with all
+its dependencies to or from another machine via the SSH protocol. It
+doesn’t copy store paths that are already present on the target machine.
+For example, the following command copies Firefox with all its
+dependencies:
+
+    $ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)
+
+See the [manpage for `nix-copy-closure`](../command-ref/nix-copy-closure.md) for details.
+
+With `nix-store
+--export` and `nix-store --import` you can write the closure of a store
+path (that is, the path and all its dependencies) to a file, and then
+unpack that file into another Nix store. For example,
+
+    $ nix-store --export $(nix-store --query --requisites $(type -p firefox)) > firefox.closure
+
+writes the closure of Firefox to a file. You can then copy this file to
+another machine and install the closure:
+
+    $ nix-store --import < firefox.closure
+
+Any store paths in the closure that are already present in the target
+store are ignored. It is also possible to pipe the export into another
+command, e.g. to copy and install a closure directly to/on another
+machine:
+
+    $ nix-store --export $(nix-store --query --requisites $(type -p firefox)) | bzip2 | \
+        ssh alice@itchy.example.org "bunzip2 | nix-store --import"
+
+However, `nix-copy-closure` is generally more efficient because it only
+copies paths that are not already present in the target Nix store.

doc/manual/src/protocols/json/derivation.md

@@ -18,30 +18,10 @@ is a JSON object with the following fields:
   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 with these fields:
 
-  * `path`:
-    The output path, if it is known in advanced.
-    Otherwise, `null`.
-
-
-  * `method`:
-    For an output which will be [content addresed], a string representing the [method](@docroot@/store/store-object/content-address.md) of content addressing that is chosen.
-    Valid method strings are:
-
-    - [`flat`](@docroot@/store/store-object/content-address.md#method-flat)
-    - [`nar`](@docroot@/store/store-object/content-address.md#method-nix-archive)
-    - [`text`](@docroot@/store/store-object/content-address.md#method-text)
-    - [`git`](@docroot@/store/store-object/content-address.md#method-git)
-
-    Otherwise, `null`.
+  * `path`: The output path.
 
   * `hashAlgo`:
-    For an output which will be [content addresed], the name of the hash algorithm used.
-    Valid algorithm strings are:
-
-    - `md5`
-    - `sha1`
-    - `sha256`
-    - `sha512`
+    For fixed-output derivations, the hashing algorithm (e.g. `sha256`), optionally prefixed by `r:` if `hash` denotes a NAR hash rather than a flat file hash.
 
   * `hash`:
     For fixed-output derivations, the expected content hash in base-16.
@@ -52,8 +32,7 @@ is a JSON object with the following fields:
   > "outputs": {
   >   "out": {
   >     "path": "/nix/store/2543j7c6jn75blc3drf4g5vhb1rhdq29-source",
-  >     "method": "nar",
-  >     "hashAlgo": "sha256",
+  >     "hashAlgo": "r:sha256",
   >     "hash": "6fc80dcc62179dbc12fc0b5881275898f93444833d21b89dfe5f7fbcbb1d0d62"
   >   }
   > }

doc/manual/src/protocols/json/store-object-info.md

@@ -24,45 +24,41 @@ Info about a [store object].
 
   An array of [store paths][store path], possibly including this one.
 
-* `ca`:
+* `ca` (optional):
 
-  If the store object is [content-addressed],
-  this is the content address of this store object's file system object, used to compute its store path.
-  Otherwise (i.e. if it is [input-addressed]), this is `null`.
+  Content address of this store object's file system object, used to compute its store path.
 
-[store path]: @docroot@/store/store-path.md
+[store path]: @docroot@/glossary.md#gloss-store-path
 [file system object]: @docroot@/store/file-system-object.md
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
+[Nix Archive]: @docroot@/glossary.md#gloss-nar
 
 ## Impure fields
 
 These are not intrinsic properties of the store object.
 In other words, the same store object residing in different store could have different values for these properties.
 
-* `deriver`:
+* `deriver` (optional):
 
-  If known, the path to the [derivation] from which this store object was produced.
-  Otherwise `null`.
+  The path to the [derivation] from which this store object is produced.
 
   [derivation]: @docroot@/glossary.md#gloss-store-derivation
 
 * `registrationTime` (optional):
 
-  If known, when this derivation was added to the store.
-  Otherwise `null`.
+  When this derivation was added to the store.
 
-* `ultimate`:
+* `ultimate` (optional):
 
   Whether this store object is trusted because we built it ourselves, rather than substituted a build product from elsewhere.
 
-* `signatures`:
+* `signatures` (optional):
 
   Signatures claiming that this store object is what it claims to be.
   Not relevant for [content-addressed] store objects,
   but useful for [input-addressed] store objects.
 
-[content-addressed]: @docroot@/store/store-object/content-address.md
-[input-addressed]: @docroot@/glossary.md#gloss-input-addressed-store-object
+  [content-addressed]: @docroot@/glossary.md#gloss-content-addressed-store-object
+  [input-addressed]: @docroot@/glossary.md#gloss-input-addressed-store-object
 
 ### `.narinfo` extra fields
 
@@ -87,7 +83,7 @@ This information is not intrinsic to the store object, but about how it is store
 
 ## Computed closure fields
 
-These fields are not stored at all, but computed by traversing the other fields across all the store objects in a [closure].
+These fields are not stored at all, but computed by traverising the other other fields across all the store objects in a [closure].
 
 * `closureSize`:
 

doc/manual/src/protocols/nix-archive.md

@@ -1,43 +0,0 @@
-# Nix Archive (NAR) format
-
-This is the complete specification of the [Nix Archive] format.
-The Nix Archive format closely follows the abstract specification of a [file system object] tree,
-because it is designed to serialize exactly that data structure.
-
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#nix-archive
-[file system object]: @docroot@/store/file-system-object.md
-
-The format of this specification is close to [Extended Backus–Naur form](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form), with the exception of the `str(..)` function / parameterized rule, which length-prefixes and pads strings.
-This makes the resulting binary format easier to parse.
-
-Regular users do *not* need to know this information.
-But for those interested in exactly how Nix works, e.g. if they are reimplementing it, this information can be useful.
-
-```ebnf
-nar = str("nix-archive-1"), nar-obj;
-
-nar-obj = str("("), nar-obj-inner, str(")");
-
-nar-obj-inner
-  = str("type"), str("regular") regular
-  | str("type"), str("symlink") symlink
-  | str("type"), str("directory") directory
-  ;
-
-regular = [ str("executable"), str("") ], str("contents"), str(contents);
-
-symlink = str("target"), str(target);
-
-(* side condition: directory entries must be ordered by their names *)
-directory = str("type"), str("directory") { directory-entry };
-
-directory-entry = str("entry"), str("("), str("name"), str(name), str("node"), nar-obj, str(")");
-```
-
-The `str` function / parameterized rule is defined as follows:
-
-- `str(s)` = `int(|s|), pad(s);`
-
-- `int(n)` = the 64-bit little endian representation of the number `n`
-
-- `pad(s)` = the byte sequence `s`, padded with 0s to a multiple of 8 byte

doc/manual/src/protocols/store-path.md

@@ -1,14 +1,12 @@
 # Complete Store Path Calculation
 
-This is the complete specification for how [store path]s are calculated.
+This is the complete specification for how store paths are calculated.
 
 The format of this specification is close to [Extended Backus–Naur form](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form), but must deviate for a few things such as hash functions which we treat as bidirectional for specification purposes.
 
 Regular users do *not* need to know this information --- store paths can be treated as black boxes computed from the properties of the store objects they refer to.
 But for those interested in exactly how Nix works, e.g. if they are reimplementing it, this information can be useful.
 
-[store path](@docroot@/store/store-path.md)
-
 ## Store path proper
 
 ```ebnf
@@ -36,23 +34,18 @@ where
 - `type` = one of:
 
   - ```ebnf
-    | "text" { ":" store-path }
+    | "text" ( ":" store-path )*
     ```
 
-    This is for the
-    ["Text"](@docroot@/store/store-object/content-address.md#method-text)
-    method of content addressing store objects.
+    for encoded derivations written to the store.
     The optional trailing store paths are the references of the store object.
 
   - ```ebnf
-    | "source" { ":" store-path } [ ":self" ]
+    | "source" ( ":" store-path )*
     ```
 
-    This is for the
-    ["Nix Archive"](@docroot@/store/store-object/content-address.md#method-nix-archive)
-    method of content addressing store objects,
-    if the hash algorithm is [SHA-256].
-    Just like in the "Text" case, we can have the store objects referenced by their paths.
+    For paths copied to the store and hashed via a [Nix Archive (NAR)] and [SHA-256][sha-256].
+    Just like in the text case, we can have the store objects referenced by their paths.
     Additionally, we can have an optional `:self` label to denote self reference.
 
   - ```ebnf
@@ -60,12 +53,8 @@ where
     ```
 
     For either the outputs built from derivations,
-    or content-addressed store objects that are not using one of the two above cases.
-    To be explicit about the latter, that is currently these methods:
-
-    - ["Flat"](@docroot@/store/store-object/content-address.md#method-flat)
-    - ["Git"](@docroot@/store/store-object/content-address.md#method-git)
-    - ["Nix Archive"](@docroot@/store/store-object/content-address.md#method-nix-archive) if the hash algorithm is not [SHA-256].
+    paths copied to the store hashed that area single file hashed directly, or the via a hash algorithm other than [SHA-256][sha-256].
+    (in that case "source" is used; this is only necessary for compatibility).
 
     `id` is the name of the output (usually, "out").
     For content-addressed store objects, `id`, is always "out".
@@ -100,20 +89,15 @@ where
 
       - `rec` = one of:
 
-        - ```ebnf
-          | ""
-          ```
-          (empty string) for hashes of the flat (single file) serialization
-
         - ```ebnf
           | "r:"
           ```
           hashes of the for [Nix Archive (NAR)] (arbitrary file system object) serialization
 
         - ```ebnf
-          | "git:"
+          | ""
           ```
-          hashes of the [Git blob/tree](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) [Merkel tree](https://en.wikipedia.org/wiki/Merkle_tree) format
+          (empty string) for hashes of the flat (single file) serialization
 
       - ```ebnf
         algo = "md5" | "sha1" | "sha256"
@@ -124,8 +108,8 @@ where
       Note that `id` = `"out"`, regardless of the name part of the store path.
       Also note that NAR + SHA-256 must not use this case, and instead must use the `type` = `"source:" ...` case.
 
-[Nix Archive (NAR)]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive
-[SHA-256]: https://en.m.wikipedia.org/wiki/SHA-256
+[Nix Archive (NAR)]: @docroot@/glossary.md#gloss-NAR
+[sha-256]: https://en.m.wikipedia.org/wiki/SHA-256
 
 ### Historical Note
 

doc/manual/src/protocols/tarball-fetcher.md

@@ -22,7 +22,7 @@ Link: <flakeref>; rel="immutable"
 
 *flakeref* must be a tarball flakeref. It can contain the tarball flake attributes
 `narHash`, `rev`, `revCount` and `lastModified`. If `narHash` is included, its
-value must be the [NAR hash][Nix Archive] of the unpacked tarball (as computed via
+value must be the NAR hash of the unpacked tarball (as computed via
 `nix hash path`). Nix checks the contents of the returned tarball
 against the `narHash` attribute. The `rev` and `revCount` attributes
 are useful when the tarball flake is a mirror of a fetcher type that
@@ -40,5 +40,3 @@ Link: <https://example.org/hello/442793d9ec0584f6a6e82fa253850c8085bb150a.tar.gz
 
 For tarball flakes, the value of the `lastModified` flake attribute is
 defined as the timestamp of the newest file inside the tarball.
-
-[Nix Archive]: @docroot@/store/file-system-object/content-address.md#serial-nix-archive

doc/manual/src/quick-start.md

@@ -34,7 +34,7 @@ For more in-depth information you are kindly referred to subsequent chapters.
    lolcat: command not found
    ```
 
-1. Search for more packages on [search.nixos.org](https://search.nixos.org/) to try them out.
+1. Search for more packages on <search.nixos.org> to try them out.
 
 1. Free up storage space:
 

doc/manual/src/release-notes/index.md

@@ -1,13 +1,12 @@
 # Nix Release Notes
 
-The Nix release cycle is calendar-based as follows:
-
 Nix has a release cycle of roughly 6 weeks.
 Notable changes and additions are announced in the release notes for each version.
 
-The supported Nix versions are:
-- The latest release
-- The version used in the stable NixOS release, which is announced in the [NixOS release notes](https://nixos.org/manual/nixos/stable/release-notes.html#ch-release-notes).
+Bugfixes can be backported on request to previous Nix releases.
+We typically backport only as far back as the Nix version used in the latest NixOS release, which is announced in the [NixOS release notes](https://nixos.org/manual/nixos/stable/release-notes.html#ch-release-notes).
+
+Backports never skip releases.
+If a feature is backported to version `x.y`, it must also be available in version `x.(y+1)`.
+This ensures that upgrading from an older version with backports is still safe and no backported functionality will go missing.
 
-Bugfixes and security issues are backported to every supported version.
-Patch releases are published as needed.

doc/manual/src/release-notes/rl-2.15.md

@@ -11,7 +11,7 @@
   As the choice of hash formats is no longer binary, the `--base16` flag is also added
   to explicitly specify the Base16 format, which is still the default.
 
-* The special handling of an [installable](../command-ref/new-cli/nix.md#installables) with `.drv` suffix being interpreted as all of the given [store derivation](@docroot@/glossary.md#gloss-store-derivation)'s output paths is removed, and instead taken as the literal store path that it represents.
+* The special handling of an [installable](../command-ref/new-cli/nix.md#installables) with `.drv` suffix being interpreted as all of the given [store derivation](../glossary.md#gloss-store-derivation)'s output paths is removed, and instead taken as the literal store path that it represents.
 
   The new `^` syntax for store paths introduced in Nix 2.13 allows explicitly referencing output paths of a derivation.
   Using this is better and more clear than relying on the now-removed `.drv` special handling.

doc/manual/src/release-notes/rl-2.20.md

@@ -200,9 +200,3 @@
   while performing various operations (including `nix develop`, `nix flake
   update`, and so on). With several fixes to Nix's signal handlers, Nix
   commands will now exit quickly after Ctrl-C is pressed.
-
-- `nix copy` to a `ssh-ng` store now needs `--substitute-on-destination` (a.k.a. `-s`)
-  in order to substitute paths on the remote store instead of copying them.
-  The behavior is consistent with `nix copy` to a different kind of remote store.
-  Previously this behavior was controlled by the
-  `builders-use-substitutes` setting and `--substitute-on-destination` was ignored.

doc/manual/src/release-notes/rl-2.21.md

@@ -1,302 +0,0 @@
-# Release 2.21.0 (2024-03-11)
-
-- Fix a fixed-output derivation sandbox escape (CVE-2024-27297)
-
-  Cooperating Nix derivations could send file descriptors to files in the Nix
-  store to each other via Unix domain sockets in the abstract namespace. This
-  allowed one derivation to modify the output of the other derivation, after Nix
-  has registered the path as "valid" and immutable in the Nix database.
-  In particular, this allowed the output of fixed-output derivations to be
-  modified from their expected content.
-
-  This isn't the case any more.
-
-- CLI options `--arg-from-file` and `--arg-from-stdin` [#10122](https://github.com/NixOS/nix/pull/10122)
-
-  The new CLI option `--arg-from-file` *name* *path* passes the contents
-  of file *path* as a string value via the function argument *name* to a
-  Nix expression. Similarly, the new option `--arg-from-stdin` *name*
-  reads the contents of the string from standard input.
-
-- Concise error printing in `nix repl` [#9928](https://github.com/NixOS/nix/pull/9928)
-
-  Previously, if an element of a list or attribute set threw an error while
-  evaluating, `nix repl` would print the entire error (including source location
-  information) inline. This output was clumsy and difficult to parse:
-
-  ```
-  nix-repl> { err = builtins.throw "uh oh!"; }
-  { err = «error:
-         … while calling the 'throw' builtin
-           at «string»:1:9:
-              1| { err = builtins.throw "uh oh!"; }
-               |         ^
-
-         error: uh oh!»; }
-  ```
-
-  Now, only the error message is displayed, making the output much more readable.
-  ```
-  nix-repl> { err = builtins.throw "uh oh!"; }
-  { err = «error: uh oh!»; }
-  ```
-
-  However, if the whole expression being evaluated throws an error, source
-  locations and (if applicable) a stack trace are printed, just like you'd expect:
-
-  ```
-  nix-repl> builtins.throw "uh oh!"
-  error:
-         … while calling the 'throw' builtin
-           at «string»:1:1:
-              1| builtins.throw "uh oh!"
-               | ^
-
-         error: uh oh!
-  ```
-
-- `--debugger` can now access bindings from `let` expressions [#8827](https://github.com/NixOS/nix/issues/8827) [#9918](https://github.com/NixOS/nix/pull/9918)
-
-  Breakpoints and errors in the bindings of a `let` expression can now access
-  those bindings in the debugger. Previously, only the body of `let` expressions
-  could access those bindings.
-
-- Enter the `--debugger` when `builtins.trace` is called if `debugger-on-trace` is set [#9914](https://github.com/NixOS/nix/pull/9914)
-
-  If the `debugger-on-trace` option is set and `--debugger` is given,
-  `builtins.trace` calls will behave similarly to `builtins.break` and will enter
-  the debug REPL. This is useful for determining where warnings are being emitted
-  from.
-
-- Debugger prints source position information [#9913](https://github.com/NixOS/nix/pull/9913)
-
-  The `--debugger` now prints source location information, instead of the
-  pointers of source location information. Before:
-
-  ```
-  nix-repl> :bt
-  0: while evaluating the attribute 'python311.pythonForBuild.pkgs'
-  0x600001522598
-  ```
-
-  After:
-
-  ```
-  0: while evaluating the attribute 'python311.pythonForBuild.pkgs'
-  /nix/store/hg65h51xnp74ikahns9hyf3py5mlbbqq-source/overrides/default.nix:132:27
-
-     131|
-     132|       bootstrappingBase = pkgs.${self.python.pythonAttr}.pythonForBuild.pkgs;
-        |                           ^
-     133|     in
-  ```
-
-- The `--debugger` will start more reliably in `let` expressions and function calls [#6649](https://github.com/NixOS/nix/issues/6649) [#9917](https://github.com/NixOS/nix/pull/9917)
-
-  Previously, if you attempted to evaluate this file with the debugger:
-
-  ```nix
-  let
-    a = builtins.trace "before inner break" (
-      builtins.break "hello"
-    );
-    b = builtins.trace "before outer break" (
-      builtins.break a
-    );
-  in
-    b
-  ```
-
-  Nix would correctly enter the debugger at `builtins.break a`, but if you asked
-  it to `:continue`, it would skip over the `builtins.break "hello"` expression
-  entirely.
-
-  Now, Nix will correctly enter the debugger at both breakpoints.
-
-- Nested debuggers are no longer supported [#9920](https://github.com/NixOS/nix/pull/9920)
-
-  Previously, evaluating an expression that throws an error in the debugger would
-  enter a second, nested debugger:
-
-  ```
-  nix-repl> builtins.throw "what"
-  error: what
-
-
-  Starting REPL to allow you to inspect the current state of the evaluator.
-
-  Welcome to Nix 2.18.1. Type :? for help.
-
-  nix-repl>
-  ```
-
-  Now, it just prints the error message like `nix repl`:
-
-  ```
-  nix-repl> builtins.throw "what"
-  error:
-         … while calling the 'throw' builtin
-           at «string»:1:1:
-              1| builtins.throw "what"
-               | ^
-
-         error: what
-  ```
-
-- Consistent order of function arguments in printed expressions [#9874](https://github.com/NixOS/nix/pull/9874)
-
-  Function arguments are now printed in lexicographic order rather than the internal, creation-time based symbol order.
-
-- Fix duplicate attribute error positions for `inherit` [#9874](https://github.com/NixOS/nix/pull/9874)
-
-  When an `inherit` caused a duplicate attribute error the position of the error was not reported correctly, placing the error with the inherit itself or at the start of the bindings block instead of the offending attribute name.
-
-- `inherit (x) ...` evaluates `x` only once [#9847](https://github.com/NixOS/nix/pull/9847)
-
-  `inherit (x) a b ...` now evaluates the expression `x` only once for all inherited attributes rather than once for each inherited attribute.
-  This does not usually have a measurable impact, but side-effects (such as `builtins.trace`) would be duplicated and expensive expressions (such as derivations) could cause a measurable slowdown.
-
-- Store paths are allowed to start with `.` [#912](https://github.com/NixOS/nix/issues/912) [#9091](https://github.com/NixOS/nix/pull/9091) [#9095](https://github.com/NixOS/nix/pull/9095) [#9120](https://github.com/NixOS/nix/pull/9120) [#9121](https://github.com/NixOS/nix/pull/9121) [#9122](https://github.com/NixOS/nix/pull/9122) [#9130](https://github.com/NixOS/nix/pull/9130) [#9219](https://github.com/NixOS/nix/pull/9219) [#9224](https://github.com/NixOS/nix/pull/9224) [#9867](https://github.com/NixOS/nix/pull/9867)
-
-  Leading periods were allowed by accident in Nix 2.4. The Nix team has considered this to be a bug, but this behavior has since been relied on by users, leading to unnecessary difficulties.
-  From now on, leading periods are supported. The names `.` and `..` are disallowed, as well as those starting with `.-` or `..-`.
-
-  Nix versions that denied leading periods are documented [in the issue](https://github.com/NixOS/nix/issues/912#issuecomment-1919583286).
-
-- `nix repl` pretty-prints values [#9931](https://github.com/NixOS/nix/pull/9931)
-
-  `nix repl` will now pretty-print values:
-
-  ```
-  {
-    attrs = {
-      a = {
-        b = {
-          c = { };
-        };
-      };
-    };
-    list = [ 1 ];
-    list' = [
-      1
-      2
-      3
-    ];
-  }
-  ```
-
-- Introduction of `--regex` and `--all` in `nix profile remove` and `nix profile upgrade` [#10166](https://github.com/NixOS/nix/pull/10166)
-
-  Previously the command-line arguments for `nix profile remove` and `nix profile upgrade` matched the package entries using regular expression.
-  For instance:
-
-  ```
-  nix profile remove '.*vim.*'
-  ```
-
-  This would remove all packages that contain `vim` in their name.
-
-  In most cases, only singular package names were used to remove and upgrade packages. Mixing this with regular expressions sometimes lead to unintended behavior. For instance, `python3.1` could match `python311`.
-
-  To avoid unintended behavior, the arguments are now only matching exact names.
-
-  Matching using regular expressions is still possible by using the new `--regex` flag:
-
-  ```
-  nix profile remove --regex '.*vim.*'
-  ```
-
-  One of the most useful cases for using regular expressions was to upgrade all packages. This was previously accomplished by:
-
-  ```
-  nix profile upgrade '.*'
-  ```
-
-  With the introduction of the `--all` flag, this now becomes more straightforward:
-
-  ```
-  nix profile upgrade --all
-  ```
-
-- Visual clutter in `--debugger` is reduced [#9919](https://github.com/NixOS/nix/pull/9919)
-
-  Before:
-  ```
-  info: breakpoint reached
-
-
-  Starting REPL to allow you to inspect the current state of the evaluator.
-
-  Welcome to Nix 2.20.0pre20231222_dirty. Type :? for help.
-
-  nix-repl> :continue
-  error: uh oh
-
-
-  Starting REPL to allow you to inspect the current state of the evaluator.
-
-  Welcome to Nix 2.20.0pre20231222_dirty. Type :? for help.
-
-  nix-repl>
-  ```
-
-  After:
-
-  ```
-  info: breakpoint reached
-
-  Nix 2.20.0pre20231222_dirty debugger
-  Type :? for help.
-  nix-repl> :continue
-  error: uh oh
-
-  nix-repl>
-  ```
-
-- Cycle detection in `nix repl` is simpler and more reliable [#8672](https://github.com/NixOS/nix/issues/8672) [#9926](https://github.com/NixOS/nix/pull/9926)
-
-  The cycle detection in `nix repl`, `nix eval`, `builtins.trace`, and everywhere
-  else values are printed is now simpler and matches the cycle detection in
-  `nix-instantiate --eval` output.
-
-  Before:
-
-  ```
-  nix eval --expr 'let self = { inherit self; }; in self'
-  { self = { self = «repeated»; }; }
-  ```
-
-  After:
-
-  ```
-  { self = «repeated»; }
-  ```
-
-- In the debugger, `while evaluating the attribute` errors now include position information [#9915](https://github.com/NixOS/nix/pull/9915)
-
-  Before:
-
-  ```
-  0: while evaluating the attribute 'python311.pythonForBuild.pkgs'
-  0x600001522598
-  ```
-
-  After:
-
-  ```
-  0: while evaluating the attribute 'python311.pythonForBuild.pkgs'
-  /nix/store/hg65h51xnp74ikahns9hyf3py5mlbbqq-source/overrides/default.nix:132:27
-
-     131|
-     132|       bootstrappingBase = pkgs.${self.python.pythonAttr}.pythonForBuild.pkgs;
-        |                           ^
-     133|     in
-  ```
-
-- Stack size is increased on macOS [#9860](https://github.com/NixOS/nix/pull/9860)
-
-  Previously, Nix would set the stack size to 64MiB on Linux, but would leave the
-  stack size set to the default (approximately 8KiB) on macOS. Now, the stack
-  size is correctly set to 64MiB on macOS as well, which should reduce stack
-  overflow segfaults in deeply-recursive Nix expressions.
-

doc/manual/src/release-notes/rl-2.22.md

@@ -1,21 +0,0 @@
-# Release 2.22.0 (2024-04-23)
-
-### Significant changes
-
-- Remove experimental repl-flake [#10103](https://github.com/NixOS/nix/issues/10103) [#10299](https://github.com/NixOS/nix/pull/10299)
-
-  The `repl-flake` experimental feature has been removed. The `nix repl` command now works like the rest of the new CLI in that `nix repl {path}` now tries to load a flake at `{path}` (or fails if the `flakes` experimental feature isn't enabled).
-
-### Other changes
-
-- `nix eval` prints derivations as `.drv` paths [#10200](https://github.com/NixOS/nix/pull/10200)
-
-  `nix eval` will now print derivations as their `.drv` paths, rather than as
-  attribute sets. This makes commands like `nix eval nixpkgs#bash` terminate
-  instead of infinitely looping into recursive self-referential attributes:
-
-  ```ShellSession
-  $ nix eval nixpkgs#bash
-  «derivation /nix/store/m32cbgbd598f4w299g0hwyv7gbw6rqcg-bash-5.2p26.drv»
-  ```
-

doc/manual/src/release-notes/rl-2.23.md

@@ -1,102 +0,0 @@
-# Release 2.23.0 (2024-06-03)
-
-- New builtin: `builtins.warn` [#306026](https://github.com/NixOS/nix/issues/306026) [#10592](https://github.com/NixOS/nix/pull/10592)
-
-  `builtins.warn` behaves like `builtins.trace "warning: ${msg}"`, has an accurate log level, and is controlled by the options
-  [`debugger-on-trace`](@docroot@/command-ref/conf-file.md#conf-debugger-on-trace),
-  [`debugger-on-warn`](@docroot@/command-ref/conf-file.md#conf-debugger-on-warn) and
-  [`abort-on-warn`](@docroot@/command-ref/conf-file.md#conf-abort-on-warn).
-
-- Make `nix build --keep-going` consistent with `nix-build --keep-going`
-
-  This means that if e.g. multiple fixed-output derivations fail to
-  build, all hash mismatches are displayed.
-
-- 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@/contributing/cli-guideline.md#returning-future-proof-json).
-  In particular, the hash algorithm and content addressing method of content-addresed derivation outputs are now separated into two fields `hashAlgo` and `method`,
-  rather than one field with an arcane `:`-separated format.
-
-  This JSON format is only used by the experimental `nix derivation` family of commands, at this time.
-  Future revisions are expected as the JSON format is still not entirely in compliance even after these changes.
-
-- Warn on unknown settings anywhere in the command line [#10701](https://github.com/NixOS/nix/pull/10701)
-
-  All `nix` commands will now properly warn when an unknown option is specified anywhere in the command line.
-
-  Before:
-
-  ```console
-  $ nix-instantiate --option foobar baz --expr '{}'
-  warning: unknown setting 'foobar'
-  $ nix-instantiate '{}' --option foobar baz --expr
-  $ nix eval --expr '{}' --option foobar baz
-  { }
-  ```
-
-  After:
-
-  ```console
-  $ nix-instantiate --option foobar baz --expr '{}'
-  warning: unknown setting 'foobar'
-  $ nix-instantiate '{}' --option foobar baz --expr
-  warning: unknown setting 'foobar'
-  $ nix eval --expr '{}' --option foobar baz
-  warning: unknown setting 'foobar'
-  { }
-  ```
-
-- `nix env shell` is the new `nix shell`, and `nix shell` remains an accepted alias [#10504](https://github.com/NixOS/nix/issues/10504) [#10807](https://github.com/NixOS/nix/pull/10807)
-
-  This is part of an effort to bring more structure to the CLI subcommands.
-
-  `nix env` will be about the process environment.
-  Future commands may include `nix env run` and `nix env print-env`.
-
-  It is also somewhat analogous to the [planned](https://github.com/NixOS/nix/issues/10504) `nix dev shell` (currently `nix develop`), which is less about environment variables, and more about running a development shell, which is a more powerful command, but also requires more setup.
-
-- Flake operations that expect derivations now print the failing value and its type [#10778](https://github.com/NixOS/nix/pull/10778)
-
-  In errors like `flake output attribute 'nixosConfigurations.yuki.config' is not a derivation or path`, the message now includes the failing value and type.
-
-  Before:
-
-  ```
-  error: flake output attribute 'nixosConfigurations.yuki.config' is not a derivation or path
-  ````
-
-  After:
-
-  ```
-  error: expected flake output attribute 'nixosConfigurations.yuki.config' to be a derivation or path but found a set: { appstream = «thunk»; assertions = «thunk»; boot = { bcache = «thunk»; binfmt = «thunk»; binfmtMiscRegistrations = «thunk»; blacklistedKernelModules = «thunk»; bootMount = «thunk»; bootspec = «thunk»; cleanTmpDir = «thunk»; consoleLogLevel = «thunk»; «43 attributes elided» }; «48 attributes elided» }
-  ```
-
-- `fetchTree` now fetches Git repositories shallowly by default [#10028](https://github.com/NixOS/nix/pull/10028)
-
-  `builtins.fetchTree` now clones Git repositories shallowly by default, which reduces network traffic and disk usage significantly in many cases.
-
-  Previously, the default behavior was to clone the full history of a specific tag or branch (e.g. `ref`) and only afterwards extract the files of one specific revision.
-
-  From now on, the `ref` and `allRefs` arguments will be ignored, except if shallow cloning is disabled by setting `shallow = false`.
-
-  The defaults for `builtins.fetchGit` remain unchanged. Here, shallow cloning has to be enabled manually by passing `shallow = true`.
-
-- Store object info JSON format now uses `null` rather than omitting fields [#9995](https://github.com/NixOS/nix/pull/9995)
-
-  The [store object info JSON format](@docroot@/protocols/json/store-object-info.md), used for e.g. `nix path-info`, no longer omits fields to indicate absent information, but instead includes the fields with a `null` value.
-  For example, `"ca": null` is used to to indicate a store object that isn't content-addressed rather than omitting the `ca` field entirely.
-  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@/contributing/json-guideline.md) in the contributing section have been updated accordingly.
-
-- Large path warnings [#10661](https://github.com/NixOS/nix/pull/10661)
-
-  Nix can now warn when evaluation of a Nix expression causes a large
-  path to be copied to the Nix store. The threshold for this warning can
-  be configured using [the `warn-large-path-threshold`
-  setting](@docroot@/command-ref/conf-file.md#warn-large-path-threshold),
-  e.g. `--warn-large-path-threshold 100M` will warn about paths larger
-  than 100 MiB.
-

doc/manual/src/store/file-system-object/content-address.md

@@ -1,85 +0,0 @@
-# Content-Addressing File System Objects
-
-For many operations, Nix needs to calculate [a content addresses](@docroot@/glossary.md#gloss-content-address) of [a file system object][file system object].
-Usually this is needed as part of
-[content addressing store objects](../store-object/content-address.md),
-since store objects always have a root file system object.
-But some command-line utilities also just work on "raw" file system objects, not part of any store object.
-
-Every content addressing scheme Nix uses ultimately involves feeding data into a [hash function](https://en.wikipedia.org/wiki/Hash_function), and getting back an opaque fixed-size digest which is deemed a content address.
-The various *methods* of content addressing thus differ in how abstract data (in this case, a file system object and its descendents) are fed into the hash function.
-
-## Serialising File System Objects { #serial }
-
-The simplest method is to serialise the entire file system object tree into a single binary string, and then hash that binary string, yielding the content address.
-In this section we describe the currently-supported methods of serialising file system objects.
-
-### Flat { #serial-flat }
-
-A single file object can just be hashed by its contents.
-This is not enough information to encode the fact that the file system object is a file,
-but if we *already* know that the FSO is a single non-executable file by other means, it is sufficient.
-
-Because the hashed data is just the raw file, as is, this choice is good for compatibility with other systems.
-For example, Unix commands like `sha256sum` or `sha1sum` will produce hashes for single files that match this.
-
-### Nix Archive (NAR) { #serial-nix-archive }
-
-For the other cases of [file system objects][file system object], especially directories with arbitrary descendents, we need a more complex serialisation format.
-Examples of such serialisations are the ZIP and TAR file formats.
-However, for our purposes these formats have two problems:
-
-- They do not have a canonical serialisation, meaning that given an FSO, there can
-be many different serialisations.
-  For instance, TAR files can have variable amounts of padding between archive members;
-  and some archive formats leave the order of directory entries undefined.
-  This would be bad because we use serialisation to compute cryptographic hashes over file system objects, and for those hashes to be useful as a content address or for integrity checking, uniqueness is crucial.
-  Otherwise, correct hashes would report false mismatches, and the store would fail to find the content.
-
-- They store more information than we have in our notion of FSOs, such as time stamps.
-  This can cause FSOs that Nix should consider equal to hash to different values on different machines, just because the dates differ.
-
-- As a practical consideration, the TAR format is the only truly universal format in the Unix environment.
-  It has many problems, such as an inability to deal with long file names and files larger than 2^33 bytes.
-  Current implementations such as GNU Tar work around these limitations in various ways.
-
-For these reasons, Nix has its very own archive format—the Nix Archive (NAR) format,
-which is carefully designed to avoid the problems described above.
-
-The exact specification of the Nix Archive format is in `protocols/nix-archive.md`
-
-## Content addressing File System Objects beyond a single serialisation pass
-
-Serialising the entire tree and then hashing that binary string is not the only option for content addressing, however.
-Another technique is that of a [Merkle graph](https://en.wikipedia.org/wiki/Merkle_tree), where previously computed hashes are included in subsequent byte strings to be hashed.
-
-In particular, the Merkle graphs can match the original graph structure of file system objects:
-we can first hash (serialised) child file system objects, and then hash parent objects using the hashes of their children in the serialisation (to be hashed) of the parent file system objects.
-
-Currently, there is one such Merkle DAG content addressing method supported.
-
-### Git ([experimental][xp-feature-git-hashing]) { #git }
-
-> **Warning**
->
-> This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
-
-Git's file system model is very close to Nix's, and so Git's content addressing method is a pretty good fit.
-Just as with regular Git, files and symlinks are hashed as git "blobs", and directories are hashed as git "trees".
-
-However, one difference between Nix's and Git's file system model needs special treatment.
-Plain files, executable files, and symlinks are not differentiated as distinctly addressable objects, but by their context: by the directory entry that refers to them.
-That means so long as the root object is a directory, there is no problem:
-every non-directory object is owned by a parent directory, and the entry that refers to it provides the missing information.
-However, if the root object is not a directory, then we have no way of knowing which one of an executable file, non-executable file, or symlink it is supposed to be.
-
-In response to this, we have decided to treat a bare file as non-executable file.
-This is similar to do what we do with [flat serialisation](#serial-flat), which also lacks this information.
-To avoid an address collision, attempts to hash a bare executable file or symlink will result in an error (just as would happen for flat serialisation also).
-Thus, Git can encode some, but not all of Nix's "File System Objects", and this sort of content-addressing is likewise partial.
-
-In the future, we may support a Git-like hash for such file system objects, or we may adopt another Merkle DAG format which is capable of representing all Nix file system objects.
-
-[file system object]: ../file-system-object.md
-[store object]: ../store-object.md
-[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing

doc/manual/src/store/store-object/content-address.md

@@ -1,95 +0,0 @@
-# Content-Addressing Store Objects
-
-Just [like][fso-ca] [File System Objects][File System Object],
-[Store Objects][Store Object] can also be [content-addressed](@docroot@/glossary.md#gloss-content-addressed),
-unless they are [input-addressed](@docroot@/glossary.md#gloss-input-addressed-store-object).
-
-For store objects, the content address we produce will take the form of a [Store Path] rather than regular hash.
-In particular, the content-addressing scheme will ensure that the digest of the store path is solely computed from the
-
-- file system object graph (the root one and its children, if it has any)
-- references
-- [store directory](../store-path.md#store-directory)
-- name
-
-of the store object, and not any other information, which would not be an intrinsic property of that store object.
-
-For the full specification of the algorithms involved, see the [specification of store path digests][sp-spec].
-
-[File System Object]: ../file-system-object.md
-[Store Object]: ../store-object.md
-[Store Path]: ../store-path.md
-
-## Content addressing each part of a store object
-
-### File System Objects
-
-With all currently supported store object content addressing methods, the file system object is always [content-addressed][fso-ca] first, and then that hash is incorporated into content address computation for the store object.
-
-### References
-
-With all currently supported store object content addressing methods,
-other objects are referred to by their regular (string-encoded-) [store paths][Store Path].
-
-Self-references however cannot be referred to by their path, because we are in the midst of describing how to compute that path!
-
-> The alternative would require finding as hash function fixed point, i.e. the solution to an equation in the form
-> ```
-> digest = hash(..... || digest || ....)
-> ```
-> which is computationally infeasible.
-> As far as we know, this is equivalent to finding a hash collision.
-
-Instead we just have a "has self reference" boolean, which will end up affecting the digest.
-
-### Name and Store Directory
-
-These two items affect the digest in a way that is standard for store path digest computations and not specific to content-addressing.
-Consult the [specification of store path digests][sp-spec] for further details.
-
-## Content addressing Methods
-
-For historical reasons, we don't support all features in all combinations.
-Each currently supported method of content addressing chooses a single method of file system object hashing, and may offer some restrictions on references.
-The names and store directories are unrestricted however.
-
-### Flat { #method-flat }
-
-This uses the corresponding [Flat](../file-system-object/content-address.md#serial-flat) method of file system object content addressing.
-
-References are not supported: store objects with flat hashing *and* references can not be created.
-
-### Text { #method-text }
-
-This also uses the corresponding [Flat](../file-system-object/content-address.md#serial-flat) method of file system object content addressing.
-
-References to other store objects are supported, but self references are not.
-
-This is the only store-object content-addressing method that is not named identically with a corresponding file system object method.
-It is somewhat obscure, mainly used for "drv files"
-(derivations serialized as store objects in their ["ATerm" file format](@docroot@/protocols/derivation-aterm.md)).
-Prefer another method if possible.
-
-### Nix Archive { #method-nix-archive }
-
-This uses the corresponding [Nix Archive](../file-system-object/content-address.md#serial-nix-archive) method of file system object content addressing.
-
-References (to other store objects and self references alike) are supported so long as the hash algorithm is SHA-256, but not (neither kind) otherwise.
-
-### Git { #method-git }
-
-> **Warning**
->
-> This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
-
-This uses the corresponding [Git](../file-system-object/content-address.md#serial-git) method of file system object content addressing.
-
-References are not supported.
-
-Only SHA-1 is supported at this time.
-If [SHA-256-based Git](https://git-scm.com/docs/hash-function-transition)
-becomes more widespread, this restriction will be revisited.
-
-[fso-ca]: ../file-system-object/content-address.md
-[sp-spec]: @docroot@/protocols/store-path.md
-[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing

doc/manual/src/store/store-path.md

@@ -1,11 +1,5 @@
 # Store Path
 
-> **Example**
->
-> `/nix/store/a040m110amc4h71lds2jmr8qrkj2jhxd-git-2.38.1`
->
-> A rendered store path
-
 Nix implements references to [store objects](./index.md#store-object) as *store paths*.
 
 Think of a store path as an [opaque], [unique identifier]:
@@ -43,10 +37,6 @@ A store path is rendered to a file system path as the concatenation of
 > store directory            digest                 name
 > ```
 
-Exactly how the digest is calculated depends on the type of store path.
-Store path digests are *supposed* to be opaque, and so for most operations, it is not necessary to know the details.
-That said, the manual has a full [specification of store path digests](@docroot@/protocols/store-path.md).
-
 ## Store Directory
 
 Every [Nix store](./index.md) has a store directory.
@@ -56,7 +46,7 @@ But if the store has a file system representation, the store directory contains
 
 [file system objects]: ./file-system-object.md
 
-This means a store path is not just derived from the referenced store object itself, but depends on the store that the store object is in.
+This means a store path is not just derived from the referenced store object itself, but depends on the store the store object is in.
 
 > **Note**
 >

flake.lock

@@ -16,41 +16,6 @@
         "type": "github"
       }
     },
-    "flake-parts": {
-      "inputs": {
-        "nixpkgs-lib": [
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1712014858,
-        "narHash": "sha256-sB4SWl2lX95bExY2gMFG5HIzvva5AVMJd4Igm+GpZNw=",
-        "owner": "hercules-ci",
-        "repo": "flake-parts",
-        "rev": "9126214d0a59633752a136528f5f3b9aa8565b7d",
-        "type": "github"
-      },
-      "original": {
-        "owner": "hercules-ci",
-        "repo": "flake-parts",
-        "type": "github"
-      }
-    },
-    "flake-utils": {
-      "locked": {
-        "lastModified": 1667395993,
-        "narHash": "sha256-nuEHfE/LcWyuSWnS8t12N1wc105Qtau+/OdUAjtQ0rA=",
-        "owner": "numtide",
-        "repo": "flake-utils",
-        "rev": "5aed5285a952e0b949eb3ba02c12fa4fcfef535f",
-        "type": "github"
-      },
-      "original": {
-        "owner": "numtide",
-        "repo": "flake-utils",
-        "type": "github"
-      }
-    },
     "libgit2": {
       "flake": false,
       "locked": {
@@ -69,16 +34,16 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1709083642,
-        "narHash": "sha256-7kkJQd4rZ+vFrzWu8sTRtta5D1kBG0LSRYAfhtmMlSo=",
+        "lastModified": 1705033721,
+        "narHash": "sha256-K5eJHmL1/kev6WuqyqqbS1cdNnSidIZ3jeqJ7GbrYnQ=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "b550fe4b4776908ac2a861124307045f8e717c8e",
+        "rev": "a1982c92d8980a0114372973cbdfe0a307f1bdea",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "release-23.11",
+        "ref": "nixos-23.05-small",
         "repo": "nixpkgs",
         "type": "github"
       }
@@ -99,40 +64,12 @@
         "type": "github"
       }
     },
-    "pre-commit-hooks": {
-      "inputs": {
-        "flake-compat": [],
-        "flake-utils": "flake-utils",
-        "gitignore": [],
-        "nixpkgs": [
-          "nixpkgs"
-        ],
-        "nixpkgs-stable": [
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1712897695,
-        "narHash": "sha256-nMirxrGteNAl9sWiOhoN5tIHyjBbVi5e2tgZUgZlK3Y=",
-        "owner": "cachix",
-        "repo": "pre-commit-hooks.nix",
-        "rev": "40e6053ecb65fcbf12863338a6dcefb3f55f1bf8",
-        "type": "github"
-      },
-      "original": {
-        "owner": "cachix",
-        "repo": "pre-commit-hooks.nix",
-        "type": "github"
-      }
-    },
     "root": {
       "inputs": {
         "flake-compat": "flake-compat",
-        "flake-parts": "flake-parts",
         "libgit2": "libgit2",
         "nixpkgs": "nixpkgs",
-        "nixpkgs-regression": "nixpkgs-regression",
-        "pre-commit-hooks": "pre-commit-hooks"
+        "nixpkgs-regression": "nixpkgs-regression"
       }
     }
   },