Merge pull request #7921 from NixOS/backport-7920-to-2.14-maintenance

[Backport 2.14-maintenance] nix-profile{,-daemon}.sh.in: Allow XDG_STATE_HOME to be unset

.github/CODEOWNERS

@@ -0,0 +1,18 @@
+# Pull requests concerning the listed files will automatically invite the respective maintainers as reviewers.
+# This file is not used for denoting any kind of ownership, but is merely a tool for handling notifications.
+#
+# Merge permissions are required for maintaining an entry in this file.
+# For documentation on this mechanism, see https://help.github.com/articles/about-codeowners/
+
+# Default reviewers if nothing else matches
+* @edolstra
+
+# This file
+.github/CODEOWNERS @edolstra
+
+# Public documentation
+/doc @fricklerhandwerk
+*.md @fricklerhandwerk
+
+# Libstore layer
+/src/libstore @thufschmitt

.github/ISSUE_TEMPLATE/bug_report.md

@@ -30,3 +30,7 @@ A clear and concise description of what you expected to happen.
 **Additional context**
 
 Add any other context about the problem here.
+
+**Priorities**
+
+Add :+1: to [issues you find important](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc).

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: ''
-labels: improvement
+labels: feature
 assignees: ''
 
 ---
@@ -18,3 +18,7 @@ A clear and concise description of any alternative solutions or features you've
 
 **Additional context**
 Add any other context or screenshots about the feature request here.
+
+**Priorities**
+
+Add :+1: to [issues you find important](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc).

.github/ISSUE_TEMPLATE/installer.md

@@ -0,0 +1,36 @@
+---
+name: Installer issue
+about: Report problems with installation
+title: ''
+labels: installer
+assignees: ''
+
+---
+
+## Platform
+
+<!-- select the platform on which you tried to install Nix -->
+
+- [ ] Linux: <!-- state your distribution, e.g. Arch Linux, Ubuntu, ... -->
+- [ ] macOS
+- [ ] WSL
+
+## Additional information
+
+<!-- state special circumstances on your system or additional steps you have taken prior to installation -->
+
+## Output
+
+<details><summary>Output</summary>
+
+```log
+
+<!-- paste console output here and remove this comment -->
+
+```
+
+</details>
+
+## Priorities
+
+Add :+1: to [issues you find important](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc).

.github/ISSUE_TEMPLATE/missing_documentation.md

@@ -0,0 +1,31 @@
+---
+name: Missing or incorrect documentation
+about: Help us improve the reference manual
+title: ''
+labels: documentation
+assignees: ''
+
+---
+
+## Problem
+
+<!-- describe your problem -->
+
+## Checklist
+
+<!-- make sure this issue is not redundant or obsolete -->
+
+- [ ] checked [latest Nix manual] \([source])
+- [ ] checked [open documentation issues and pull requests] for possible duplicates
+
+[latest Nix manual]: https://nixos.org/manual/nix/unstable/
+[source]: https://github.com/NixOS/nix/tree/master/doc/manual/src
+[open documentation issues and pull requests]: https://github.com/NixOS/nix/labels/documentation
+
+## Proposal
+
+<!-- propose a solution -->
+
+## Priorities
+
+Add :+1: to [issues you find important](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc).

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+# Motivation
+<!-- Briefly explain what the change is about and why it is desirable. -->
+
+# Context
+<!-- Provide context. Reference open issues if available. -->
+
+<!-- Non-trivial change: Briefly outline the implementation strategy. -->
+
+<!-- Invasive change: Discuss alternative designs or approaches you considered. -->
+
+<!-- Large change: Provide instructions to reviewers how to read the diff. -->
+
+# Checklist for maintainers
+
+<!-- Contributors: please leave this as is -->
+
+Maintainers: tick if completed or explain if not relevant
+
+ - [ ] agreed on idea
+ - [ ] agreed on implementation strategy
+ - [ ] tests, as appropriate
+   - functional tests - `tests/**.sh`
+   - unit tests - `src/*/tests`
+   - integration tests - `tests/nixos/*`
+ - [ ] documentation in the manual
+ - [ ] code and comments are self-explanatory
+ - [ ] commit message explains why the change was made
+ - [ ] new feature or incompatible change: updated release notes

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -5,3 +5,7 @@ Please include relevant [release notes](https://github.com/NixOS/nix/blob/master
 **Testing**
 
 If this issue is a regression or something that should block release, please consider including a test either in the [testsuite](https://github.com/NixOS/nix/tree/master/tests) or as a [hydraJob]( https://github.com/NixOS/nix/blob/master/flake.nix#L396) so that it can be part of the [automatic checks](https://hydra.nixos.org/jobset/nix/master).
+
+**Priorities**
+
+Add :+1: to [pull requests you find important](https://github.com/NixOS/nix/pulls?q=is%3Aopen+sort%3Areactions-%2B1-desc).

.github/workflows/backport.yml

@@ -2,9 +2,15 @@ name: Backport
 on:
   pull_request_target:
     types: [closed, labeled]
+permissions:
+  contents: read
 jobs:
   backport:
     name: Backport Pull Request
+    permissions:
+      # for zeebe-io/backport-action
+      contents: write
+      pull-requests: write
     if: github.repository_owner == 'NixOS' && github.event.pull_request.merged == true && (github.event_name != 'labeled' || startsWith('backport', github.event.label.name))
     runs-on: ubuntu-latest
     steps:
@@ -15,12 +21,12 @@ jobs:
           fetch-depth: 0
       - name: Create backport PRs
         # should be kept in sync with `version`
-        uses: zeebe-io/backport-action@v0.0.8
+        uses: zeebe-io/backport-action@v1.2.0
         with:
           # Config README: https://github.com/zeebe-io/backport-action#backport-action
           github_token: ${{ secrets.GITHUB_TOKEN }}
           github_workspace: ${{ github.workspace }}
           pull_description: |-
-            Bot-based backport to `${target_branch}`, triggered by a label in #${pull_number}.
+            Automatic backport to `${target_branch}`, triggered by a label in #${pull_number}.
           # should be kept in sync with `uses`
           version: v0.0.5

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ permissions: read-all
 jobs:
 
   tests:
-    needs: [check_cachix]
+    needs: [check_secrets]
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
@@ -19,33 +19,39 @@ jobs:
     - uses: actions/checkout@v3
       with:
         fetch-depth: 0
-    - uses: cachix/install-nix-action@v17
+    - uses: cachix/install-nix-action@v19
+      with:
+        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
-    - uses: cachix/cachix-action@v10
-      if: needs.check_cachix.outputs.secret == 'true'
+    - uses: cachix/cachix-action@v12
+      if: needs.check_secrets.outputs.cachix == 'true'
       with:
         name: '${{ env.CACHIX_NAME }}'
         signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
         authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
     - run: nix --experimental-features 'nix-command flakes' flake check -L
 
-  check_cachix:
+  check_secrets:
     permissions:
       contents: none
-    name: Cachix secret present for installer tests
+    name: Check Cachix and Docker secrets present for installer tests
     runs-on: ubuntu-latest
     outputs:
-      secret: ${{ steps.secret.outputs.secret }}
+      cachix: ${{ steps.secret.outputs.cachix }}
+      docker: ${{ steps.secret.outputs.docker }}
     steps:
-      - name: Check for Cachix secret
+      - name: Check for secrets
         id: secret
         env:
           _CACHIX_SECRETS: ${{ secrets.CACHIX_SIGNING_KEY }}${{ secrets.CACHIX_AUTH_TOKEN }}
-        run: echo "::set-output name=secret::${{ env._CACHIX_SECRETS != '' }}"
+          _DOCKER_SECRETS: ${{ secrets.DOCKERHUB_USERNAME }}${{ secrets.DOCKERHUB_TOKEN }}
+        run: |
+          echo "::set-output name=cachix::${{ env._CACHIX_SECRETS != '' }}"
+          echo "::set-output name=docker::${{ env._DOCKER_SECRETS != '' }}"
 
   installer:
-    needs: [tests, check_cachix]
-    if: github.event_name == 'push' && needs.check_cachix.outputs.secret == 'true'
+    needs: [tests, check_secrets]
+    if: github.event_name == 'push' && needs.check_secrets.outputs.cachix == 'true'
     runs-on: ubuntu-latest
     outputs:
       installerURL: ${{ steps.prepare-installer.outputs.installerURL }}
@@ -54,8 +60,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@v17
-    - uses: cachix/cachix-action@v10
+    - uses: cachix/install-nix-action@v19
+      with:
+        install_url: https://releases.nixos.org/nix/nix-2.13.3/install
+    - uses: cachix/cachix-action@v12
       with:
         name: '${{ env.CACHIX_NAME }}'
         signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
@@ -64,8 +72,8 @@ jobs:
       run: scripts/prepare-installer-for-github-actions
 
   installer_test:
-    needs: [installer, check_cachix]
-    if: github.event_name == 'push' && needs.check_cachix.outputs.secret == 'true'
+    needs: [installer, check_secrets]
+    if: github.event_name == 'push' && needs.check_secrets.outputs.cachix == 'true'
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
@@ -73,28 +81,38 @@ jobs:
     steps:
     - uses: actions/checkout@v3
     - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
-    - uses: cachix/install-nix-action@v17
+    - uses: cachix/install-nix-action@v19
       with:
         install_url: '${{needs.installer.outputs.installerURL}}'
         install_options: "--tarball-url-prefix https://${{ env.CACHIX_NAME }}.cachix.org/serve"
-    - run: nix-instantiate -E 'builtins.currentTime' --eval
+    - run: sudo apt install fish zsh
+      if: matrix.os == 'ubuntu-latest'
+    - run: brew install fish
+      if: matrix.os == 'macos-latest'
+    - run: exec bash -c "nix-instantiate -E 'builtins.currentTime' --eval"
+    - run: exec sh -c "nix-instantiate -E 'builtins.currentTime' --eval"
+    - run: exec zsh -c "nix-instantiate -E 'builtins.currentTime' --eval"
+    - run: exec fish -c "nix-instantiate -E 'builtins.currentTime' --eval"
 
   docker_push_image:
-    needs: [check_cachix, tests]
+    needs: [check_secrets, tests]
     if: >-
       github.event_name == 'push' &&
       github.ref_name == 'master' &&
-      needs.check_cachix.outputs.secret == 'true'
+      needs.check_secrets.outputs.cachix == 'true' &&
+      needs.check_secrets.outputs.docker == 'true'
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
       with:
         fetch-depth: 0
-    - uses: cachix/install-nix-action@v17
+    - uses: cachix/install-nix-action@v19
+      with:
+        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@v10
-      if: needs.check_cachix.outputs.secret == 'true'
+    - uses: cachix/cachix-action@v12
+      if: needs.check_secrets.outputs.cachix == 'true'
       with:
         name: '${{ env.CACHIX_NAME }}'
         signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'

.gitignore

@@ -27,6 +27,8 @@ perl/Makefile.config
 # /scripts/
 /scripts/nix-profile.sh
 /scripts/nix-profile-daemon.sh
+/scripts/nix-profile.fish
+/scripts/nix-profile-daemon.fish
 
 # /src/libexpr/
 /src/libexpr/lexer-tab.cc
@@ -35,14 +37,14 @@ perl/Makefile.config
 /src/libexpr/parser-tab.hh
 /src/libexpr/parser-tab.output
 /src/libexpr/nix.tbl
-/src/libexpr/tests/libexpr-tests
+/src/libexpr/tests/libnixexpr-tests
 
 # /src/libstore/
 *.gen.*
-/src/libstore/tests/libstore-tests
+/src/libstore/tests/libnixstore-tests
 
 # /src/libutil/
-/src/libutil/tests/libutil-tests
+/src/libutil/tests/libnixutil-tests
 
 /src/nix/nix
 
@@ -73,7 +75,7 @@ perl/Makefile.config
 
 # /tests/
 /tests/test-tmp
-/tests/common.sh
+/tests/common/vars-and-functions.sh
 /tests/result*
 /tests/restricted-innocent
 /tests/shell
@@ -101,6 +103,7 @@ outputs/
 
 *.a
 *.o
+*.o.tmp
 *.so
 *.dylib
 *.dll

.version

@@ -1 +1 @@
-2.11.0
+2.14.1

Makefile

@@ -36,4 +36,4 @@ endif
 
 include mk/lib.mk
 
-GLOBAL_CXXFLAGS += -g -Wall -include config.h -std=c++17 -I src
+GLOBAL_CXXFLAGS += -g -Wall -include config.h -std=c++2a -I src

README.md

@@ -20,8 +20,8 @@ Information on additional installation methods is available on the [Nix download
 
 ## Building And Developing
 
-See our [Hacking guide](https://nixos.org/manual/nix/stable/contributing/hacking.html) in our manual for instruction on how to
-build nix from source with nix-build or how to get a development environment.
+See our [Hacking guide](https://nixos.org/manual/nix/unstable/contributing/hacking.html) in our manual for instruction on how to
+to set up a development environment and build Nix from source.
 
 ## Additional Resources
 

boehmgc-coroutine-sp-fallback.diff

@@ -1,17 +1,49 @@
+diff --git a/darwin_stop_world.c b/darwin_stop_world.c
+index 3dbaa3fb..36a1d1f7 100644
+--- a/darwin_stop_world.c
++++ b/darwin_stop_world.c
+@@ -352,6 +352,7 @@ GC_INNER void GC_push_all_stacks(void)
+   int nthreads = 0;
+   word total_size = 0;
+   mach_msg_type_number_t listcount = (mach_msg_type_number_t)THREAD_TABLE_SZ;
++  size_t stack_limit;
+   if (!EXPECT(GC_thr_initialized, TRUE))
+     GC_thr_init();
+ 
+@@ -407,6 +408,19 @@ GC_INNER void GC_push_all_stacks(void)
+             GC_push_all_stack_sections(lo, hi, p->traced_stack_sect);
+           }
+           if (altstack_lo) {
++            // When a thread goes into a coroutine, we lose its original sp until
++            // control flow returns to the thread.
++            // While in the coroutine, the sp points outside the thread stack,
++            // so we can detect this and push the entire thread stack instead,
++            // as an approximation.
++            // We assume that the coroutine has similarly added its entire stack.
++            // This could be made accurate by cooperating with the application
++            // via new functions and/or callbacks.
++            stack_limit = pthread_get_stacksize_np(p->id);
++            if (altstack_lo >= altstack_hi || altstack_lo < altstack_hi - stack_limit) { // sp outside stack
++              altstack_lo = altstack_hi - stack_limit;
++            }
++
+             total_size += altstack_hi - altstack_lo;
+             GC_push_all_stack(altstack_lo, altstack_hi);
+           }
 diff --git a/pthread_stop_world.c b/pthread_stop_world.c
-index 4b2c429..1fb4c52 100644
+index b5d71e62..aed7b0bf 100644
 --- a/pthread_stop_world.c
 +++ b/pthread_stop_world.c
-@@ -673,6 +673,8 @@ GC_INNER void GC_push_all_stacks(void)
-     struct GC_traced_stack_sect_s *traced_stack_sect;
-     pthread_t self = pthread_self();
-     word total_size = 0;
+@@ -768,6 +768,8 @@ STATIC void GC_restart_handler(int sig)
+ /* world is stopped.  Should not fail if it isn't.                      */
+ GC_INNER void GC_push_all_stacks(void)
+ {
 +    size_t stack_limit;
 +    pthread_attr_t pattr;
- 
-     if (!EXPECT(GC_thr_initialized, TRUE))
-       GC_thr_init();
-@@ -722,6 +724,31 @@ GC_INNER void GC_push_all_stacks(void)
+     GC_bool found_me = FALSE;
+     size_t nthreads = 0;
+     int i;
+@@ -851,6 +853,31 @@ GC_INNER void GC_push_all_stacks(void)
            hi = p->altstack + p->altstack_size;
            /* FIXME: Need to scan the normal stack too, but how ? */
            /* FIXME: Assume stack grows down */

configure.ac

@@ -41,8 +41,6 @@ AC_DEFINE_UNQUOTED(SYSTEM, ["$system"], [platform identifier ('cpu-os')])
 test "$localstatedir" = '${prefix}/var' && localstatedir=/nix/var
 
 
-CFLAGS=
-CXXFLAGS=
 AC_PROG_CC
 AC_PROG_CXX
 AC_PROG_CPP
@@ -177,7 +175,7 @@ fi
 PKG_CHECK_MODULES([OPENSSL], [libcrypto], [CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"])
 
 
-# Checks for libarchive
+# Look for libarchive.
 PKG_CHECK_MODULES([LIBARCHIVE], [libarchive >= 3.1.2], [CXXFLAGS="$LIBARCHIVE_CFLAGS $CXXFLAGS"])
 # Workaround until https://github.com/libarchive/libarchive/issues/1446 is fixed
 if test "$shared" != yes; then
@@ -276,6 +274,15 @@ fi
 PKG_CHECK_MODULES([GTEST], [gtest_main])
 
 
+# Look for rapidcheck.
+# No pkg-config yet, https://github.com/emil-e/rapidcheck/issues/302
+AC_LANG_PUSH(C++)
+AC_CHECK_HEADERS([rapidcheck/gtest.h], [], [], [#include <gtest/gtest.h>])
+dnl No good for C++ libs with mangled symbols
+dnl AC_CHECK_LIB([rapidcheck], [])
+AC_LANG_POP(C++)
+
+
 # Look for nlohmann/json.
 PKG_CHECK_MODULES([NLOHMANN_JSON], [nlohmann_json >= 3.9])
 

doc/manual/book.toml

@@ -1,7 +1,21 @@
+[book]
+title = "Nix Reference Manual"
+
 [output.html]
 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"
 
 [preprocessor.anchors]
 renderers = ["html"]
 command = "jq --from-file doc/manual/anchors.jq"
+
+[output.linkcheck]
+# no Internet during the build (in the sandbox)
+follow-web-links = false
+
+# mdbook-linkcheck does not understand [foo]{#bar} style links, resulting in
+# excessive "Potential incomplete link" warnings. No other kind of warning was
+# produced at the time of writing.
+warning-policy = "ignore"

doc/manual/custom.css

@@ -5,3 +5,7 @@ h1:not(:first-of-type) {
 h2 {
     margin-top: 1em;
 }
+
+.hljs-meta {
+    user-select: none;
+}

doc/manual/generate-builtins.nix

@@ -1,16 +1,20 @@
-with builtins;
-with import ./utils.nix;
+builtinsDump:
+let
+  showBuiltin = name:
+    let
+      inherit (builtinsDump.${name}) doc args;
+    in
+    ''
+      <dt id="builtins-${name}">
+        <a href="#builtins-${name}"><code>${name} ${listArgs args}</code></a>
+      </dt>
+      <dd>
 
-builtins:
+        ${doc}
+
+      </dd>
+    '';
+  listArgs = args: builtins.concatStringsSep " " (map (s: "<var>${s}</var>") args);
+in
+with builtins; concatStringsSep "\n" (map showBuiltin (attrNames builtinsDump))
 
-concatStrings (map
-  (name:
-    let builtin = builtins.${name}; in
-    "<dt id=\"builtins-${name}\"><a href=\"#builtins-${name}\"><code>${name} "
-    + concatStringsSep " " (map (s: "<var>${s}</var>") builtin.args)
-    + "</code></a></dt>"
-    + "<dd>\n\n"
-    + builtin.doc
-    + "\n\n</dd>"
-  )
-  (attrNames builtins))

doc/manual/generate-manpage.nix

@@ -1,99 +1,115 @@
-{ command, renderLinks ? false }:
+{ toplevel }:
 
 with builtins;
 with import ./utils.nix;
 
 let
 
-  showCommand =
-    { command, def, filename }:
-    ''
-      **Warning**: This program is **experimental** and its interface is subject to change.
-    ''
-    + "# Name\n\n"
-    + "`${command}` - ${def.description}\n\n"
-    + "# Synopsis\n\n"
-    + showSynopsis { inherit command; args = def.args; }
-    + (if def.commands or {} != {}
-       then
-         let
-           categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands)));
-           listCommands = cmds:
-             concatStrings (map (name:
-               "* "
-               + (if renderLinks
-                  then "[`${command} ${name}`](./${appendName filename name}.md)"
-                  else "`${command} ${name}`")
-               + " - ${cmds.${name}.description}\n")
-               (attrNames cmds));
-         in
-         "where *subcommand* is one of the following:\n\n"
-         # FIXME: group by category
-         + (if length categories > 1
-            then
-              concatStrings (map
-                (cat:
-                  "**${toString cat.description}:**\n\n"
-                  + listCommands (filterAttrs (n: v: v.category == cat) def.commands)
-                  + "\n"
-                ) categories)
-              + "\n"
-            else
-              listCommands def.commands
-              + "\n")
-       else "")
-    + (if def ? doc
-       then def.doc + "\n\n"
-       else "")
-    + (let s = showOptions def.flags; in
-       if s != ""
-       then "# Options\n\n${s}"
-       else "")
-  ;
+  showCommand = { command, details, filename, toplevel }:
+    let
+      result = ''
+        > **Warning** \
+        > This program is **experimental** and its interface is subject to change.
+
+        # Name
+
+        `${command}` - ${details.description}
+
+        # Synopsis
+
+        ${showSynopsis command details.args}
+
+        ${maybeSubcommands}
+
+        ${maybeDocumentation}
+
+        ${maybeOptions}
+      '';
+      showSynopsis = command: args:
+        let
+          showArgument = arg: "*${arg.label}*" + (if arg ? arity then "" else "...");
+          arguments = concatStringsSep " " (map showArgument args);
+        in ''
+         `${command}` [*option*...] ${arguments}
+        '';
+      maybeSubcommands = if details ? commands && details.commands != {}
+        then ''
+           where *subcommand* is one of the following:
+
+           ${subcommands}
+         ''
+        else "";
+      subcommands = if length categories > 1
+        then listCategories
+        else listSubcommands details.commands;
+      categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands)));
+      listCategories = concatStrings (map showCategory categories);
+      showCategory = cat: ''
+        **${toString cat.description}:**
+
+        ${listSubcommands (filterAttrs (n: v: v.category == cat) details.commands)}
+      '';
+      listSubcommands = cmds: concatStrings (attrValues (mapAttrs showSubcommand cmds));
+      showSubcommand = name: subcmd: ''
+        * [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
+      '';
+      maybeDocumentation = if details ? doc then details.doc else "";
+      maybeOptions = if details.flags == {} then "" else ''
+        # Options
+
+        ${showOptions details.flags toplevel.flags}
+      '';
+      showOptions = options: commonOptions:
+        let
+          allOptions = options // commonOptions;
+          showCategory = cat: ''
+            ${if cat != "" then "**${cat}:**" else ""}
+
+            ${listOptions (filterAttrs (n: v: v.category == cat) allOptions)}
+            '';
+          listOptions = opts: concatStringsSep "\n" (attrValues (mapAttrs showOption opts));
+          showOption = name: option:
+            let
+              shortName = if option ? shortName then "/ `-${option.shortName}`" else "";
+              labels = if option ? labels then (concatStringsSep " " (map (s: "*${s}*") option.labels)) else "";
+            in trim ''
+              - `--${name}` ${shortName} ${labels}
+
+                ${option.description}
+            '';
+          categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues allOptions)));
+        in concatStrings (map showCategory categories);
+    in squash result;
 
   appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
 
-  showOptions = flags:
+  processCommand = { command, details, filename, toplevel }:
     let
-      categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues flags)));
-    in
-      concatStrings (map
-        (cat:
-          (if cat != ""
-           then "**${cat}:**\n\n"
-           else "")
-          + concatStrings
-            (map (longName:
-              let
-                flag = flags.${longName};
-              in
-                "  - `--${longName}`"
-                + (if flag ? shortName then " / `-${flag.shortName}`" else "")
-                + (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "")
-                + "  \n"
-                + "    " + flag.description + "\n\n"
-            ) (attrNames (filterAttrs (n: v: v.category == cat) flags))))
-        categories);
+      cmd = {
+        inherit command;
+        name = filename + ".md";
+        value = showCommand { inherit command details filename toplevel; };
+      };
+      subcommand = subCmd: processCommand {
+        command = command + " " + subCmd;
+        details = details.commands.${subCmd};
+        filename = appendName filename subCmd;
+        inherit toplevel;
+      };
+    in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
 
-  showSynopsis =
-    { command, args }:
-    "`${command}` [*option*...] ${concatStringsSep " "
-      (map (arg: "*${arg.label}*" + (if arg ? arity then "" else "...")) args)}\n\n";
+  parsedToplevel = builtins.fromJSON toplevel;
+  
+  manpages = processCommand {
+    command = "nix";
+    details = parsedToplevel;
+    filename = "nix";
+    toplevel = parsedToplevel;
+  };
 
-  processCommand = { command, def, filename }:
-    [ { name = filename + ".md"; value = showCommand { inherit command def filename; }; inherit command; } ]
-    ++ concatMap
-      (name: processCommand {
-        filename = appendName filename name;
-        command = command + " " + name;
-        def = def.commands.${name};
-      })
-      (attrNames def.commands or {});
+  tableOfContents = let
+    showEntry = page:
+      "    - [${page.command}](command-ref/new-cli/${page.name})";
+    in concatStringsSep "\n" (map showEntry manpages) + "\n";
 
-in
-
-let
-  manpages = processCommand { filename = "nix"; command = "nix"; def = builtins.fromJSON command; };
-  summary = concatStrings (map (manpage: "    - [${manpage.command}](command-ref/new-cli/${manpage.name})\n") manpages);
-in
-(listToAttrs manpages) // { "SUMMARY.md" = summary; }
+in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }

doc/manual/generate-options.nix

@@ -1,29 +1,41 @@
-with builtins;
-with import ./utils.nix;
+let
+  inherit (builtins) attrNames concatStringsSep isAttrs isBool;
+  inherit (import ./utils.nix) concatStrings squash splitLines;
+in
 
-options:
+optionsInfo:
+let
+  showOption = name:
+    let
+      inherit (optionsInfo.${name}) description documentDefault defaultValue aliases;
+      result = squash ''
+          - <span id="conf-${name}">[`${name}`](#conf-${name})</span>
 
-concatStrings (map
-  (name:
-    let option = options.${name}; in
-    "  - [`${name}`](#conf-${name})"
-    + "<p id=\"conf-${name}\"></p>\n\n"
-    + concatStrings (map (s: "    ${s}\n") (splitLines option.description)) + "\n\n"
-    + (if option.documentDefault
-       then "    **Default:** " + (
-       if option.value == "" || option.value == []
-       then "*empty*"
-       else if isBool option.value
-       then (if option.value then "`true`" else "`false`")
-       else
-         # n.b. a StringMap value type is specified as a string, but
-         # this shows the value type.  The empty stringmap is "null" in
-         # JSON, but that converts to "{ }" here.
-         (if isAttrs option.value then "`\"\"`"
-          else "`" + toString option.value + "`")) + "\n\n"
-       else "    **Default:** *machine-specific*\n")
-    + (if option.aliases != []
-       then "    **Deprecated alias:** " + (concatStringsSep ", " (map (s: "`${s}`") option.aliases)) + "\n\n"
-       else "")
-    )
-  (attrNames options))
+          ${indent "  " body}
+        '';
+      # separate body to cleanly handle indentation
+      body = ''
+          ${description}
+
+          **Default:** ${showDefault documentDefault defaultValue}
+
+          ${showAliases aliases}
+        '';
+      showDefault = documentDefault: defaultValue:
+        if documentDefault then
+          # a StringMap value type is specified as a string, but
+          # this shows the value type. The empty stringmap is `null` in
+          # JSON, but that converts to `{ }` here.
+          if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
+            then "*empty*"
+            else if isBool defaultValue then
+              if defaultValue then "`true`" else "`false`"
+            else "`${toString defaultValue}`"
+        else "*machine-specific*";
+      showAliases = aliases:
+          if aliases == [] then "" else
+            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
+      indent = prefix: s:
+        concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
+      in result;
+in concatStrings (map showOption (attrNames optionsInfo))

doc/manual/local.mk

@@ -29,19 +29,19 @@ nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -
 $(d)/%.1: $(d)/src/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=1 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/%.8: $(d)/src/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=8 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
 	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=5 $^.tmp -o $@
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
 	@rm $^.tmp
 
 $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
@@ -50,11 +50,16 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
 
 $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix
 	@rm -rf $@
-	$(trace-gen) $(nix-eval) --write-to $@ --expr 'import doc/manual/generate-manpage.nix { command = builtins.readFile $<; renderLinks = true; }'
+	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix { toplevel = builtins.readFile $<; }'
+	@# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
+	$(trace-gen) sed -i $@.tmp/*.md -e 's^@docroot@^../..^g'
+	@mv $@.tmp $@
 
 $(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix
 	@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp
+	@# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' \
+	  | sed -e 's^@docroot@^..^g'>> $@.tmp
 	@mv $@.tmp $@
 
 $(d)/nix.json: $(bindir)/nix
@@ -67,7 +72,9 @@ $(d)/conf-file.json: $(bindir)/nix
 
 $(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
 	@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp
+	@# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' \
+	  | sed -e 's^@docroot@^..^g' >> $@.tmp
 	@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
 	@mv $@.tmp $@
 
@@ -96,12 +103,18 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 	  if [[ $$name = SUMMARY ]]; then continue; fi; \
 	  printf "Title: %s\n\n" "$$name" > $$tmpFile; \
 	  cat $$i >> $$tmpFile; \
-	  lowdown -sT man -M section=1 $$tmpFile -o $(DESTDIR)$$(dirname $@)/$$name.1; \
+	  lowdown -sT man --nroff-nolinks -M section=1 $$tmpFile -o $(DESTDIR)$$(dirname $@)/$$name.1; \
 	  rm $$tmpFile; \
 	done
 	@touch $@
 
 $(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md
-	$(trace-gen) RUST_LOG=warn mdbook build doc/manual -d $(DESTDIR)$(docdir)/manual
+	$(trace-gen) \
+	  set -euo pipefail; \
+	  RUST_LOG=warn mdbook build doc/manual -d $(DESTDIR)$(docdir)/manual.tmp 2>&1 \
+		  | { grep -Fv "because fragment resolution isn't implemented" || :; }
+	@rm -rf $(DESTDIR)$(docdir)/manual
+	@mv $(DESTDIR)$(docdir)/manual.tmp/html $(DESTDIR)$(docdir)/manual
+	@rm -rf $(DESTDIR)$(docdir)/manual.tmp
 
 endif

doc/manual/redirects.js

@@ -1,330 +1,421 @@
-// Redirects from old DocBook manual.
-var redirects = {
-  "#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",
-  "#chap-distributed-builds": "advanced-topics/distributed-builds.html",
-  "#chap-post-build-hook": "advanced-topics/post-build-hook.html",
-  "#chap-post-build-hook-caveats": "advanced-topics/post-build-hook.html#implementation-caveats",
-  "#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",
-  "#conf-allowed-users": "command-ref/conf-file.html#conf-allowed-users",
-  "#conf-auto-optimise-store": "command-ref/conf-file.html#conf-auto-optimise-store",
-  "#conf-binary-cache-public-keys": "command-ref/conf-file.html#conf-binary-cache-public-keys",
-  "#conf-binary-caches": "command-ref/conf-file.html#conf-binary-caches",
-  "#conf-build-compress-log": "command-ref/conf-file.html#conf-build-compress-log",
-  "#conf-build-cores": "command-ref/conf-file.html#conf-build-cores",
-  "#conf-build-extra-chroot-dirs": "command-ref/conf-file.html#conf-build-extra-chroot-dirs",
-  "#conf-build-extra-sandbox-paths": "command-ref/conf-file.html#conf-build-extra-sandbox-paths",
-  "#conf-build-fallback": "command-ref/conf-file.html#conf-build-fallback",
-  "#conf-build-max-jobs": "command-ref/conf-file.html#conf-build-max-jobs",
-  "#conf-build-max-log-size": "command-ref/conf-file.html#conf-build-max-log-size",
-  "#conf-build-max-silent-time": "command-ref/conf-file.html#conf-build-max-silent-time",
-  "#conf-build-repeat": "command-ref/conf-file.html#conf-build-repeat",
-  "#conf-build-timeout": "command-ref/conf-file.html#conf-build-timeout",
-  "#conf-build-use-chroot": "command-ref/conf-file.html#conf-build-use-chroot",
-  "#conf-build-use-sandbox": "command-ref/conf-file.html#conf-build-use-sandbox",
-  "#conf-build-use-substitutes": "command-ref/conf-file.html#conf-build-use-substitutes",
-  "#conf-build-users-group": "command-ref/conf-file.html#conf-build-users-group",
-  "#conf-builders": "command-ref/conf-file.html#conf-builders",
-  "#conf-builders-use-substitutes": "command-ref/conf-file.html#conf-builders-use-substitutes",
-  "#conf-compress-build-log": "command-ref/conf-file.html#conf-compress-build-log",
-  "#conf-connect-timeout": "command-ref/conf-file.html#conf-connect-timeout",
-  "#conf-cores": "command-ref/conf-file.html#conf-cores",
-  "#conf-diff-hook": "command-ref/conf-file.html#conf-diff-hook",
-  "#conf-enforce-determinism": "command-ref/conf-file.html#conf-enforce-determinism",
-  "#conf-env-keep-derivations": "command-ref/conf-file.html#conf-env-keep-derivations",
-  "#conf-extra-binary-caches": "command-ref/conf-file.html#conf-extra-binary-caches",
-  "#conf-extra-platforms": "command-ref/conf-file.html#conf-extra-platforms",
-  "#conf-extra-sandbox-paths": "command-ref/conf-file.html#conf-extra-sandbox-paths",
-  "#conf-extra-substituters": "command-ref/conf-file.html#conf-extra-substituters",
-  "#conf-fallback": "command-ref/conf-file.html#conf-fallback",
-  "#conf-fsync-metadata": "command-ref/conf-file.html#conf-fsync-metadata",
-  "#conf-gc-keep-derivations": "command-ref/conf-file.html#conf-gc-keep-derivations",
-  "#conf-gc-keep-outputs": "command-ref/conf-file.html#conf-gc-keep-outputs",
-  "#conf-hashed-mirrors": "command-ref/conf-file.html#conf-hashed-mirrors",
-  "#conf-http-connections": "command-ref/conf-file.html#conf-http-connections",
-  "#conf-keep-build-log": "command-ref/conf-file.html#conf-keep-build-log",
-  "#conf-keep-derivations": "command-ref/conf-file.html#conf-keep-derivations",
-  "#conf-keep-env-derivations": "command-ref/conf-file.html#conf-keep-env-derivations",
-  "#conf-keep-outputs": "command-ref/conf-file.html#conf-keep-outputs",
-  "#conf-max-build-log-size": "command-ref/conf-file.html#conf-max-build-log-size",
-  "#conf-max-free": "command-ref/conf-file.html#conf-max-free",
-  "#conf-max-jobs": "command-ref/conf-file.html#conf-max-jobs",
-  "#conf-max-silent-time": "command-ref/conf-file.html#conf-max-silent-time",
-  "#conf-min-free": "command-ref/conf-file.html#conf-min-free",
-  "#conf-narinfo-cache-negative-ttl": "command-ref/conf-file.html#conf-narinfo-cache-negative-ttl",
-  "#conf-narinfo-cache-positive-ttl": "command-ref/conf-file.html#conf-narinfo-cache-positive-ttl",
-  "#conf-netrc-file": "command-ref/conf-file.html#conf-netrc-file",
-  "#conf-plugin-files": "command-ref/conf-file.html#conf-plugin-files",
-  "#conf-post-build-hook": "command-ref/conf-file.html#conf-post-build-hook",
-  "#conf-pre-build-hook": "command-ref/conf-file.html#conf-pre-build-hook",
-  "#conf-repeat": "command-ref/conf-file.html#conf-repeat",
-  "#conf-require-sigs": "command-ref/conf-file.html#conf-require-sigs",
-  "#conf-restrict-eval": "command-ref/conf-file.html#conf-restrict-eval",
-  "#conf-run-diff-hook": "command-ref/conf-file.html#conf-run-diff-hook",
-  "#conf-sandbox": "command-ref/conf-file.html#conf-sandbox",
-  "#conf-sandbox-dev-shm-size": "command-ref/conf-file.html#conf-sandbox-dev-shm-size",
-  "#conf-sandbox-paths": "command-ref/conf-file.html#conf-sandbox-paths",
-  "#conf-secret-key-files": "command-ref/conf-file.html#conf-secret-key-files",
-  "#conf-show-trace": "command-ref/conf-file.html#conf-show-trace",
-  "#conf-stalled-download-timeout": "command-ref/conf-file.html#conf-stalled-download-timeout",
-  "#conf-substitute": "command-ref/conf-file.html#conf-substitute",
-  "#conf-substituters": "command-ref/conf-file.html#conf-substituters",
-  "#conf-system": "command-ref/conf-file.html#conf-system",
-  "#conf-system-features": "command-ref/conf-file.html#conf-system-features",
-  "#conf-tarball-ttl": "command-ref/conf-file.html#conf-tarball-ttl",
-  "#conf-timeout": "command-ref/conf-file.html#conf-timeout",
-  "#conf-trace-function-calls": "command-ref/conf-file.html#conf-trace-function-calls",
-  "#conf-trusted-binary-caches": "command-ref/conf-file.html#conf-trusted-binary-caches",
-  "#conf-trusted-public-keys": "command-ref/conf-file.html#conf-trusted-public-keys",
-  "#conf-trusted-substituters": "command-ref/conf-file.html#conf-trusted-substituters",
-  "#conf-trusted-users": "command-ref/conf-file.html#conf-trusted-users",
-  "#extra-sandbox-paths": "command-ref/conf-file.html#extra-sandbox-paths",
-  "#sec-conf-file": "command-ref/conf-file.html",
-  "#env-NIX_PATH": "command-ref/env-common.html#env-NIX_PATH",
-  "#env-common": "command-ref/env-common.html",
-  "#envar-remote": "command-ref/env-common.html#env-NIX_REMOTE",
-  "#sec-common-env": "command-ref/env-common.html",
-  "#ch-files": "command-ref/files.html",
-  "#ch-main-commands": "command-ref/main-commands.html",
-  "#opt-out-link": "command-ref/nix-build.html#opt-out-link",
-  "#sec-nix-build": "command-ref/nix-build.html",
-  "#sec-nix-channel": "command-ref/nix-channel.html",
-  "#sec-nix-collect-garbage": "command-ref/nix-collect-garbage.html",
-  "#sec-nix-copy-closure": "command-ref/nix-copy-closure.html",
-  "#sec-nix-daemon": "command-ref/nix-daemon.html",
-  "#refsec-nix-env-install-examples": "command-ref/nix-env.html#examples",
-  "#rsec-nix-env-install": "command-ref/nix-env.html#operation---install",
-  "#rsec-nix-env-set": "command-ref/nix-env.html#operation---set",
-  "#rsec-nix-env-set-flag": "command-ref/nix-env.html#operation---set-flag",
-  "#rsec-nix-env-upgrade": "command-ref/nix-env.html#operation---upgrade",
-  "#sec-nix-env": "command-ref/nix-env.html",
-  "#ssec-version-comparisons": "command-ref/nix-env.html#versions",
-  "#sec-nix-hash": "command-ref/nix-hash.html",
-  "#sec-nix-instantiate": "command-ref/nix-instantiate.html",
-  "#sec-nix-prefetch-url": "command-ref/nix-prefetch-url.html",
-  "#sec-nix-shell": "command-ref/nix-shell.html",
-  "#ssec-nix-shell-shebang": "command-ref/nix-shell.html#use-as-a--interpreter",
-  "#nixref-queries": "command-ref/nix-store.html#queries",
-  "#opt-add-root": "command-ref/nix-store.html#opt-add-root",
-  "#refsec-nix-store-dump": "command-ref/nix-store.html#operation---dump",
-  "#refsec-nix-store-export": "command-ref/nix-store.html#operation---export",
-  "#refsec-nix-store-import": "command-ref/nix-store.html#operation---import",
-  "#refsec-nix-store-query": "command-ref/nix-store.html#operation---query",
-  "#refsec-nix-store-verify": "command-ref/nix-store.html#operation---verify",
-  "#rsec-nix-store-gc": "command-ref/nix-store.html#operation---gc",
-  "#rsec-nix-store-generate-binary-cache-key": "command-ref/nix-store.html#operation---generate-binary-cache-key",
-  "#rsec-nix-store-realise": "command-ref/nix-store.html#operation---realise",
-  "#rsec-nix-store-serve": "command-ref/nix-store.html#operation---serve",
-  "#sec-nix-store": "command-ref/nix-store.html",
-  "#opt-I": "command-ref/opt-common.html#opt-I",
-  "#opt-attr": "command-ref/opt-common.html#opt-attr",
-  "#opt-common": "command-ref/opt-common.html",
-  "#opt-cores": "command-ref/opt-common.html#opt-cores",
-  "#opt-log-format": "command-ref/opt-common.html#opt-log-format",
-  "#opt-max-jobs": "command-ref/opt-common.html#opt-max-jobs",
-  "#opt-max-silent-time": "command-ref/opt-common.html#opt-max-silent-time",
-  "#opt-timeout": "command-ref/opt-common.html#opt-timeout",
-  "#sec-common-options": "command-ref/opt-common.html",
-  "#ch-utilities": "command-ref/utilities.html",
-  "#chap-hacking": "contributing/hacking.html",
-  "#adv-attr-allowSubstitutes": "language/advanced-attributes.html#adv-attr-allowSubstitutes",
-  "#adv-attr-allowedReferences": "language/advanced-attributes.html#adv-attr-allowedReferences",
-  "#adv-attr-allowedRequisites": "language/advanced-attributes.html#adv-attr-allowedRequisites",
-  "#adv-attr-disallowedReferences": "language/advanced-attributes.html#adv-attr-disallowedReferences",
-  "#adv-attr-disallowedRequisites": "language/advanced-attributes.html#adv-attr-disallowedRequisites",
-  "#adv-attr-exportReferencesGraph": "language/advanced-attributes.html#adv-attr-exportReferencesGraph",
-  "#adv-attr-impureEnvVars": "language/advanced-attributes.html#adv-attr-impureEnvVars",
-  "#adv-attr-outputHash": "language/advanced-attributes.html#adv-attr-outputHash",
-  "#adv-attr-outputHashAlgo": "language/advanced-attributes.html#adv-attr-outputHashAlgo",
-  "#adv-attr-outputHashMode": "language/advanced-attributes.html#adv-attr-outputHashMode",
-  "#adv-attr-passAsFile": "language/advanced-attributes.html#adv-attr-passAsFile",
-  "#adv-attr-preferLocalBuild": "language/advanced-attributes.html#adv-attr-preferLocalBuild",
-  "#fixed-output-drvs": "language/advanced-attributes.html#adv-attr-outputHash",
-  "#sec-advanced-attributes": "language/advanced-attributes.html",
-  "#builtin-abort": "language/builtins.html#builtins-abort",
-  "#builtin-add": "language/builtins.html#builtins-add",
-  "#builtin-all": "language/builtins.html#builtins-all",
-  "#builtin-any": "language/builtins.html#builtins-any",
-  "#builtin-attrNames": "language/builtins.html#builtins-attrNames",
-  "#builtin-attrValues": "language/builtins.html#builtins-attrValues",
-  "#builtin-baseNameOf": "language/builtins.html#builtins-baseNameOf",
-  "#builtin-bitAnd": "language/builtins.html#builtins-bitAnd",
-  "#builtin-bitOr": "language/builtins.html#builtins-bitOr",
-  "#builtin-bitXor": "language/builtins.html#builtins-bitXor",
-  "#builtin-builtins": "language/builtins.html#builtins-builtins",
-  "#builtin-compareVersions": "language/builtins.html#builtins-compareVersions",
-  "#builtin-concatLists": "language/builtins.html#builtins-concatLists",
-  "#builtin-concatStringsSep": "language/builtins.html#builtins-concatStringsSep",
-  "#builtin-currentSystem": "language/builtins.html#builtins-currentSystem",
-  "#builtin-deepSeq": "language/builtins.html#builtins-deepSeq",
-  "#builtin-derivation": "language/builtins.html#builtins-derivation",
-  "#builtin-dirOf": "language/builtins.html#builtins-dirOf",
-  "#builtin-div": "language/builtins.html#builtins-div",
-  "#builtin-elem": "language/builtins.html#builtins-elem",
-  "#builtin-elemAt": "language/builtins.html#builtins-elemAt",
-  "#builtin-fetchGit": "language/builtins.html#builtins-fetchGit",
-  "#builtin-fetchTarball": "language/builtins.html#builtins-fetchTarball",
-  "#builtin-fetchurl": "language/builtins.html#builtins-fetchurl",
-  "#builtin-filterSource": "language/builtins.html#builtins-filterSource",
-  "#builtin-foldl-prime": "language/builtins.html#builtins-foldl-prime",
-  "#builtin-fromJSON": "language/builtins.html#builtins-fromJSON",
-  "#builtin-functionArgs": "language/builtins.html#builtins-functionArgs",
-  "#builtin-genList": "language/builtins.html#builtins-genList",
-  "#builtin-getAttr": "language/builtins.html#builtins-getAttr",
-  "#builtin-getEnv": "language/builtins.html#builtins-getEnv",
-  "#builtin-hasAttr": "language/builtins.html#builtins-hasAttr",
-  "#builtin-hashFile": "language/builtins.html#builtins-hashFile",
-  "#builtin-hashString": "language/builtins.html#builtins-hashString",
-  "#builtin-head": "language/builtins.html#builtins-head",
-  "#builtin-import": "language/builtins.html#builtins-import",
-  "#builtin-intersectAttrs": "language/builtins.html#builtins-intersectAttrs",
-  "#builtin-isAttrs": "language/builtins.html#builtins-isAttrs",
-  "#builtin-isBool": "language/builtins.html#builtins-isBool",
-  "#builtin-isFloat": "language/builtins.html#builtins-isFloat",
-  "#builtin-isFunction": "language/builtins.html#builtins-isFunction",
-  "#builtin-isInt": "language/builtins.html#builtins-isInt",
-  "#builtin-isList": "language/builtins.html#builtins-isList",
-  "#builtin-isNull": "language/builtins.html#builtins-isNull",
-  "#builtin-isString": "language/builtins.html#builtins-isString",
-  "#builtin-length": "language/builtins.html#builtins-length",
-  "#builtin-lessThan": "language/builtins.html#builtins-lessThan",
-  "#builtin-listToAttrs": "language/builtins.html#builtins-listToAttrs",
-  "#builtin-map": "language/builtins.html#builtins-map",
-  "#builtin-match": "language/builtins.html#builtins-match",
-  "#builtin-mul": "language/builtins.html#builtins-mul",
-  "#builtin-parseDrvName": "language/builtins.html#builtins-parseDrvName",
-  "#builtin-path": "language/builtins.html#builtins-path",
-  "#builtin-pathExists": "language/builtins.html#builtins-pathExists",
-  "#builtin-placeholder": "language/builtins.html#builtins-placeholder",
-  "#builtin-readDir": "language/builtins.html#builtins-readDir",
-  "#builtin-readFile": "language/builtins.html#builtins-readFile",
-  "#builtin-removeAttrs": "language/builtins.html#builtins-removeAttrs",
-  "#builtin-replaceStrings": "language/builtins.html#builtins-replaceStrings",
-  "#builtin-seq": "language/builtins.html#builtins-seq",
-  "#builtin-sort": "language/builtins.html#builtins-sort",
-  "#builtin-split": "language/builtins.html#builtins-split",
-  "#builtin-splitVersion": "language/builtins.html#builtins-splitVersion",
-  "#builtin-stringLength": "language/builtins.html#builtins-stringLength",
-  "#builtin-sub": "language/builtins.html#builtins-sub",
-  "#builtin-substring": "language/builtins.html#builtins-substring",
-  "#builtin-tail": "language/builtins.html#builtins-tail",
-  "#builtin-throw": "language/builtins.html#builtins-throw",
-  "#builtin-toFile": "language/builtins.html#builtins-toFile",
-  "#builtin-toJSON": "language/builtins.html#builtins-toJSON",
-  "#builtin-toPath": "language/builtins.html#builtins-toPath",
-  "#builtin-toString": "language/builtins.html#builtins-toString",
-  "#builtin-toXML": "language/builtins.html#builtins-toXML",
-  "#builtin-trace": "language/builtins.html#builtins-trace",
-  "#builtin-tryEval": "language/builtins.html#builtins-tryEval",
-  "#builtin-typeOf": "language/builtins.html#builtins-typeOf",
-  "#ssec-builtins": "language/builtins.html",
-  "#attr-system": "language/derivations.html#attr-system",
-  "#ssec-derivation": "language/derivations.html",
-  "#ch-expression-language": "language/index.html",
-  "#sec-constructs": "language/constructs.html",
-  "#sect-let-language": "language/constructs.html#let-language",
-  "#ss-functions": "language/constructs.html#functions",
-  "#sec-language-operators": "language/operators.html",
-  "#table-operators": "language/operators.html",
-  "#ssec-values": "language/values.html",
-  "#gloss-closure": "glossary.html#gloss-closure",
-  "#gloss-derivation": "glossary.html#gloss-derivation",
-  "#gloss-deriver": "glossary.html#gloss-deriver",
-  "#gloss-nar": "glossary.html#gloss-nar",
-  "#gloss-output-path": "glossary.html#gloss-output-path",
-  "#gloss-profile": "glossary.html#gloss-profile",
-  "#gloss-reachable": "glossary.html#gloss-reachable",
-  "#gloss-reference": "glossary.html#gloss-reference",
-  "#gloss-substitute": "glossary.html#gloss-substitute",
-  "#gloss-user-env": "glossary.html#gloss-user-env",
-  "#gloss-validity": "glossary.html#gloss-validity",
-  "#part-glossary": "glossary.html",
-  "#sec-building-source": "installation/building-source.html",
-  "#ch-env-variables": "installation/env-variables.html",
-  "#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/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",
-  "#sect-macos-installation-encrypted-volume": "installation/installing-binary.html#macos-installation",
-  "#sect-macos-installation-recommended-notes": "installation/installing-binary.html#macos-installation",
-  "#sect-macos-installation-symlink": "installation/installing-binary.html#macos-installation",
-  "#sect-multi-user-installation": "installation/installing-binary.html#multi-user-installation",
-  "#sect-nix-install-binary-tarball": "installation/installing-binary.html#installing-from-a-binary-tarball",
-  "#sect-nix-install-pinned-version-url": "installation/installing-binary.html#installing-a-pinned-nix-version-from-a-url",
-  "#sect-single-user-installation": "installation/installing-binary.html#single-user-installation",
-  "#ch-installing-source": "installation/installing-source.html",
-  "#ssec-multi-user": "installation/multi-user.html",
-  "#ch-nix-security": "installation/nix-security.html",
-  "#sec-obtaining-source": "installation/obtaining-source.html",
-  "#sec-prerequisites-source": "installation/prerequisites-source.html",
-  "#sec-single-user": "installation/single-user.html",
-  "#ch-supported-platforms": "installation/supported-platforms.html",
-  "#ch-upgrading-nix": "installation/upgrading.html",
-  "#ch-about-nix": "introduction.html",
-  "#chap-introduction": "introduction.html",
-  "#ch-basic-package-mgmt": "package-management/basic-package-mgmt.html",
-  "#ssec-binary-cache-substituter": "package-management/binary-cache-substituter.html",
-  "#sec-channels": "package-management/channels.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/package-management.html",
-  "#sec-profiles": "package-management/profiles.html",
-  "#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/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",
-  "#ssec-relnotes-0.12": "release-notes/rl-0.12.html",
-  "#ssec-relnotes-0.13": "release-notes/rl-0.13.html",
-  "#ssec-relnotes-0.14": "release-notes/rl-0.14.html",
-  "#ssec-relnotes-0.15": "release-notes/rl-0.15.html",
-  "#ssec-relnotes-0.16": "release-notes/rl-0.16.html",
-  "#ch-relnotes-0.5": "release-notes/rl-0.5.html",
-  "#ch-relnotes-0.6": "release-notes/rl-0.6.html",
-  "#ch-relnotes-0.7": "release-notes/rl-0.7.html",
-  "#ch-relnotes-0.8.1": "release-notes/rl-0.8.1.html",
-  "#ch-relnotes-0.8": "release-notes/rl-0.8.html",
-  "#ch-relnotes-0.9.1": "release-notes/rl-0.9.1.html",
-  "#ch-relnotes-0.9.2": "release-notes/rl-0.9.2.html",
-  "#ch-relnotes-0.9": "release-notes/rl-0.9.html",
-  "#ssec-relnotes-1.0": "release-notes/rl-1.0.html",
-  "#ssec-relnotes-1.1": "release-notes/rl-1.1.html",
-  "#ssec-relnotes-1.10": "release-notes/rl-1.10.html",
-  "#ssec-relnotes-1.11.10": "release-notes/rl-1.11.10.html",
-  "#ssec-relnotes-1.11": "release-notes/rl-1.11.html",
-  "#ssec-relnotes-1.2": "release-notes/rl-1.2.html",
-  "#ssec-relnotes-1.3": "release-notes/rl-1.3.html",
-  "#ssec-relnotes-1.4": "release-notes/rl-1.4.html",
-  "#ssec-relnotes-1.5.1": "release-notes/rl-1.5.1.html",
-  "#ssec-relnotes-1.5.2": "release-notes/rl-1.5.2.html",
-  "#ssec-relnotes-1.5": "release-notes/rl-1.5.html",
-  "#ssec-relnotes-1.6.1": "release-notes/rl-1.6.1.html",
-  "#ssec-relnotes-1.6.0": "release-notes/rl-1.6.html",
-  "#ssec-relnotes-1.7": "release-notes/rl-1.7.html",
-  "#ssec-relnotes-1.8": "release-notes/rl-1.8.html",
-  "#ssec-relnotes-1.9": "release-notes/rl-1.9.html",
-  "#ssec-relnotes-2.0": "release-notes/rl-2.0.html",
-  "#ssec-relnotes-2.1": "release-notes/rl-2.1.html",
-  "#ssec-relnotes-2.2": "release-notes/rl-2.2.html",
-  "#ssec-relnotes-2.3": "release-notes/rl-2.3.html"
+// redirect rules for anchors ensure backwards compatibility of URLs.
+// this must be done on the client side, as web servers do not see the anchor part of the URL.
+
+// redirections are declared as follows:
+// each entry has as its key a path matching the requested URL path, relative to the mdBook document root.
+//
+//     IMPORTANT: it must specify the full path with file name and suffix
+//
+// each entry is itself a set of key-value pairs, where
+// - keys are anchors on the matched path.
+// - values are redirection targets relative to the current path.
+
+const redirects = {
+ "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",
+    "chap-distributed-builds": "advanced-topics/distributed-builds.html",
+    "chap-post-build-hook": "advanced-topics/post-build-hook.html",
+    "chap-post-build-hook-caveats": "advanced-topics/post-build-hook.html#implementation-caveats",
+    "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",
+    "conf-allowed-users": "command-ref/conf-file.html#conf-allowed-users",
+    "conf-auto-optimise-store": "command-ref/conf-file.html#conf-auto-optimise-store",
+    "conf-binary-cache-public-keys": "command-ref/conf-file.html#conf-binary-cache-public-keys",
+    "conf-binary-caches": "command-ref/conf-file.html#conf-binary-caches",
+    "conf-build-compress-log": "command-ref/conf-file.html#conf-build-compress-log",
+    "conf-build-cores": "command-ref/conf-file.html#conf-build-cores",
+    "conf-build-extra-chroot-dirs": "command-ref/conf-file.html#conf-build-extra-chroot-dirs",
+    "conf-build-extra-sandbox-paths": "command-ref/conf-file.html#conf-build-extra-sandbox-paths",
+    "conf-build-fallback": "command-ref/conf-file.html#conf-build-fallback",
+    "conf-build-max-jobs": "command-ref/conf-file.html#conf-build-max-jobs",
+    "conf-build-max-log-size": "command-ref/conf-file.html#conf-build-max-log-size",
+    "conf-build-max-silent-time": "command-ref/conf-file.html#conf-build-max-silent-time",
+    "conf-build-timeout": "command-ref/conf-file.html#conf-build-timeout",
+    "conf-build-use-chroot": "command-ref/conf-file.html#conf-build-use-chroot",
+    "conf-build-use-sandbox": "command-ref/conf-file.html#conf-build-use-sandbox",
+    "conf-build-use-substitutes": "command-ref/conf-file.html#conf-build-use-substitutes",
+    "conf-build-users-group": "command-ref/conf-file.html#conf-build-users-group",
+    "conf-builders": "command-ref/conf-file.html#conf-builders",
+    "conf-builders-use-substitutes": "command-ref/conf-file.html#conf-builders-use-substitutes",
+    "conf-compress-build-log": "command-ref/conf-file.html#conf-compress-build-log",
+    "conf-connect-timeout": "command-ref/conf-file.html#conf-connect-timeout",
+    "conf-cores": "command-ref/conf-file.html#conf-cores",
+    "conf-diff-hook": "command-ref/conf-file.html#conf-diff-hook",
+    "conf-env-keep-derivations": "command-ref/conf-file.html#conf-env-keep-derivations",
+    "conf-extra-binary-caches": "command-ref/conf-file.html#conf-extra-binary-caches",
+    "conf-extra-platforms": "command-ref/conf-file.html#conf-extra-platforms",
+    "conf-extra-sandbox-paths": "command-ref/conf-file.html#conf-extra-sandbox-paths",
+    "conf-extra-substituters": "command-ref/conf-file.html#conf-extra-substituters",
+    "conf-fallback": "command-ref/conf-file.html#conf-fallback",
+    "conf-fsync-metadata": "command-ref/conf-file.html#conf-fsync-metadata",
+    "conf-gc-keep-derivations": "command-ref/conf-file.html#conf-gc-keep-derivations",
+    "conf-gc-keep-outputs": "command-ref/conf-file.html#conf-gc-keep-outputs",
+    "conf-hashed-mirrors": "command-ref/conf-file.html#conf-hashed-mirrors",
+    "conf-http-connections": "command-ref/conf-file.html#conf-http-connections",
+    "conf-keep-build-log": "command-ref/conf-file.html#conf-keep-build-log",
+    "conf-keep-derivations": "command-ref/conf-file.html#conf-keep-derivations",
+    "conf-keep-env-derivations": "command-ref/conf-file.html#conf-keep-env-derivations",
+    "conf-keep-outputs": "command-ref/conf-file.html#conf-keep-outputs",
+    "conf-max-build-log-size": "command-ref/conf-file.html#conf-max-build-log-size",
+    "conf-max-free": "command-ref/conf-file.html#conf-max-free",
+    "conf-max-jobs": "command-ref/conf-file.html#conf-max-jobs",
+    "conf-max-silent-time": "command-ref/conf-file.html#conf-max-silent-time",
+    "conf-min-free": "command-ref/conf-file.html#conf-min-free",
+    "conf-narinfo-cache-negative-ttl": "command-ref/conf-file.html#conf-narinfo-cache-negative-ttl",
+    "conf-narinfo-cache-positive-ttl": "command-ref/conf-file.html#conf-narinfo-cache-positive-ttl",
+    "conf-netrc-file": "command-ref/conf-file.html#conf-netrc-file",
+    "conf-plugin-files": "command-ref/conf-file.html#conf-plugin-files",
+    "conf-post-build-hook": "command-ref/conf-file.html#conf-post-build-hook",
+    "conf-pre-build-hook": "command-ref/conf-file.html#conf-pre-build-hook",
+    "conf-require-sigs": "command-ref/conf-file.html#conf-require-sigs",
+    "conf-restrict-eval": "command-ref/conf-file.html#conf-restrict-eval",
+    "conf-run-diff-hook": "command-ref/conf-file.html#conf-run-diff-hook",
+    "conf-sandbox": "command-ref/conf-file.html#conf-sandbox",
+    "conf-sandbox-dev-shm-size": "command-ref/conf-file.html#conf-sandbox-dev-shm-size",
+    "conf-sandbox-paths": "command-ref/conf-file.html#conf-sandbox-paths",
+    "conf-secret-key-files": "command-ref/conf-file.html#conf-secret-key-files",
+    "conf-show-trace": "command-ref/conf-file.html#conf-show-trace",
+    "conf-stalled-download-timeout": "command-ref/conf-file.html#conf-stalled-download-timeout",
+    "conf-substitute": "command-ref/conf-file.html#conf-substitute",
+    "conf-substituters": "command-ref/conf-file.html#conf-substituters",
+    "conf-system": "command-ref/conf-file.html#conf-system",
+    "conf-system-features": "command-ref/conf-file.html#conf-system-features",
+    "conf-tarball-ttl": "command-ref/conf-file.html#conf-tarball-ttl",
+    "conf-timeout": "command-ref/conf-file.html#conf-timeout",
+    "conf-trace-function-calls": "command-ref/conf-file.html#conf-trace-function-calls",
+    "conf-trusted-binary-caches": "command-ref/conf-file.html#conf-trusted-binary-caches",
+    "conf-trusted-public-keys": "command-ref/conf-file.html#conf-trusted-public-keys",
+    "conf-trusted-substituters": "command-ref/conf-file.html#conf-trusted-substituters",
+    "conf-trusted-users": "command-ref/conf-file.html#conf-trusted-users",
+    "extra-sandbox-paths": "command-ref/conf-file.html#extra-sandbox-paths",
+    "sec-conf-file": "command-ref/conf-file.html",
+    "env-NIX_PATH": "command-ref/env-common.html#env-NIX_PATH",
+    "env-common": "command-ref/env-common.html",
+    "envar-remote": "command-ref/env-common.html#env-NIX_REMOTE",
+    "sec-common-env": "command-ref/env-common.html",
+    "ch-files": "command-ref/files.html",
+    "ch-main-commands": "command-ref/main-commands.html",
+    "opt-out-link": "command-ref/nix-build.html#opt-out-link",
+    "sec-nix-build": "command-ref/nix-build.html",
+    "sec-nix-channel": "command-ref/nix-channel.html",
+    "sec-nix-collect-garbage": "command-ref/nix-collect-garbage.html",
+    "sec-nix-copy-closure": "command-ref/nix-copy-closure.html",
+    "sec-nix-daemon": "command-ref/nix-daemon.html",
+    "refsec-nix-env-install-examples": "command-ref/nix-env.html#examples",
+    "rsec-nix-env-install": "command-ref/nix-env.html#operation---install",
+    "rsec-nix-env-set": "command-ref/nix-env.html#operation---set",
+    "rsec-nix-env-set-flag": "command-ref/nix-env.html#operation---set-flag",
+    "rsec-nix-env-upgrade": "command-ref/nix-env.html#operation---upgrade",
+    "sec-nix-env": "command-ref/nix-env.html",
+    "ssec-version-comparisons": "command-ref/nix-env.html#versions",
+    "sec-nix-hash": "command-ref/nix-hash.html",
+    "sec-nix-instantiate": "command-ref/nix-instantiate.html",
+    "sec-nix-prefetch-url": "command-ref/nix-prefetch-url.html",
+    "sec-nix-shell": "command-ref/nix-shell.html",
+    "ssec-nix-shell-shebang": "command-ref/nix-shell.html#use-as-a--interpreter",
+    "nixref-queries": "command-ref/nix-store.html#queries",
+    "opt-add-root": "command-ref/nix-store.html#opt-add-root",
+    "refsec-nix-store-dump": "command-ref/nix-store.html#operation---dump",
+    "refsec-nix-store-export": "command-ref/nix-store.html#operation---export",
+    "refsec-nix-store-import": "command-ref/nix-store.html#operation---import",
+    "refsec-nix-store-query": "command-ref/nix-store.html#operation---query",
+    "refsec-nix-store-verify": "command-ref/nix-store.html#operation---verify",
+    "rsec-nix-store-gc": "command-ref/nix-store.html#operation---gc",
+    "rsec-nix-store-generate-binary-cache-key": "command-ref/nix-store.html#operation---generate-binary-cache-key",
+    "rsec-nix-store-realise": "command-ref/nix-store.html#operation---realise",
+    "rsec-nix-store-serve": "command-ref/nix-store.html#operation---serve",
+    "sec-nix-store": "command-ref/nix-store.html",
+    "opt-I": "command-ref/opt-common.html#opt-I",
+    "opt-attr": "command-ref/opt-common.html#opt-attr",
+    "opt-common": "command-ref/opt-common.html",
+    "opt-cores": "command-ref/opt-common.html#opt-cores",
+    "opt-log-format": "command-ref/opt-common.html#opt-log-format",
+    "opt-max-jobs": "command-ref/opt-common.html#opt-max-jobs",
+    "opt-max-silent-time": "command-ref/opt-common.html#opt-max-silent-time",
+    "opt-timeout": "command-ref/opt-common.html#opt-timeout",
+    "sec-common-options": "command-ref/opt-common.html",
+    "ch-utilities": "command-ref/utilities.html",
+    "chap-hacking": "contributing/hacking.html",
+    "adv-attr-allowSubstitutes": "language/advanced-attributes.html#adv-attr-allowSubstitutes",
+    "adv-attr-allowedReferences": "language/advanced-attributes.html#adv-attr-allowedReferences",
+    "adv-attr-allowedRequisites": "language/advanced-attributes.html#adv-attr-allowedRequisites",
+    "adv-attr-disallowedReferences": "language/advanced-attributes.html#adv-attr-disallowedReferences",
+    "adv-attr-disallowedRequisites": "language/advanced-attributes.html#adv-attr-disallowedRequisites",
+    "adv-attr-exportReferencesGraph": "language/advanced-attributes.html#adv-attr-exportReferencesGraph",
+    "adv-attr-impureEnvVars": "language/advanced-attributes.html#adv-attr-impureEnvVars",
+    "adv-attr-outputHash": "language/advanced-attributes.html#adv-attr-outputHash",
+    "adv-attr-outputHashAlgo": "language/advanced-attributes.html#adv-attr-outputHashAlgo",
+    "adv-attr-outputHashMode": "language/advanced-attributes.html#adv-attr-outputHashMode",
+    "adv-attr-passAsFile": "language/advanced-attributes.html#adv-attr-passAsFile",
+    "adv-attr-preferLocalBuild": "language/advanced-attributes.html#adv-attr-preferLocalBuild",
+    "fixed-output-drvs": "language/advanced-attributes.html#adv-attr-outputHash",
+    "sec-advanced-attributes": "language/advanced-attributes.html",
+    "builtin-abort": "language/builtins.html#builtins-abort",
+    "builtin-add": "language/builtins.html#builtins-add",
+    "builtin-all": "language/builtins.html#builtins-all",
+    "builtin-any": "language/builtins.html#builtins-any",
+    "builtin-attrNames": "language/builtins.html#builtins-attrNames",
+    "builtin-attrValues": "language/builtins.html#builtins-attrValues",
+    "builtin-baseNameOf": "language/builtins.html#builtins-baseNameOf",
+    "builtin-bitAnd": "language/builtins.html#builtins-bitAnd",
+    "builtin-bitOr": "language/builtins.html#builtins-bitOr",
+    "builtin-bitXor": "language/builtins.html#builtins-bitXor",
+    "builtin-builtins": "language/builtins.html#builtins-builtins",
+    "builtin-compareVersions": "language/builtins.html#builtins-compareVersions",
+    "builtin-concatLists": "language/builtins.html#builtins-concatLists",
+    "builtin-concatStringsSep": "language/builtins.html#builtins-concatStringsSep",
+    "builtin-currentSystem": "language/builtins.html#builtins-currentSystem",
+    "builtin-deepSeq": "language/builtins.html#builtins-deepSeq",
+    "builtin-derivation": "language/builtins.html#builtins-derivation",
+    "builtin-dirOf": "language/builtins.html#builtins-dirOf",
+    "builtin-div": "language/builtins.html#builtins-div",
+    "builtin-elem": "language/builtins.html#builtins-elem",
+    "builtin-elemAt": "language/builtins.html#builtins-elemAt",
+    "builtin-fetchGit": "language/builtins.html#builtins-fetchGit",
+    "builtin-fetchTarball": "language/builtins.html#builtins-fetchTarball",
+    "builtin-fetchurl": "language/builtins.html#builtins-fetchurl",
+    "builtin-filterSource": "language/builtins.html#builtins-filterSource",
+    "builtin-foldl-prime": "language/builtins.html#builtins-foldl-prime",
+    "builtin-fromJSON": "language/builtins.html#builtins-fromJSON",
+    "builtin-functionArgs": "language/builtins.html#builtins-functionArgs",
+    "builtin-genList": "language/builtins.html#builtins-genList",
+    "builtin-getAttr": "language/builtins.html#builtins-getAttr",
+    "builtin-getEnv": "language/builtins.html#builtins-getEnv",
+    "builtin-hasAttr": "language/builtins.html#builtins-hasAttr",
+    "builtin-hashFile": "language/builtins.html#builtins-hashFile",
+    "builtin-hashString": "language/builtins.html#builtins-hashString",
+    "builtin-head": "language/builtins.html#builtins-head",
+    "builtin-import": "language/builtins.html#builtins-import",
+    "builtin-intersectAttrs": "language/builtins.html#builtins-intersectAttrs",
+    "builtin-isAttrs": "language/builtins.html#builtins-isAttrs",
+    "builtin-isBool": "language/builtins.html#builtins-isBool",
+    "builtin-isFloat": "language/builtins.html#builtins-isFloat",
+    "builtin-isFunction": "language/builtins.html#builtins-isFunction",
+    "builtin-isInt": "language/builtins.html#builtins-isInt",
+    "builtin-isList": "language/builtins.html#builtins-isList",
+    "builtin-isNull": "language/builtins.html#builtins-isNull",
+    "builtin-isString": "language/builtins.html#builtins-isString",
+    "builtin-length": "language/builtins.html#builtins-length",
+    "builtin-lessThan": "language/builtins.html#builtins-lessThan",
+    "builtin-listToAttrs": "language/builtins.html#builtins-listToAttrs",
+    "builtin-map": "language/builtins.html#builtins-map",
+    "builtin-match": "language/builtins.html#builtins-match",
+    "builtin-mul": "language/builtins.html#builtins-mul",
+    "builtin-parseDrvName": "language/builtins.html#builtins-parseDrvName",
+    "builtin-path": "language/builtins.html#builtins-path",
+    "builtin-pathExists": "language/builtins.html#builtins-pathExists",
+    "builtin-placeholder": "language/builtins.html#builtins-placeholder",
+    "builtin-readDir": "language/builtins.html#builtins-readDir",
+    "builtin-readFile": "language/builtins.html#builtins-readFile",
+    "builtin-removeAttrs": "language/builtins.html#builtins-removeAttrs",
+    "builtin-replaceStrings": "language/builtins.html#builtins-replaceStrings",
+    "builtin-seq": "language/builtins.html#builtins-seq",
+    "builtin-sort": "language/builtins.html#builtins-sort",
+    "builtin-split": "language/builtins.html#builtins-split",
+    "builtin-splitVersion": "language/builtins.html#builtins-splitVersion",
+    "builtin-stringLength": "language/builtins.html#builtins-stringLength",
+    "builtin-sub": "language/builtins.html#builtins-sub",
+    "builtin-substring": "language/builtins.html#builtins-substring",
+    "builtin-tail": "language/builtins.html#builtins-tail",
+    "builtin-throw": "language/builtins.html#builtins-throw",
+    "builtin-toFile": "language/builtins.html#builtins-toFile",
+    "builtin-toJSON": "language/builtins.html#builtins-toJSON",
+    "builtin-toPath": "language/builtins.html#builtins-toPath",
+    "builtin-toString": "language/builtins.html#builtins-toString",
+    "builtin-toXML": "language/builtins.html#builtins-toXML",
+    "builtin-trace": "language/builtins.html#builtins-trace",
+    "builtin-tryEval": "language/builtins.html#builtins-tryEval",
+    "builtin-typeOf": "language/builtins.html#builtins-typeOf",
+    "ssec-builtins": "language/builtins.html",
+    "attr-system": "language/derivations.html#attr-system",
+    "ssec-derivation": "language/derivations.html",
+    "ch-expression-language": "language/index.html",
+    "sec-constructs": "language/constructs.html",
+    "sect-let-language": "language/constructs.html#let-language",
+    "ss-functions": "language/constructs.html#functions",
+    "sec-language-operators": "language/operators.html",
+    "table-operators": "language/operators.html",
+    "ssec-values": "language/values.html",
+    "gloss-closure": "glossary.html#gloss-closure",
+    "gloss-derivation": "glossary.html#gloss-derivation",
+    "gloss-deriver": "glossary.html#gloss-deriver",
+    "gloss-nar": "glossary.html#gloss-nar",
+    "gloss-output-path": "glossary.html#gloss-output-path",
+    "gloss-profile": "glossary.html#gloss-profile",
+    "gloss-reachable": "glossary.html#gloss-reachable",
+    "gloss-reference": "glossary.html#gloss-reference",
+    "gloss-substitute": "glossary.html#gloss-substitute",
+    "gloss-user-env": "glossary.html#gloss-user-env",
+    "gloss-validity": "glossary.html#gloss-validity",
+    "part-glossary": "glossary.html",
+    "sec-building-source": "installation/building-source.html",
+    "ch-env-variables": "installation/env-variables.html",
+    "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/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",
+    "sect-macos-installation-encrypted-volume": "installation/installing-binary.html#macos-installation",
+    "sect-macos-installation-recommended-notes": "installation/installing-binary.html#macos-installation",
+    "sect-macos-installation-symlink": "installation/installing-binary.html#macos-installation",
+    "sect-multi-user-installation": "installation/installing-binary.html#multi-user-installation",
+    "sect-nix-install-binary-tarball": "installation/installing-binary.html#installing-from-a-binary-tarball",
+    "sect-nix-install-pinned-version-url": "installation/installing-binary.html#installing-a-pinned-nix-version-from-a-url",
+    "sect-single-user-installation": "installation/installing-binary.html#single-user-installation",
+    "ch-installing-source": "installation/installing-source.html",
+    "ssec-multi-user": "installation/multi-user.html",
+    "ch-nix-security": "installation/nix-security.html",
+    "sec-obtaining-source": "installation/obtaining-source.html",
+    "sec-prerequisites-source": "installation/prerequisites-source.html",
+    "sec-single-user": "installation/single-user.html",
+    "ch-supported-platforms": "installation/supported-platforms.html",
+    "ch-upgrading-nix": "installation/upgrading.html",
+    "ch-about-nix": "introduction.html",
+    "chap-introduction": "introduction.html",
+    "ch-basic-package-mgmt": "package-management/basic-package-mgmt.html",
+    "ssec-binary-cache-substituter": "package-management/binary-cache-substituter.html",
+    "sec-channels": "package-management/channels.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/package-management.html",
+    "sec-profiles": "package-management/profiles.html",
+    "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/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",
+    "ssec-relnotes-0.12": "release-notes/rl-0.12.html",
+    "ssec-relnotes-0.13": "release-notes/rl-0.13.html",
+    "ssec-relnotes-0.14": "release-notes/rl-0.14.html",
+    "ssec-relnotes-0.15": "release-notes/rl-0.15.html",
+    "ssec-relnotes-0.16": "release-notes/rl-0.16.html",
+    "ch-relnotes-0.5": "release-notes/rl-0.5.html",
+    "ch-relnotes-0.6": "release-notes/rl-0.6.html",
+    "ch-relnotes-0.7": "release-notes/rl-0.7.html",
+    "ch-relnotes-0.8.1": "release-notes/rl-0.8.1.html",
+    "ch-relnotes-0.8": "release-notes/rl-0.8.html",
+    "ch-relnotes-0.9.1": "release-notes/rl-0.9.1.html",
+    "ch-relnotes-0.9.2": "release-notes/rl-0.9.2.html",
+    "ch-relnotes-0.9": "release-notes/rl-0.9.html",
+    "ssec-relnotes-1.0": "release-notes/rl-1.0.html",
+    "ssec-relnotes-1.1": "release-notes/rl-1.1.html",
+    "ssec-relnotes-1.10": "release-notes/rl-1.10.html",
+    "ssec-relnotes-1.11.10": "release-notes/rl-1.11.10.html",
+    "ssec-relnotes-1.11": "release-notes/rl-1.11.html",
+    "ssec-relnotes-1.2": "release-notes/rl-1.2.html",
+    "ssec-relnotes-1.3": "release-notes/rl-1.3.html",
+    "ssec-relnotes-1.4": "release-notes/rl-1.4.html",
+    "ssec-relnotes-1.5.1": "release-notes/rl-1.5.1.html",
+    "ssec-relnotes-1.5.2": "release-notes/rl-1.5.2.html",
+    "ssec-relnotes-1.5": "release-notes/rl-1.5.html",
+    "ssec-relnotes-1.6.1": "release-notes/rl-1.6.1.html",
+    "ssec-relnotes-1.6.0": "release-notes/rl-1.6.html",
+    "ssec-relnotes-1.7": "release-notes/rl-1.7.html",
+    "ssec-relnotes-1.8": "release-notes/rl-1.8.html",
+    "ssec-relnotes-1.9": "release-notes/rl-1.9.html",
+    "ssec-relnotes-2.0": "release-notes/rl-2.0.html",
+    "ssec-relnotes-2.1": "release-notes/rl-2.1.html",
+    "ssec-relnotes-2.2": "release-notes/rl-2.2.html",
+    "ssec-relnotes-2.3": "release-notes/rl-2.3.html"
+  },
+  "language/values.html": {
+    "simple-values": "#primitives",
+    "lists": "#list",
+    "strings": "#string",
+    "lists": "#list",
+    "attribute-sets": "#attribute-set"
+  }
 };
 
-var isRoot = (document.location.pathname.endsWith('/') || document.location.pathname.endsWith('/index.html')) && path_to_root === '';
-if (isRoot && redirects[document.location.hash]) {
-  document.location.href = path_to_root + redirects[document.location.hash];
+// the following code matches the current page's URL against the set of redirects.
+//
+// it is written to minimize the latency between page load and redirect.
+// therefore we avoid function calls, copying data, and unnecessary loops.
+// IMPORTANT: we use stateful array operations and their order matters!
+//
+// matching URLs is more involved than it should be:
+//
+// 1. `document.location.pathname` can have an arbitrary prefix.
+//
+// 2. `path_to_root` is set by mdBook. it consists only of `../`s and
+//    determines the depth of `<path>` relative to the prefix:
+//
+//          `document.location.pathname`
+//        |------------------------------|
+//        /<prefix>/<path>/[<file>[.html]][#<anchor>]
+//                  |----|
+//              `path_to_root` has same number of path segments
+//
+//    source: https://phaiax.github.io/mdBook/format/theme/index-hbs.html#data
+//
+// 3. the following paths are equivalent:
+//
+//        /foo/bar/
+//        /foo/bar/index.html
+//        /foo/bar/index
+//
+//  4. the following paths are also equivalent:
+//
+//        /foo/bar/baz
+//        /foo/bar/baz.html
+//
+
+let segments = document.location.pathname.split('/');
+
+let file = segments.pop();
+
+// normalize file name
+if (file === '') { file = "index.html"; }
+else if (!file.endsWith('.html')) { file = file + '.html'; }
+
+segments.push(file);
+
+// use `path_to_root` to discern prefix from path.
+const depth = path_to_root.split('/').length;
+
+// remove segments containing prefix. the following works because
+// 1. the original `document.location.pathname` is absolute,
+//    hence first element of `segments` is always empty.
+// 2. last element of splitting `path_to_root` is also always empty.
+// 3. last element of `segments` is the file name.
+//
+// visual example:
+//
+//     '/foo/bar/baz.html'.split('/') -> [ '', 'foo', 'bar', 'baz.html' ]
+//          '../'.split('/')          -> [ '..', '' ]
+//
+// the following operations will then result in
+//
+//     path = 'bar/baz.html'
+//
+segments.splice(0, segments.length - depth);
+const path = segments.join('/');
+
+// anchor starts with the hash character (`#`),
+// but our redirect declarations don't, so we strip it.
+// example:
+//     document.location.hash -> '#foo'
+//     document.location.hash.substring(1) -> 'foo'
+const anchor = document.location.hash.substring(1);
+
+const redirect = redirects[path];
+if (redirect) {
+  const target = redirect[anchor];
+  if (target) {
+    document.location.href = target;
+  }
 }

doc/manual/src/SUMMARY.md.in

@@ -29,6 +29,7 @@
 - [Nix Language](language/index.md)
   - [Data Types](language/values.md)
   - [Language Constructs](language/constructs.md)
+    - [String interpolation](language/string-interpolation.md)
   - [Operators](language/operators.md)
   - [Derivations](language/derivations.md)
     - [Advanced Attributes](language/advanced-attributes.md)
@@ -59,20 +60,15 @@
 @manpages@
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
-<!--
 - [Architecture](architecture/architecture.md)
-  - [Store](architecture/store/store.md)
-    - [Closure](architecture/store/store/closure.md)
-    - [Build system terminology](architecture/store/store/build-system-terminology.md)
-  - [Store Path](architecture/store/path.md)
-  - [File System Object](architecture/store/fso.md)
--->
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
   - [CLI guideline](contributing/cli-guideline.md)
 - [Release Notes](release-notes/release-notes.md)
-  - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+  - [Release 2.14 (2023-02-28)](release-notes/rl-2.14.md)
+  - [Release 2.13 (2023-01-17)](release-notes/rl-2.13.md)
+  - [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
   - [Release 2.11 (2022-08-25)](release-notes/rl-2.11.md)
   - [Release 2.10 (2022-07-11)](release-notes/rl-2.10.md)
   - [Release 2.9 (2022-05-30)](release-notes/rl-2.9.md)

doc/manual/src/advanced-topics/diff-hook.md

@@ -121,37 +121,3 @@ error:
     are not valid, so checking is not possible
 
 Run the build without `--check`, and then try with `--check` again.
-
-# Automatic and Optionally Enforced Determinism Verification
-
-Automatically verify every build at build time by executing the build
-multiple times.
-
-Setting `repeat` and `enforce-determinism` in your `nix.conf` permits
-the automated verification of every build Nix performs.
-
-The following configuration will run each build three times, and will
-require the build to be deterministic:
-
-    enforce-determinism = true
-    repeat = 2
-
-Setting `enforce-determinism` to false as in the following
-configuration will run the build multiple times, execute the build
-hook, but will allow the build to succeed even if it does not build
-reproducibly:
-
-    enforce-determinism = false
-    repeat = 1
-
-An example output of this configuration:
-
-```console
-$ nix-build ./test.nix -A unstable
-this derivation will be built:
-  /nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv
-building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 1/2)...
-building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 2/2)...
-output '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable' of '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' differs from '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable.check' from previous round
-/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable
-```

doc/manual/src/advanced-topics/post-build-hook.md

@@ -33,12 +33,17 @@ distribute the public key for verifying the authenticity of the paths.
 example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
 ```
 
-Then, add the public key and the cache URL to your `nix.conf`'s
-`trusted-public-keys` and `substituters` options:
+Then update [`nix.conf`](../command-ref/conf-file.md) on any machine that will access the cache.
+Add the cache URL to [`substituters`](../command-ref/conf-file.md#conf-substituters) and the public key to [`trusted-public-keys`](../command-ref/conf-file.md#conf-trusted-public-keys):
 
     substituters = https://cache.nixos.org/ s3://example-nix-cache
     trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
 
+Machines that build for the cache must sign derivations using the private key.
+On those machines, add the path to the key file to the [`secret-key-files`](../command-ref/conf-file.md#conf-secret-key-files) field in their [`nix.conf`](../command-ref/conf-file.md):
+
+    secret-key-files = /etc/nix/key.private
+
 We will restart the Nix daemon in a later step.
 
 # Implementing the build hook
@@ -52,14 +57,12 @@ set -eu
 set -f # disable globbing
 export IFS=' '
 
-echo "Signing paths" $OUT_PATHS
-nix store sign --key-file /etc/nix/key.private $OUT_PATHS
 echo "Uploading paths" $OUT_PATHS
-exec nix copy --to 's3://example-nix-cache' $OUT_PATHS
+exec nix copy --to "s3://example-nix-cache" $OUT_PATHS
 ```
 
 > **Note**
-> 
+>
 > The `$OUT_PATHS` variable is a space-separated list of Nix store
 > paths. In this case, we expect and want the shell to perform word
 > splitting to make each output path its own argument to `nix

doc/manual/src/architecture/architecture.md

@@ -1,79 +1,115 @@
 # Architecture
 
-*(This chapter is unstable and a work in progress. Incoming links may rot.)*
-
 This chapter describes how Nix works.
 It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.
 
 ## Overview
 
-Nix consists of [hierarchical layers][layer-architecture].
+Nix consists of [hierarchical layers].
+
+[hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
+
+The following [concept map] shows its main components (rectangles), the objects they operate on (rounded rectangles), and their interactions (connecting phrases):
+
+[concept map]: https://en.m.wikipedia.org/wiki/Concept_map
 
 ```
-+-----------------------------------------------------------------+
-| Nix                                                             |
-|                  [ commmand line interface ]------,             |
-|                               |                   |             |
-|                           evaluates               |             |
-|                               |                manages          |
-|                               V                   |             |
-|                  [ configuration language  ]      |             |
-|                               |                   |             |
-| +-----------------------------|-------------------V-----------+ |
-| | store                  evaluates to                         | |
-| |                             |                               | |
-| |             referenced by   V       builds                  | |
-| |  [ build input ] ---> [ build plan ] ---> [ build result ]  | |
-| |                                                             | |
-| +-------------------------------------------------------------+ |
-+-----------------------------------------------------------------+
+
+   .----------------.
+   | Nix expression |----------.
+   '----------------'          |
+           |              passed to
+           |                   |
++----------|-------------------|--------------------------------+
+| Nix      |                   V                                |
+|          |      +-------------------------+                   |
+|          |      | commmand line interface |------.            |
+|          |      +-------------------------+      |            |
+|          |                   |                   |            |
+|    evaluated by            calls              manages         |
+|          |                   |                   |            |
+|          |                   V                   |            |
+|          |         +--------------------+        |            |
+|          '-------->| language evaluator |        |            |
+|                    +--------------------+        |            |
+|                              |                   |            |
+|                           produces               |            |
+|                              |                   V            |
+| +----------------------------|------------------------------+ |
+| | store                      |                              | |
+| |            referenced by   V       builds                 | |
+| | .-------------.      .------------.      .--------------. | |
+| | | build input |----->| build plan |----->| build result | | |
+| | '-------------'      '------------'      '--------------' | |
+| +-------------------------------------------------|---------+ |
++---------------------------------------------------|-----------+
+                                                    |
+                                              represented as
+                                                    |
+                                                    V
+                                            .---------------.
+                                            |     file      |
+                                            '---------------'
 ```
 
-At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
+At the top is the [command line interface](../command-ref/command-ref.md) that drives the underlying layers.
 
-Below that is the [Nix expression language](../expressions/expression-language.md), a [purely functional][purely-functional-programming] configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
+The [Nix language](../language/index.md) evaluator transforms Nix expressions into self-contained *build plans*, which are used to derive *build results* from referenced *build inputs*.
 
-The command line and Nix language are what users interact with most.
+The command line interface and Nix expressions are what users deal with most.
 
 > **Note**
 > The Nix language itself does not have a notion of *packages* or *configurations*.
 > As far as we are concerned here, the inputs and results of a build plan are just data.
 
-Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
-It can also execute build plans to produce new data.
+Underlying the command line interface and the Nix language evaluator is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+It can also execute build plans to produce new data, which are made available to the operating system as files.
 
-A build plan is a series of *build tasks*.
-Each build task has a special build input which is used as *build instructions*.
+A build plan itself is a series of *build tasks*, together with their build inputs.
+
+> **Important**
+> 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.
 
+The following [data flow diagram] shows a build plan for illustration.
+Build inputs used as instructions to a build task are marked accordingly:
+
+[data flow diagram]: https://en.m.wikipedia.org/wiki/Data-flow_diagram
+
 ```
-+-----------------------------------------------------------------------------------------+
-| store                                                                                   |
-|                   .................................................                     |
-|                   :  build plan                                   :                     |
-|                   :                                               :                     |
-|  [ build input ]-----instructions-,                               :                     |
-|                   :               |                               :                     |
-|                   :               v                               :                     |
-|  [ build input ]----------->[ build task ]--instructions-,        :                     |
-|                   :                                      |        :                     |
-|                   :                                      |        :                     |
-|                   :                                      v        :                     |
-|                   :                               [ build task ]----->[ build result ]  |
-|  [ build input ]-----instructions-,                      ^        :                     |
-|                   :               |                      |        :                     |
-|                   :               v                      |        :                     |
-|  [ build input ]----------->[ build task ]---------------'        :                     |
-|                   :               ^                               :                     |
-|                   :               |                               :                     |
-|  [ build input ]------------------'                               :                     |
-|                   :                                               :                     |
-|                   :                                               :                     |
-|                   :...............................................:                     |
-|                                                                                         |
-+-----------------------------------------------------------------------------------------+
++--------------------------------------------------------------------+
+| build plan                                                         |
+|                                                                    |
+| .-------------.                                                    |
+| | build input |---------.                                          |
+| '-------------'         |                                          |
+|                    instructions                                    |
+|                         |                                          |
+|                         v                                          |
+| .-------------.    .----------.                                    |
+| | build input |-->( build task )-------.                           |
+| '-------------'    '----------'        |                           |
+|                                  instructions                      |
+|                                        |                           |
+|                                        v                           |
+| .-------------.                  .----------.     .--------------. |
+| | build input |---------.       ( build task )--->| build result | |
+| '-------------'         |        '----------'     '--------------' |
+|                    instructions        ^                           |
+|                         |              |                           |
+|                         v              |                           |
+| .-------------.    .----------.        |                           |
+| | build input |-->( build task )-------'                           |
+| '-------------'    '----------'                                    |
+|                         ^                                          |
+|                         |                                          |
+|                         |                                          |
+| .-------------.         |                                          |
+| | build input |---------'                                          |
+| '-------------'                                                    |
+|                                                                    |
++--------------------------------------------------------------------+
 ```
 
-[layer-architecture]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
-[purely-functional-programming]: https://en.m.wikipedia.org/wiki/Purely_functional_programming

doc/manual/src/architecture/store/fso.md

@@ -1,69 +0,0 @@
-# File System Object
-
-The Nix store uses a simple file system model for the data it holds in [store objects](store.md#store-object).
-
-Every file system object is one of the following:
-
- - File: an executable flag, and arbitrary data for contents
- - Directory: mapping of names to child file system objects
- - [Symbolic link][symlink]: may point anywhere.
-
-We call a store object's outermost file system object the *root*.
-
-    data FileSystemObject
-      = File      { isExecutable :: Bool, contents :: Bytes }
-      | Directory { entries :: Map FileName FileSystemObject }
-      | SymLink   { target :: Path }
-
-Examples:
-
-- a directory with contents
-
-      /nix/store/<hash>-hello-2.10
-      ├── bin
-      │   └── hello
-      └── share
-          ├── info
-          │   └── hello.info
-          └── man
-              └── man1
-                  └── hello.1.gz
-
-- a directory with relative symlink and other contents
-
-      /nix/store/<hash>-go-1.16.9
-      ├── bin -> share/go/bin
-      ├── nix-support/
-      └── share/
-
-- a directory with absolute symlink
-
-      /nix/store/d3k...-nodejs
-      └── nix_node -> /nix/store/f20...-nodejs-10.24.
-
-A bare file or symlink can be a root file system object.
-Examples:
-
-    /nix/store/<hash>-hello-2.10.tar.gz
-
-    /nix/store/4j5...-pkg-config-wrapper-0.29.2-doc -> /nix/store/i99...-pkg-config-0.29.2-doc
-
-Symlinks pointing outside of their own root or to a store object without a matching reference are allowed, but might not function as intended.
-Examples:
-
-- an arbitrarily symlinked file may change or not exist at all
-
-      /nix/store/<hash>-foo
-      └── foo -> /home/foo
-
-- if a symlink to a store path was not automatically created by Nix, it may be invalid or get invalidated when the store object is deleted
-
-      /nix/store/<hash>-bar
-      └── bar -> /nix/store/abc...-foo
-
-Nix file system objects do not support [hard links][hardlink]:
-each file system object which is not the root has exactly one parent and one name.
-However, as store objects are immutable, an underlying file system can use hard links for optimization.
-
-[symlink]: https://en.m.wikipedia.org/wiki/Symbolic_link
-[hardlink]: https://en.m.wikipedia.org/wiki/Hard_link

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

@@ -1,105 +0,0 @@
-# Store Path
-
-Nix implements [references](store.md#reference) to [store objects](store.md#store-object) as *store paths*.
-
-Store paths are pairs of
-
-- a 20-byte [digest](#digest) for identification
-- a symbolic name for people to read.
-
-Example:
-
-- digest: `b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z`
-- name:   `firefox-33.1`
-
-It is rendered to a file system path as the concatenation of
-
-  - [store directory](#store-directory)
-  - path-separator (`/`)
-  - [digest](#digest) rendered in a custom variant of [base-32](https://en.m.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
-  - hyphen (`-`)
-  - name
-
-Example:
-
-      /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
-      |--------| |------------------------------| |----------|
-    store directory            digest                 name
-
-## Store Directory
-
-Every [store](./store.md) has a store directory.
-
-If the store has a [file system representation](./store.md#files-and-processes), this directory contains the store’s [file system objects](#file-system-object), which can be addressed by [store paths](#store-path).
-
-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**
-> The store directory defaults to `/nix/store`, but is in principle arbitrary.
-
-It is important which store a given store object belongs to:
-Files in the store object can contain store paths, and processes may read these paths.
-Nix can only guarantee [referential integrity](store/closure.md) if store paths do not cross store boundaries.
-
-Therefore one can only copy store objects to a different store if
-
-- the source and target stores' directories match
-
-  or
-
-- the store object in question has no references, that is, contains no store paths.
-
-One cannot copy a store object to a store with a different store directory.
-Instead, it has to be rebuilt, together with all its dependencies.
-It is in general not enough to replace the store directory string in file contents, as this may render executables unusable by invalidating their internal offsets or checksums.
-
-# Digest
-
-In a [store path](#store-path), the [digest][digest] is the output of a [cryptographic hash function][hash] of either all *inputs* involved in building the referenced store object or its actual *contents*.
-
-Store objects are therefore said to be either [input-addressed](#input-addressing) or [content-addressed](#content-addressing).
-
-> **Historical Note**
-> The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
-> Nix now uses [SHA-256][sha-256], and longer hashes are still reduced to 20 bytes for compatibility.
-
-[digest]: https://en.m.wiktionary.org/wiki/digest#Noun
-[hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
-[sha-1]: https://en.m.wikipedia.org/wiki/SHA-1
-[sha-256]: https://en.m.wikipedia.org/wiki/SHA-256
-
-### Reference scanning
-
-When a new store object is built, Nix scans its file contents for store paths to construct its set of references.
-
-The special format of a store path's [digest](#digest) allows reliably detecting it among arbitrary data.
-Nix uses the [closure](store.md#closure) of build inputs to derive the list of allowed store paths, to avoid false positives.
-
-This way, scanning files captures run time dependencies without the user having to declare them explicitly.
-Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
-
-> **Note**
-> In practice, it is sometimes still necessary for users to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
-This depends on the specifics of the software to build and run.
->
-> For example, Java programs are compressed after compilation, which obfuscates any store paths they may refer to and prevents Nix from automatically detecting them.
-
-## Input Addressing
-
-Input addressing means that the digest derives from how the store object was produced, namely its build inputs and build plan.
-
-To compute the hash of a store object one needs a deterministic serialisation, i.e., a binary string representation which only changes if the store object changes.
-
-Nix has a custom serialisation format called Nix Archive (NAR)
-
-Store object references of this sort can *not* be validated from the content of the store object.
-Rather, a cryptographic signature has to be used to indicate that someone is vouching for the store object really being produced from a build plan with that digest.
-
-## Content Addressing
-
-Content addressing means that the digest derives from the store object's contents, namely its file system objects and references.
-If one knows content addressing was used, one can recalculate the reference and thus verify the store object.
-
-Content addressing is currently only used for the special cases of source files and "fixed-output derivations", where the contents of a store object are known in advance.
-Content addressing of build results is still an [experimental feature subject to some restrictions](https://github.com/tweag/rfcs/blob/cas-rfc/rfcs/0062-content-addressed-paths.md).
-

doc/manual/src/architecture/store/store.md

@@ -1,151 +0,0 @@
-# Store
-
-A Nix store is a collection of *store objects* with references between them.
-It supports operations to manipulate that collection.
-
-The following concept map is a graphical outline of this chapter.
-Arrows indicate suggested reading order.
-
-```
-                      ,--------------[ store ]----------------,
-                      |                  |                    |
-                      v                  v                    v
-               [ store object ]     [ closure ]--,      [ operations ]
-                      |               |   |      |        |        |
-                      v               |   |      v        v        |
-           [ files and processes ]    |   | [ garbage collection ] |
-               /          \           |   |                        |
-              v            v          |   v                        v
-[ file system object ] [ store path ] | [ derivation ]--->[ building ]
-                  |        ^      |   |                         |
-                  v        |      v   v                         |
-             [ digest ]----' [ reference scanning ]<------------'
-              /      \
-             v        v
-[ input addressing ] [ content addressing ]
-```
-
-## Store Object
-
-A store object can hold
-
-- arbitrary *data*
-- *references* to other store objects.
-
-Store objects can be build inputs, build results, or build tasks.
-
-Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
-
-## Reference
-
-A store object reference is an [opaque][opaque-data-type], [unique identifier][unique-identifier]:
-The only way to obtain references is by adding or building store objects.
-A reference will always point to exactly one store object.
-
-## Operations
-
-A Nix store can *add*, *retrieve*, and *delete* store objects.
-
-                [ data ]
-                    |
-                    V
-    [ store ] ---> add ----> [ store' ]
-                    |
-                    V
-              [ reference ]
-
-<!-- -->
-
-              [ reference ]
-                    |
-                    V
-    [ store ] ---> get
-                    |
-                    V
-             [ store object ]
-
-<!-- -->
-
-              [ reference ]
-                    |
-                    V
-    [ store ] --> delete --> [ store' ]
-
-
-It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks.
-
-
-              [ reference ]
-                    |
-                    V
-    [ store ] --> build --(maybe)--> [ store' ]
-                             |
-                             V
-                       [ reference ]
-
-
-As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
-
-
-    [ store ] --> collect garbage --> [ store' ]
-
-## Files and Processes
-
-Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
-That allows processes to resolve references contained in files and thus access the contents of store objects.
-
-Store objects are therefore implemented as the pair of
-
-  - a [file system object](fso.md) for data
-  - a set of [store paths](path.md) for references.
-
-[unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file
-[file-descriptor]: https://en.m.wikipedia.org/wiki/File_descriptor
-
-The following diagram shows a radical simplification of how Nix interacts with the operating system:
-It uses files as build inputs, and build outputs are files again.
-On the operating system, files can be run as processes, which in turn operate on files.
-A build function also amounts to an operating system process (not depicted).
-
-```
-+-----------------------------------------------------------------+
-| Nix                                                             |
-|                  [ commmand line interface ]------,             |
-|                               |                   |             |
-|                           evaluates               |             |
-|                               |                manages          |
-|                               V                   |             |
-|                  [ configuration language  ]      |             |
-|                               |                   |             |
-| +-----------------------------|-------------------V-----------+ |
-| | store                  evaluates to                         | |
-| |                             |                               | |
-| |             referenced by   V       builds                  | |
-| |  [ build input ] ---> [ build plan ] ---> [ build result ]  | |
-| |         ^                                        |          | |
-| +---------|----------------------------------------|----------+ |
-+-----------|----------------------------------------|------------+
-            |                                        |
-    file system object                          store path
-            |                                        |
-+-----------|----------------------------------------|------------+
-| operating system        +------------+             |            |
-|           '------------ |            | <-----------'            |
-|                         |    file    |                          |
-|                     ,-- |            | <-,                      |
-|                     |   +------------+   |                      |
-|          execute as |                    | read, write, execute |
-|                     |   +------------+   |                      |
-|                     '-> |  process   | --'                      |
-|                         +------------+                          |
-+-----------------------------------------------------------------+
-```
-
-There exist different types of stores, which all follow this model.
-Examples:
-- store on the local file system
-- remote store accessible via SSH
-- binary cache store accessible via HTTP
-
-To make store objects accessible to processes, stores ultimately have to expose store objects through the file system.
-

doc/manual/src/architecture/store/store/build-system-terminology.md

@@ -1,32 +0,0 @@
-# A [Rosetta stone][rosetta-stone] for build system terminology
-
-The Nix store's design is comparable to other build systems.
-Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
-
-The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
-
-| generic build system             | Nix              | [Bazel][bazel]                                                       | [Build Systems à la Carte][bsalc] | programming language     |
-| -------------------------------- | ---------------- | -------------------------------------------------------------------- | --------------------------------- | ------------------------ |
-| data (build input, build result) | store object     | [artifact][bazel-artifact]                                           | value                             | value                    |
-| build instructions               | builder          | ([depends on action type][bazel-actions])                            | function                          | function                 |
-| build task                       | derivation       | [action][bazel-action]                                               | `Task`                            | [thunk][thunk]           |
-| build plan                       | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks`                           | [call graph][call-graph] |
-| build                            | build            | build                                                                | application of `Build`            | evaluation               |
-| persistence layer                | store            | [action cache][bazel-action-cache]                                   | `Store`                           | heap                     |
-
-All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
-
-[rosetta-stone]: https://en.m.wikipedia.org/wiki/Rosetta_Stone
-[bazel]: https://bazel.build/start/bazel-intro
-[bazel-artifact]: https://bazel.build/reference/glossary#artifact
-[bazel-actions]: https://docs.bazel.build/versions/main/skylark/lib/actions.html
-[bazel-action]: https://bazel.build/reference/glossary#action
-[bazel-action-graph]: https://bazel.build/reference/glossary#action-graph
-[bazel-build-graph]: https://bazel.build/reference/glossary#build-graph
-[bazel-action-cache]: https://bazel.build/reference/glossary#action-cache
-[thunk]: https://en.m.wikipedia.org/wiki/Thunk
-[call-graph]: https://en.m.wikipedia.org/wiki/Call_graph
-[declarative-programming]: https://en.m.wikipedia.org/wiki/Declarative_programming
-[immdsd]: https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf
-[phd-thesis]: https://edolstra.github.io/pubs/phd-thesis.pdf
-[bsalc]: https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf

doc/manual/src/architecture/store/store/closure.md

@@ -1,29 +0,0 @@
-# Closure
-
-Nix stores ensure [referential integrity][referential-integrity]: for each store object in the store, all the store objects it references must also be in the store.
-
-The set of all store objects reachable by following references from a given initial set of store objects is called a *closure*.
-
-Adding, building, copying and deleting store objects must be done in a way that preserves referential integrity:
-
-- A newly added store object cannot have references, unless it is a build task.
-
-- Build results must only refer to store objects in the closure of the build inputs.
-
-  Building a store object will add appropriate references, according to the build task.
-
-- Store objects being copied must refer to objects already in the destination store.
-
-  Recursive copying must either proceed in dependency order or be atomic.
-
-- We can only safely delete store objects which are not reachable from any reference still in use.
-
-  <!-- more details in section on garbage collection, link to it once it exists -->
-
-[referential-integrity]: https://en.m.wikipedia.org/wiki/Referential_integrity
-[garbage-collection]: https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)
-[immutable-object]: https://en.m.wikipedia.org/wiki/Immutable_object
-[opaque-data-type]: https://en.m.wikipedia.org/wiki/Opaque_data_type
-[unique-identifier]: https://en.m.wikipedia.org/wiki/Unique_identifier
-
-

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

@@ -7,42 +7,11 @@ Most Nix commands interpret the following environment variables:
     `nix-shell`. It can have the values `pure` or `impure`.
 
   - [`NIX_PATH`]{#env-NIX_PATH}\
-    A colon-separated list of directories used to look up Nix
-    expressions enclosed in angle brackets (i.e., `<path>`). For
-    instance, the value
-
-        /home/eelco/Dev:/etc/nixos
-
-    will cause Nix to look for paths relative to `/home/eelco/Dev` and
-    `/etc/nixos`, in this order. It is also possible to match paths
-    against a prefix. For example, the value
-
-        nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos
-
-    will cause Nix to search for `<nixpkgs/path>` in
-    `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`.
-
-    If a path in the Nix search path starts with `http://` or
-    `https://`, it is interpreted as the URL of a tarball that will be
-    downloaded and unpacked to a temporary location. The tarball must
-    consist of a single top-level directory. For example, setting
-    `NIX_PATH` to
-
-        nixpkgs=https://github.com/NixOS/nixpkgs/archive/master.tar.gz
-
-    tells Nix to download and use the current contents of the
-    `master` branch in the `nixpkgs` repository.
-
-    The URLs of the tarballs from the official nixos.org channels (see
-    [the manual for `nix-channel`](nix-channel.md)) can be abbreviated
-    as `channel:<channel-name>`.  For instance, the following two
-    values of `NIX_PATH` are equivalent:
-
-        nixpkgs=channel:nixos-21.05
-        nixpkgs=https://nixos.org/channels/nixos-21.05/nixexprs.tar.xz
-
-    The Nix search path can also be extended using the `-I` option to
-    many Nix commands, which takes precedence over `NIX_PATH`.
+    A colon-separated list of directories used to look up the location of Nix
+    expressions using [paths](../language/values.md#type-path)
+    enclosed in angle brackets (i.e., `<path>`),
+    e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
+    [`-I` option](./opt-common.md#opt-I).
 
   - [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
     Normally, the Nix store directory (typically `/nix/store`) is not
@@ -122,3 +91,16 @@ Most Nix commands interpret the following environment variables:
     variable sets the initial size of the heap in bytes. It defaults to
     384 MiB. Setting it to a low value reduces memory consumption, but
     will increase runtime due to the overhead of garbage collection.
+
+## XDG Base Directory
+
+New Nix commands conform to the [XDG Base Directory Specification], and use the following environment variables to determine locations of various state and configuration files:
+
+- [`XDG_CONFIG_HOME`]{#env-XDG_CONFIG_HOME} (default `~/.config`)
+- [`XDG_STATE_HOME`]{#env-XDG_STATE_HOME} (default `~/.local/state`)
+- [`XDG_CACHE_HOME`]{#env-XDG_CACHE_HOME} (default `~/.cache`)
+
+Classic Nix commands can also be made to follow this standard using the [`use-xdg-base-directories`] configuration option.
+
+[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+[`use-xdg-base-directories`]: ../command-ref/conf-file.md#conf-use-xdg-base-directories

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

@@ -37,10 +37,12 @@ directory containing at least a file named `default.nix`.
 
 `nix-build` is essentially a wrapper around
 [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix
-expression to a low-level store derivation) and [`nix-store
+expression to a low-level [store derivation]) and [`nix-store
 --realise`](nix-store.md#operation---realise) (to build the store
 derivation).
 
+[store derivation]: ../glossary.md#gloss-store-derivation
+
 > **Warning**
 >
 > The result of the build is automatically registered as a root of the
@@ -53,16 +55,18 @@ All options not listed here are passed to `nix-store
 --realise`, except for `--arg` and `--attr` / `-A` which are passed to
 `nix-instantiate`.
 
-  - [`--no-out-link`]{#opt-no-out-link}\
+  - <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
+
     Do not create a symlink to the output path. Note that as a result
     the output does not become a root of the garbage collector, and so
-    might be deleted by `nix-store
-                    --gc`.
+    might be deleted by `nix-store --gc`.
+
+  - <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
 
-  - [`--dry-run`]{#opt-dry-run}\
     Show what store paths would be built or downloaded.
 
-  - [`--out-link`]{#opt-out-link} / `-o` *outlink*\
+  - <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
+
     Change the name of the symlink to the output path created from
     `result` to *outlink*.
 

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

@@ -30,8 +30,8 @@ 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.  If this bothers you, use
-`ssh-agent`.
+and second to send the dump of those paths.  When using public key
+authentication, you can avoid typing the passphrase with `ssh-agent`.
 
 # Options
 
@@ -47,7 +47,9 @@ and second to send the dump of those paths.  If this bothers you, use
     Enable compression of the SSH connection.
 
   - `--include-outputs`\
-    Also copy the outputs of store derivations included in the closure.
+    Also copy the outputs of [store derivation]s included in the closure.
+
+    [store derivation]: ../glossary.md#gloss-store-derivation
 
   - `--use-substitutes` / `-s`\
     Attempt to download missing paths on the target machine using Nix’s

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

@@ -8,6 +8,6 @@
 
 # Description
 
-The Nix daemon is necessary in multi-user Nix installations. It performs
-build actions and other operations on the Nix store on behalf of
+The Nix daemon is necessary in multi-user Nix installations. It runs
+build tasks and other operations on the Nix store on behalf of
 unprivileged users.

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

@@ -205,10 +205,12 @@ a number of possible ways:
     unambiguous way, which is necessary if there are multiple
     derivations with the same name.
 
-  - If *args* are store derivations, then these are
+  - If *args* are [store derivation]s, then these are
     [realised](nix-store.md#operation---realise), and the resulting output paths
     are installed.
 
+    [store derivation]: ../glossary.md#gloss-store-derivation
+
   - If *args* are store paths that are not store derivations, then these
     are [realised](nix-store.md#operation---realise) and installed.
 
@@ -280,7 +282,7 @@ To copy the store path with symbolic name `gcc` from another profile:
 $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
 ```
 
-To install a specific store derivation (typically created by
+To install a specific [store derivation] (typically created by
 `nix-instantiate`):
 
 ```console
@@ -665,7 +667,7 @@ derivation is shown unless `--no-name` is specified.
     Print the `system` attribute of the derivation.
 
   - `--drv-path`\
-    Print the path of the store derivation.
+    Print the path of the [store derivation].
 
   - `--out-path`\
     Print the output path of the derivation.

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

@@ -17,13 +17,14 @@
 
 # Description
 
-The command `nix-instantiate` generates [store
-derivations](../glossary.md) from (high-level) Nix expressions. It
-evaluates the Nix expressions in each of *files* (which defaults to
+The command `nix-instantiate` produces [store derivation]s from (high-level) Nix expressions.
+It evaluates the Nix expressions in each of *files* (which defaults to
 *./default.nix*). Each top-level expression should evaluate to a
 derivation, a list of derivations, or a set of derivations. The paths
 of the resulting store derivations are printed on standard output.
 
+[store derivation]: ../glossary.md#gloss-store-derivation
+
 If *files* is the character `-`, then a Nix expression will be read from
 standard input.
 
@@ -79,8 +80,7 @@ standard input.
 
 # Examples
 
-Instantiating store derivations from a Nix expression, and building them
-using `nix-store`:
+Instantiate [store derivation]s from a Nix expression, and build them using `nix-store`:
 
 ```console
 $ nix-instantiate test.nix (instantiate)

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

@@ -22,7 +22,8 @@ This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
 have an effect.
 
-  - [`--add-root`]{#opt-add-root} *path*\
+  - <span id="opt-add-root">[`--add-root`](#opt-add-root)</span> *path*
+
     Causes the result of a realisation (`--realise` and
     `--force-realise`) to be registered as a root of the garbage
     collector. *path* will be created as a symlink to the resulting
@@ -65,13 +66,13 @@ The operation `--realise` essentially “builds” the specified store
 paths. Realisation is a somewhat overloaded term:
 
   - If the store path is a *derivation*, realisation ensures that the
-    output paths of the derivation are [valid](../glossary.md) (i.e.,
+    output paths of the derivation are [valid] (i.e.,
     the output path and its closure exist in the file system). This
     can be done in several ways. First, it is possible that the
     outputs are already valid, in which case we are done
-    immediately. Otherwise, there may be [substitutes](../glossary.md)
+    immediately. Otherwise, there may be [substitutes]
     that produce the outputs (e.g., by downloading them). Finally, the
-    outputs can be produced by performing the build action described
+    outputs can be produced by running the build task described
     by the derivation.
 
   - If the store path is not a derivation, realisation ensures that the
@@ -81,6 +82,9 @@ paths. Realisation is a somewhat overloaded term:
     produced through substitutes. If there are no (successful)
     substitutes, realisation fails.
 
+[valid]: ../glossary.md#gloss-validity
+[substitutes]: ../glossary.md#gloss-substitute
+
 The output path of each derivation is printed on standard output. (For
 non-derivations argument, the argument itself is printed.)
 
@@ -104,10 +108,6 @@ The following flags are available:
     previous build, the new output path is left in
     `/nix/store/name.check.`
 
-    See also the `build-repeat` configuration option, which repeats a
-    derivation a number of times and prevents its outputs from being
-    registered as “valid” in the Nix store unless they are identical.
-
 Special exit codes:
 
   - `100`\
@@ -140,8 +140,10 @@ or.
 
 ## Examples
 
-This operation is typically used to build store derivations produced by
-[`nix-instantiate`](nix-instantiate.md):
+This operation is typically used to build [store derivation]s produced by
+[`nix-instantiate`](./nix-instantiate.md):
+
+[store derivation]: ../glossary.md#gloss-store-derivation
 
 ```console
 $ nix-store -r $(nix-instantiate ./test.nix)
@@ -156,6 +158,12 @@ To test whether a previously-built derivation is deterministic:
 $ nix-build '<nixpkgs>' -A hello --check -K
 ```
 
+Use [`--read-log`](#operation---read-log) to show the stderr and stdout of a build:
+
+```console
+$ nix-store --read-log $(nix-instantiate ./test.nix)
+```
+
 # Operation `--serve`
 
 ## Synopsis
@@ -290,8 +298,8 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4'
 
 ## Description
 
-The operation `--query` displays various bits of information about the
-store paths . The queries are described below. At most one query can be
+The operation `--query` displays information about [store path]s.
+The queries are described below. At most one query can be
 specified. The default query is `--outputs`.
 
 The paths *paths* may also be symlinks from outside of the Nix store, to
@@ -301,7 +309,7 @@ symlink.
 ## Common query options
 
   - `--use-output`; `-u`\
-    For each argument to the query that is a store derivation, apply the
+    For each argument to the query that is a [store derivation], apply the
     query to the output path of the derivation instead.
 
   - `--force-realise`; `-f`\
@@ -311,17 +319,17 @@ symlink.
 ## Queries
 
   - `--outputs`\
-    Prints out the [output paths](../glossary.md) of the store
+    Prints out the [output path]s of the store
     derivations *paths*. These are the paths that will be produced when
     the derivation is built.
 
   - `--requisites`; `-R`\
-    Prints out the [closure](../glossary.md) of the store path *paths*.
+    Prints out the [closure] of the given *paths*.
 
     This query has one option:
 
       - `--include-outputs`
-        Also include the existing output paths of store derivations,
+        Also include the existing output paths of [store derivation]s,
         and their closures.
 
     This query can be used to implement various kinds of deployment. A
@@ -333,10 +341,12 @@ symlink.
     derivation and specifying the option `--include-outputs`.
 
   - `--references`\
-    Prints the set of [references](../glossary.md) of the store paths
+    Prints the set of [references]s of the store paths
     *paths*, that is, their immediate dependencies. (For *all*
     dependencies, use `--requisites`.)
 
+    [reference]: ../glossary.md#gloss-reference
+
   - `--referrers`\
     Prints the set of *referrers* of the store paths *paths*, that is,
     the store paths currently existing in the Nix store that refer to
@@ -351,11 +361,13 @@ symlink.
     in the Nix store that are dependent on *paths*.
 
   - `--deriver`; `-d`\
-    Prints the [deriver](../glossary.md) of the store paths *paths*. If
+    Prints the [deriver] of the store paths *paths*. If
     the path has no deriver (e.g., if it is a source file), or if the
     deriver is not known (e.g., in the case of a binary-only
     deployment), the string `unknown-deriver` is printed.
 
+    [deriver]: ../glossary.md#gloss-deriver
+
   - `--graph`\
     Prints the references graph of the store paths *paths* in the format
     of the `dot` tool of AT\&T's [Graphviz
@@ -375,12 +387,12 @@ symlink.
     Prints the references graph of the store paths *paths* in the
     [GraphML](http://graphml.graphdrawing.org/) file format. This can be
     used to visualise dependency graphs. To obtain a build-time
-    dependency graph, apply this to a store derivation. To obtain a
+    dependency graph, apply this to a [store derivation]. To obtain a
     runtime dependency graph, apply it to an output path.
 
   - `--binding` *name*; `-b` *name*\
     Prints the value of the attribute *name* (i.e., environment
-    variable) of the store derivations *paths*. It is an error for a
+    variable) of the [store derivation]s *paths*. It is an error for a
     derivation to not have the specified attribute.
 
   - `--hash`\
@@ -621,7 +633,7 @@ written to standard output.
 
 A NAR archive is like a TAR or Zip archive, but it contains only the
 information that Nix considers important. For instance, timestamps are
-elided because all files in the Nix store have their timestamp set to 0
+elided because all files in the Nix store have their timestamp set to 1
 anyway. Likewise, all permissions are left out except for the execute
 bit, because all files in the Nix store have 444 or 555 permission.
 

doc/manual/src/contributing/hacking.md

@@ -8,25 +8,64 @@ $ git clone https://github.com/NixOS/nix.git
 $ cd nix
 ```
 
-To build Nix for the current operating system/architecture use
+The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment. If you don't have it installed, follow the [installation instructions].
+
+[installation instructions]: ../installation/installation.md
+
+## Nix with flakes
+
+This section assumes you are using Nix with [flakes] enabled. See the [next section](#classic-nix) for equivalent instructions which don't require flakes.
+
+[flakes]: ../command-ref/new-cli/nix3-flake.md#description
+
+To build all dependencies and start a shell in which all environment
+variables are set up so that those dependencies can be found:
 
 ```console
-$ nix-build
+$ nix develop
 ```
 
-or if you have a flake-enabled nix:
+This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` immediately after building it.
+
+To get a shell with one of the other [supported compilation environments](#compilation-environments):
+
+```console
+$ nix develop .#native-clang11StdenvPackages
+```
+
+> **Note**
+>
+> Use `ccacheStdenv` to drastically improve rebuild time.
+> By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
+
+To build Nix itself in this shell:
+
+```console
+[nix-shell]$ ./bootstrap.sh
+[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
+[nix-shell]$ make -j $NIX_BUILD_CORES
+```
+
+To install it in `$(pwd)/outputs` and test it:
+
+```console
+[nix-shell]$ make install
+[nix-shell]$ make installcheck -j $NIX_BUILD_CORES
+[nix-shell]$ nix --version
+nix (Nix) 2.12
+```
+
+To build a release version of Nix:
 
 ```console
 $ nix build
 ```
 
-This will build `defaultPackage` attribute defined in the `flake.nix`
-file. To build for other platforms add one of the following suffixes to
-it: aarch64-linux, i686-linux, x86\_64-darwin, x86\_64-linux. i.e.
+You can also build Nix for one of the [supported target platforms](#target-platforms).
 
-```console
-$ nix-build -A defaultPackage.x86_64-linux
-```
+## Classic Nix
+
+This section is for Nix without [flakes].
 
 To build all dependencies and start a shell in which all environment
 variables are set up so that those dependencies can be found:
@@ -35,24 +74,16 @@ variables are set up so that those dependencies can be found:
 $ nix-shell
 ```
 
-or if you have a flake-enabled nix:
+To get a shell with one of the other [supported compilation environments](#compilation-environments):
 
 ```console
-$ nix develop
+$ nix-shell -A devShells.x86_64-linux.native-clang11StdenvPackages
 ```
 
-To get a shell with a different compilation environment (e.g. stdenv,
-gccStdenv, clangStdenv, clang11Stdenv):
-
-```console
-$ nix-shell -A devShells.x86_64-linux.clang11StdenvPackages
-```
-
-or if you have a flake-enabled nix:
-
-```console
-$ nix develop .#clang11StdenvPackages
-```
+> **Note**
+>
+> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time.
+> By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
 
 To build Nix itself in this shell:
 
@@ -68,38 +99,186 @@ To install it in `$(pwd)/outputs` and test it:
 [nix-shell]$ make install
 [nix-shell]$ make installcheck -j $NIX_BUILD_CORES
 [nix-shell]$ ./outputs/out/bin/nix --version
-nix (Nix) 3.0
+nix (Nix) 2.12
 ```
 
-If you have a flakes-enabled Nix you can replace:
+To build Nix for the current operating system and CPU architecture use
 
 ```console
-$ nix-shell
+$ nix-build
 ```
 
-by:
+You can also build Nix for one of the [supported target platforms](#target-platforms).
+
+## Platforms
+
+As specified in [`flake.nix`], Nix can be built for various platforms:
+
+- `aarch64-linux`
+- `i686-linux`
+- `x86_64-darwin`
+- `x86_64-linux`
+
+[`flake.nix`]: https://github.com/nixos/nix/blob/master/flake.nix
+
+In order to build Nix for a different platform than the one you're currently
+on, you need to have some way for your system Nix to build code for that
+platform. Common solutions include [remote builders] and [binfmt emulation]
+(only supported on NixOS).
+
+[remote builders]: ../advanced-topics/distributed-builds.md
+[binfmt emulation]: https://nixos.org/manual/nixos/stable/options.html#opt-boot.binfmt.emulatedSystems
+
+These solutions let Nix perform builds as if you're on the native platform, so
+executing the build is as simple as
 
 ```console
-$ nix develop
+$ nix build .#packages.aarch64-linux.default
 ```
 
-## Testing
+for flake-enabled Nix, or
 
-Nix comes with three different flavors of tests: unit, functional and integration.
+```console
+$ nix-build -A packages.aarch64-linux.default
+```
+
+for classic Nix.
+
+You can use any of the other supported platforms in place of `aarch64-linux`.
+
+Cross-compiled builds are available for ARMv6 and ARMv7, and Nix on unsupported platforms can be bootstrapped by adding more `crossSystems` in `flake.nix`.
+
+## Compilation environments
+
+Nix can be compiled using multiple environments:
+
+- `stdenv`: default;
+- `gccStdenv`: force the use of `gcc` compiler;
+- `clangStdenv`: force the use of `clang` compiler;
+- `ccacheStdenv`: enable [ccache], a compiler cache to speed up compilation.
+
+To build with one of those environments, you can use
+
+```console
+$ nix build .#nix-ccacheStdenv
+```
+
+for flake-enabled Nix, or
+
+```console
+$ nix-build -A nix-ccacheStdenv
+```
+
+for classic Nix.
+
+You can use any of the other supported environments in place of `nix-ccacheStdenv`.
+
+## Editor integration
+
+The `clangd` LSP server is installed by default on the `clang`-based `devShell`s.
+See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#nix-with-flakes) or in [classic Nix](#classic-nix).
+
+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 clean && bear -- make -j$NIX_BUILD_CORES install
+```
+
+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**
+>
+> For some editors (e.g. Visual Studio Code), you may need to install a [special extension](https://open-vsx.org/extension/llvm-vs-code-extensions/vscode-clangd) for the editor to interact with `clangd`.
+> 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.
+
+## Running tests
 
 ### Unit-tests
 
 The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined
 under `src/{library_name}/tests` using the
-[googletest](https://google.github.io/googletest/) framework.
+[googletest](https://google.github.io/googletest/) and
+[rapidcheck](https://github.com/emil-e/rapidcheck) frameworks.
 
 You can run the whole testsuite with `make check`, or the tests for a specific component with `make libfoo-tests_RUN`. Finer-grained filtering is also possible using the [--gtest_filter](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) command-line option.
 
 ### Functional tests
 
 The functional tests reside under the `tests` directory and are listed in `tests/local.mk`.
-The whole testsuite can be run with `make install && make installcheck`.
-Individual tests can be run with `make tests/{testName}.sh.test`.
+Each test is a bash script.
+
+The whole test suite can be run with:
+
+```shell-session
+$ make install && make installcheck
+ran test tests/foo.sh... [PASS]
+ran test tests/bar.sh... [PASS]
+...
+```
+
+Individual tests can be run with `make`:
+
+```shell-session
+$ make tests/${testName}.sh.test
+ran test tests/${testName}.sh... [PASS]
+```
+
+or without `make`:
+
+```shell-session
+$ ./mk/run-test.sh tests/${testName}.sh
+ran test tests/${testName}.sh... [PASS]
+```
+
+To see the complete output, one can also run:
+
+```shell-session
+$ ./mk/debug-test.sh tests/${testName}.sh
++ foo
+output from foo
++ bar
+output from bar
+...
+```
+
+The test script will then be traced with `set -x` and the output displayed as it happens, regardless of whether the test succeeds or fails.
+
+#### Debugging failing functional tests
+
+When a functional test fails, it usually does so somewhere in the middle of the script.
+
+To figure out what's wrong, it is convenient to run the test regularly up to the failing `nix` command, and then run that command with a debugger like GDB.
+
+For example, if the script looks like:
+
+```bash
+foo
+nix blah blub
+bar
+```
+edit it like so:
+
+```diff
+ foo
+-nix blah blub
++gdb --args nix blah blub
+ bar
+```
+
+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/${testName}.sh
+...
++ gdb blash blub
+GNU gdb (GDB) 12.1
+...
+(gdb)
+```
+
+One can debug the Nix invocation in all the usual ways.
+For example, enter `run` to start the Nix invocation.
 
 ### Integration tests
 
@@ -108,3 +287,105 @@ These tests include everything that needs to interact with external services or
 Because these tests are expensive and require more than what the standard github-actions setup provides, they only run on the master branch (on <https://hydra.nixos.org/jobset/nix/master>).
 
 You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}`
+
+### Installer tests
+
+After a one-time setup, the Nix repository's GitHub Actions continuous integration (CI) workflow can test the installer each time you push to a branch.
+
+Creating a Cachix cache for your installer tests and adding its authorization token to GitHub enables [two installer-specific jobs in the CI workflow](https://github.com/NixOS/nix/blob/88a45d6149c0e304f6eb2efcc2d7a4d0d569f8af/.github/workflows/ci.yml#L50-L91):
+
+- The `installer` job generates installers for the platforms below and uploads them to your Cachix cache:
+  - `x86_64-linux`
+  - `armv6l-linux`
+  - `armv7l-linux`
+  - `x86_64-darwin`
+
+- The `installer_test` job (which runs on `ubuntu-latest` and `macos-latest`) will try to install Nix with the cached installer and run a trivial Nix command.
+
+#### One-time setup
+
+1. Have a GitHub account with a fork of the [Nix repository](https://github.com/NixOS/nix).
+2. At cachix.org:
+    - Create or log in to an account.
+    - Create a Cachix cache using the format `<github-username>-nix-install-tests`.
+    - Navigate to the new cache > Settings > Auth Tokens.
+    - Generate a new Cachix auth token and copy the generated value.
+3. At github.com:
+    - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret.
+    - Name the secret `CACHIX_AUTH_TOKEN`.
+    - Paste the copied value of the Cachix cache auth token.
+
+#### Using the CI-generated installer for manual testing
+
+After the CI run completes, you can check the output to extract the installer URL:
+1. Click into the detailed view of the CI run.
+2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them).
+3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`)
+4. Copy the value of `install_url`
+5. To generate an install command, plug this `install_url` and your GitHub username into this template:
+
+    ```console
+    curl -L <install_url> | sh -s -- --tarball-url-prefix https://<github-username>-nix-install-tests.cachix.org/serve
+    ```
+
+<!-- #### Manually generating test installers
+
+There's obviously a manual way to do this, and it's still the only way for
+platforms that lack GA runners.
+
+I did do this back in Fall 2020 (before the GA approach encouraged here). I'll
+sketch what I recall in case it encourages someone to fill in detail, but: I
+didn't know what I was doing at the time and had to fumble/ask around a lot--
+so I don't want to uphold any of it as "right". It may have been dumb or
+the _hard_ way from the getgo. Fundamentals may have changed since.
+
+Here's the build command I used to do this on and for x86_64-darwin:
+nix build --out-link /tmp/foo ".#checks.x86_64-darwin.binaryTarball"
+
+I used the stable out-link to make it easier to script the next steps:
+link=$(readlink /tmp/foo)
+cp $link/*-darwin.tar.xz ~/somewheres
+
+I've lost the last steps and am just going from memory:
+
+From here, I think I had to extract and modify the `install` script to point
+it at this tarball (which I scped to my own site, but it might make more sense
+to just share them locally). I extracted this script once and then just
+search/replaced in it for each new build.
+
+The installer now supports a `--tarball-url-prefix` flag which _may_ have
+solved this need?
+-->
+
+### Checking links in the manual
+
+The build checks for broken internal links.
+This happens late in the process, so `nix build` is not suitable for iterating.
+To build the manual incrementally, run:
+
+```console
+make html -j $NIX_BUILD_CORES
+```
+
+In order to reflect changes to the [Makefile], clear all generated files before re-building:
+
+[Makefile]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
+
+```console
+rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make html -j $NIX_BUILD_CORES
+```
+
+[`mdbook-linkcheck`] does not implement checking [URI fragments] yet.
+
+[`mdbook-linkcheck`]: https://github.com/Michael-F-Bryan/mdbook-linkcheck
+[URI fragments]: https://en.m.wikipedia.org/wiki/URI_fragment
+
+#### `@docroot@` variable
+
+`@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.
+
+If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
+
+If the `@docroot@` literal appears in an error message from the `mdbook-linkcheck` tool, the `@docroot@` replacement needs to be applied to the generated source file that mentions it.
+See existing `@docroot@` logic in the [Makefile].
+Regular markdown files used for the manual have a base path of their own and they can use relative paths instead of `@docroot@`.

doc/manual/src/glossary.md

@@ -1,26 +1,111 @@
 # Glossary
 
   - [derivation]{#gloss-derivation}\
-    A description of a build action. The result of a derivation is a
+    A description of a build task. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
-    using the [`derivation` primitive](language/derivations.md). These are
+    using the [`derivation` primitive](./language/derivations.md). These are
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
+    [derivation]: #gloss-derivation
+
+  - [store derivation]{#gloss-store-derivation}\
+    A [derivation] represented as a `.drv` file in the [store].
+    It has a [store path], like any [store object].
+
+    Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
+
+    See [`nix show-derivation`](./command-ref/new-cli/nix3-show-derivation.md) (experimental) for displaying the contents of store derivations.
+
+    [store derivation]: #gloss-store-derivation
+
+  - [instantiate]{#gloss-instantiate}, instantiation\
+    Translate a [derivation] into a [store derivation].
+
+    See [`nix-instantiate`](./command-ref/nix-instantiate.md).
+
+    [instantiate]: #gloss-instantiate
+
+  - [realise]{#gloss-realise}, realisation\
+    Ensure a [store path] is [valid][validity].
+
+    This means either running the `builder` executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter].
+
+    See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](./command-ref/nix-store.md#operation---realise).
+
+    See [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental).
+
+    [realise]: #gloss-realise
+
+  - [content-addressed derivation]{#gloss-content-addressed-derivation}\
+    A derivation which has the
+    [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
+    attribute set to `true`.
+
+  - [fixed-output derivation]{#gloss-fixed-output-derivation}\
+    A derivation which includes the
+    [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute.
+
   - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
     `/nix/store`.
 
+    From   the  perspective   of   the  location   where  Nix   is
+    invoked, the  Nix store can be  referred to
+    as a "_local_" or a "_remote_" one:
+
+    + A *local  store* exists  on the filesystem of
+      the machine where Nix is  invoked. You can use other
+      local stores  by passing  the `--store` flag  to the
+      `nix` command.  Local stores can be used for building derivations.
+
+    + A  *remote store*  exists  anywhere  other than  the
+      local  filesystem. One  example is  the `/nix/store`
+      directory on another machine,  accessed via `ssh` or
+      served by the `nix-serve` Perl script.
+
+    [store]: #gloss-store
+
+  - [chroot store]{#gloss-chroot-store}\
+    A local store whose canonical path is anything other than `/nix/store`.
+
+  - [binary cache]{#gloss-binary-cache}\
+    A *binary cache* is a Nix store which uses a different format: its
+    metadata and signatures are kept in `.narinfo` files rather than in a
+    Nix database.  This different format simplifies serving store objects
+    over the network, but cannot host builds.  Examples of binary caches
+    include S3 buckets and the [NixOS binary
+    cache](https://cache.nixos.org).
+
   - [store path]{#gloss-store-path}\
-    The location in the file system of a store object, i.e., an
+    The location of a [store object] in the file system, i.e., an
     immediate child of the Nix store directory.
 
+    Example: `/nix/store/a040m110amc4h71lds2jmr8qrkj2jhxd-git-2.38.1`
+
+    [store path]: #gloss-store-path
+
   - [store object]{#gloss-store-object}\
     A file that is an immediate child of the Nix store directory. These
     can be regular files, but also entire directory trees. Store objects
     can be sources (objects copied from outside of the store),
-    derivation outputs (objects produced by running a build action), or
-    derivations (files describing a build action).
+    derivation outputs (objects produced by running a build task), or
+    derivations (files describing a build task).
+
+    [store object]: #gloss-store-object
+
+  - [input-addressed store object]{#gloss-input-addressed-store-object}\
+    A store object produced by building a
+    non-[content-addressed](#gloss-content-addressed-derivation),
+    non-[fixed-output](#gloss-fixed-output-derivation)
+    derivation.
+
+  - [output-addressed store object]{#gloss-output-addressed-store-object}\
+    A store object whose store path hashes its content.  This
+    includes derivations, the outputs of
+    [content-addressed derivations](#gloss-content-addressed-derivation),
+    and the outputs of
+    [fixed-output derivations](#gloss-fixed-output-derivation).
 
   - [substitute]{#gloss-substitute}\
     A substitute is a command invocation stored in the Nix database that
@@ -29,6 +114,13 @@
     store object by downloading a pre-built version of the store object
     from some server.
 
+  - [substituter]{#gloss-substituter}\
+    A *substituter* is an additional store from which Nix will
+    copy store objects it doesn't have.  For details, see the
+    [`substituters` option](./command-ref/conf-file.md#conf-substituters).
+
+    [substituter]: #gloss-substituter
+
   - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
     the same output. This cannot be guaranteed in general (e.g., a
@@ -71,23 +163,31 @@
     to path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
     references `R` then `R` is also in the closure of `P`.
 
+    [closure]: #gloss-closure
+
   - [output path]{#gloss-output-path}\
-    A store path produced by a derivation.
+    A [store path] produced by a [derivation].
+
+    [output path]: #gloss-output-path
 
   - [deriver]{#gloss-deriver}\
-    The deriver of an *output path* is the store
-    derivation that built it.
+    The [store derivation] that produced an [output path].
 
   - [validity]{#gloss-validity}\
-    A store path is considered *valid* if it exists in the file system,
-    is listed in the Nix database as being valid, and if all paths in
-    its closure are also valid.
+    A store path is valid if all [store object]s in its [closure] can be read from the [store].
+
+    For a local store, this means:
+    - The store path leads to an existing [store object] in that [store].
+    - The store path is listed in the Nix database as being valid.
+    - All paths in the store path's [closure] are valid.
+
+    [validity]: #gloss-validity
 
   - [user environment]{#gloss-user-env}\
     An automatically generated store object that consists of a set of
     symlinks to “active” applications, i.e., other store paths. These
     are generated automatically by
-    [`nix-env`](command-ref/nix-env.md). See *profiles*.
+    [`nix-env`](./command-ref/nix-env.md). See *profiles*.
 
   - [profile]{#gloss-profile}\
     A symlink to the current *user environment* of a user, e.g.,
@@ -98,7 +198,18 @@
     store. It can contain regular files, directories and symbolic
     links.  NARs are generated and unpacked using `nix-store --dump`
     and `nix-store --restore`.
+
   - [`∅`]{#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.
+
   - [`ε`]{#gloss-epsilon}\
     The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute.
+
+  - [string interpolation]{#gloss-string-interpolation}\
+    Expanding expressions enclosed in `${ }` within a [string], [path], or [attribute name].
+
+    See [String interpolation](./language/string-interpolation.md) for details.
+
+    [string]: ./language/values.md#type-string
+    [path]: ./language/values.md#type-path
+    [attribute name]: ./language/values.md#attribute-set

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

@@ -27,7 +27,7 @@ Set the environment variable and install Nix
 
 ```console
 $ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
-$ sh <(curl -L https://nixos.org/nix/install)
+$ curl -L https://nixos.org/nix/install | sh
 ```
 
 In the shell profile and rc files (for example, `/etc/bashrc`,
@@ -38,7 +38,7 @@ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
 ```
 
 > **Note**
-> 
+>
 > You must not add the export and then do the install, as the Nix
 > installer will detect the presence of Nix configuration, and abort.
 

doc/manual/src/installation/installation.md

@@ -1,2 +1,38 @@
-This section describes how to install and configure Nix for first-time
-use.
+# Installation
+
+This section describes how to install and configure Nix for first-time use.
+
+The current recommended option on Linux and MacOS is [multi-user](#multi-user).
+
+## Multi-user
+
+This installation offers better sharing, improved isolation, and more security
+over a single user installation.
+
+This option requires either:
+
+* Linux running systemd, with SELinux disabled
+* MacOS
+
+```console
+$ bash <(curl -L https://nixos.org/nix/install) --daemon
+```
+
+## Single-user
+
+> Single-user is not supported on Mac.
+
+This installation has less requirements than the multi-user install, however it
+cannot offer equivalent sharing, isolation, or security.
+
+This option is suitable for systems without systemd.
+
+```console
+$ bash <(curl -L https://nixos.org/nix/install) --no-daemon
+```
+
+## Distributions
+
+The Nix community maintains installers for several distributions.
+
+They can be found in the [`nix-community/nix-installers`](https://github.com/nix-community/nix-installers) repository.

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

@@ -3,7 +3,7 @@
 The easiest way to install Nix is to run the following command:
 
 ```console
-$ sh <(curl -L https://nixos.org/nix/install)
+$ curl -L https://nixos.org/nix/install | sh
 ```
 
 This will run the installer interactively (causing it to explain what
@@ -27,7 +27,7 @@ you can authenticate with `sudo`.
 To explicitly select a single-user installation on your system:
 
 ```console
-$ sh <(curl -L https://nixos.org/nix/install) --no-daemon
+$ curl -L https://nixos.org/nix/install | sh -s -- --no-daemon
 ```
 
 This will perform a single-user installation of Nix, meaning that `/nix`
@@ -66,7 +66,7 @@ You can instruct the installer to perform a multi-user installation on
 your system:
 
 ```console
-$ sh <(curl -L https://nixos.org/nix/install) --daemon
+$ curl -L https://nixos.org/nix/install | sh -s -- --daemon
 ```
 
 The multi-user installation of Nix will create build users between the
@@ -88,19 +88,51 @@ extension. The installer will also create `/etc/profile.d/nix.sh`.
 
 ### Linux
 
-```console
-sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
+If you are on Linux with systemd:
 
-# If you are on Linux with systemd, you will need to run:
-sudo systemctl stop nix-daemon.socket
-sudo systemctl stop nix-daemon.service
-sudo systemctl disable nix-daemon.socket
-sudo systemctl disable nix-daemon.service
-sudo systemctl daemon-reload
+1. Remove the Nix daemon service:
+
+   ```console
+   sudo systemctl stop nix-daemon.service
+   sudo systemctl disable nix-daemon.socket nix-daemon.service
+   sudo systemctl daemon-reload
+   ```
+
+1. Remove systemd service files:
+
+   ```console
+   sudo rm /etc/systemd/system/nix-daemon.service /etc/systemd/system/nix-daemon.socket
+   ```
+
+1. The installer script uses systemd-tmpfiles to create the socket directory.
+    You may also want to remove the configuration for that:
+
+   ```console
+   sudo rm /etc/tmpfiles.d/nix-daemon.conf
+   ```
+
+Remove files created by Nix:
+
+```console
+sudo rm -rf /nix /etc/nix /etc/profile/nix.sh ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
 ```
 
-There may also be references to Nix in `/etc/profile`, `/etc/bashrc`,
-and `/etc/zshrc` which you may remove.
+Remove build users and their group:
+
+```console
+for i in $(seq 1 32); do
+  sudo userdel nixbld$i
+done
+sudo groupdel nixbld
+```
+
+There may also be references to Nix in
+
+- `/etc/profile`
+- `/etc/bashrc`
+- `/etc/zshrc`
+
+which you may remove.
 
 ### macOS
 
@@ -255,7 +287,7 @@ These install scripts can be used the same as the main NixOS.org
 installation script:
 
 ```console
-$ sh <(curl -L https://nixos.org/nix/install)
+$ curl -L https://nixos.org/nix/install | sh
 ```
 
 In the same directory of the install script are sha256 sums, and gpg

doc/manual/src/introduction.md

@@ -104,7 +104,7 @@ a currently running program.
 
 Packages are built from _Nix expressions_, which is a simple
 functional language.  A Nix expression describes everything that goes
-into a package build action (a “derivation”): other packages, sources,
+into a package build task (a “derivation”): other packages, sources,
 the build script, environment variables for the build script, etc.
 Nix tries very hard to ensure that Nix expressions are
 _deterministic_: building a Nix expression twice should yield the same

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

@@ -207,13 +207,13 @@ Derivations can declare some infrequently used optional attributes.
     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}
     If this **experimental** attribute is set to true, then the derivation
     outputs will be stored in a content-addressed location rather than the
     traditional input-addressed one.
-    This only has an effect if the `ca-derivation` experimental feature is enabled.
-    
+    This only has an effect if the `ca-derivations` experimental feature is enabled.
+
     Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above).
 
   - [`passAsFile`]{#adv-attr-passAsFile}\
@@ -255,3 +255,78 @@ Derivations can declare some infrequently used optional attributes.
     > substituted. Thus it is usually a good idea to align `system` with
     > `builtins.currentSystem` when setting `allowSubstitutes` to
     > `false`. For most trivial derivations this should be the case.
+
+  - [`__structuredAttrs`]{#adv-attr-structuredAttrs}\
+    If the special attribute `__structuredAttrs` is set to `true`, the other derivation
+    attributes are serialised in JSON format and made available to the
+    builder via the file `.attrs.json` in the builder’s temporary
+    directory. This obviates the need for [`passAsFile`](#adv-attr-passAsFile) since JSON files
+    have no size restrictions, unlike process environments.
+
+    It also makes it possible to tweak derivation settings in a structured way; see
+    [`outputChecks`](#adv-attr-outputChecks) for example.
+
+    As a convenience to Bash builders,
+    Nix writes a script named `.attrs.sh` to the builder’s directory
+    that initialises shell variables corresponding to all attributes
+    that are representable in Bash. This includes non-nested
+    (associative) arrays. For example, the attribute `hardening.format = true`
+    ends up as the Bash associative array element `${hardening[format]}`.
+
+  - [`outputChecks`]{#adv-attr-outputChecks}\
+    When using [structured attributes](#adv-attr-structuredAttrs), the `outputChecks`
+    attribute allows defining checks per-output.
+
+    In addition to
+    [`allowedReferences`](#adv-attr-allowedReferences), [`allowedRequisites`](#adv-attr-allowedRequisites),
+    [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites),
+    the following attributes are available:
+
+    - `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.
+
+    Example:
+
+    ```nix
+    __structuredAttrs = true;
+
+    outputChecks.out = {
+      # The closure of 'out' must not be larger than 256 MiB.
+      maxClosureSize = 256 * 1024 * 1024;
+
+      # It must not refer to the C compiler or to the 'dev' output.
+      disallowedRequisites = [ stdenv.cc "dev" ];
+    };
+
+    outputChecks.dev = {
+      # The 'dev' output must not be larger than 128 KiB.
+      maxSize = 128 * 1024;
+    };
+    ```
+
+  - [`unsafeDiscardReferences`]{#adv-attr-unsafeDiscardReferences}\
+    > **Warning**
+    > This is an experimental feature.
+    >
+    > To enable it, add the following to [nix.conf](../command-ref/conf-file.md):
+    >
+    > ```
+    > extra-experimental-features = discard-references
+    > ```
+
+    When using [structured attributes](#adv-attr-structuredAttrs), the
+    attribute `unsafeDiscardReferences` is an attribute set with a boolean value for each output name.
+    If set to `true`, it disables scanning the output for runtime dependencies.
+
+    Example:
+
+    ```nix
+    __structuredAttrs = true;
+    unsafeDiscardReferences.out = true;
+    ```
+
+    This is useful, for example, when generating self-contained filesystem images with
+    their own embedded Nix store: hashes found inside such an image refer
+    to the embedded store and not to the host's Nix store.

doc/manual/src/language/derivations.md

@@ -1,7 +1,7 @@
 # Derivations
 
 The most important built-in function is `derivation`, which is used to
-describe a single derivation (a build action). It takes as input a set,
+describe a single derivation (a build task). It takes as input a set,
 the attributes of which specify the inputs of the build.
 
   - There must be an attribute named [`system`]{#attr-system} whose value must be a

doc/manual/src/language/index.md

@@ -31,3 +31,551 @@ The Nix language is
 
   Type errors are only detected when expressions are evaluated.
 
+# Overview
+
+This is an incomplete overview of language features, by example.
+
+<table>
+ <tr>
+  <th>
+   Example
+  </th>
+  <th>
+   Description
+  </th>
+ </tr>
+ <tr>
+  <td>
+
+
+   *Basic values*
+
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"hello world"`
+
+  </td>
+  <td>
+
+   A string
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   ```
+   ''
+     multi
+      line
+       string
+   ''
+   ```
+
+  </td>
+  <td>
+
+   A multi-line string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n  string"`.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"hello ${ { a = "world"; }.a }"`
+
+   `"1 2 ${toString 3}"`
+
+   `"${pkgs.bash}/bin/sh"`
+
+  </td>
+  <td>
+
+   String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `true`, `false`
+
+  </td>
+  <td>
+
+   Booleans
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `null`
+
+  </td>
+  <td>
+
+   Null value
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `123`
+
+  </td>
+  <td>
+
+   An integer
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `3.141`
+
+  </td>
+  <td>
+
+   A floating point number
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `/etc`
+
+  </td>
+  <td>
+
+   An absolute path
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `./foo.png`
+
+  </td>
+  <td>
+
+   A path relative to the file containing this Nix expression
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `~/.config`
+
+  </td>
+  <td>
+
+   A home path. Evaluates to the `"<user's home directory>/.config"`.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `<nixpkgs>`
+
+  </td>
+  <td>
+
+   Search path for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Compound values*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }`
+
+  </td>
+  <td>
+
+   A set with attributes named `x` and `y`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ foo.bar = 1; }`
+
+  </td>
+  <td>
+
+   A nested set, equivalent to `{ foo = { bar = 1; }; }`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `rec { x = "foo"; y = x + "bar"; }`
+
+  </td>
+  <td>
+
+   A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `[ "foo" "bar" "baz" ]`
+
+   `[ 1 2 3 ]`
+
+   `[ (f 1) { a = 1; b = 2; } [ "c" ] ]`
+
+  </td>
+  <td>
+
+   Lists with three elements.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Operators*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" + "bar"`
+
+  </td>
+  <td>
+
+   String concatenation
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `1 + 2`
+
+  </td>
+  <td>
+
+   Integer addition
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" == "f" + "oo"`
+
+  </td>
+  <td>
+
+   Equality test (evaluates to `true`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" != "bar"`
+
+  </td>
+  <td>
+
+   Inequality test (evaluates to `true`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `!true`
+
+  </td>
+  <td>
+
+   Boolean negation
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }.x`
+
+  </td>
+  <td>
+
+   Attribute selection (evaluates to `1`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }.z or 3`
+
+  </td>
+  <td>
+
+   Attribute selection with default (evaluates to `3`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; } // { z = 3; }`
+
+  </td>
+  <td>
+
+   Merge two sets (attributes in the right-hand set taking precedence)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Control structures*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `if 1 + 1 == 2 then "yes!" else "no!"`
+
+  </td>
+  <td>
+
+   Conditional expression
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `assert 1 + 1 == 2; "yes!"`
+
+  </td>
+  <td>
+
+   Assertion check (evaluates to `"yes!"`).
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `let x = "foo"; y = "bar"; in x + y`
+
+  </td>
+  <td>
+
+   Variable definition
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `with builtins; head [ 1 2 3 ]`
+
+  </td>
+  <td>
+
+   Add all attributes from the given set to the scope (evaluates to `1`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Functions (lambdas)*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `x: x + 1`
+
+  </td>
+  <td>
+
+   A function that expects an integer and returns it increased by 1
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `x: y: x + y`
+
+  </td>
+  <td>
+
+   Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `(x: x + 1) 100`
+
+  </td>
+  <td>
+
+   A function call (evaluates to 101)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `let inc = x: x + 1; in inc (inc (inc 100))`
+
+  </td>
+  <td>
+
+   A function bound to a variable and subsequently called by name (evaluates to 103)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y` and concatenates them
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y ? "bar" }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y, ... }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y` and ignores any other attributes
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y } @ args: x + y`
+
+   `args @ { x, y }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Built-in functions*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `import ./foo.nix`
+
+  </td>
+  <td>
+
+   Load and return Nix expression in given file
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `map (x: x + x) [ 1 2 3 ]`
+
+  </td>
+  <td>
+
+   Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
+
+  </td>
+ </tr>
+</table>

doc/manual/src/language/operators.md

@@ -1,28 +1,167 @@
 # Operators
 
-The table below lists the operators in the Nix language, in
-order of precedence (from strongest to weakest binding).
+| Name                                   | Syntax                                     | Associativity | Precedence |
+|----------------------------------------|--------------------------------------------|---------------|------------|
+| [Attribute selection]                  | *attrset* `.` *attrpath* \[ `or` *expr* \] | none          | 1          |
+| Function application                   | *func* *expr*                              | left          | 2          |
+| [Arithmetic negation][arithmetic]      | `-` *number*                               | none          | 3          |
+| [Has attribute]                        | *attrset* `?` *attrpath*                   | none          | 4          |
+| List concatenation                     | *list* `++` *list*                         | right         | 5          |
+| [Multiplication][arithmetic]           | *number* `*` *number*                      | left          | 6          |
+| [Division][arithmetic]                 | *number* `/` *number*                      | left          | 6          |
+| [Subtraction][arithmetic]              | *number* `-` *number*                      | left          | 7          |
+| [Addition][arithmetic]                 | *number* `+` *number*                      | left          | 7          |
+| [String concatenation]                 | *string* `+` *string*                      | left          | 7          |
+| [Path concatenation]                   | *path* `+` *path*                          | left          | 7          |
+| [Path and string concatenation]        | *path* `+` *string*                        | left          | 7          |
+| [String and path concatenation]        | *string* `+` *path*                        | left          | 7          |
+| Logical negation (`NOT`)               | `!` *bool*                                 | none          | 8          |
+| [Update]                               | *attrset* `//` *attrset*                   | right         | 9          |
+| [Less than][Comparison]                | *expr* `<` *expr*                          | none          | 10         |
+| [Less than or equal to][Comparison]    | *expr* `<=` *expr*                         | none          | 10         |
+| [Greater than][Comparison]             | *expr* `>` *expr*                          | none          | 10         |
+| [Greater than or equal to][Comparison] | *expr* `>=` *expr*                         | none          | 10         |
+| [Equality]                             | *expr* `==` *expr*                         | none          | 11         |
+| Inequality                             | *expr* `!=` *expr*                         | none          | 11         |
+| Logical conjunction (`AND`)            | *bool* `&&` *bool*                         | left          | 12         |
+| Logical disjunction (`OR`)             | *bool* <code>\|\|</code> *bool*            | left          | 13         |
+| [Logical implication]                  | *bool* `->` *bool*                         | none          | 14         |
+
+[string]: ./values.md#type-string
+[path]: ./values.md#type-path
+[number]: ./values.md#type-number
+[list]: ./values.md#list
+[attribute set]: ./values.md#attribute-set
+
+## Attribute selection
+
+Select the attribute denoted by attribute path *attrpath* from [attribute set] *attrset*.
+If the attribute doesn’t exist, return *value* if provided, otherwise abort evaluation.
+
+<!-- FIXME: the following should to into its own language syntax section, but that needs more work to fit in well -->
+
+An attribute path is a dot-separated list of attribute names.
+An attribute name can be an identifier or a string.
+
+> *attrpath* = *name* [ `.` *name* ]...
+> *name* = *identifier* | *string*
+> *identifier* ~ `[a-zA-Z_][a-zA-Z0-9_'-]*`
+
+[Attribute selection]: #attribute-selection
+
+## Has attribute
+
+> *attrset* `?` *attrpath*
+
+Test whether [attribute set] *attrset* contains the attribute denoted by *attrpath*.
+The result is a [Boolean] value.
+
+[Boolean]: ./values.md#type-boolean
+
+[Has attribute]: #has-attribute
+
+## Arithmetic
+
+Numbers are type-compatible:
+Pure integer operations will always return integers, whereas any operation involving at least one floating point number return a floating point number.
+
+See also [Comparison] and [Equality].
+
+The `+` operator is overloaded to also work on strings and paths.
+
+[arithmetic]: #arithmetic
+
+## String concatenation
+
+> *string* `+` *string*
+
+Concatenate two [string]s and merge their string contexts.
+
+[String concatenation]: #string-concatenation
+
+## Path concatenation
+
+> *path* `+` *path*
+
+Concatenate two [path]s.
+The result is a path.
+
+[Path concatenation]: #path-concatenation
+
+## Path and string concatenation
+
+> *path* + *string*
+
+Concatenate *[path]* with *[string]*.
+The result is a path.
+
+> **Note**
+>
+> The string must not have a string context that refers to a [store path].
+
+[Path and string concatenation]: #path-and-string-concatenation
+
+## String and path concatenation
+
+> *string* + *path*
+
+Concatenate *[string]* with *[path]*.
+The result is a string.
+
+> **Important**
+>
+> 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]: ../glossary.md#gloss-store-path
+[store]: ../glossary.md#gloss-store
+
+[String and path concatenation]: #string-and-path-concatenation
+
+## Update
+
+> *attrset1* // *attrset2*
+
+Update [attribute set] *attrset1* with names and values from *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
+
+## Comparison
+
+Comparison is
+
+- [arithmetic] for [number]s
+- lexicographic for [string]s and [path]s
+- item-wise lexicographic for [list]s:
+  elements at the same index in both lists are compared according to their type and skipped if they are equal.
+
+All comparison operators are implemented in terms of `<`, and the following equivalencies hold:
+
+| comparison   | implementation        |
+|--------------|-----------------------|
+| *a* `<=` *b* | `! (` *b* `<` *a* `)` |
+| *a* `>`  *b* |       *b* `<` *a*     |
+| *a* `>=` *b* | `! (` *a* `<` *b* `)` |
+
+[Comparison]: #comparison-operators
+
+## Equality
+
+- [Attribute sets][attribute set] and [list]s are compared recursively, and therefore are fully evaluated.
+- Comparison of [function]s always returns `false`.
+- Numbers are type-compatible, see [arithmetic] operators.
+- Floating point numbers only differ up to a limited precision.
+
+[function]: ./constructs.md#functions
+
+[Equality]: #equality
+
+## Logical implication
+
+Equivalent to `!`*b1* `||` *b2*.
+
+[Logical implication]: #logical-implication
 
-| Name                     | Syntax                              | Associativity | Description                                                                                                                                                                                                                   | Precedence |
-| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Select                   | *e* `.` *attrpath* \[ `or` *def* \] | none          | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | 1          |
-| Application              | *e1* *e2*                           | left          | Call function *e1* with argument *e2*.                                                                                                                                                                                        | 2          |
-| Arithmetic Negation      | `-` *e*                             | none          | Arithmetic negation.                                                                                                                                                                                                          | 3          |
-| Has Attribute            | *e* `?` *attrpath*                  | none          | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.                                                                                                                                  | 4          |
-| List Concatenation       | *e1* `++` *e2*                      | right         | List concatenation.                                                                                                                                                                                                           | 5          |
-| Multiplication           | *e1* `*` *e2*,                      | left          | Arithmetic multiplication.                                                                                                                                                                                                    | 6          |
-| Division                 | *e1* `/` *e2*                       | left          | Arithmetic division.                                                                                                                                                                                                          | 6          |
-| Addition                 | *e1* `+` *e2*                       | left          | Arithmetic addition.                                                                                                                                                                                                          | 7          |
-| Subtraction              | *e1* `-` *e2*                       | left          | Arithmetic subtraction.                                                                                                                                                                                                       | 7          |
-| String Concatenation     | *string1* `+` *string2*             | left          | String concatenation.                                                                                                                                                                                                         | 7          |
-| Not                      | `!` *e*                             | none          | Boolean negation.                                                                                                                                                                                                             | 8          |
-| Update                   | *e1* `//` *e2*                      | right         | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).                                                                           | 9          |
-| Less Than                | *e1* `<` *e2*,                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Less Than or Equal To    | *e1* `<=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Greater Than             | *e1* `>` *e2*                       | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Greater Than or Equal To | *e1* `>=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Equality                 | *e1* `==` *e2*                      | none          | Equality.                                                                                                                                                                                                                     | 11         |
-| Inequality               | *e1* `!=` *e2*                      | none          | Inequality.                                                                                                                                                                                                                   | 11         |
-| Logical AND              | *e1* `&&` *e2*                      | left          | Logical AND.                                                                                                                                                                                                                  | 12         |
-| Logical OR               | *e1* <code>&#124;&#124;</code> *e2* | left          | Logical OR.                                                                                                                                                                                                                   | 13         |
-| Logical Implication      | *e1* `->` *e2*                      | none          | Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).                                                                                                                                                                            | 14         |

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

@@ -0,0 +1,82 @@
+# String interpolation
+
+String interpolation is a language feature where a [string], [path], or [attribute name] can contain expressions enclosed in `${ }` (dollar-sign with curly brackets).
+
+Such a string is an *interpolated string*, and an expression inside is an *interpolated expression*.
+
+Interpolated expressions must evaluate to one of the following:
+
+- a [string]
+- a [path]
+- a [derivation]
+
+[string]: ./values.md#type-string
+[path]: ./values.md#type-path
+[attribute name]: ./values.md#attribute-set
+[derivation]: ../glossary.md#gloss-derivation
+
+## Examples
+
+### String
+
+Rather than writing
+
+```nix
+"--with-freetype2-library=" + freetype + "/lib"
+```
+
+(where `freetype` is a [derivation]), you can instead write
+
+```nix
+"--with-freetype2-library=${freetype}/lib"
+```
+
+The latter is automatically translated to the former.
+
+A more complicated example (from the Nix expression for [Qt](http://www.trolltech.com/products/qt)):
+
+```nix
+configureFlags = "
+  -system-zlib -system-libpng -system-libjpeg
+  ${if openglSupport then "-dlopen-opengl
+    -L${mesa}/lib -I${mesa}/include
+    -L${libXmu}/lib -I${libXmu}/include" else ""}
+  ${if threadSupport then "-thread" else "-no-thread"}
+";
+```
+
+Note that Nix expressions and strings can be arbitrarily nested;
+in this case the outer string contains various interpolated expressions that themselves contain strings (e.g., `"-thread"`), some of which in turn contain interpolated expressions (e.g., `${mesa}`).
+
+### Path
+
+Rather than writing
+
+```nix
+./. + "/" + foo + "-" + bar + ".nix"
+```
+
+or
+
+```nix
+./. + "/${foo}-${bar}.nix"
+```
+
+you can instead write
+
+```nix
+./${foo}-${bar}.nix
+```
+
+### Attribute name
+
+Attribute names can be created dynamically with string interpolation:
+
+```nix
+let name = "foo"; in
+{
+  ${name} = "bar";
+}
+```
+
+    { foo = "bar"; }

doc/manual/src/language/values.md

@@ -13,41 +13,9 @@
   returns and tabs can be written as `\n`, `\r` and `\t`,
   respectively.
 
-  You can include the result of an expression into a string by
-  enclosing it in `${...}`, a feature known as *antiquotation*. The
-  enclosed expression must evaluate to something that can be coerced
-  into a string (meaning that it must be a string, a path, or a
-  derivation). For instance, rather than writing
+  You can include the results of other expressions into a string by enclosing them in `${ }`, a feature known as [string interpolation].
 
-  ```nix
-  "--with-freetype2-library=" + freetype + "/lib"
-  ```
-
-  (where `freetype` is a derivation), you can instead write the more
-  natural
-
-  ```nix
-  "--with-freetype2-library=${freetype}/lib"
-  ```
-
-  The latter is automatically translated to the former. A more
-  complicated example (from the Nix expression for
-  [Qt](http://www.trolltech.com/products/qt)):
-
-  ```nix
-  configureFlags = "
-    -system-zlib -system-libpng -system-libjpeg
-    ${if openglSupport then "-dlopen-opengl
-      -L${mesa}/lib -I${mesa}/include
-      -L${libXmu}/lib -I${libXmu}/include" else ""}
-    ${if threadSupport then "-thread" else "-no-thread"}
-  ";
-  ```
-
-  Note that Nix expressions and strings can be arbitrarily nested; in
-  this case the outer string contains various antiquotations that
-  themselves contain strings (e.g., `"-thread"`), some of which in
-  turn contain expressions (e.g., `${mesa}`).
+  [string interpolation]: ./string-interpolation.md
 
   The second way to write string literals is as an *indented string*,
   which is enclosed between pairs of *double single-quotes*, like so:
@@ -75,7 +43,7 @@
   Note that the whitespace and newline following the opening `''` is
   ignored if there is no non-whitespace text on the initial line.
 
-  Antiquotation (`${expr}`) is supported in indented strings.
+  Indented strings support [string interpolation].
 
   Since `${` and `''` have special meaning in indented strings, you
   need a way to quote them. `$` can be escaped by prefixing it with
@@ -117,9 +85,10 @@
   Numbers, which can be *integers* (like `123`) or *floating point*
   (like `123.43` or `.27e13`).
 
-  Numbers are type-compatible: pure integer operations will always
-  return integers, whereas any operation involving at least one
-  floating point number will have a floating point number as a result.
+  See [arithmetic] and [comparison] operators for semantics.
+
+  [arithmetic]: ./operators.md#arithmetic
+  [comparison]: ./operators.md#comparison
 
 - <a id="type-path" href="#type-path">Path</a>
 
@@ -143,12 +112,23 @@
   environment variable `NIX_PATH` will be searched for the given file
   or directory name.
 
-  Antiquotation is supported in any paths except those in angle brackets.
-  `./${foo}-${bar}.nix` is a more convenient way of writing
-  `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
-  least one slash must appear *before* any antiquotations for this to be
-  recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
-  operation. `./a.${foo}/b.${bar}` is a path.
+  When an [interpolated string][string interpolation] evaluates to a path, the path is first copied into the Nix store and the resulting string is the [store path] of the newly created [store object].
+
+  [store path]: ../glossary.md#gloss-store-path
+  [store object]: ../glossary.md#gloss-store-object
+
+  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"`.
+
+  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.
+
+  Paths themselves, except those in angle brackets (`< >`), support [string interpolation].
+
+  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 division operation.
+  `./a.${foo}/b.${bar}` is a path.
 
 - <a id="type-boolean" href="#type-boolean">Boolean</a>
 
@@ -221,23 +201,33 @@ will evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
 You can use arbitrary double-quoted strings as attribute names:
 
 ```nix
-{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
+{ "$!@#?" = 123; }."$!@#?"
 ```
 
-This will evaluate to `123` (Assuming `bar` is antiquotable). In the
-case where an attribute name is just a single antiquotation, the quotes
-can be dropped:
-
 ```nix
-{ foo = 123; }.${bar} or 456
+let bar = "bar";
+{ "foo ${bar}" = 123; }."foo ${bar}"
 ```
 
-This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced
-to a string and `456` otherwise (again assuming `bar` is antiquotable).
+Both will evaluate to `123`.
+
+Attribute names support [string interpolation]:
+
+```nix
+let bar = "foo"; in
+{ foo = 123; }.${bar}
+```
+
+```nix
+let bar = "foo"; in
+{ ${bar} = 123; }.foo
+```
+
+Both will evaluate to `123`.
 
 In the special case where an attribute name inside of a set declaration
-evaluates to `null` (which is normally an error, as `null` is not
-antiquotable), that attribute is simply not added to the set:
+evaluates to `null` (which is normally an error, as `null` cannot be coerced to
+a string), that attribute is simply not added to the set:
 
 ```nix
 { ${if foo then "bar" else null} = true; }

doc/manual/src/package-management/binary-cache-substituter.md

@@ -32,13 +32,13 @@ which should print something like:
     Priority: 30
 
 On the client side, you can tell Nix to use your binary cache using
-`--option extra-binary-caches`, e.g.:
+`--substituters`, e.g.:
 
 ```console
-$ nix-env -iA nixpkgs.firefox --option extra-binary-caches http://avalon:8080/
+$ nix-env -iA nixpkgs.firefox --substituters http://avalon:8080/
 ```
 
-The option `extra-binary-caches` tells Nix to use this binary cache in
+The option `substituters` tells Nix to use this binary cache in
 addition to your default caches, such as <https://cache.nixos.org>.
 Thus, for any path in the closure of Firefox, Nix will first check if
 the path is available on the server `avalon` or another binary caches.
@@ -47,4 +47,4 @@ If not, it will fall back to building from source.
 You can also tell Nix to always use your binary cache by adding a line
 to the `nix.conf` configuration file like this:
 
-    binary-caches = http://avalon:8080/ https://cache.nixos.org/
+    substituters = http://avalon:8080/ https://cache.nixos.org/

doc/manual/src/quick-start.md

@@ -4,16 +4,16 @@ This chapter is for impatient people who don't like reading
 documentation.  For more in-depth information you are kindly referred
 to subsequent chapters.
 
-1. Install single-user Nix by running the following:
+1. Install Nix by running the following:
 
    ```console
-   $ bash <(curl -L https://nixos.org/nix/install)
+   $ curl -L https://nixos.org/nix/install | sh
    ```
 
-   This will install Nix in `/nix`. The install script will create
-   `/nix` using `sudo`, so make sure you have sufficient rights.  (For
-   other installation methods, see
-   [here](installation/installation.md).)
+   The install script will use `sudo`, so make sure you have sufficient rights.
+   On Linux, `--daemon` can be omitted for a single-user install.
+
+   For other installation methods, see [here](installation/installation.md).
 
 1. See what installable packages are currently available in the
    channel:

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

@@ -0,0 +1,43 @@
+# Release 2.12 (2022-12-06)
+
+* On Linux, Nix can now run builds in a user namespace where they run
+  as root (UID 0) and have 65,536 UIDs available.
+  <!-- FIXME: move this to its own section about system features -->
+  This is primarily useful for running containers such as `systemd-nspawn`
+  inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn].
+
+  [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
+
+  A build can enable this by setting the derivation attribute:
+
+  ```
+  requiredSystemFeatures = [ "uid-range" ];
+  ```
+
+  The `uid-range` [system feature] requires the [`auto-allocate-uids`]
+  setting to be enabled.
+
+  [system feature]: ../command-ref/conf-file.md#conf-system-features
+
+* Nix can now automatically pick UIDs for builds, removing the need to
+  create `nixbld*` user accounts. See [`auto-allocate-uids`].
+
+  [`auto-allocate-uids`]: ../command-ref/conf-file.md#conf-auto-allocate-uids
+
+* On Linux, Nix has experimental support for running builds inside a
+  cgroup. See
+  [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups).
+
+* `<nix/fetchurl.nix>` now accepts an additional argument `impure` which
+  defaults to `false`.  If it is set to `true`, the `hash` and `sha256`
+  arguments will be ignored and the resulting derivation will have
+  `__impure` set to `true`, making it an impure derivation.
+
+* If `builtins.readFile` is called on a file with context, then only
+  the parts of the context that appear in the content of the file are
+  retained.  This avoids a lot of spurious errors where strings end up
+  having a context just because they are read from a store path
+  ([#7260](https://github.com/NixOS/nix/pull/7260)).
+
+* `nix build --json` now prints some statistics about top-level
+  derivations, such as CPU statistics when cgroups are enabled.

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

@@ -0,0 +1,44 @@
+# Release 2.13 (2023-01-17)
+
+* The `repeat` and `enforce-determinism` options have been removed
+  since they had been broken under many circumstances for a long time.
+
+* You can now use [flake references] in the [old command line interface], e.g.
+
+   [flake references]: ../command-ref/new-cli/nix3-flake.md#flake-references
+   [old command line interface]: ../command-ref/main-commands.md
+
+  ```shell-session
+  # nix-build flake:nixpkgs -A hello
+  # nix-build -I nixpkgs=flake:github:NixOS/nixpkgs/nixos-22.05 \
+      '<nixpkgs>' -A hello
+  # NIX_PATH=nixpkgs=flake:nixpkgs nix-build '<nixpkgs>' -A hello
+  ```
+
+* Instead of "antiquotation", the more common term [string interpolation](../language/string-interpolation.md) is now used consistently.
+  Historical release notes were not changed.
+
+* Error traces have been reworked to provide detailed explanations and more
+  accurate error locations. A short excerpt of the trace is now shown by
+  default when an error occurs.
+
+* Allow explicitly selecting outputs in a store derivation installable, just like we can do with other sorts of installables.
+  For example,
+  ```shell-session
+  # nix build /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^dev
+  ```
+  now works just as
+  ```shell-session
+  # nix build nixpkgs#glibc^dev
+  ```
+  does already.
+
+* On Linux, `nix develop` now sets the
+  [*personality*](https://man7.org/linux/man-pages/man2/personality.2.html)
+  for the development shell in the same way as the actual build of the
+  derivation. This makes shells for `i686-linux` derivations work
+  correctly on `x86_64-linux`.
+
+* You can now disable the global flake registry by setting the `flake-registry`
+  configuration option to an empty string. The same can be achieved at runtime with
+  `--flake-registry ""`.

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

@@ -0,0 +1,22 @@
+# Release 2.14 (2023-02-28)
+
+* A new function `builtins.readFileType` is available. It is similar to
+  `builtins.readDir` but acts on a single file or directory.
+
+* In flakes, the `.outPath` attribute of a flake now always refers to
+  the directory containing the `flake.nix`. This was not the case for
+  when `flake.nix` was in a subdirectory of e.g. a Git repository.
+  The root of the source of a flake in a subdirectory is still
+  available in `.sourceInfo.outPath`.
+
+* In derivations that use structured attributes, you can now use `unsafeDiscardReferences`
+  to disable scanning a given output for runtime dependencies:
+  ```nix
+  __structuredAttrs = true;
+  unsafeDiscardReferences.out = true;
+  ```
+  This is useful e.g. when generating self-contained filesystem images with
+  their own embedded Nix store: hashes found inside such an image refer
+  to the embedded store and not to the host's Nix store.
+
+  This requires the `discard-references` experimental feature.

doc/manual/utils.nix

@@ -5,6 +5,32 @@ rec {
 
   concatStrings = concatStringsSep "";
 
+  replaceStringsRec = from: to: string:
+    # recursively replace occurrences of `from` with `to` within `string`
+    # example:
+    #     replaceStringRec "--" "-" "hello-----world"
+    #     => "hello-world"
+    let
+      replaced = replaceStrings [ from ] [ to ] string;
+    in
+      if replaced == string then string else replaceStringsRec from to replaced;
+
+  squash = replaceStringsRec "\n\n\n" "\n\n";
+
+  trim = string:
+    # trim trailing spaces and squash non-leading spaces
+    let
+      trimLine = line:
+        let
+          # separate leading spaces from the rest
+          parts = split "(^ *)" line;
+          spaces = head (elemAt parts 1);
+          rest = elemAt parts 2;
+          # drop trailing spaces
+          body = head (split " *$" rest);
+        in spaces + replaceStringsRec "  " " " body;
+    in concatStringsSep "\n" (map trimLine (splitLines string));
+
   # FIXME: O(n^2)
   unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) [];
 

docker.nix

@@ -33,9 +33,20 @@ let
 
     root = {
       uid = 0;
-      shell = "/bin/bash";
+      shell = "${pkgs.bashInteractive}/bin/bash";
       home = "/root";
       gid = 0;
+      groups = [ "root" ];
+      description = "System administrator";
+    };
+
+    nobody = {
+      uid = 65534;
+      shell = "${pkgs.shadow}/bin/nologin";
+      home = "/var/empty";
+      gid = 65534;
+      groups = [ "nobody" ];
+      description = "Unprivileged account (don't use!)";
     };
 
   } // lib.listToAttrs (
@@ -57,6 +68,7 @@ let
   groups = {
     root.gid = 0;
     nixbld.gid = 30000;
+    nobody.gid = 65534;
   };
 
   userToPasswd = (

flake.lock

@@ -18,16 +18,16 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1657693803,
-        "narHash": "sha256-G++2CJ9u0E7NNTAi9n5G8TdDmGJXcIjkJ3NF8cetQB8=",
+        "lastModified": 1670461440,
+        "narHash": "sha256-jy1LB8HOMKGJEGXgzFRLDU1CBGL0/LlkolgnqIsF0D8=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "365e1b3a859281cf11b94f87231adeabbdd878a2",
+        "rev": "04a75b2eecc0acf6239acf9dd04485ff8d14f425",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-22.05-small",
+        "ref": "nixos-22.11-small",
         "repo": "nixpkgs",
         "type": "github"
       }

flake.nix

@@ -1,60 +1,67 @@
 {
   description = "The purely functional package manager";
 
-  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-22.05-small";
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-22.11-small";
   inputs.nixpkgs-regression.url = "github:NixOS/nixpkgs/215d4d0fd80ca5163643b03a33fde804a29cc1e2";
   inputs.lowdown-src = { url = "github:kristapsdz/lowdown"; flake = false; };
 
   outputs = { self, nixpkgs, nixpkgs-regression, lowdown-src }:
 
     let
+      inherit (nixpkgs) lib;
 
-      version = builtins.readFile ./.version + versionSuffix;
+      officialRelease = true;
+
+      version = lib.fileContents ./.version + versionSuffix;
       versionSuffix =
         if officialRelease
         then ""
         else "pre${builtins.substring 0 8 (self.lastModifiedDate or self.lastModified or "19700101")}_${self.shortRev or "dirty"}";
 
-      officialRelease = false;
-
       linux64BitSystems = [ "x86_64-linux" "aarch64-linux" ];
       linuxSystems = linux64BitSystems ++ [ "i686-linux" ];
       systems = linuxSystems ++ [ "x86_64-darwin" "aarch64-darwin" ];
 
       crossSystems = [ "armv6l-linux" "armv7l-linux" ];
 
-      stdenvs = [ "gccStdenv" "clangStdenv" "clang11Stdenv" "stdenv" "libcxxStdenv" ];
+      stdenvs = [ "gccStdenv" "clangStdenv" "clang11Stdenv" "stdenv" "libcxxStdenv" "ccacheStdenv" ];
 
-      forAllSystems = f: nixpkgs.lib.genAttrs systems (system: f system);
-      forAllSystemsAndStdenvs = f: forAllSystems (system:
-        nixpkgs.lib.listToAttrs
+      forAllSystems = lib.genAttrs systems;
+
+      forAllCrossSystems = lib.genAttrs crossSystems;
+
+      forAllStdenvs = f:
+        lib.listToAttrs
           (map
-            (n:
-            nixpkgs.lib.nameValuePair "${n}Packages" (
-              f system n
-            )) stdenvs
-          )
-      );
+            (stdenvName: {
+              name = "${stdenvName}Packages";
+              value = f stdenvName;
+            })
+            stdenvs);
 
-      forAllStdenvs = f: nixpkgs.lib.genAttrs stdenvs (stdenv: f stdenv);
 
       # Memoize nixpkgs for different platforms for efficiency.
-      nixpkgsFor =
-        let stdenvsPackages = forAllSystemsAndStdenvs
-          (system: stdenv:
-            import nixpkgs {
-              inherit system;
-              overlays = [
-                (overlayFor (p: p.${stdenv}))
-              ];
-            }
-          );
-        in
-        # Add the `stdenvPackages` at toplevel, both because these are the ones
-        # we want most of the time and for backwards compatibility
-        forAllSystems (system: stdenvsPackages.${system} // stdenvsPackages.${system}.stdenvPackages);
+      nixpkgsFor = forAllSystems
+        (system: let
+          make-pkgs = crossSystem: stdenv: import nixpkgs {
+            inherit system crossSystem;
+            overlays = [
+              (overlayFor (p: p.${stdenv}))
+            ];
+          };
+          stdenvs = forAllStdenvs (make-pkgs null);
+          native = stdenvs.stdenvPackages;
+        in {
+          inherit stdenvs native;
+          static = native.pkgsStatic;
+          cross = forAllCrossSystems (crossSystem: make-pkgs crossSystem "stdenv");
+        });
 
-      commonDeps = { pkgs, isStatic ? false }: with pkgs; rec {
+      commonDeps =
+        { pkgs
+        , isStatic ? pkgs.stdenv.hostPlatform.isStatic
+        }:
+        with pkgs; rec {
         # Use "busybox-sandbox-shell" if present,
         # if not (legacy) fallback and hope it's sufficient.
         sh = pkgs.busybox-sandbox-shell or (busybox.override {
@@ -82,7 +89,9 @@
         });
 
         configureFlags =
-          lib.optionals stdenv.isLinux [
+          [
+            "CXXFLAGS=-I${lib.getDev rapidcheck}/extras/gtest/include"
+          ] ++ lib.optionals stdenv.isLinux [
             "--with-boost=${boost}/lib"
             "--with-sandbox-shell=${sh}/bin/busybox"
           ]
@@ -96,6 +105,7 @@
             buildPackages.flex
             (lib.getBin buildPackages.lowdown-nix)
             buildPackages.mdbook
+            buildPackages.mdbook-linkcheck
             buildPackages.autoconf-archive
             buildPackages.autoreconfHook
             buildPackages.pkg-config
@@ -108,13 +118,14 @@
           ++ lib.optionals stdenv.hostPlatform.isLinux [(buildPackages.util-linuxMinimal or buildPackages.utillinuxMinimal)];
 
         buildDeps =
-          [ (curl.override { patchNetrcRegression = true; })
+          [ curl
             bzip2 xz brotli editline
             openssl sqlite
             libarchive
             boost
             lowdown-nix
             gtest
+            rapidcheck
           ]
           ++ lib.optionals stdenv.isLinux [libseccomp]
           ++ lib.optional (stdenv.isLinux || stdenv.isDarwin) libsodium
@@ -133,13 +144,14 @@
               patches = (o.patches or []) ++ [
                 ./boehmgc-coroutine-sp-fallback.diff
               ];
-            }))
+            })
+            )
             nlohmann_json
           ];
       };
 
       installScriptFor = systems:
-        with nixpkgsFor.x86_64-linux;
+        with nixpkgsFor.x86_64-linux.native;
         runCommand "installer-script"
           { buildInputs = [ nix ];
           }
@@ -203,8 +215,9 @@
         installCheckPhase = "make installcheck -j$NIX_BUILD_CORES -l$NIX_BUILD_CORES";
       };
 
-      binaryTarball = buildPackages: nix: pkgs:
+      binaryTarball = nix: pkgs:
         let
+          inherit (pkgs) buildPackages;
           inherit (pkgs) cacert;
           installerClosureInfo = buildPackages.closureInfo { rootPaths = [ nix cacert ]; };
         in
@@ -260,6 +273,7 @@
             echo "file binary-dist $fn" >> $out/nix-support/hydra-build-products
             tar cvfJ $fn \
               --owner=0 --group=0 --mode=u+rw,uga+r \
+              --mtime='1970-01-01' \
               --absolute-names \
               --hard-dereference \
               --transform "s,$TMPDIR/install,$dir/install," \
@@ -283,7 +297,15 @@
           # Forward from the previous stage as we don’t want it to pick the lowdown override
           nixUnstable = prev.nixUnstable;
 
-          nix = with final; with commonDeps { inherit pkgs; }; currentStdenv.mkDerivation {
+          nix =
+          with final;
+          with commonDeps {
+            inherit pkgs;
+            inherit (currentStdenv.hostPlatform) isStatic;
+          };
+          let
+            canRunInstalled = currentStdenv.buildPlatform.canExecute currentStdenv.hostPlatform;
+          in currentStdenv.mkDerivation {
             name = "nix-${version}";
             inherit version;
 
@@ -294,24 +316,26 @@
             outputs = [ "out" "dev" "doc" ];
 
             nativeBuildInputs = nativeBuildDeps;
-            buildInputs = buildDeps ++ awsDeps;
+            buildInputs = buildDeps
+              # There have been issues building these dependencies
+              ++ lib.optionals (currentStdenv.hostPlatform == currentStdenv.buildPlatform) awsDeps;
 
             propagatedBuildInputs = propagatedDeps;
 
             disallowedReferences = [ boost ];
 
-            preConfigure =
+            preConfigure = lib.optionalString (! currentStdenv.hostPlatform.isStatic)
               ''
                 # Copy libboost_context so we don't get all of Boost in our closure.
                 # https://github.com/NixOS/nixpkgs/issues/45462
                 mkdir -p $out/lib
                 cp -pd ${boost}/lib/{libboost_context*,libboost_thread*,libboost_system*} $out/lib
                 rm -f $out/lib/*.a
-                ${lib.optionalString currentStdenv.isLinux ''
+                ${lib.optionalString currentStdenv.hostPlatform.isLinux ''
                   chmod u+w $out/lib/*.so.*
                   patchelf --set-rpath $out/lib:${currentStdenv.cc.cc.lib}/lib $out/lib/libboost_thread.so.*
                 ''}
-                ${lib.optionalString currentStdenv.isDarwin ''
+                ${lib.optionalString currentStdenv.hostPlatform.isDarwin ''
                   for LIB in $out/lib/*.dylib; do
                     chmod u+w $LIB
                     install_name_tool -id $LIB $LIB
@@ -322,7 +346,9 @@
               '';
 
             configureFlags = configureFlags ++
-              [ "--sysconfdir=/etc" ];
+              [ "--sysconfdir=/etc" ] ++
+              lib.optional stdenv.hostPlatform.isStatic "--enable-embedded-sandbox-shell" ++
+              lib.optional (!canRunInstalled) "--disable-doc-gen";
 
             enableParallelBuilding = true;
 
@@ -346,10 +372,12 @@
             doInstallCheck = true;
             installCheckFlags = "sysconfdir=$(out)/etc";
 
-            separateDebugInfo = true;
+            separateDebugInfo = !currentStdenv.hostPlatform.isStatic;
 
             strictDeps = true;
 
+            hardeningDisable = lib.optional stdenv.hostPlatform.isStatic "pie";
+
             passthru.perl-bindings = with final; perl.pkgs.toPerlModule (currentStdenv.mkDerivation {
               name = "nix-perl-${version}";
 
@@ -363,7 +391,7 @@
 
               buildInputs =
                 [ nix
-                  (curl.override { patchNetrcRegression = true; })
+                  curl
                   bzip2
                   xz
                   pkgs.perl
@@ -382,7 +410,7 @@
               postUnpack = "sourceRoot=$sourceRoot/perl";
             });
 
-            meta.platforms = systems;
+            meta.platforms = lib.platforms.unix;
           };
 
           lowdown-nix = with final; currentStdenv.mkDerivation rec {
@@ -403,7 +431,20 @@
           };
         };
 
+      nixos-lib = import (nixpkgs + "/nixos/lib") { };
+
+      # https://nixos.org/manual/nixos/unstable/index.html#sec-calling-nixos-tests
+      runNixOSTestFor = system: test: nixos-lib.runTest {
+        imports = [ test ];
+        hostPkgs = nixpkgsFor.${system}.native;
+        defaults = {
+          nixpkgs.pkgs = nixpkgsFor.${system}.native;
+        };
+        _module.args.nixpkgs = nixpkgs;
+      };
+
     in {
+      inherit nixpkgsFor;
 
       # A Nixpkgs overlay that overrides the 'nix' and
       # 'nix.perl-bindings' packages.
@@ -412,30 +453,28 @@
       hydraJobs = {
 
         # Binary package for various platforms.
-        build = nixpkgs.lib.genAttrs systems (system: self.packages.${system}.nix);
+        build = forAllSystems (system: self.packages.${system}.nix);
 
-        buildStatic = nixpkgs.lib.genAttrs linux64BitSystems (system: self.packages.${system}.nix-static);
+        buildStatic = lib.genAttrs linux64BitSystems (system: self.packages.${system}.nix-static);
 
-        buildCross = nixpkgs.lib.genAttrs crossSystems (crossSystem:
-          nixpkgs.lib.genAttrs ["x86_64-linux"] (system: self.packages.${system}."nix-${crossSystem}"));
+        buildCross = forAllCrossSystems (crossSystem:
+          lib.genAttrs ["x86_64-linux"] (system: self.packages.${system}."nix-${crossSystem}"));
+
+        buildNoGc = forAllSystems (system: self.packages.${system}.nix.overrideAttrs (a: { configureFlags = (a.configureFlags or []) ++ ["--enable-gc=no"];}));
 
         # Perl bindings for various platforms.
-        perlBindings = nixpkgs.lib.genAttrs systems (system: self.packages.${system}.nix.perl-bindings);
+        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 = nixpkgs.lib.genAttrs systems (system: binaryTarball nixpkgsFor.${system} nixpkgsFor.${system}.nix nixpkgsFor.${system});
+        binaryTarball = forAllSystems (system: binaryTarball nixpkgsFor.${system}.native.nix nixpkgsFor.${system}.native);
 
-        binaryTarballCross = nixpkgs.lib.genAttrs ["x86_64-linux"] (system: builtins.listToAttrs (map (crossSystem: {
-          name = crossSystem;
-          value = let
-            nixpkgsCross = import nixpkgs {
-              inherit system crossSystem;
-              overlays = [ self.overlays.default ];
-            };
-          in binaryTarball nixpkgsFor.${system} self.packages.${system}."nix-${crossSystem}" nixpkgsCross;
-        }) crossSystems));
+        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
@@ -445,11 +484,11 @@
         installerScriptForGHA = installScriptFor [ "x86_64-linux" "x86_64-darwin" "armv6l-linux" "armv7l-linux"];
 
         # docker image with Nix inside
-        dockerImage = nixpkgs.lib.genAttrs linux64BitSystems (system: self.packages.${system}.dockerImage);
+        dockerImage = lib.genAttrs linux64BitSystems (system: self.packages.${system}.dockerImage);
 
         # Line coverage analysis.
         coverage =
-          with nixpkgsFor.x86_64-linux;
+          with nixpkgsFor.x86_64-linux.native;
           with commonDeps { inherit pkgs; };
 
           releaseTools.coverageAnalysis {
@@ -457,6 +496,10 @@
 
             src = self;
 
+            configureFlags = [
+              "CXXFLAGS=-I${lib.getDev pkgs.rapidcheck}/extras/gtest/include"
+            ];
+
             enableParallelBuilding = true;
 
             nativeBuildInputs = nativeBuildDeps;
@@ -475,48 +518,29 @@
           };
 
         # System tests.
-        tests.remoteBuilds = import ./tests/remote-builds.nix {
-          system = "x86_64-linux";
-          inherit nixpkgs;
-          overlay = self.overlays.default;
-        };
+        tests.authorization = runNixOSTestFor "x86_64-linux" ./tests/nixos/authorization.nix;
 
-        tests.nix-copy-closure = import ./tests/nix-copy-closure.nix {
-          system = "x86_64-linux";
-          inherit nixpkgs;
-          overlay = self.overlays.default;
-        };
+        tests.remoteBuilds = runNixOSTestFor "x86_64-linux" ./tests/nixos/remote-builds.nix;
 
-        tests.nssPreload = (import ./tests/nss-preload.nix rec {
-          system = "x86_64-linux";
-          inherit nixpkgs;
-          overlay = self.overlays.default;
-        });
+        tests.nix-copy-closure = runNixOSTestFor "x86_64-linux" ./tests/nixos/nix-copy-closure.nix;
 
-        tests.githubFlakes = (import ./tests/github-flakes.nix rec {
-          system = "x86_64-linux";
-          inherit nixpkgs;
-          overlay = self.overlays.default;
-        });
+        tests.nssPreload = runNixOSTestFor "x86_64-linux" ./tests/nixos/nss-preload.nix;
 
-        tests.sourcehutFlakes = (import ./tests/sourcehut-flakes.nix rec {
-          system = "x86_64-linux";
-          inherit nixpkgs;
-          overlay = self.overlays.default;
-        });
+        tests.githubFlakes = runNixOSTestFor "x86_64-linux" ./tests/nixos/github-flakes.nix;
 
-        tests.setuid = nixpkgs.lib.genAttrs
+        tests.sourcehutFlakes = runNixOSTestFor "x86_64-linux" ./tests/nixos/sourcehut-flakes.nix;
+
+        tests.containers = runNixOSTestFor "x86_64-linux" ./tests/nixos/containers/containers.nix;
+
+        tests.setuid = lib.genAttrs
           ["i686-linux" "x86_64-linux"]
-          (system:
-            import ./tests/setuid.nix rec {
-              inherit nixpkgs system;
-              overlay = self.overlays.default;
-            });
+          (system: runNixOSTestFor system ./tests/nixos/setuid.nix);
+
 
         # Make sure that nix-env still produces the exact same result
         # on a particular version of Nixpkgs.
         tests.evalNixpkgs =
-          with nixpkgsFor.x86_64-linux;
+          with nixpkgsFor.x86_64-linux.native;
           runCommand "eval-nixos" { buildInputs = [ nix ]; }
             ''
               type -p nix-env
@@ -526,13 +550,19 @@
               mkdir $out
             '';
 
+        tests.nixpkgsLibTests =
+          forAllSystems (system:
+            import (nixpkgs + "/lib/tests/release.nix")
+              { pkgs = nixpkgsFor.${system}.native; }
+          );
+
         metrics.nixpkgs = import "${nixpkgs-regression}/pkgs/top-level/metrics.nix" {
-          pkgs = nixpkgsFor.x86_64-linux;
+          pkgs = nixpkgsFor.x86_64-linux.native;
           nixpkgs = nixpkgs-regression;
         };
 
         installTests = forAllSystems (system:
-          let pkgs = nixpkgsFor.${system}; in
+          let pkgs = nixpkgsFor.${system}.native; in
           pkgs.runCommand "install-tests" {
             againstSelf = testNixVersions pkgs pkgs.nix pkgs.pkgs.nix;
             againstCurrentUnstable =
@@ -545,73 +575,30 @@
             # againstLatestStable = testNixVersions pkgs pkgs.nix pkgs.nixStable;
           } "touch $out");
 
+        installerTests = import ./tests/installer {
+          binaryTarballs = self.hydraJobs.binaryTarball;
+          inherit nixpkgsFor;
+        };
+
       };
 
       checks = forAllSystems (system: {
         binaryTarball = self.hydraJobs.binaryTarball.${system};
         perlBindings = self.hydraJobs.perlBindings.${system};
         installTests = self.hydraJobs.installTests.${system};
-      } // (nixpkgs.lib.optionalAttrs (builtins.elem system linux64BitSystems)) {
+        nixpkgsLibTests = self.hydraJobs.tests.nixpkgsLibTests.${system};
+      } // (lib.optionalAttrs (builtins.elem system linux64BitSystems)) {
         dockerImage = self.hydraJobs.dockerImage.${system};
       });
 
       packages = forAllSystems (system: rec {
-        inherit (nixpkgsFor.${system}) nix;
+        inherit (nixpkgsFor.${system}.native) nix;
         default = nix;
-      } // (nixpkgs.lib.optionalAttrs (builtins.elem system linux64BitSystems) {
-        nix-static = let
-          nixpkgs = nixpkgsFor.${system}.pkgsStatic;
-        in with commonDeps { pkgs = nixpkgs; isStatic = true; }; nixpkgs.stdenv.mkDerivation {
-          name = "nix-${version}";
-
-          src = self;
-
-          VERSION_SUFFIX = versionSuffix;
-
-          outputs = [ "out" "dev" "doc" ];
-
-          nativeBuildInputs = nativeBuildDeps;
-          buildInputs = buildDeps ++ propagatedDeps;
-
-          # Work around pkgsStatic disabling all tests.
-          # Remove in NixOS 22.11, see https://github.com/NixOS/nixpkgs/pull/140271.
-          preHook =
-            ''
-              doCheck=1
-              doInstallCheck=1
-            '';
-
-          configureFlags =
-            configureFlags ++
-            [ "--sysconfdir=/etc"
-              "--enable-embedded-sandbox-shell"
-            ];
-
-          enableParallelBuilding = true;
-
-          makeFlags = "profiledir=$(out)/etc/profile.d";
-
-          installFlags = "sysconfdir=$(out)/etc";
-
-          postInstall = ''
-            mkdir -p $doc/nix-support
-            echo "doc manual $doc/share/doc/nix/manual" >> $doc/nix-support/hydra-build-products
-            mkdir -p $out/nix-support
-            echo "file binary-dist $out/bin/nix" >> $out/nix-support/hydra-build-products
-          '';
-
-          installCheckFlags = "sysconfdir=$(out)/etc";
-
-          stripAllList = ["bin"];
-
-          strictDeps = true;
-
-          hardeningDisable = [ "pie" ];
-        };
-
+      } // (lib.optionalAttrs (builtins.elem system linux64BitSystems) {
+        nix-static = nixpkgsFor.${system}.static.nix;
         dockerImage =
           let
-            pkgs = nixpkgsFor.${system};
+            pkgs = nixpkgsFor.${system}.native;
             image = import ./docker.nix { inherit pkgs; tag = version; };
           in
           pkgs.runCommand
@@ -623,65 +610,30 @@
               ln -s ${image} $image
               echo "file binary-dist $image" >> $out/nix-support/hydra-build-products
             '';
-      }
+      } // builtins.listToAttrs (map
+          (crossSystem: {
+            name = "nix-${crossSystem}";
+            value = nixpkgsFor.${system}.cross.${crossSystem}.nix;
+          })
+          crossSystems)
+        // builtins.listToAttrs (map
+          (stdenvName: {
+            name = "nix-${stdenvName}";
+            value = nixpkgsFor.${system}.stdenvs."${stdenvName}Packages".nix;
+          })
+          stdenvs)));
 
-      // builtins.listToAttrs (map (crossSystem: {
-        name = "nix-${crossSystem}";
-        value = let
-          nixpkgsCross = import nixpkgs {
-            inherit system crossSystem;
-            overlays = [ self.overlays.default ];
-          };
-        in with commonDeps { pkgs = nixpkgsCross; }; nixpkgsCross.stdenv.mkDerivation {
-          name = "nix-${version}";
-
-          src = self;
-
-          VERSION_SUFFIX = versionSuffix;
-
-          outputs = [ "out" "dev" "doc" ];
-
-          nativeBuildInputs = nativeBuildDeps;
-          buildInputs = buildDeps ++ propagatedDeps;
-
-          configureFlags = [ "--sysconfdir=/etc" "--disable-doc-gen" ];
-
-          enableParallelBuilding = true;
-
-          makeFlags = "profiledir=$(out)/etc/profile.d";
-
-          doCheck = true;
-
-          installFlags = "sysconfdir=$(out)/etc";
-
-          postInstall = ''
-            mkdir -p $doc/nix-support
-            echo "doc manual $doc/share/doc/nix/manual" >> $doc/nix-support/hydra-build-products
-            mkdir -p $out/nix-support
-            echo "file binary-dist $out/bin/nix" >> $out/nix-support/hydra-build-products
-          '';
-
-          doInstallCheck = true;
-          installCheckFlags = "sysconfdir=$(out)/etc";
-        };
-      }) (if system == "x86_64-linux" then crossSystems else [])))
-
-      // (builtins.listToAttrs (map (stdenvName:
-        nixpkgsFor.${system}.lib.nameValuePair
-          "nix-${stdenvName}"
-          nixpkgsFor.${system}."${stdenvName}Packages".nix
-      ) stdenvs)));
-
-      devShells = forAllSystems (system:
-        forAllStdenvs (stdenv:
-          with nixpkgsFor.${system};
+      devShells = let
+        makeShell = pkgs: stdenv:
           with commonDeps { inherit pkgs; };
-          nixpkgsFor.${system}.${stdenv}.mkDerivation {
+          stdenv.mkDerivation {
             name = "nix";
 
             outputs = [ "out" "dev" "doc" ];
 
-            nativeBuildInputs = nativeBuildDeps;
+            nativeBuildInputs = nativeBuildDeps
+                                ++ (lib.optionals stdenv.cc.isClang [ pkgs.bear pkgs.clang-tools ]);
+
             buildInputs = buildDeps ++ propagatedDeps ++ awsDeps;
 
             inherit configureFlags;
@@ -699,10 +651,21 @@
                 # Make bash completion work.
                 XDG_DATA_DIRS+=:$out/share
               '';
-          }
-        )
-        // { default = self.devShells.${system}.stdenv; }
-      );
-
+          };
+        in
+        forAllSystems (system:
+          let
+            makeShells = prefix: pkgs:
+              lib.mapAttrs'
+              (k: v: lib.nameValuePair "${prefix}-${k}" v)
+              (forAllStdenvs (stdenvName: makeShell pkgs pkgs.${stdenvName}));
+          in
+            (makeShells "native" nixpkgsFor.${system}.native) //
+            (makeShells "static" nixpkgsFor.${system}.static) //
+            (forAllCrossSystems (crossSystem: let pkgs = nixpkgsFor.${system}.cross.${crossSystem}; in makeShell pkgs pkgs.stdenv)) //
+            {
+              default = self.devShells.${system}.native-stdenvPackages;
+            }
+        );
   };
 }

maintainers/README.md

@@ -0,0 +1,107 @@
+# Nix maintainers team
+
+## Motivation
+
+The goal of the team is to help other people to contribute to Nix.
+
+## Members
+
+- Eelco Dolstra (@edolstra) – Team lead
+- Théophane Hufschmitt (@thufschmitt)
+- Valentin Gagarin (@fricklerhandwerk)
+- Thomas Bereknyei (@tomberek)
+- Robert Hensing (@roberth)
+
+## Meeting protocol
+
+The team meets twice a week:
+
+- Discussion meeting: [Fridays 13:00-14:00 CET](https://calendar.google.com/calendar/event?eid=MHNtOGVuNWtrZXNpZHR2bW1sM3QyN2ZjaGNfMjAyMjExMjVUMTIwMDAwWiBiOW81MmZvYnFqYWs4b3E4bGZraGczdDBxZ0Bn)
+
+  1. Triage issues and pull requests from the _No Status_ column (30 min)
+  2. Discuss issues and pull requests from the _To discuss_ column (30 min)
+
+- Work meeting: [Mondays 13:00-15:00 CET](https://calendar.google.com/calendar/event?eid=NTM1MG1wNGJnOGpmOTZhYms3bTB1bnY5cWxfMjAyMjExMjFUMTIwMDAwWiBiOW81MmZvYnFqYWs4b3E4bGZraGczdDBxZ0Bn)
+
+  1. Code review on pull requests from _In review_.
+  2. Other chores and tasks.
+
+Meeting notes are collected on a [collaborative scratchpad](https://pad.lassul.us/Cv7FpYx-Ri-4VjUykQOLAw), and published on Discourse under the [Nix category](https://discourse.nixos.org/c/dev/nix/50).
+
+## Project board protocol
+
+The team uses a [GitHub project board](https://github.com/orgs/NixOS/projects/19/views/1) for tracking its work.
+
+Issues on the board progress through the following states:
+
+- No Status
+
+  During the discussion meeting, the team triages new items.
+  To be considered, issues and pull requests must have a high-level description to provide the whole team with the necessary context at a glance.
+
+  On every meeting, at least one item from each of the following categories is inspected:
+
+  1. [critical](https://github.com/NixOS/nix/labels/critical)
+  2. [security](https://github.com/NixOS/nix/labels/security)
+  3. [regression](https://github.com/NixOS/nix/labels/regression)
+  4. [bug](https://github.com/NixOS/nix/issues?q=is%3Aopen+label%3Abug+sort%3Areactions-%2B1-desc)
+
+  - [oldest pull requests](https://github.com/NixOS/nix/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc)
+  - [most popular pull requests](https://github.com/NixOS/nix/pulls?q=is%3Apr+is%3Aopen+sort%3Areactions-%2B1-desc)
+  - [oldest issues](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc)
+  - [most popular issues](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc)
+
+  Team members can also add pull requests or issues they would like the whole team to consider.
+
+  If there is disagreement on the general idea behind an issue or pull request, it is moved to _To discuss_, otherwise to _In review_.
+
+- To discuss
+
+  Pull requests and issues that are deemed important and controversial are discussed by the team during discussion meetings.
+
+  This may be where the merit of the change itself or the implementation strategy is contested by a team member.
+
+  As a general guideline, the order of items is determined as follows:
+
+  - Prioritise pull requests over issues
+
+    Contributors who took the time to implement concrete change proposals should not wait indefinitely.
+
+  - Prioritise fixing bugs over documentation, improvements or new features
+
+    The team values stability and accessibility higher than raw functionality.
+
+  - Interleave issues and PRs
+
+    This way issues without attempts at a solution get a chance to get addressed.
+
+- In review
+
+  Pull requests in this column are reviewed together during work meetings.
+  This is both for spreading implementation knowledge and for establishing common values in code reviews.
+
+  When the overall direction is agreed upon, even when further changes are required, the pull request is assigned to one team member.
+
+- Assigned for merging
+
+  One team member is assigned to each of these pull requests.
+  They will communicate with the authors, and make the final approval once all remaining issues are addressed.
+
+  If more substantive issues arise, the assignee can move the pull request back to _To discuss_ to involve the team again.
+
+The process is illustrated in the following diagram:
+
+```mermaid
+flowchart TD
+    discuss[To discuss]
+
+    review[To review]
+
+    New --> |Disagreement on idea| discuss
+    New & discuss --> |Consensus on idea| review
+
+    review --> |Consensus on implementation| Assigned
+
+    Assigned --> |Implementation issues arise| review
+    Assigned --> |Remaining issues fixed| Merged
+```

maintainers/backporting.md

@@ -0,0 +1,12 @@
+
+# Backporting
+
+To [automatically backport a pull request](https://github.com/NixOS/nix/blob/master/.github/workflows/backport.yml) to a release branch once it's merged, assign it a label of the form [`backport <branch>`](https://github.com/NixOS/nix/labels?q=backport).
+
+Since [GitHub Actions workflows will not trigger other workflows](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow), checks on the automatic backport need to be triggered by another actor.
+This is achieved by closing and reopening the backport pull request.
+
+This specifically affects the [`installer_test`] check.
+Note that it only runs after the other tests, so it may take a while to appear.
+
+[`installer_test`]: https://github.com/NixOS/nix/blob/895dfc656a21f6252ddf48df0d1f215effa04ecb/.github/workflows/ci.yml#L70-L91

maintainers/release-process.md

@@ -0,0 +1,181 @@
+# Nix release process
+
+## Release artifacts
+
+The release process is intended to create the following for each
+release:
+
+* A Git tag
+
+* Binary tarballs in https://releases.nixos.org/?prefix=nix/
+
+* Docker images
+
+* Closures in https://cache.nixos.org
+
+* (Optionally) Updated `fallback-paths.nix` in Nixpkgs
+
+* An updated manual on https://nixos.org/manual/nix/stable/
+
+## Creating a new release from the `master` branch
+
+* Make sure that the [Hydra `master` jobset](https://hydra.nixos.org/jobset/nix/master) succeeds.
+
+* In a checkout of the Nix repo, make sure you're on `master` and run
+  `git pull`.
+
+* Move the contents of `doc/manual/src/release-notes/rl-next.md`
+  (except the first line) to
+  `doc/manual/src/release-notes/rl-$VERSION.md` (where `$VERSION` is
+  the contents of `.version` *without* the patch level, e.g. `2.12`
+  rather than `2.12.0`).
+
+* Add a header to `doc/manual/src/release-notes/rl-$VERSION.md` like
+
+  ```
+  # Release 2.12 (2022-12-06)
+  ```
+
+* Proof-read / edit / rearrange the release notes. Breaking changes
+  and highlights should go to the top.
+
+* Add a link to the release notes to `doc/manual/src/SUMMARY.md.in`
+  (*not* `SUMMARY.md`), e.g.
+
+  ```
+  - [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
+  ```
+
+* Run
+
+  ```console
+  $ git checkout -b release-notes
+  $ git add doc/manual/src/release-notes/rl-$VERSION.md
+  $ git commit -a -m 'Release notes'
+  $ git push --set-upstream $REMOTE release-notes
+  ```
+
+* Create a PR for `release-notes`.
+
+* Wait for the PR to be merged.
+
+* Create a branch for the release:
+
+  ```console
+  $ git checkout master
+  $ git pull
+  $ git checkout -b $VERSION-maintenance
+  ```
+
+* Mark the release as stable:
+
+  ```console
+  $ git cherry-pick f673551e71942a52b6d7ae66af8b67140904a76a
+  ```
+
+  This removes the link to `rl-next.md` from the manual and sets
+  `officialRelease = true` in `flake.nix`.
+
+* Push the release branch:
+
+  ```console
+  $ git push --set-upstream origin $VERSION-maintenance
+  ```
+
+* Create a jobset for the release branch on Hydra as follows:
+
+  * Go to the jobset of the previous release
+  (e.g. https://hydra.nixos.org/jobset/nix/maintenance-2.11).
+
+  * Select `Actions -> Clone this jobset`.
+
+  * Set identifier to `maintenance-$VERSION`.
+
+  * Set description to `$VERSION release branch`.
+
+  * Set flake URL to `github:NixOS/nix/$VERSION-maintenance`.
+
+  * Hit `Create jobset`.
+
+* Wait for the new jobset to evaluate and build. If impatient, go to
+  the evaluation and select `Actions -> Bump builds to front of
+  queue`.
+
+* When the jobset evaluation has succeeded building, take note of the
+  evaluation ID (e.g. `1780832` in
+  `https://hydra.nixos.org/eval/1780832`).
+
+* Tag the release and upload the release artifacts to
+  [`releases.nixos.org`](https://releases.nixos.org/) and [Docker Hub](https://hub.docker.com/):
+
+  ```console
+  $ IS_LATEST=1 ./maintainers/upload-release.pl <EVAL-ID>
+  ```
+
+  Note: `IS_LATEST=1` causes the `latest-release` branch to be
+  force-updated. This is used by the `nixos.org` website to get the
+  [latest Nix manual](https://nixos.org/manual/nixpkgs/unstable/).
+
+  TODO: This script requires the right AWS credentials. Document.
+
+  TODO: This script currently requires a
+  `/home/eelco/Dev/nix-pristine` and
+  `/home/eelco/Dev/nixpkgs-pristine`.
+
+  TODO: trigger nixos.org netlify: https://docs.netlify.com/configure-builds/build-hooks/
+* Prepare for the next point release by editing `.version` to
+  e.g.
+
+  ```console
+  $ echo 2.12.1 > .version
+  $ git commit -a -m 'Bump version'
+  $ git push
+  ```
+
+  Commit and push this to the maintenance branch.
+
+* Bump the version of `master`:
+
+  ```console
+  $ git checkout master
+  $ git pull
+  $ NEW_VERSION=2.13.0
+  $ echo -n $NEW_VERSION > .version
+  $ git checkout -b bump-$NEW_VERSION
+  $ git commit -a -m 'Bump version'
+  $ git push --set-upstream origin bump-$NEW_VERSION
+  ```
+
+  Make a pull request and auto-merge it.
+
+* Create a milestone for the next release, move all unresolved issues
+  from the previous milestone, and close the previous milestone. Set
+  the date for the next milestone 6 weeks from now.
+
+* Create a backport label
+
+* Post an [announcement on Discourse](https://discourse.nixos.org/c/announcements/8), including the contents of
+  `rl-$VERSION.md`.
+
+## Creating a point release
+
+* Wait for the desired evaluation of the maintenance jobset to finish
+  building.
+
+* Run
+
+  ```console
+  $ IS_LATEST=1 ./maintainers/upload-release.pl <EVAL-ID>
+  ```
+
+  Omit `IS_LATEST=1` when creating a point release that is not on the
+  most recent stable branch. This prevents `nixos.org` to going back
+  to an older release.
+
+* Bump the version number of the release branch as above (e.g. to
+  `2.12.2`).
+  
+## Recovering from mistakes
+
+`upload-release.pl` should be idempotent. For instance a wrong `IS_LATEST` value can be fixed that way, by running the script on the actual latest release.
+

maintainers/upload-release.pl

@@ -115,10 +115,6 @@ sub downloadFile {
 
     write_file("$tmpFile.sha256", $sha256_actual);
 
-    if (! -e "$tmpFile.asc") {
-        system("gpg2 --detach-sign --armor $tmpFile") == 0 or die "unable to sign $tmpFile\n";
-    }
-
     return $sha256_expected;
 }
 
@@ -194,7 +190,7 @@ for my $fn (glob "$tmpDir/*") {
         my $configuration = ();
         $configuration->{content_type} = "application/octet-stream";
 
-        if ($fn =~ /.sha256|.asc|install/) {
+        if ($fn =~ /.sha256|install/) {
             # Text files
             $configuration->{content_type} = "text/plain";
         }

misc/launchd/org.nixos.nix-daemon.plist.in

@@ -28,7 +28,7 @@
     <key>SoftResourceLimits</key>
     <dict>
       <key>NumberOfFiles</key>
-      <integer>4096</integer>
+      <integer>1048576</integer>
     </dict>
   </dict>
 </plist>

misc/systemd/nix-daemon.service.in

@@ -9,7 +9,7 @@ ConditionPathIsReadWrite=@localstatedir@/nix/daemon-socket
 [Service]
 ExecStart=@@bindir@/nix-daemon nix-daemon --daemon
 KillMode=process
-LimitNOFILE=4096
+LimitNOFILE=1048576
 
 [Install]
 WantedBy=multi-user.target

misc/zsh/completion.zsh

@@ -10,14 +10,15 @@ function _nix() {
   local -a suggestions
   declare -a suggestions
   for suggestion in ${res:1}; do
-    # FIXME: This doesn't work properly if the suggestion word contains a `:`
-    # itself
-    suggestions+="${suggestion/	/:}"
+    suggestions+=("${suggestion%%	*}")
   done
+  local -a args
   if [[ "$tpe" == filenames ]]; then
-    compadd -f
+    args+=('-f')
+  elif [[ "$tpe" == attrs ]]; then
+    args+=('-S' '')
   fi
-  _describe 'nix' suggestions
+  compadd -J nix "${args[@]}" -a suggestions
 }
 
 _nix "$@"

mk/common-test.sh

@@ -0,0 +1,11 @@
+TESTS_ENVIRONMENT=("TEST_NAME=${test%.*}" 'NIX_REMOTE=')
+
+: ${BASH:=/usr/bin/env bash}
+
+init_test () {
+   cd tests && env "${TESTS_ENVIRONMENT[@]}" $BASH -e init.sh 2>/dev/null > /dev/null
+}
+
+run_test_proper () {
+   cd $(dirname $test) && env "${TESTS_ENVIRONMENT[@]}" $BASH -e $(basename $test)
+}

mk/debug-test.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -eu
+
+test=$1
+
+dir="$(dirname "${BASH_SOURCE[0]}")"
+source "$dir/common-test.sh"
+
+(init_test)
+run_test_proper

mk/libraries.mk

@@ -67,6 +67,7 @@ define build-library
 
   $(1)_LDFLAGS_USE :=
   $(1)_LDFLAGS_USE_INSTALLED :=
+  $(1)_LIB_CLOSURE := $(1)
 
   $$(eval $$(call create-dir, $$(_d)))
 
@@ -128,10 +129,12 @@ define build-library
 	+$$(trace-ld) $(LD) -Ur -o $$(_d)/$$($(1)_NAME).o $$^
 	$$(trace-ar) $(AR) crs $$@ $$(_d)/$$($(1)_NAME).o
 
-    $(1)_LDFLAGS_USE += $$($(1)_PATH) $$($(1)_LDFLAGS)
+    $(1)_LDFLAGS_USE += $$($(1)_PATH) $$($(1)_LDFLAGS) $$(foreach lib, $$($(1)_LIBS), $$($$(lib)_LDFLAGS_USE))
 
     $(1)_INSTALL_PATH := $$(libdir)/$$($(1)_NAME).a
 
+    $(1)_LIB_CLOSURE += $$($(1)_LIBS)
+
   endif
 
   $(1)_LDFLAGS_USE += $$($(1)_LDFLAGS_PROPAGATED)

mk/programs.mk

@@ -3,6 +3,9 @@ programs-list :=
 # Build a program with symbolic name $(1).  The program is defined by
 # various variables prefixed by ‘$(1)_’:
 #
+# - $(1)_NAME: the name of the program (e.g. ‘foo’); defaults to
+#   $(1).
+#
 # - $(1)_DIR: the directory where the (non-installed) program will be
 #   placed.
 #
@@ -23,11 +26,12 @@ programs-list :=
 # - $(1)_INSTALL_DIR: the directory where the program will be
 #   installed; defaults to $(bindir).
 define build-program
+  $(1)_NAME ?= $(1)
   _d := $(buildprefix)$$($(1)_DIR)
   _srcs := $$(sort $$(foreach src, $$($(1)_SOURCES), $$(src)))
   $(1)_OBJS := $$(addprefix $(buildprefix), $$(addsuffix .o, $$(basename $$(_srcs))))
-  _libs := $$(foreach lib, $$($(1)_LIBS), $$($$(lib)_PATH))
-  $(1)_PATH := $$(_d)/$(1)
+  _libs := $$(foreach lib, $$($(1)_LIBS), $$(foreach lib2, $$($$(lib)_LIB_CLOSURE), $$($$(lib2)_PATH)))
+  $(1)_PATH := $$(_d)/$$($(1)_NAME)
 
   $$(eval $$(call create-dir, $$(_d)))
 
@@ -38,7 +42,7 @@ define build-program
 
   ifdef $(1)_INSTALL_DIR
 
-    $(1)_INSTALL_PATH := $$($(1)_INSTALL_DIR)/$(1)
+    $(1)_INSTALL_PATH := $$($(1)_INSTALL_DIR)/$$($(1)_NAME)
 
     $$(eval $$(call create-dir, $$($(1)_INSTALL_DIR)))
 
@@ -54,7 +58,7 @@ define build-program
     else
 
       $(DESTDIR)$$($(1)_INSTALL_PATH): $$($(1)_PATH) | $(DESTDIR)$$($(1)_INSTALL_DIR)/
-	install -t $(DESTDIR)$$($(1)_INSTALL_DIR) $$<
+	+$$(trace-install) install -t $(DESTDIR)$$($(1)_INSTALL_DIR) $$<
 
     endif
   endif

mk/run-test.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env bash
 
 set -u
 
@@ -7,7 +7,12 @@ green=""
 yellow=""
 normal=""
 
-post_run_msg="ran test $1..."
+test=$1
+
+dir="$(dirname "${BASH_SOURCE[0]}")"
+source "$dir/common-test.sh"
+
+post_run_msg="ran test $test..."
 if [ -t 1 ]; then
     red=""
     green=""
@@ -16,12 +21,12 @@ if [ -t 1 ]; then
 fi
 
 run_test () {
-    (cd tests && env ${TESTS_ENVIRONMENT} init.sh 2>/dev/null > /dev/null)
-    log="$(cd $(dirname $1) && env ${TESTS_ENVIRONMENT} $(basename $1) 2>&1)"
+    (init_test 2>/dev/null > /dev/null)
+    log="$(run_test_proper 2>&1)"
     status=$?
 }
 
-run_test "$1"
+run_test
 
 # Hack: Retry the test if it fails with “unexpected EOF reading a line” as these
 # appear randomly without anyone knowing why.
@@ -32,7 +37,7 @@ if [[ $status -ne 0 && $status -ne 99 && \
 ]]; then
     echo "$post_run_msg [${yellow}FAIL$normal] (possibly flaky, so will be retried)"
     echo "$log" | sed 's/^/    /'
-    run_test "$1"
+    run_test
 fi
 
 if [ $status -eq 0 ]; then

mk/tests.mk

@@ -8,7 +8,11 @@ define run-install-test
 
   .PHONY: $1.test
   $1.test: $1 $(test-deps)
-	@env TEST_NAME=$(basename $1) TESTS_ENVIRONMENT="$(tests-environment)" mk/run_test.sh $1 < /dev/null
+	@env BASH=$(bash) $(bash) mk/run-test.sh $1 < /dev/null
+
+  .PHONY: $1.test-debug
+  $1.test-debug: $1 $(test-deps)
+	@env BASH=$(bash) $(bash) mk/debug-test.sh $1 < /dev/null
 
 endef
 

perl/Makefile

@@ -1,6 +1,6 @@
 makefiles = local.mk
 
-GLOBAL_CXXFLAGS += -g -Wall -std=c++17 -I ../src
+GLOBAL_CXXFLAGS += -g -Wall -std=c++2a -I ../src
 
 -include Makefile.config
 

perl/lib/Nix/Store.xs

@@ -26,6 +26,7 @@ static ref<Store> store()
     static std::shared_ptr<Store> _store;
     if (!_store) {
         try {
+            initLibStore();
             loadConfFile();
             settings.lockCPU = false;
             _store = openStore();

scripts/install-multi-user.sh

@@ -37,6 +37,19 @@ readonly PROFILE_TARGETS=("/etc/bashrc" "/etc/profile.d/nix.sh" "/etc/zshrc" "/e
 readonly PROFILE_BACKUP_SUFFIX=".backup-before-nix"
 readonly PROFILE_NIX_FILE="$NIX_ROOT/var/nix/profiles/default/etc/profile.d/nix-daemon.sh"
 
+# Fish has different syntax than zsh/bash, treat it separate
+readonly PROFILE_FISH_SUFFIX="conf.d/nix.fish"
+readonly PROFILE_FISH_PREFIXES=(
+    # each of these are common values of $__fish_sysconf_dir,
+    # under which Fish will look for a file named
+    # $PROFILE_FISH_SUFFIX.
+    "/etc/fish"              # standard
+    "/usr/local/etc/fish"    # their installer .pkg for macOS
+    "/opt/homebrew/etc/fish" # homebrew
+    "/opt/local/etc/fish"    # macports
+)
+readonly PROFILE_NIX_FILE_FISH="$NIX_ROOT/var/nix/profiles/default/etc/profile.d/nix-daemon.fish"
+
 readonly NIX_INSTALLED_NIX="@nix@"
 readonly NIX_INSTALLED_CACERT="@cacert@"
 #readonly NIX_INSTALLED_NIX="/nix/store/j8dbv5w6jl34caywh2ygdy88knx1mdf7-nix-2.3.6"
@@ -45,7 +58,7 @@ readonly EXTRACTED_NIX_PATH="$(dirname "$0")"
 
 readonly ROOT_HOME=~root
 
-if [ -t 0 ]; then
+if [ -t 0 ] && [ -z "${NIX_INSTALLER_YES:-}" ]; then
     readonly IS_HEADLESS='no'
 else
     readonly IS_HEADLESS='yes'
@@ -84,13 +97,10 @@ is_os_darwin() {
 }
 
 contact_us() {
-    echo "You can open an issue at https://github.com/nixos/nix/issues"
+    echo "You can open an issue at"
+    echo "https://github.com/NixOS/nix/issues/new?labels=installer&template=installer.md"
     echo ""
-    echo "Or feel free to contact the team:"
-    echo " - Matrix: #nix:nixos.org"
-    echo " - IRC: in #nixos on irc.libera.chat"
-    echo " - twitter: @nixos_org"
-    echo " - forum: https://discourse.nixos.org"
+    echo "Or get in touch with the community: https://nixos.org/community"
 }
 get_help() {
     echo "We'd love to help if you need it."
@@ -126,7 +136,7 @@ EOF
     cat <<EOF
 $step. Delete the files Nix added to your system:
 
-  sudo rm -rf /etc/nix $NIX_ROOT $ROOT_HOME/.nix-profile $ROOT_HOME/.nix-defexpr $ROOT_HOME/.nix-channels $HOME/.nix-profile $HOME/.nix-defexpr $HOME/.nix-channels
+  sudo rm -rf "/etc/nix" "$NIX_ROOT" "$ROOT_HOME/.nix-profile" "$ROOT_HOME/.nix-defexpr" "$ROOT_HOME/.nix-channels" "$ROOT_HOME/.local/state/nix" "$ROOT_HOME/.cache/nix" "$HOME/.nix-profile" "$HOME/.nix-defexpr" "$HOME/.nix-channels" "$HOME/.local/state/nix" "$HOME/.cache/nix"
 
 and that is it.
 
@@ -362,7 +372,7 @@ finish_fail() {
     finish_cleanup
 
     failure <<EOF
-Jeeze, something went wrong. If you can take all the output and open
+Oh no, something went wrong. If you can take all the output and open
 an issue, we'd love to fix the problem so nobody else has this issue.
 
 :(
@@ -565,7 +575,7 @@ EOF
     # to extract _just_ the user's note, instead it is prefixed with
     # some plist junk. This was causing the user note to always be set,
     # even if there was no reason for it.
-    if ! poly_user_note_get "$username" | grep -q "Nix build user $coreid"; then
+    if poly_user_note_get "$username" | grep -q "Nix build user $coreid"; then
         row "              Note" "Nix build user $coreid"
     else
         poly_user_note_set "$username" "Nix build user $coreid"
@@ -810,7 +820,7 @@ EOF
         fi
 
         _sudo "to load data for the first time in to the Nix Database" \
-              "$NIX_INSTALLED_NIX/bin/nix-store" --load-db < ./.reginfo
+              HOME="$ROOT_HOME" "$NIX_INSTALLED_NIX/bin/nix-store" --load-db < ./.reginfo
 
         echo "      Just finished getting the nix database ready."
     )
@@ -828,6 +838,19 @@ fi
 EOF
 }
 
+# Fish has differing syntax
+fish_source_lines() {
+    cat <<EOF
+
+# Nix
+if test -e '$PROFILE_NIX_FILE_FISH'
+  . '$PROFILE_NIX_FILE_FISH'
+end
+# End Nix
+
+EOF
+}
+
 configure_shell_profile() {
     task "Setting up shell profiles: ${PROFILE_TARGETS[*]}"
     for profile_target in "${PROFILE_TARGETS[@]}"; do
@@ -849,6 +872,27 @@ configure_shell_profile() {
                         tee -a "$profile_target"
         fi
     done
+
+    task "Setting up shell profiles for Fish with with ${PROFILE_FISH_SUFFIX} inside ${PROFILE_FISH_PREFIXES[*]}"
+    for fish_prefix in "${PROFILE_FISH_PREFIXES[@]}"; do
+        if [ ! -d "$fish_prefix" ]; then
+            # this specific prefix (ie: /etc/fish) is very likely to exist
+            # if Fish is installed with this sysconfdir.
+            continue
+        fi
+
+        profile_target="${fish_prefix}/${PROFILE_FISH_SUFFIX}"
+        conf_dir=$(dirname "$profile_target")
+        if [ ! -d "$conf_dir" ]; then
+            _sudo "create $conf_dir for our Fish hook" \
+                mkdir "$conf_dir"
+        fi
+
+        fish_source_lines \
+            | _sudo "write nix-daemon settings to $profile_target" \
+                    tee "$profile_target"
+    done
+
     # TODO: should we suggest '. $PROFILE_NIX_FILE'? It would get them on
     # their way less disruptively, but a counter-argument is that they won't
     # immediately notice if something didn't get set up right?

scripts/install-nix-from-closure.sh

@@ -71,6 +71,8 @@ while [ $# -gt 0 ]; do
         #     # intentional tail space
         #     ACTIONS="${ACTIONS}uninstall "
         #     ;;
+        --yes)
+            export NIX_INSTALLER_YES=1;;
         --no-channel-add)
             export NIX_INSTALLER_NO_CHANNEL_ADD=1;;
         --daemon-user-count)
@@ -90,7 +92,7 @@ while [ $# -gt 0 ]; do
             shift;;
         *)
             {
-                echo "Nix Installer [--daemon|--no-daemon] [--daemon-user-count INT] [--no-channel-add] [--no-modify-profile] [--nix-extra-conf-file FILE]"
+                echo "Nix Installer [--daemon|--no-daemon] [--daemon-user-count INT] [--yes] [--no-channel-add] [--no-modify-profile] [--nix-extra-conf-file FILE]"
 
                 echo "Choose installation method."
                 echo ""
@@ -104,6 +106,8 @@ while [ $# -gt 0 ]; do
                 echo "              trivial to uninstall."
                 echo "              (default)"
                 echo ""
+                echo " --yes:               Run the script non-interactively, accepting all prompts."
+                echo ""
                 echo " --no-channel-add:    Don't add any channels. nixpkgs-unstable is installed by default."
                 echo ""
                 echo " --no-modify-profile: Don't modify the user profile to automatically load nix."
@@ -184,6 +188,8 @@ fi
 # shellcheck source=./nix-profile.sh.in
 . "$nix/etc/profile.d/nix.sh"
 
+NIX_LINK="$HOME/.nix-profile"
+
 if ! "$nix/bin/nix-env" -i "$nix"; then
     echo "$0: unable to install Nix into your default profile" >&2
     exit 1
@@ -192,7 +198,7 @@ fi
 # Install an SSL certificate bundle.
 if [ -z "$NIX_SSL_CERT_FILE" ] || ! [ -f "$NIX_SSL_CERT_FILE" ]; then
     "$nix/bin/nix-env" -i "$cacert"
-    export NIX_SSL_CERT_FILE="$HOME/.nix-profile/etc/ssl/certs/ca-bundle.crt"
+    export NIX_SSL_CERT_FILE="$NIX_LINK/etc/ssl/certs/ca-bundle.crt"
 fi
 
 # Subscribe the user to the Nixpkgs channel and fetch it.
@@ -209,31 +215,50 @@ if [ -z "$NIX_INSTALLER_NO_CHANNEL_ADD" ]; then
 fi
 
 added=
-p=$HOME/.nix-profile/etc/profile.d/nix.sh
+p=
+p_sh=$NIX_LINK/etc/profile.d/nix.sh
+p_fish=$NIX_LINK/etc/profile.d/nix.fish
 if [ -z "$NIX_INSTALLER_NO_MODIFY_PROFILE" ]; then
     # Make the shell source nix.sh during login.
     for i in .bash_profile .bash_login .profile; do
         fn="$HOME/$i"
         if [ -w "$fn" ]; then
-            if ! grep -q "$p" "$fn"; then
+            if ! grep -q "$p_sh" "$fn"; then
                 echo "modifying $fn..." >&2
-                printf '\nif [ -e %s ]; then . %s; fi # added by Nix installer\n' "$p" "$p" >> "$fn"
+                printf '\nif [ -e %s ]; then . %s; fi # added by Nix installer\n' "$p_sh" "$p_sh" >> "$fn"
             fi
             added=1
+            p=${p_sh}
             break
         fi
     done
     for i in .zshenv .zshrc; do
         fn="$HOME/$i"
         if [ -w "$fn" ]; then
-            if ! grep -q "$p" "$fn"; then
+            if ! grep -q "$p_sh" "$fn"; then
                 echo "modifying $fn..." >&2
-                printf '\nif [ -e %s ]; then . %s; fi # added by Nix installer\n' "$p" "$p" >> "$fn"
+                printf '\nif [ -e %s ]; then . %s; fi # added by Nix installer\n' "$p_sh" "$p_sh" >> "$fn"
             fi
             added=1
+            p=${p_sh}
             break
         fi
     done
+
+    if [ -d "$HOME/.config/fish" ]; then
+        fishdir=$HOME/.config/fish/conf.d
+        if [ ! -d "$fishdir" ]; then
+            mkdir -p "$fishdir"
+        fi
+
+        fn="$fishdir/nix.fish"
+        echo "placing $fn..." >&2
+        printf '\nif test -e %s; . %s; end # added by Nix installer\n' "$p_fish" "$p_fish" > "$fn"
+        added=1
+        p=${p_fish}
+    fi
+else
+    p=${p_sh}
 fi
 
 if [ -z "$added" ]; then

scripts/install-systemd-multi-user.sh

@@ -24,12 +24,17 @@ $1
 EOF
 }
 
+escape_systemd_env() {
+    temp_var="${1//\'/\\\'}"
+    echo "${temp_var//\%/%%}"
+}
+
 # Gather all non-empty proxy environment variables into a string
 create_systemd_proxy_env() {
     vars="http_proxy https_proxy ftp_proxy no_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY NO_PROXY"
     for v in $vars; do
         if [ "x${!v:-}" != "x" ]; then
-            echo "Environment=${v}=${!v}"
+            echo "Environment=${v}=$(escape_systemd_env ${!v})"
         fi
     done
 }

scripts/install.in

@@ -40,12 +40,12 @@ case "$(uname -s).$(uname -m)" in
         path=@tarballPath_aarch64-linux@
         system=aarch64-linux
         ;;
-    Linux.armv6l_linux)
+    Linux.armv6l)
         hash=@tarballHash_armv6l-linux@
         path=@tarballPath_armv6l-linux@
         system=armv6l-linux
         ;;
-    Linux.armv7l_linux)
+    Linux.armv7l)
         hash=@tarballHash_armv7l-linux@
         path=@tarballPath_armv7l-linux@
         system=armv7l-linux

scripts/local.mk

@@ -6,6 +6,8 @@ noinst-scripts += $(nix_noinst_scripts)
 profiledir = $(sysconfdir)/profile.d
 
 $(eval $(call install-file-as, $(d)/nix-profile.sh, $(profiledir)/nix.sh, 0644))
+$(eval $(call install-file-as, $(d)/nix-profile.fish, $(profiledir)/nix.fish, 0644))
 $(eval $(call install-file-as, $(d)/nix-profile-daemon.sh, $(profiledir)/nix-daemon.sh, 0644))
+$(eval $(call install-file-as, $(d)/nix-profile-daemon.fish, $(profiledir)/nix-daemon.fish, 0644))
 
 clean-files += $(nix_noinst_scripts)

scripts/nix-profile-daemon.fish.in

@@ -0,0 +1,49 @@
+function add_path --argument-names new_path
+    if type -q fish_add_path
+        # fish 3.2.0 or newer
+	fish_add_path --prepend --global $new_path
+    else
+        # older versions of fish
+        if not contains $new_path $fish_user_paths
+            set --global fish_user_paths $new_path $fish_user_paths
+        end
+    end
+end
+
+# Only execute this file once per shell.
+if test -n "$__ETC_PROFILE_NIX_SOURCED"
+  exit
+end
+
+set __ETC_PROFILE_NIX_SOURCED 1
+
+set --export NIX_PROFILES "@localstatedir@/nix/profiles/default $HOME/.nix-profile"
+
+# Set $NIX_SSL_CERT_FILE so that Nixpkgs applications like curl work.
+if test -n "$NIX_SSH_CERT_FILE"
+  : # Allow users to override the NIX_SSL_CERT_FILE
+else if test -e /etc/ssl/certs/ca-certificates.crt # NixOS, Ubuntu, Debian, Gentoo, Arch
+  set --export NIX_SSL_CERT_FILE /etc/ssl/certs/ca-certificates.crt
+else if test -e /etc/ssl/ca-bundle.pem # openSUSE Tumbleweed
+  set --export NIX_SSL_CERT_FILE /etc/ssl/ca-bundle.pem
+else if test -e /etc/ssl/certs/ca-bundle.crt # Old NixOS
+  set --export NIX_SSL_CERT_FILE /etc/ssl/certs/ca-bundle.crt
+else if test -e /etc/pki/tls/certs/ca-bundle.crt # Fedora, CentOS
+  set --export NIX_SSL_CERT_FILE /etc/pki/tls/certs/ca-bundle.crt
+else if test -e "$NIX_LINK/etc/ssl/certs/ca-bundle.crt" # fall back to cacert in Nix profile
+  set --export NIX_SSL_CERT_FILE "$NIX_LINK/etc/ssl/certs/ca-bundle.crt"
+else if test -e "$NIX_LINK/etc/ca-bundle.crt" # old cacert in Nix profile
+  set --export NIX_SSL_CERT_FILE "$NIX_LINK/etc/ca-bundle.crt"
+else
+  # Fall back to what is in the nix profiles, favouring whatever is defined last.
+  for i in $NIX_PROFILES
+    if test -e "$i/etc/ssl/certs/ca-bundle.crt"
+      set --export NIX_SSL_CERT_FILE "$i/etc/ssl/certs/ca-bundle.crt"
+    end
+  end
+end
+
+add_path "@localstatedir@/nix/profiles/default/bin"
+add_path "$HOME/.nix-profile/bin"
+
+functions -e add_path

scripts/nix-profile-daemon.sh.in

@@ -2,7 +2,33 @@
 if [ -n "${__ETC_PROFILE_NIX_SOURCED:-}" ]; then return; fi
 __ETC_PROFILE_NIX_SOURCED=1
 
-export NIX_PROFILES="@localstatedir@/nix/profiles/default $HOME/.nix-profile"
+NIX_LINK=$HOME/.nix-profile
+if [ -n "${XDG_STATE_HOME-}" ]; then
+    NIX_LINK_NEW="$XDG_STATE_HOME/nix/profile"
+else
+    NIX_LINK_NEW=$HOME/.local/state/nix/profile
+fi
+if [ -e "$NIX_LINK_NEW" ]; then
+    NIX_LINK="$NIX_LINK_NEW"
+else
+    if [ -t 2 ] && [ -e "$NIX_LINK_NEW" ]; then
+        warning="\033[1;35mwarning:\033[0m"
+        printf "$warning Both %s and legacy %s exist; using the latter.\n" "$NIX_LINK_NEW" "$NIX_LINK" 1>&2
+        if [ "$(realpath "$NIX_LINK")" = "$(realpath "$NIX_LINK_NEW")" ]; then
+            printf "         Since the profiles match, you can safely delete either of them.\n" 1>&2
+        else
+            # This should be an exceptionally rare occasion: the only way to get it would be to
+            # 1. Update to newer Nix;
+            # 2. Remove .nix-profile;
+            # 3. Set the $NIX_LINK_NEW to something other than the default user profile;
+            # 4. Roll back to older Nix.
+            # If someone did all that, they can probably figure out how to migrate the profile.
+            printf "$warning Profiles do not match. You should manually migrate from %s to %s.\n" "$NIX_LINK" "$NIX_LINK_NEW" 1>&2
+        fi
+    fi
+fi
+
+export NIX_PROFILES="@localstatedir@/nix/profiles/default $NIX_LINK"
 
 # Set $NIX_SSL_CERT_FILE so that Nixpkgs applications like curl work.
 if [ -n "${NIX_SSL_CERT_FILE:-}" ]; then
@@ -34,4 +60,5 @@ else
   unset -f check_nix_profiles
 fi
 
-export PATH="$HOME/.nix-profile/bin:@localstatedir@/nix/profiles/default/bin:$PATH"
+export PATH="$NIX_LINK/bin:@localstatedir@/nix/profiles/default/bin:$PATH"
+unset NIX_LINK

scripts/nix-profile.fish.in

@@ -0,0 +1,51 @@
+function add_path --argument-names new_path
+    if type -q fish_add_path
+        # fish 3.2.0 or newer
+	fish_add_path --prepend --global $new_path
+    else
+        # older versions of fish
+        if not contains $new_path $fish_user_paths
+            set --global fish_user_paths $new_path $fish_user_paths
+        end
+    end
+end
+
+if test -n "$HOME" && test -n "$USER"
+
+    # Set up the per-user profile.
+
+    set NIX_LINK $HOME/.nix-profile
+
+    # Set up environment.
+    # This part should be kept in sync with nixpkgs:nixos/modules/programs/environment.nix
+    set --export NIX_PROFILES "@localstatedir@/nix/profiles/default $HOME/.nix-profile"
+
+    # Set $NIX_SSL_CERT_FILE so that Nixpkgs applications like curl work.
+    if test -n "$NIX_SSH_CERT_FILE"
+        : # Allow users to override the NIX_SSL_CERT_FILE
+    else if test -e /etc/ssl/certs/ca-certificates.crt # NixOS, Ubuntu, Debian, Gentoo, Arch
+        set --export NIX_SSL_CERT_FILE /etc/ssl/certs/ca-certificates.crt
+    else if test -e /etc/ssl/ca-bundle.pem # openSUSE Tumbleweed
+        set --export NIX_SSL_CERT_FILE /etc/ssl/ca-bundle.pem
+    else if test -e /etc/ssl/certs/ca-bundle.crt # Old NixOS
+        set --export NIX_SSL_CERT_FILE /etc/ssl/certs/ca-bundle.crt
+    else if test -e /etc/pki/tls/certs/ca-bundle.crt # Fedora, CentOS
+        set --export NIX_SSL_CERT_FILE /etc/pki/tls/certs/ca-bundle.crt
+    else if test -e "$NIX_LINK/etc/ssl/certs/ca-bundle.crt" # fall back to cacert in Nix profile
+        set --export NIX_SSL_CERT_FILE "$NIX_LINK/etc/ssl/certs/ca-bundle.crt"
+    else if test -e "$NIX_LINK/etc/ca-bundle.crt" # old cacert in Nix profile
+        set --export NIX_SSL_CERT_FILE "$NIX_LINK/etc/ca-bundle.crt"
+    end
+
+    # Only use MANPATH if it is already set. In general `man` will just simply
+    # pick up `.nix-profile/share/man` because is it close to `.nix-profile/bin`
+    # which is in the $PATH. For more info, run `manpath -d`.
+    if set --query MANPATH
+      set --export --prepend --path MANPATH "$NIX_LINK/share/man"
+    end
+
+    add_path "$NIX_LINK/bin"
+    set --erase NIX_LINK
+end
+
+functions -e add_path

scripts/nix-profile.sh.in

@@ -1,13 +1,36 @@
 if [ -n "$HOME" ] && [ -n "$USER" ]; then
 
     # Set up the per-user profile.
-    # This part should be kept in sync with nixpkgs:nixos/modules/programs/shell.nix
 
-    NIX_LINK=$HOME/.nix-profile
+    NIX_LINK="$HOME/.nix-profile"
+    if [ -n "${XDG_STATE_HOME-}" ]; then
+        NIX_LINK_NEW="$XDG_STATE_HOME/nix/profile"
+    else
+        NIX_LINK_NEW="$HOME/.local/state/nix/profile"
+    fi
+    if [ -e "$NIX_LINK_NEW" ]; then
+        NIX_LINK="$NIX_LINK_NEW"
+    else
+        if [ -t 2 ] && [ -e "$NIX_LINK_NEW" ]; then
+            warning="\033[1;35mwarning:\033[0m"
+            printf "$warning Both %s and legacy %s exist; using the latter.\n" "$NIX_LINK_NEW" "$NIX_LINK" 1>&2
+            if [ "$(realpath "$NIX_LINK")" = "$(realpath "$NIX_LINK_NEW")" ]; then
+                printf "         Since the profiles match, you can safely delete either of them.\n" 1>&2
+            else
+                # This should be an exceptionally rare occasion: the only way to get it would be to
+                # 1. Update to newer Nix;
+                # 2. Remove .nix-profile;
+                # 3. Set the $NIX_LINK_NEW to something other than the default user profile;
+                # 4. Roll back to older Nix.
+                # If someone did all that, they can probably figure out how to migrate the profile.
+                printf "$warning Profiles do not match. You should manually migrate from %s to %s.\n" "$NIX_LINK" "$NIX_LINK_NEW" 1>&2
+            fi
+        fi
+    fi
 
     # Set up environment.
     # This part should be kept in sync with nixpkgs:nixos/modules/programs/environment.nix
-    export NIX_PROFILES="@localstatedir@/nix/profiles/default $HOME/.nix-profile"
+    export NIX_PROFILES="@localstatedir@/nix/profiles/default $NIX_LINK"
 
     # Set $NIX_SSL_CERT_FILE so that Nixpkgs applications like curl work.
     if [ -e /etc/ssl/certs/ca-certificates.crt ]; then # NixOS, Ubuntu, Debian, Gentoo, Arch
@@ -32,5 +55,5 @@ if [ -n "$HOME" ] && [ -n "$USER" ]; then
     fi
 
     export PATH="$NIX_LINK/bin:$PATH"
-    unset NIX_LINK
+    unset NIX_LINK NIX_LINK_NEW
 fi

src/build-remote/build-remote.cc

@@ -72,6 +72,7 @@ static int main_build_remote(int argc, char * * argv)
             settings.set(name, value);
         }
 
+        auto maxBuildJobs = settings.maxBuildJobs;
         settings.maxBuildJobs.set("1"); // hack to make tests with local?root= work
 
         initPlugins();
@@ -112,10 +113,14 @@ static int main_build_remote(int argc, char * * argv)
             drvPath = store->parseStorePath(readString(source));
             auto requiredFeatures = readStrings<std::set<std::string>>(source);
 
-            auto canBuildLocally = amWilling
+            /* It would be possible to build locally after some builds clear out,
+               so don't show the warning now: */
+            bool couldBuildLocally = maxBuildJobs > 0
                  &&  (  neededSystem == settings.thisSystem
                      || settings.extraPlatforms.get().count(neededSystem) > 0)
                  &&  allSupportedLocally(*store, requiredFeatures);
+            /* It's possible to build this locally right now: */
+            bool canBuildLocally = amWilling && couldBuildLocally;
 
             /* Error ignored here, will be caught later */
             mkdir(currentLoad.c_str(), 0777);
@@ -186,12 +191,12 @@ static int main_build_remote(int argc, char * * argv)
                         // build the hint template.
                         std::string errorText =
                             "Failed to find a machine for remote build!\n"
-                            "derivation: %s\nrequired (system, features): (%s, %s)";
+                            "derivation: %s\nrequired (system, features): (%s, [%s])";
                         errorText += "\n%s available machines:";
                         errorText += "\n(systems, maxjobs, supportedFeatures, mandatoryFeatures)";
 
                         for (unsigned int i = 0; i < machines.size(); ++i)
-                            errorText += "\n(%s, %s, %s, %s)";
+                            errorText += "\n([%s], %s, [%s], [%s])";
 
                         // add the template values.
                         std::string drvstr;
@@ -214,7 +219,7 @@ static int main_build_remote(int argc, char * * argv)
                                 % concatStringsSep<StringSet>(", ", m.supportedFeatures)
                                 % concatStringsSep<StringSet>(", ", m.mandatoryFeatures);
 
-                        printMsg(canBuildLocally ? lvlChatty : lvlWarn, error);
+                        printMsg(couldBuildLocally ? lvlChatty : lvlWarn, error);
 
                         std::cerr << "# decline\n";
                     }

src/libcmd/command.cc

@@ -4,6 +4,7 @@
 #include "derivations.hh"
 #include "nixexpr.hh"
 #include "profiles.hh"
+#include "repl.hh"
 
 #include <nlohmann/json.hpp>
 
@@ -88,7 +89,8 @@ EvalCommand::EvalCommand()
 {
     addFlag({
         .longName = "debugger",
-        .description = "start an interactive environment if evaluation fails",
+        .description = "Start an interactive environment if evaluation fails.",
+        .category = MixEvalArgs::category,
         .handler = {&startReplOnEvalErrors, true},
     });
 }
@@ -120,12 +122,22 @@ ref<EvalState> EvalCommand::getEvalState()
             ;
 
         if (startReplOnEvalErrors) {
-            evalState->debugRepl = &runRepl;
+            evalState->debugRepl = &AbstractNixRepl::runSimple;
         };
     }
     return ref<EvalState>(evalState);
 }
 
+MixOperateOnOptions::MixOperateOnOptions()
+{
+    addFlag({
+        .longName = "derivation",
+        .description = "Operate on the [store derivation](../../glossary.md#gloss-store-derivation) rather than its outputs.",
+        .category = installablesCategory,
+        .handler = {&operateOn, OperateOn::Derivation},
+    });
+}
+
 BuiltPathsCommand::BuiltPathsCommand(bool recursive)
     : recursive(recursive)
 {
@@ -207,25 +219,11 @@ void StorePathCommand::run(ref<Store> store, std::vector<StorePath> && storePath
     run(store, *storePaths.begin());
 }
 
-Strings editorFor(const Path & file, uint32_t line)
-{
-    auto editor = getEnv("EDITOR").value_or("cat");
-    auto args = tokenizeString<Strings>(editor);
-    if (line > 0 && (
-        editor.find("emacs") != std::string::npos ||
-        editor.find("nano") != std::string::npos ||
-        editor.find("vim") != std::string::npos ||
-        editor.find("kak") != std::string::npos))
-        args.push_back(fmt("+%d", line));
-    args.push_back(file);
-    return args;
-}
-
 MixProfile::MixProfile()
 {
     addFlag({
         .longName = "profile",
-        .description = "The profile to update.",
+        .description = "The profile to operate on.",
         .labels = {"path"},
         .handler = {&profile},
         .completer = completePath

src/libcmd/command.hh

@@ -94,12 +94,8 @@ struct SourceExprCommand : virtual Args, MixFlakeOptions
 {
     std::optional<Path> file;
     std::optional<std::string> expr;
-    bool readOnlyMode = false;
 
-    // FIXME: move this; not all commands (e.g. 'nix run') use it.
-    OperateOn operateOn = OperateOn::Output;
-
-    SourceExprCommand(bool supportReadOnlyMode = false);
+    SourceExprCommand();
 
     std::vector<std::shared_ptr<Installable>> parseInstallables(
         ref<Store> store, std::vector<std::string> ss);
@@ -114,6 +110,11 @@ struct SourceExprCommand : virtual Args, MixFlakeOptions
     void completeInstallable(std::string_view prefix);
 };
 
+struct MixReadOnlyOption : virtual Args
+{
+    MixReadOnlyOption();
+};
+
 /* A command that operates on a list of "installables", which can be
    store paths, attribute paths, Nix expressions, etc. */
 struct InstallablesCommand : virtual Args, SourceExprCommand
@@ -139,7 +140,7 @@ struct InstallableCommand : virtual Args, SourceExprCommand
 {
     std::shared_ptr<Installable> installable;
 
-    InstallableCommand(bool supportReadOnlyMode = false);
+    InstallableCommand();
 
     void prepare() override;
 
@@ -153,8 +154,15 @@ private:
     std::string _installable{"."};
 };
 
+struct MixOperateOnOptions : virtual Args
+{
+    OperateOn operateOn = OperateOn::Output;
+
+    MixOperateOnOptions();
+};
+
 /* A command that operates on zero or more store paths. */
-struct BuiltPathsCommand : public InstallablesCommand
+struct BuiltPathsCommand : InstallablesCommand, virtual MixOperateOnOptions
 {
 private:
 
@@ -227,10 +235,6 @@ static RegisterCommand registerCommand2(std::vector<std::string> && name)
     return RegisterCommand(std::move(name), [](){ return make_ref<T>(); });
 }
 
-/* Helper function to generate args that invoke $EDITOR on
-   filename:lineno. */
-Strings editorFor(const Path & file, uint32_t line);
-
 struct MixProfile : virtual StoreCommand
 {
     std::optional<Path> profile;
@@ -280,8 +284,4 @@ void printClosureDiff(
     const StorePath & afterPath,
     std::string_view indent);
 
-
-void runRepl(
-    ref<EvalState> evalState,
-    const ValMap & extraEnv);
 }

src/libcmd/common-eval-args.cc

@@ -13,8 +13,6 @@ namespace nix {
 
 MixEvalArgs::MixEvalArgs()
 {
-    auto category = "Common evaluation options";
-
     addFlag({
         .longName = "arg",
         .description = "Pass the value *expr* as the argument *name* to Nix functions.",
@@ -34,7 +32,77 @@ MixEvalArgs::MixEvalArgs()
     addFlag({
         .longName = "include",
         .shortName = 'I',
-        .description = "Add *path* to the list of locations used to look up `<...>` file names.",
+        .description = R"(
+  Add *path* to the Nix search path. The Nix search path is
+  initialized from the colon-separated [`NIX_PATH`](@docroot@/command-ref/env-common.md#env-NIX_PATH) environment
+  variable, and is used to look up the location of Nix expressions using [paths](@docroot@/language/values.md#type-path) enclosed in angle
+  brackets (i.e., `<nixpkgs>`).
+
+  For instance, passing
+
+  ```
+  -I /home/eelco/Dev
+  -I /etc/nixos
+  ```
+
+  will cause Nix to look for paths relative to `/home/eelco/Dev` and
+  `/etc/nixos`, in that order. This is equivalent to setting the
+  `NIX_PATH` environment variable to
+
+  ```
+  /home/eelco/Dev:/etc/nixos
+  ```
+
+  It is also possible to match paths against a prefix. For example,
+  passing
+
+  ```
+  -I nixpkgs=/home/eelco/Dev/nixpkgs-branch
+  -I /etc/nixos
+  ```
+
+  will cause Nix to search for `<nixpkgs/path>` in
+  `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`.
+
+  If a path in the Nix search path starts with `http://` or `https://`,
+  it is interpreted as the URL of a tarball that will be downloaded and
+  unpacked to a temporary location. The tarball must consist of a single
+  top-level directory. For example, passing
+
+  ```
+  -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/master.tar.gz
+  ```
+
+  tells Nix to download and use the current contents of the `master`
+  branch in the `nixpkgs` repository.
+
+  The URLs of the tarballs from the official `nixos.org` channels
+  (see [the manual page for `nix-channel`](../nix-channel.md)) can be
+  abbreviated as `channel:<channel-name>`.  For instance, the
+  following two flags are equivalent:
+
+  ```
+  -I nixpkgs=channel:nixos-21.05
+  -I nixpkgs=https://nixos.org/channels/nixos-21.05/nixexprs.tar.xz
+  ```
+
+  You can also fetch source trees using [flake URLs](./nix3-flake.md#url-like-syntax) and add them to the
+  search path. For instance,
+
+  ```
+  -I nixpkgs=flake:nixpkgs
+  ```
+
+  specifies that the prefix `nixpkgs` shall refer to the source tree
+  downloaded from the `nixpkgs` entry in the flake registry. Similarly,
+
+  ```
+  -I nixpkgs=flake:github:NixOS/nixpkgs/nixos-22.05
+  ```
+
+  makes `<nixpkgs>` refer to a particular branch of the
+  `NixOS/nixpkgs` repository on GitHub.
+  )",
         .category = category,
         .labels = {"path"},
         .handler = {[&](std::string s) { searchPath.push_back(s); }}
@@ -91,14 +159,25 @@ Bindings * MixEvalArgs::getAutoArgs(EvalState & state)
 
 Path lookupFileArg(EvalState & state, std::string_view s)
 {
-    if (isUri(s)) {
-        return state.store->toRealPath(
-            fetchers::downloadTarball(
-                state.store, resolveUri(s), "source", false).first.storePath);
-    } else if (s.size() > 2 && s.at(0) == '<' && s.at(s.size() - 1) == '>') {
+    if (EvalSettings::isPseudoUrl(s)) {
+        auto storePath = fetchers::downloadTarball(
+            state.store, EvalSettings::resolvePseudoUrl(s), "source", false).first.storePath;
+        return state.store->toRealPath(storePath);
+    }
+
+    else if (hasPrefix(s, "flake:")) {
+        settings.requireExperimentalFeature(Xp::Flakes);
+        auto flakeRef = parseFlakeRef(std::string(s.substr(6)), {}, true, false);
+        auto storePath = flakeRef.resolve(state.store).fetchTree(state.store).first.storePath;
+        return state.store->toRealPath(storePath);
+    }
+
+    else if (s.size() > 2 && s.at(0) == '<' && s.at(s.size() - 1) == '>') {
         Path p(s.substr(1, s.size() - 2));
         return state.findFile(p);
-    } else
+    }
+
+    else
         return absPath(std::string(s));
 }
 

src/libcmd/common-eval-args.hh

@@ -10,6 +10,8 @@ class Bindings;
 
 struct MixEvalArgs : virtual Args
 {
+    static constexpr auto category = "Common evaluation options";
+
     MixEvalArgs();
 
     Bindings * getAutoArgs(EvalState & state);

src/libcmd/editor-for.cc

@@ -0,0 +1,20 @@
+#include "util.hh"
+#include "editor-for.hh"
+
+namespace nix {
+
+Strings editorFor(const Path & file, uint32_t line)
+{
+    auto editor = getEnv("EDITOR").value_or("cat");
+    auto args = tokenizeString<Strings>(editor);
+    if (line > 0 && (
+        editor.find("emacs") != std::string::npos ||
+        editor.find("nano") != std::string::npos ||
+        editor.find("vim") != std::string::npos ||
+        editor.find("kak") != std::string::npos))
+        args.push_back(fmt("+%d", line));
+    args.push_back(file);
+    return args;
+}
+
+}

src/libcmd/editor-for.hh

@@ -0,0 +1,11 @@
+#pragma once
+
+#include "types.hh"
+
+namespace nix {
+
+/* Helper function to generate args that invoke $EDITOR on
+   filename:lineno. */
+Strings editorFor(const Path & file, uint32_t line);
+
+}

src/libcmd/installable-attr-path.cc

@@ -0,0 +1,109 @@
+#include "globals.hh"
+#include "installable-attr-path.hh"
+#include "outputs-spec.hh"
+#include "util.hh"
+#include "command.hh"
+#include "attr-path.hh"
+#include "common-eval-args.hh"
+#include "derivations.hh"
+#include "eval-inline.hh"
+#include "eval.hh"
+#include "get-drvs.hh"
+#include "store-api.hh"
+#include "shared.hh"
+#include "flake/flake.hh"
+#include "eval-cache.hh"
+#include "url.hh"
+#include "registry.hh"
+#include "build-result.hh"
+
+#include <regex>
+#include <queue>
+
+#include <nlohmann/json.hpp>
+
+namespace nix {
+
+InstallableAttrPath::InstallableAttrPath(
+    ref<EvalState> state,
+    SourceExprCommand & cmd,
+    Value * v,
+    const std::string & attrPath,
+    ExtendedOutputsSpec extendedOutputsSpec)
+    : InstallableValue(state)
+    , cmd(cmd)
+    , v(allocRootValue(v))
+    , attrPath(attrPath)
+    , extendedOutputsSpec(std::move(extendedOutputsSpec))
+{ }
+
+std::pair<Value *, PosIdx> InstallableAttrPath::toValue(EvalState & state)
+{
+    auto [vRes, pos] = findAlongAttrPath(state, attrPath, *cmd.getAutoArgs(state), **v);
+    state.forceValue(*vRes, pos);
+    return {vRes, pos};
+}
+
+DerivedPathsWithInfo InstallableAttrPath::toDerivedPaths()
+{
+    auto v = toValue(*state).first;
+
+    Bindings & autoArgs = *cmd.getAutoArgs(*state);
+
+    DrvInfos drvInfos;
+    getDerivations(*state, *v, "", autoArgs, drvInfos, false);
+
+    // Backward compatibility hack: group results by drvPath. This
+    // helps keep .all output together.
+    std::map<StorePath, OutputsSpec> byDrvPath;
+
+    for (auto & drvInfo : drvInfos) {
+        auto drvPath = drvInfo.queryDrvPath();
+        if (!drvPath)
+            throw Error("'%s' is not a derivation", what());
+
+        auto newOutputs = std::visit(overloaded {
+            [&](const ExtendedOutputsSpec::Default & d) -> OutputsSpec {
+                std::set<std::string> outputsToInstall;
+                for (auto & output : drvInfo.queryOutputs(false, true))
+                    outputsToInstall.insert(output.first);
+                return OutputsSpec::Names { std::move(outputsToInstall) };
+            },
+            [&](const ExtendedOutputsSpec::Explicit & e) -> OutputsSpec {
+                return e;
+            },
+        }, extendedOutputsSpec.raw());
+
+        auto [iter, didInsert] = byDrvPath.emplace(*drvPath, newOutputs);
+
+        if (!didInsert)
+            iter->second = iter->second.union_(newOutputs);
+    }
+
+    DerivedPathsWithInfo res;
+    for (auto & [drvPath, outputs] : byDrvPath)
+        res.push_back({
+            .path = DerivedPath::Built {
+                .drvPath = drvPath,
+                .outputs = outputs,
+            },
+        });
+
+    return res;
+}
+
+InstallableAttrPath InstallableAttrPath::parse(
+    ref<EvalState> state,
+    SourceExprCommand & cmd,
+    Value * v,
+    std::string_view prefix,
+    ExtendedOutputsSpec extendedOutputsSpec)
+{
+    return {
+        state, cmd, v,
+        prefix == "." ? "" : std::string { prefix },
+        extendedOutputsSpec
+    };
+}
+
+}

src/libcmd/installable-attr-path.hh

@@ -0,0 +1,56 @@
+#include "globals.hh"
+#include "installable-value.hh"
+#include "outputs-spec.hh"
+#include "util.hh"
+#include "command.hh"
+#include "attr-path.hh"
+#include "common-eval-args.hh"
+#include "derivations.hh"
+#include "eval-inline.hh"
+#include "eval.hh"
+#include "get-drvs.hh"
+#include "store-api.hh"
+#include "shared.hh"
+#include "eval-cache.hh"
+#include "url.hh"
+#include "registry.hh"
+#include "build-result.hh"
+
+#include <regex>
+#include <queue>
+
+#include <nlohmann/json.hpp>
+
+namespace nix {
+
+class InstallableAttrPath : public InstallableValue
+{
+    SourceExprCommand & cmd;
+    RootValue v;
+    std::string attrPath;
+    ExtendedOutputsSpec extendedOutputsSpec;
+
+    InstallableAttrPath(
+        ref<EvalState> state,
+        SourceExprCommand & cmd,
+        Value * v,
+        const std::string & attrPath,
+        ExtendedOutputsSpec extendedOutputsSpec);
+
+    std::string what() const override { return attrPath; };
+
+    std::pair<Value *, PosIdx> toValue(EvalState & state) override;
+
+    DerivedPathsWithInfo toDerivedPaths() override;
+
+public:
+
+    static InstallableAttrPath parse(
+        ref<EvalState> state,
+        SourceExprCommand & cmd,
+        Value * v,
+        std::string_view prefix,
+        ExtendedOutputsSpec extendedOutputsSpec);
+};
+
+}

src/libcmd/installable-derived-path.cc

@@ -0,0 +1,70 @@
+#include "installable-derived-path.hh"
+#include "derivations.hh"
+
+namespace nix {
+
+std::string InstallableDerivedPath::what() const
+{
+    return derivedPath.to_string(*store);
+}
+
+DerivedPathsWithInfo InstallableDerivedPath::toDerivedPaths()
+{
+    return {{.path = derivedPath, .info = {} }};
+}
+
+std::optional<StorePath> InstallableDerivedPath::getStorePath()
+{
+    return std::visit(overloaded {
+        [&](const DerivedPath::Built & bfd) {
+            return bfd.drvPath;
+        },
+        [&](const DerivedPath::Opaque & bo) {
+            return bo.path;
+        },
+    }, derivedPath.raw());
+}
+
+InstallableDerivedPath InstallableDerivedPath::parse(
+    ref<Store> store,
+    std::string_view prefix,
+    ExtendedOutputsSpec extendedOutputsSpec)
+{
+    auto derivedPath = std::visit(overloaded {
+        // If the user did not use ^, we treat the output more liberally.
+        [&](const ExtendedOutputsSpec::Default &) -> DerivedPath {
+            // First, we accept a symlink chain or an actual store path.
+            auto storePath = store->followLinksToStorePath(prefix);
+            // Second, we see if the store path ends in `.drv` to decide what sort
+            // of derived path they want.
+            //
+            // This handling predates the `^` syntax. The `^*` in
+            // `/nix/store/hash-foo.drv^*` unambiguously means "do the
+            // `DerivedPath::Built` case", so plain `/nix/store/hash-foo.drv` could
+            // also unambiguously mean "do the DerivedPath::Opaque` case".
+            //
+            // Issue #7261 tracks reconsidering this `.drv` dispatching.
+            return storePath.isDerivation()
+                ? (DerivedPath) DerivedPath::Built {
+                    .drvPath = std::move(storePath),
+                    .outputs = OutputsSpec::All {},
+                }
+                : (DerivedPath) DerivedPath::Opaque {
+                    .path = std::move(storePath),
+                };
+        },
+        // If the user did use ^, we just do exactly what is written.
+        [&](const ExtendedOutputsSpec::Explicit & outputSpec) -> DerivedPath {
+            return DerivedPath::Built {
+                .drvPath = store->parseStorePath(prefix),
+                .outputs = outputSpec,
+            };
+        },
+    }, extendedOutputsSpec.raw());
+    return InstallableDerivedPath {
+        store,
+        std::move(derivedPath),
+    };
+}
+
+}

src/libcmd/installable-derived-path.hh

@@ -0,0 +1,28 @@
+#pragma once
+
+#include "installables.hh"
+
+namespace nix {
+
+struct InstallableDerivedPath : Installable
+{
+    ref<Store> store;
+    DerivedPath derivedPath;
+
+    InstallableDerivedPath(ref<Store> store, DerivedPath && derivedPath)
+        : store(store), derivedPath(std::move(derivedPath))
+    { }
+
+    std::string what() const override;
+
+    DerivedPathsWithInfo toDerivedPaths() override;
+
+    std::optional<StorePath> getStorePath() override;
+
+    static InstallableDerivedPath parse(
+        ref<Store> store,
+        std::string_view prefix,
+        ExtendedOutputsSpec extendedOutputsSpec);
+};
+
+}

src/libcmd/installable-flake.cc

@@ -0,0 +1,236 @@
+#include "globals.hh"
+#include "installable-flake.hh"
+#include "installable-derived-path.hh"
+#include "outputs-spec.hh"
+#include "util.hh"
+#include "command.hh"
+#include "attr-path.hh"
+#include "common-eval-args.hh"
+#include "derivations.hh"
+#include "eval-inline.hh"
+#include "eval.hh"
+#include "get-drvs.hh"
+#include "store-api.hh"
+#include "shared.hh"
+#include "flake/flake.hh"
+#include "eval-cache.hh"
+#include "url.hh"
+#include "registry.hh"
+#include "build-result.hh"
+
+#include <regex>
+#include <queue>
+
+#include <nlohmann/json.hpp>
+
+namespace nix {
+
+std::vector<std::string> InstallableFlake::getActualAttrPaths()
+{
+    std::vector<std::string> res;
+
+    for (auto & prefix : prefixes)
+        res.push_back(prefix + *attrPaths.begin());
+
+    for (auto & s : attrPaths)
+        res.push_back(s);
+
+    return res;
+}
+
+Value * InstallableFlake::getFlakeOutputs(EvalState & state, const flake::LockedFlake & lockedFlake)
+{
+    auto vFlake = state.allocValue();
+
+    callFlake(state, lockedFlake, *vFlake);
+
+    auto aOutputs = vFlake->attrs->get(state.symbols.create("outputs"));
+    assert(aOutputs);
+
+    state.forceValue(*aOutputs->value, [&]() { return aOutputs->value->determinePos(noPos); });
+
+    return aOutputs->value;
+}
+
+static std::string showAttrPaths(const std::vector<std::string> & paths)
+{
+    std::string s;
+    for (const auto & [n, i] : enumerate(paths)) {
+        if (n > 0) s += n + 1 == paths.size() ? " or " : ", ";
+        s += '\''; s += i; s += '\'';
+    }
+    return s;
+}
+
+InstallableFlake::InstallableFlake(
+    SourceExprCommand * cmd,
+    ref<EvalState> state,
+    FlakeRef && flakeRef,
+    std::string_view fragment,
+    ExtendedOutputsSpec extendedOutputsSpec,
+    Strings attrPaths,
+    Strings prefixes,
+    const flake::LockFlags & lockFlags)
+    : InstallableValue(state),
+      flakeRef(flakeRef),
+      attrPaths(fragment == "" ? attrPaths : Strings{(std::string) fragment}),
+      prefixes(fragment == "" ? Strings{} : prefixes),
+      extendedOutputsSpec(std::move(extendedOutputsSpec)),
+      lockFlags(lockFlags)
+{
+    if (cmd && cmd->getAutoArgs(*state)->size())
+        throw UsageError("'--arg' and '--argstr' are incompatible with flakes");
+}
+
+DerivedPathsWithInfo InstallableFlake::toDerivedPaths()
+{
+    Activity act(*logger, lvlTalkative, actUnknown, fmt("evaluating derivation '%s'", what()));
+
+    auto attr = getCursor(*state);
+
+    auto attrPath = attr->getAttrPathStr();
+
+    if (!attr->isDerivation()) {
+
+        // FIXME: use eval cache?
+        auto v = attr->forceValue();
+
+        if (v.type() == nPath) {
+            PathSet context;
+            auto storePath = state->copyPathToStore(context, Path(v.path));
+            return {{
+                .path = DerivedPath::Opaque {
+                    .path = std::move(storePath),
+                }
+            }};
+        }
+
+        else if (v.type() == nString) {
+            PathSet context;
+            auto s = state->forceString(v, context, noPos, fmt("while evaluating the flake output attribute '%s'", attrPath));
+            auto storePath = state->store->maybeParseStorePath(s);
+            if (storePath && context.count(std::string(s))) {
+                return {{
+                    .path = DerivedPath::Opaque {
+                        .path = std::move(*storePath),
+                    }
+                }};
+            } else
+                throw Error("flake output attribute '%s' evaluates to the string '%s' which is not a store path", attrPath, s);
+        }
+
+        else
+            throw Error("flake output attribute '%s' is not a derivation or path", attrPath);
+    }
+
+    auto drvPath = attr->forceDerivation();
+
+    std::optional<NixInt> priority;
+
+    if (attr->maybeGetAttr(state->sOutputSpecified)) {
+    } else if (auto aMeta = attr->maybeGetAttr(state->sMeta)) {
+        if (auto aPriority = aMeta->maybeGetAttr("priority"))
+            priority = aPriority->getInt();
+    }
+
+    return {{
+        .path = DerivedPath::Built {
+            .drvPath = std::move(drvPath),
+            .outputs = std::visit(overloaded {
+                [&](const ExtendedOutputsSpec::Default & d) -> OutputsSpec {
+                    std::set<std::string> outputsToInstall;
+                    if (auto aOutputSpecified = attr->maybeGetAttr(state->sOutputSpecified)) {
+                        if (aOutputSpecified->getBool()) {
+                            if (auto aOutputName = attr->maybeGetAttr("outputName"))
+                                outputsToInstall = { aOutputName->getString() };
+                        }
+                    } else if (auto aMeta = attr->maybeGetAttr(state->sMeta)) {
+                        if (auto aOutputsToInstall = aMeta->maybeGetAttr("outputsToInstall"))
+                            for (auto & s : aOutputsToInstall->getListOfStrings())
+                                outputsToInstall.insert(s);
+                    }
+
+                    if (outputsToInstall.empty())
+                        outputsToInstall.insert("out");
+
+                    return OutputsSpec::Names { std::move(outputsToInstall) };
+                },
+                [&](const ExtendedOutputsSpec::Explicit & e) -> OutputsSpec {
+                    return e;
+                },
+            }, extendedOutputsSpec.raw()),
+        },
+        .info = {
+            .priority = priority,
+            .originalRef = flakeRef,
+            .resolvedRef = getLockedFlake()->flake.lockedRef,
+            .attrPath = attrPath,
+            .extendedOutputsSpec = extendedOutputsSpec,
+        }
+    }};
+}
+
+std::pair<Value *, PosIdx> InstallableFlake::toValue(EvalState & state)
+{
+    return {&getCursor(state)->forceValue(), noPos};
+}
+
+std::vector<ref<eval_cache::AttrCursor>>
+InstallableFlake::getCursors(EvalState & state)
+{
+    auto evalCache = openEvalCache(state,
+        std::make_shared<flake::LockedFlake>(lockFlake(state, flakeRef, lockFlags)));
+
+    auto root = evalCache->getRoot();
+
+    std::vector<ref<eval_cache::AttrCursor>> res;
+
+    Suggestions suggestions;
+    auto attrPaths = getActualAttrPaths();
+
+    for (auto & attrPath : attrPaths) {
+        debug("trying flake output attribute '%s'", attrPath);
+
+        auto attr = root->findAlongAttrPath(parseAttrPath(state, attrPath));
+        if (attr) {
+            res.push_back(ref(*attr));
+        } else {
+            suggestions += attr.getSuggestions();
+        }
+    }
+
+    if (res.size() == 0)
+        throw Error(
+            suggestions,
+            "flake '%s' does not provide attribute %s",
+            flakeRef,
+            showAttrPaths(attrPaths));
+
+    return res;
+}
+
+std::shared_ptr<flake::LockedFlake> InstallableFlake::getLockedFlake() const
+{
+    if (!_lockedFlake) {
+        flake::LockFlags lockFlagsApplyConfig = lockFlags;
+        lockFlagsApplyConfig.applyNixConfig = true;
+        _lockedFlake = std::make_shared<flake::LockedFlake>(lockFlake(*state, flakeRef, lockFlagsApplyConfig));
+    }
+    return _lockedFlake;
+}
+
+FlakeRef InstallableFlake::nixpkgsFlakeRef() const
+{
+    auto lockedFlake = getLockedFlake();
+
+    if (auto nixpkgsInput = lockedFlake->lockFile.findInput({"nixpkgs"})) {
+        if (auto lockedNode = std::dynamic_pointer_cast<const flake::LockedNode>(nixpkgsInput)) {
+            debug("using nixpkgs flake '%s'", lockedNode->lockedRef);
+            return std::move(lockedNode->lockedRef);
+        }
+    }
+
+    return Installable::nixpkgsFlakeRef();
+}
+
+}

src/libcmd/installable-flake.hh

@@ -0,0 +1,50 @@
+#pragma once
+
+#include "installable-value.hh"
+
+namespace nix {
+
+struct InstallableFlake : InstallableValue
+{
+    FlakeRef flakeRef;
+    Strings attrPaths;
+    Strings prefixes;
+    ExtendedOutputsSpec extendedOutputsSpec;
+    const flake::LockFlags & lockFlags;
+    mutable std::shared_ptr<flake::LockedFlake> _lockedFlake;
+
+    InstallableFlake(
+        SourceExprCommand * cmd,
+        ref<EvalState> state,
+        FlakeRef && flakeRef,
+        std::string_view fragment,
+        ExtendedOutputsSpec extendedOutputsSpec,
+        Strings attrPaths,
+        Strings prefixes,
+        const flake::LockFlags & lockFlags);
+
+    std::string what() const override { return flakeRef.to_string() + "#" + *attrPaths.begin(); }
+
+    std::vector<std::string> getActualAttrPaths();
+
+    Value * getFlakeOutputs(EvalState & state, const flake::LockedFlake & lockedFlake);
+
+    DerivedPathsWithInfo toDerivedPaths() override;
+
+    std::pair<Value *, PosIdx> toValue(EvalState & state) override;
+
+    /* Get a cursor to every attrpath in getActualAttrPaths()
+       that exists. However if none exists, throw an exception. */
+    std::vector<ref<eval_cache::AttrCursor>>
+    getCursors(EvalState & state) override;
+
+    std::shared_ptr<flake::LockedFlake> getLockedFlake() const;
+
+    FlakeRef nixpkgsFlakeRef() const override;
+};
+
+ref<eval_cache::EvalCache> openEvalCache(
+    EvalState & state,
+    std::shared_ptr<flake::LockedFlake> lockedFlake);
+
+}

src/libcmd/installable-value.hh

@@ -0,0 +1,14 @@
+#pragma once
+
+#include "installables.hh"
+
+namespace nix {
+
+struct InstallableValue : Installable
+{
+    ref<EvalState> state;
+
+    InstallableValue(ref<EvalState> state) : state(state) {}
+};
+
+}

src/libcmd/installables.cc

@@ -1,5 +1,9 @@
 #include "globals.hh"
 #include "installables.hh"
+#include "installable-derived-path.hh"
+#include "installable-attr-path.hh"
+#include "installable-flake.hh"
+#include "outputs-spec.hh"
 #include "util.hh"
 #include "command.hh"
 #include "attr-path.hh"
@@ -143,7 +147,7 @@ void MixFlakeOptions::completionHook()
         completeFlakeInput(*prefix);
 }
 
-SourceExprCommand::SourceExprCommand(bool supportReadOnlyMode)
+SourceExprCommand::SourceExprCommand()
 {
     addFlag({
         .longName = "file",
@@ -165,24 +169,18 @@ SourceExprCommand::SourceExprCommand(bool supportReadOnlyMode)
         .labels = {"expr"},
         .handler = {&expr}
     });
+}
 
+MixReadOnlyOption::MixReadOnlyOption()
+{
     addFlag({
-        .longName = "derivation",
-        .description = "Operate on the store derivation rather than its outputs.",
-        .category = installablesCategory,
-        .handler = {&operateOn, OperateOn::Derivation},
+        .longName = "read-only",
+        .description =
+            "Do not instantiate each evaluated derivation. "
+            "This improves performance, but can cause errors when accessing "
+            "store paths of derivations during evaluation.",
+        .handler = {&settings.readOnlyMode, true},
     });
-
-    if (supportReadOnlyMode) {
-        addFlag({
-            .longName = "read-only",
-            .description =
-                "Do not instantiate each evaluated derivation. "
-                "This improves performance, but can cause errors when accessing "
-                "store paths of derivations during evaluation.",
-            .handler = {&readOnlyMode, true},
-        });
-    }
 }
 
 Strings SourceExprCommand::getDefaultFlakeAttrPaths()
@@ -207,55 +205,59 @@ Strings SourceExprCommand::getDefaultFlakeAttrPathPrefixes()
 
 void SourceExprCommand::completeInstallable(std::string_view prefix)
 {
-    if (file) {
-        completionType = ctAttrs;
+    try {
+        if (file) {
+            completionType = ctAttrs;
 
-        evalSettings.pureEval = false;
-        auto state = getEvalState();
-        Expr *e = state->parseExprFromFile(
-            resolveExprPath(state->checkSourcePath(lookupFileArg(*state, *file)))
-        );
+            evalSettings.pureEval = false;
+            auto state = getEvalState();
+            Expr *e = state->parseExprFromFile(
+                resolveExprPath(state->checkSourcePath(lookupFileArg(*state, *file)))
+                );
 
-        Value root;
-        state->eval(e, root);
+            Value root;
+            state->eval(e, root);
 
-        auto autoArgs = getAutoArgs(*state);
+            auto autoArgs = getAutoArgs(*state);
 
-        std::string prefix_ = std::string(prefix);
-        auto sep = prefix_.rfind('.');
-        std::string searchWord;
-        if (sep != std::string::npos) {
-            searchWord = prefix_.substr(sep + 1, std::string::npos);
-            prefix_ = prefix_.substr(0, sep);
-        } else {
-            searchWord = prefix_;
-            prefix_ = "";
-        }
+            std::string prefix_ = std::string(prefix);
+            auto sep = prefix_.rfind('.');
+            std::string searchWord;
+            if (sep != std::string::npos) {
+                searchWord = prefix_.substr(sep + 1, std::string::npos);
+                prefix_ = prefix_.substr(0, sep);
+            } else {
+                searchWord = prefix_;
+                prefix_ = "";
+            }
 
-        auto [v, pos] = findAlongAttrPath(*state, prefix_, *autoArgs, root);
-        Value &v1(*v);
-        state->forceValue(v1, pos);
-        Value v2;
-        state->autoCallFunction(*autoArgs, v1, v2);
+            auto [v, pos] = findAlongAttrPath(*state, prefix_, *autoArgs, root);
+            Value &v1(*v);
+            state->forceValue(v1, pos);
+            Value v2;
+            state->autoCallFunction(*autoArgs, v1, v2);
 
-        if (v2.type() == nAttrs) {
-            for (auto & i : *v2.attrs) {
-                std::string name = state->symbols[i.name];
-                if (name.find(searchWord) == 0) {
-                    if (prefix_ == "")
-                        completions->add(name);
-                    else
-                        completions->add(prefix_ + "." + name);
+            if (v2.type() == nAttrs) {
+                for (auto & i : *v2.attrs) {
+                    std::string name = state->symbols[i.name];
+                    if (name.find(searchWord) == 0) {
+                        if (prefix_ == "")
+                            completions->add(name);
+                        else
+                            completions->add(prefix_ + "." + name);
+                    }
                 }
             }
+        } else {
+            completeFlakeRefWithFragment(
+                getEvalState(),
+                lockFlags,
+                getDefaultFlakeAttrPathPrefixes(),
+                getDefaultFlakeAttrPaths(),
+                prefix);
         }
-    } else {
-        completeFlakeRefWithFragment(
-            getEvalState(),
-            lockFlags,
-            getDefaultFlakeAttrPathPrefixes(),
-            getDefaultFlakeAttrPaths(),
-            prefix);
+    } catch (EvalError&) {
+        // Don't want eval errors to mess-up with the completion engine, so let's just swallow them
     }
 }
 
@@ -354,7 +356,7 @@ void completeFlakeRef(ref<Store> store, std::string_view prefix)
     }
 }
 
-DerivedPath Installable::toDerivedPath()
+DerivedPathWithInfo Installable::toDerivedPath()
 {
     auto buildables = toDerivedPaths();
     if (buildables.size() != 1)
@@ -374,10 +376,9 @@ Installable::getCursors(EvalState & state)
 ref<eval_cache::AttrCursor>
 Installable::getCursor(EvalState & state)
 {
-    auto cursors = getCursors(state);
-    if (cursors.empty())
-        throw Error("cannot find flake attribute '%s'", what());
-    return cursors[0];
+    /* Although getCursors should return at least one element, in case it doesn't,
+       bound check to avoid an undefined behavior for vector[0] */
+    return getCursors(state).at(0);
 }
 
 static StorePath getDeriver(
@@ -392,169 +393,6 @@ static StorePath getDeriver(
     return *derivers.begin();
 }
 
-struct InstallableStorePath : Installable
-{
-    ref<Store> store;
-    StorePath storePath;
-
-    InstallableStorePath(ref<Store> store, StorePath && storePath)
-        : store(store), storePath(std::move(storePath)) { }
-
-    std::string what() const override { return store->printStorePath(storePath); }
-
-    DerivedPaths toDerivedPaths() override
-    {
-        if (storePath.isDerivation()) {
-            auto drv = store->readDerivation(storePath);
-            return {
-                DerivedPath::Built {
-                    .drvPath = storePath,
-                    .outputs = drv.outputNames(),
-                }
-            };
-        } else {
-            return {
-                DerivedPath::Opaque {
-                    .path = storePath,
-                }
-            };
-        }
-    }
-
-    StorePathSet toDrvPaths(ref<Store> store) override
-    {
-        if (storePath.isDerivation()) {
-            return {storePath};
-        } else {
-            return {getDeriver(store, *this, storePath)};
-        }
-    }
-
-    std::optional<StorePath> getStorePath() override
-    {
-        return storePath;
-    }
-};
-
-DerivedPaths InstallableValue::toDerivedPaths()
-{
-    DerivedPaths res;
-
-    std::map<StorePath, std::set<std::string>> drvsToOutputs;
-    RealisedPath::Set drvsToCopy;
-
-    // Group by derivation, helps with .all in particular
-    for (auto & drv : toDerivations()) {
-        for (auto & outputName : drv.outputsToInstall)
-            drvsToOutputs[drv.drvPath].insert(outputName);
-        drvsToCopy.insert(drv.drvPath);
-    }
-
-    for (auto & i : drvsToOutputs)
-        res.push_back(DerivedPath::Built { i.first, i.second });
-
-    return res;
-}
-
-StorePathSet InstallableValue::toDrvPaths(ref<Store> store)
-{
-    StorePathSet res;
-    for (auto & drv : toDerivations())
-        res.insert(drv.drvPath);
-    return res;
-}
-
-struct InstallableAttrPath : InstallableValue
-{
-    SourceExprCommand & cmd;
-    RootValue v;
-    std::string attrPath;
-    OutputsSpec outputsSpec;
-
-    InstallableAttrPath(
-        ref<EvalState> state,
-        SourceExprCommand & cmd,
-        Value * v,
-        const std::string & attrPath,
-        OutputsSpec outputsSpec)
-        : InstallableValue(state)
-        , cmd(cmd)
-        , v(allocRootValue(v))
-        , attrPath(attrPath)
-        , outputsSpec(std::move(outputsSpec))
-    { }
-
-    std::string what() const override { return attrPath; }
-
-    std::pair<Value *, PosIdx> toValue(EvalState & state) override
-    {
-        auto [vRes, pos] = findAlongAttrPath(state, attrPath, *cmd.getAutoArgs(state), **v);
-        state.forceValue(*vRes, pos);
-        return {vRes, pos};
-    }
-
-    virtual std::vector<InstallableValue::DerivationInfo> toDerivations() override;
-};
-
-std::vector<InstallableValue::DerivationInfo> InstallableAttrPath::toDerivations()
-{
-    auto v = toValue(*state).first;
-
-    Bindings & autoArgs = *cmd.getAutoArgs(*state);
-
-    DrvInfos drvInfos;
-    getDerivations(*state, *v, "", autoArgs, drvInfos, false);
-
-    std::vector<DerivationInfo> res;
-    for (auto & drvInfo : drvInfos) {
-        auto drvPath = drvInfo.queryDrvPath();
-        if (!drvPath)
-            throw Error("'%s' is not a derivation", what());
-
-        std::set<std::string> outputsToInstall;
-
-        if (auto outputNames = std::get_if<OutputNames>(&outputsSpec))
-            outputsToInstall = *outputNames;
-        else
-            for (auto & output : drvInfo.queryOutputs(false, std::get_if<DefaultOutputs>(&outputsSpec)))
-                outputsToInstall.insert(output.first);
-
-        res.push_back(DerivationInfo {
-            .drvPath = *drvPath,
-            .outputsToInstall = std::move(outputsToInstall)
-        });
-    }
-
-    return res;
-}
-
-std::vector<std::string> InstallableFlake::getActualAttrPaths()
-{
-    std::vector<std::string> res;
-
-    for (auto & prefix : prefixes)
-        res.push_back(prefix + *attrPaths.begin());
-
-    for (auto & s : attrPaths)
-        res.push_back(s);
-
-    return res;
-}
-
-Value * InstallableFlake::getFlakeOutputs(EvalState & state, const flake::LockedFlake & lockedFlake)
-{
-    auto vFlake = state.allocValue();
-
-    callFlake(state, lockedFlake, *vFlake);
-
-    auto aOutputs = vFlake->attrs->get(state.symbols.create("outputs"));
-    assert(aOutputs);
-
-    state.forceValue(*aOutputs->value, [&]() { return aOutputs->value->determinePos(noPos); });
-
-    return aOutputs->value;
-}
-
 ref<eval_cache::EvalCache> openEvalCache(
     EvalState & state,
     std::shared_ptr<flake::LockedFlake> lockedFlake)
@@ -575,7 +413,7 @@ ref<eval_cache::EvalCache> openEvalCache(
             auto vFlake = state.allocValue();
             flake::callFlake(state, *lockedFlake, *vFlake);
 
-            state.forceAttrs(*vFlake, noPos);
+            state.forceAttrs(*vFlake, noPos, "while parsing cached flake data");
 
             auto aOutputs = vFlake->attrs->get(state.symbols.create("outputs"));
             assert(aOutputs);
@@ -584,186 +422,11 @@ ref<eval_cache::EvalCache> openEvalCache(
         });
 }
 
-static std::string showAttrPaths(const std::vector<std::string> & paths)
-{
-    std::string s;
-    for (const auto & [n, i] : enumerate(paths)) {
-        if (n > 0) s += n + 1 == paths.size() ? " or " : ", ";
-        s += '\''; s += i; s += '\'';
-    }
-    return s;
-}
-
-InstallableFlake::InstallableFlake(
-    SourceExprCommand * cmd,
-    ref<EvalState> state,
-    FlakeRef && flakeRef,
-    std::string_view fragment,
-    OutputsSpec outputsSpec,
-    Strings attrPaths,
-    Strings prefixes,
-    const flake::LockFlags & lockFlags)
-    : InstallableValue(state),
-      flakeRef(flakeRef),
-      attrPaths(fragment == "" ? attrPaths : Strings{(std::string) fragment}),
-      prefixes(fragment == "" ? Strings{} : prefixes),
-      outputsSpec(std::move(outputsSpec)),
-      lockFlags(lockFlags)
-{
-    if (cmd && cmd->getAutoArgs(*state)->size())
-        throw UsageError("'--arg' and '--argstr' are incompatible with flakes");
-}
-
-std::tuple<std::string, FlakeRef, InstallableValue::DerivationInfo> InstallableFlake::toDerivation()
-{
-    Activity act(*logger, lvlTalkative, actUnknown, fmt("evaluating derivation '%s'", what()));
-
-    auto attr = getCursor(*state);
-
-    auto attrPath = attr->getAttrPathStr();
-
-    if (!attr->isDerivation())
-        throw Error("flake output attribute '%s' is not a derivation", attrPath);
-
-    auto drvPath = attr->forceDerivation();
-
-    std::set<std::string> outputsToInstall;
-    std::optional<NixInt> priority;
-
-    if (auto aOutputSpecified = attr->maybeGetAttr(state->sOutputSpecified)) {
-        if (aOutputSpecified->getBool()) {
-            if (auto aOutputName = attr->maybeGetAttr("outputName"))
-                outputsToInstall = { aOutputName->getString() };
-        }
-    }
-
-    else if (auto aMeta = attr->maybeGetAttr(state->sMeta)) {
-        if (auto aOutputsToInstall = aMeta->maybeGetAttr("outputsToInstall"))
-            for (auto & s : aOutputsToInstall->getListOfStrings())
-                outputsToInstall.insert(s);
-        if (auto aPriority = aMeta->maybeGetAttr("priority"))
-            priority = aPriority->getInt();
-    }
-
-    if (outputsToInstall.empty() || std::get_if<AllOutputs>(&outputsSpec)) {
-        outputsToInstall.clear();
-        if (auto aOutputs = attr->maybeGetAttr(state->sOutputs))
-            for (auto & s : aOutputs->getListOfStrings())
-                outputsToInstall.insert(s);
-    }
-
-    if (outputsToInstall.empty())
-        outputsToInstall.insert("out");
-
-    if (auto outputNames = std::get_if<OutputNames>(&outputsSpec))
-        outputsToInstall = *outputNames;
-
-    auto drvInfo = DerivationInfo {
-        .drvPath = std::move(drvPath),
-        .outputsToInstall = std::move(outputsToInstall),
-        .priority = priority,
-    };
-
-    return {attrPath, getLockedFlake()->flake.lockedRef, std::move(drvInfo)};
-}
-
-std::vector<InstallableValue::DerivationInfo> InstallableFlake::toDerivations()
-{
-    std::vector<DerivationInfo> res;
-    res.push_back(std::get<2>(toDerivation()));
-    return res;
-}
-
-std::pair<Value *, PosIdx> InstallableFlake::toValue(EvalState & state)
-{
-    return {&getCursor(state)->forceValue(), noPos};
-}
-
-std::vector<ref<eval_cache::AttrCursor>>
-InstallableFlake::getCursors(EvalState & state)
-{
-    auto evalCache = openEvalCache(state,
-        std::make_shared<flake::LockedFlake>(lockFlake(state, flakeRef, lockFlags)));
-
-    auto root = evalCache->getRoot();
-
-    std::vector<ref<eval_cache::AttrCursor>> res;
-
-    for (auto & attrPath : getActualAttrPaths()) {
-        auto attr = root->findAlongAttrPath(parseAttrPath(state, attrPath));
-        if (attr) res.push_back(ref(*attr));
-    }
-
-    return res;
-}
-
-ref<eval_cache::AttrCursor> InstallableFlake::getCursor(EvalState & state)
-{
-    auto lockedFlake = getLockedFlake();
-
-    auto cache = openEvalCache(state, lockedFlake);
-    auto root = cache->getRoot();
-
-    Suggestions suggestions;
-
-    auto attrPaths = getActualAttrPaths();
-
-    for (auto & attrPath : attrPaths) {
-        debug("trying flake output attribute '%s'", attrPath);
-
-        auto attrOrSuggestions = root->findAlongAttrPath(
-            parseAttrPath(state, attrPath),
-            true
-        );
-
-        if (!attrOrSuggestions) {
-            suggestions += attrOrSuggestions.getSuggestions();
-            continue;
-        }
-
-        return *attrOrSuggestions;
-    }
-
-    throw Error(
-        suggestions,
-        "flake '%s' does not provide attribute %s",
-        flakeRef,
-        showAttrPaths(attrPaths));
-}
-
-std::shared_ptr<flake::LockedFlake> InstallableFlake::getLockedFlake() const
-{
-    if (!_lockedFlake) {
-        flake::LockFlags lockFlagsApplyConfig = lockFlags;
-        lockFlagsApplyConfig.applyNixConfig = true;
-        _lockedFlake = std::make_shared<flake::LockedFlake>(lockFlake(*state, flakeRef, lockFlagsApplyConfig));
-    }
-    return _lockedFlake;
-}
-
-FlakeRef InstallableFlake::nixpkgsFlakeRef() const
-{
-    auto lockedFlake = getLockedFlake();
-
-    if (auto nixpkgsInput = lockedFlake->lockFile.findInput({"nixpkgs"})) {
-        if (auto lockedNode = std::dynamic_pointer_cast<const flake::LockedNode>(nixpkgsInput)) {
-            debug("using nixpkgs flake '%s'", lockedNode->lockedRef);
-            return std::move(lockedNode->lockedRef);
-        }
-    }
-
-    return Installable::nixpkgsFlakeRef();
-}
-
 std::vector<std::shared_ptr<Installable>> SourceExprCommand::parseInstallables(
     ref<Store> store, std::vector<std::string> ss)
 {
     std::vector<std::shared_ptr<Installable>> result;
 
-    if (readOnlyMode) {
-        settings.readOnlyMode = true;
-    }
-
     if (file || expr) {
         if (file && expr)
             throw UsageError("'--file' and '--expr' are exclusive");
@@ -777,7 +440,8 @@ std::vector<std::shared_ptr<Installable>> SourceExprCommand::parseInstallables(
         if (file == "-") {
             auto e = state->parseStdin();
             state->eval(e, *vFile);
-        } else if (file)
+        }
+        else if (file)
             state->evalFile(lookupFileArg(*state, *file), *vFile);
         else {
             auto e = state->parseExprFromString(*expr, absPath("."));
@@ -785,12 +449,11 @@ std::vector<std::shared_ptr<Installable>> SourceExprCommand::parseInstallables(
         }
 
         for (auto & s : ss) {
-            auto [prefix, outputsSpec] = parseOutputsSpec(s);
+            auto [prefix, extendedOutputsSpec] = ExtendedOutputsSpec::parse(s);
             result.push_back(
                 std::make_shared<InstallableAttrPath>(
-                    state, *this, vFile,
-                    prefix == "." ? "" : prefix,
-                    outputsSpec));
+                    InstallableAttrPath::parse(
+                        state, *this, vFile, prefix, extendedOutputsSpec)));
         }
 
     } else {
@@ -798,9 +461,15 @@ std::vector<std::shared_ptr<Installable>> SourceExprCommand::parseInstallables(
         for (auto & s : ss) {
             std::exception_ptr ex;
 
-            if (s.find('/') != std::string::npos) {
+            auto [prefix_, extendedOutputsSpec_] = ExtendedOutputsSpec::parse(s);
+            // To avoid clang's pedantry
+            auto prefix = std::move(prefix_);
+            auto extendedOutputsSpec = std::move(extendedOutputsSpec_);
+
+            if (prefix.find('/') != std::string::npos) {
                 try {
-                    result.push_back(std::make_shared<InstallableStorePath>(store, store->followLinksToStorePath(s)));
+                    result.push_back(std::make_shared<InstallableDerivedPath>(
+                        InstallableDerivedPath::parse(store, prefix, extendedOutputsSpec)));
                     continue;
                 } catch (BadStorePath &) {
                 } catch (...) {
@@ -810,13 +479,13 @@ std::vector<std::shared_ptr<Installable>> SourceExprCommand::parseInstallables(
             }
 
             try {
-                auto [flakeRef, fragment, outputsSpec] = parseFlakeRefWithFragmentAndOutputsSpec(s, absPath("."));
+                auto [flakeRef, fragment] = parseFlakeRefWithFragment(std::string { prefix }, absPath("."));
                 result.push_back(std::make_shared<InstallableFlake>(
                         this,
                         getEvalState(),
                         std::move(flakeRef),
                         fragment,
-                        outputsSpec,
+                        extendedOutputsSpec,
                         getDefaultFlakeAttrPaths(),
                         getDefaultFlakeAttrPathPrefixes(),
                         lockFlags));
@@ -840,20 +509,20 @@ std::shared_ptr<Installable> SourceExprCommand::parseInstallable(
     return installables.front();
 }
 
-BuiltPaths Installable::build(
+std::vector<BuiltPathWithResult> Installable::build(
     ref<Store> evalStore,
     ref<Store> store,
     Realise mode,
     const std::vector<std::shared_ptr<Installable>> & installables,
     BuildMode bMode)
 {
-    BuiltPaths res;
-    for (auto & [_, builtPath] : build2(evalStore, store, mode, installables, bMode))
-        res.push_back(builtPath);
+    std::vector<BuiltPathWithResult> res;
+    for (auto & [_, builtPathWithResult] : build2(evalStore, store, mode, installables, bMode))
+        res.push_back(builtPathWithResult);
     return res;
 }
 
-std::vector<std::pair<std::shared_ptr<Installable>, BuiltPath>> Installable::build2(
+std::vector<std::pair<std::shared_ptr<Installable>, BuiltPathWithResult>> Installable::build2(
     ref<Store> evalStore,
     ref<Store> store,
     Realise mode,
@@ -863,17 +532,23 @@ std::vector<std::pair<std::shared_ptr<Installable>, BuiltPath>> Installable::bui
     if (mode == Realise::Nothing)
         settings.readOnlyMode = true;
 
+    struct Aux
+    {
+        ExtraPathInfo info;
+        std::shared_ptr<Installable> installable;
+    };
+
     std::vector<DerivedPath> pathsToBuild;
-    std::map<DerivedPath, std::vector<std::shared_ptr<Installable>>> backmap;
+    std::map<DerivedPath, std::vector<Aux>> backmap;
 
     for (auto & i : installables) {
         for (auto b : i->toDerivedPaths()) {
-            pathsToBuild.push_back(b);
-            backmap[b].push_back(i);
+            pathsToBuild.push_back(b.path);
+            backmap[b.path].push_back({.info = b.info, .installable = i});
         }
     }
 
-    std::vector<std::pair<std::shared_ptr<Installable>, BuiltPath>> res;
+    std::vector<std::pair<std::shared_ptr<Installable>, BuiltPathWithResult>> res;
 
     switch (mode) {
 
@@ -882,42 +557,18 @@ std::vector<std::pair<std::shared_ptr<Installable>, BuiltPath>> Installable::bui
         printMissing(store, pathsToBuild, lvlError);
 
         for (auto & path : pathsToBuild) {
-            for (auto & installable : backmap[path]) {
+            for (auto & aux : backmap[path]) {
                 std::visit(overloaded {
                     [&](const DerivedPath::Built & bfd) {
-                        OutputPathMap outputs;
-                        auto drv = evalStore->readDerivation(bfd.drvPath);
-                        auto outputHashes = staticOutputHashes(*evalStore, drv); // FIXME: expensive
-                        auto drvOutputs = drv.outputsAndOptPaths(*store);
-                        for (auto & output : bfd.outputs) {
-                            auto outputHash = get(outputHashes, output);
-                            if (!outputHash)
-                                throw Error(
-                                    "the derivation '%s' doesn't have an output named '%s'",
-                                    store->printStorePath(bfd.drvPath), output);
-                            if (settings.isExperimentalFeatureEnabled(Xp::CaDerivations)) {
-                                DrvOutput outputId { *outputHash, output };
-                                auto realisation = store->queryRealisation(outputId);
-                                if (!realisation)
-                                    throw Error(
-                                        "cannot operate on an output of the "
-                                        "unbuilt derivation '%s'",
-                                        outputId.to_string());
-                                outputs.insert_or_assign(output, realisation->outPath);
-                            } else {
-                                // If ca-derivations isn't enabled, assume that
-                                // the output path is statically known.
-                                auto drvOutput = get(drvOutputs, output);
-                                assert(drvOutput);
-                                assert(drvOutput->second);
-                                outputs.insert_or_assign(
-                                    output, *drvOutput->second);
-                            }
-                        }
-                        res.push_back({installable, BuiltPath::Built { bfd.drvPath, outputs }});
+                        auto outputs = resolveDerivedPath(*store, bfd, &*evalStore);
+                        res.push_back({aux.installable, {
+                            .path = BuiltPath::Built { bfd.drvPath, outputs },
+                            .info = aux.info}});
                     },
                     [&](const DerivedPath::Opaque & bo) {
-                        res.push_back({installable, BuiltPath::Opaque { bo.path }});
+                        res.push_back({aux.installable, {
+                            .path = BuiltPath::Opaque { bo.path },
+                            .info = aux.info}});
                     },
                 }, path.raw());
             }
@@ -927,22 +578,28 @@ std::vector<std::pair<std::shared_ptr<Installable>, BuiltPath>> Installable::bui
 
     case Realise::Outputs: {
         if (settings.printMissing)
-          printMissing(store, pathsToBuild, lvlInfo);
+            printMissing(store, pathsToBuild, lvlInfo);
 
         for (auto & buildResult : store->buildPathsWithResults(pathsToBuild, bMode, evalStore)) {
             if (!buildResult.success())
                 buildResult.rethrow();
 
-            for (auto & installable : backmap[buildResult.path]) {
+            for (auto & aux : backmap[buildResult.path]) {
                 std::visit(overloaded {
                     [&](const DerivedPath::Built & bfd) {
                         std::map<std::string, StorePath> outputs;
                         for (auto & path : buildResult.builtOutputs)
                             outputs.emplace(path.first.outputName, path.second.outPath);
-                        res.push_back({installable, BuiltPath::Built { bfd.drvPath, outputs }});
+                        res.push_back({aux.installable, {
+                            .path = BuiltPath::Built { bfd.drvPath, outputs },
+                            .info = aux.info,
+                            .result = buildResult}});
                     },
                     [&](const DerivedPath::Opaque & bo) {
-                        res.push_back({installable, BuiltPath::Opaque { bo.path }});
+                        res.push_back({aux.installable, {
+                            .path = BuiltPath::Opaque { bo.path },
+                            .info = aux.info,
+                            .result = buildResult}});
                     },
                 }, buildResult.path.raw());
             }
@@ -965,9 +622,12 @@ BuiltPaths Installable::toBuiltPaths(
     OperateOn operateOn,
     const std::vector<std::shared_ptr<Installable>> & installables)
 {
-    if (operateOn == OperateOn::Output)
-        return Installable::build(evalStore, store, mode, installables);
-    else {
+    if (operateOn == OperateOn::Output) {
+        BuiltPaths res;
+        for (auto & p : Installable::build(evalStore, store, mode, installables))
+            res.push_back(p.path);
+        return res;
+    } else {
         if (mode == Realise::Nothing)
             settings.readOnlyMode = true;
 
@@ -1024,7 +684,7 @@ StorePathSet Installable::toDerivations(
                 [&](const DerivedPath::Built & bfd) {
                     drvPaths.insert(bfd.drvPath);
                 },
-            }, b.raw());
+            }, b.path.raw());
 
     return drvPaths;
 }
@@ -1045,8 +705,8 @@ void InstallablesCommand::prepare()
     installables = load();
 }
 
-Installables InstallablesCommand::load() {
-    Installables installables;
+Installables InstallablesCommand::load()
+{
     if (_installables.empty() && useDefaultInstallables())
         // FIXME: commands like "nix profile install" should not have a
         // default, probably.
@@ -1056,16 +716,13 @@ Installables InstallablesCommand::load() {
 
 std::vector<std::string> InstallablesCommand::getFlakesForCompletion()
 {
-    if (_installables.empty()) {
-        if (useDefaultInstallables())
-            return {"."};
-        return {};
-    }
+    if (_installables.empty() && useDefaultInstallables())
+        return {"."};
     return _installables;
 }
 
-InstallableCommand::InstallableCommand(bool supportReadOnlyMode)
-    : SourceExprCommand(supportReadOnlyMode)
+InstallableCommand::InstallableCommand()
+    : SourceExprCommand()
 {
     expectArgs({
         .label = "installable",

src/libcmd/installables.hh

@@ -2,11 +2,12 @@
 
 #include "util.hh"
 #include "path.hh"
-#include "path-with-outputs.hh"
+#include "outputs-spec.hh"
 #include "derived-path.hh"
 #include "eval.hh"
 #include "store-api.hh"
 #include "flake/flake.hh"
+#include "build-result.hh"
 
 #include <optional>
 
@@ -19,7 +20,7 @@ namespace eval_cache { class EvalCache; class AttrCursor; }
 
 struct App
 {
-    std::vector<StorePathWithOutputs> context;
+    std::vector<DerivedPath> context;
     Path program;
     // FIXME: add args, sandbox settings, metadata, ...
 };
@@ -51,20 +52,42 @@ enum class OperateOn {
     Derivation
 };
 
+struct ExtraPathInfo
+{
+    std::optional<NixInt> priority;
+    std::optional<FlakeRef> originalRef;
+    std::optional<FlakeRef> resolvedRef;
+    std::optional<std::string> attrPath;
+    // FIXME: merge with DerivedPath's 'outputs' field?
+    std::optional<ExtendedOutputsSpec> extendedOutputsSpec;
+};
+
+/* A derived path with any additional info that commands might
+   need from the derivation. */
+struct DerivedPathWithInfo
+{
+    DerivedPath path;
+    ExtraPathInfo info;
+};
+
+struct BuiltPathWithResult
+{
+    BuiltPath path;
+    ExtraPathInfo info;
+    std::optional<BuildResult> result;
+};
+
+typedef std::vector<DerivedPathWithInfo> DerivedPathsWithInfo;
+
 struct Installable
 {
     virtual ~Installable() { }
 
     virtual std::string what() const = 0;
 
-    virtual DerivedPaths toDerivedPaths() = 0;
+    virtual DerivedPathsWithInfo toDerivedPaths() = 0;
 
-    virtual StorePathSet toDrvPaths(ref<Store> store)
-    {
-        throw Error("'%s' cannot be converted to a derivation path", what());
-    }
-
-    DerivedPath toDerivedPath();
+    DerivedPathWithInfo toDerivedPath();
 
     UnresolvedApp toApp(EvalState & state);
 
@@ -80,9 +103,13 @@ struct Installable
         return {};
     }
 
+    /* Get a cursor to each value this Installable could refer to. However
+       if none exists, throw exception instead of returning empty vector. */
     virtual std::vector<ref<eval_cache::AttrCursor>>
     getCursors(EvalState & state);
 
+    /* Get the first and most preferred cursor this Installable could refer
+       to, or throw an exception if none exists. */
     virtual ref<eval_cache::AttrCursor>
     getCursor(EvalState & state);
 
@@ -91,14 +118,14 @@ struct Installable
         return FlakeRef::fromAttrs({{"type","indirect"}, {"id", "nixpkgs"}});
     }
 
-    static BuiltPaths build(
+    static std::vector<BuiltPathWithResult> build(
         ref<Store> evalStore,
         ref<Store> store,
         Realise mode,
         const std::vector<std::shared_ptr<Installable>> & installables,
         BuildMode bMode = bmNormal);
 
-    static std::vector<std::pair<std::shared_ptr<Installable>, BuiltPath>> build2(
+    static std::vector<std::pair<std::shared_ptr<Installable>, BuiltPathWithResult>> build2(
         ref<Store> evalStore,
         ref<Store> store,
         Realise mode,
@@ -134,73 +161,4 @@ struct Installable
 
 typedef std::vector<std::shared_ptr<Installable>> Installables;
 
-struct InstallableValue : Installable
-{
-    ref<EvalState> state;
-
-    InstallableValue(ref<EvalState> state) : state(state) {}
-
-    struct DerivationInfo
-    {
-        StorePath drvPath;
-        std::set<std::string> outputsToInstall;
-        std::optional<NixInt> priority;
-    };
-
-    virtual std::vector<DerivationInfo> toDerivations() = 0;
-
-    DerivedPaths toDerivedPaths() override;
-
-    StorePathSet toDrvPaths(ref<Store> store) override;
-};
-
-struct InstallableFlake : InstallableValue
-{
-    FlakeRef flakeRef;
-    Strings attrPaths;
-    Strings prefixes;
-    OutputsSpec outputsSpec;
-    const flake::LockFlags & lockFlags;
-    mutable std::shared_ptr<flake::LockedFlake> _lockedFlake;
-
-    InstallableFlake(
-        SourceExprCommand * cmd,
-        ref<EvalState> state,
-        FlakeRef && flakeRef,
-        std::string_view fragment,
-        OutputsSpec outputsSpec,
-        Strings attrPaths,
-        Strings prefixes,
-        const flake::LockFlags & lockFlags);
-
-    std::string what() const override { return flakeRef.to_string() + "#" + *attrPaths.begin(); }
-
-    std::vector<std::string> getActualAttrPaths();
-
-    Value * getFlakeOutputs(EvalState & state, const flake::LockedFlake & lockedFlake);
-
-    std::tuple<std::string, FlakeRef, DerivationInfo> toDerivation();
-
-    std::vector<DerivationInfo> toDerivations() override;
-
-    std::pair<Value *, PosIdx> toValue(EvalState & state) override;
-
-    /* Get a cursor to every attrpath in getActualAttrPaths() that
-       exists. */
-    std::vector<ref<eval_cache::AttrCursor>>
-    getCursors(EvalState & state) override;
-
-    /* Get a cursor to the first attrpath in getActualAttrPaths() that
-       exists, or throw an exception with suggestions if none exists. */
-    ref<eval_cache::AttrCursor> getCursor(EvalState & state) override;
-
-    std::shared_ptr<flake::LockedFlake> getLockedFlake() const;
-
-    FlakeRef nixpkgsFlakeRef() const override;
-};
-
-ref<eval_cache::EvalCache> openEvalCache(
-    EvalState & state,
-    std::shared_ptr<flake::LockedFlake> lockedFlake);
-
 }

src/libcmd/local.mk

@@ -6,9 +6,9 @@ libcmd_DIR := $(d)
 
 libcmd_SOURCES := $(wildcard $(d)/*.cc)
 
-libcmd_CXXFLAGS += -I src/libutil -I src/libstore -I src/libexpr -I src/libmain -I src/libfetchers -I src/nix
+libcmd_CXXFLAGS += -I src/libutil -I src/libstore -I src/libexpr -I src/libmain -I src/libfetchers
 
-libcmd_LDFLAGS = $(EDITLINE_LIBS) -llowdown -pthread
+libcmd_LDFLAGS = $(EDITLINE_LIBS) $(LOWDOWN_LIBS) -pthread
 
 libcmd_LIBS = libstore libutil libexpr libmain libfetchers