Merge commit '1af94bf47' into progress-bar

.clang-format

@@ -0,0 +1,34 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterStruct: true
+  AfterClass: true
+  AfterFunction: true
+  AfterUnion: true
+  SplitEmptyRecord: false
+PointerAlignment: Middle
+FixNamespaceComments: false
+SortIncludes: Never
+#IndentPPDirectives: BeforeHash
+SpaceAfterCStyleCast: true
+SpaceAfterTemplateKeyword: false
+AccessModifierOffset: -4
+AlignAfterOpenBracket: AlwaysBreak
+AlignEscapedNewlines: Left
+ColumnLimit: 120
+BreakStringLiterals: false
+BitFieldColonSpacing: None
+AllowShortFunctionsOnASingleLine: Empty
+AlwaysBreakTemplateDeclarations: Yes
+BinPackParameters: false
+BreakConstructorInitializers: BeforeComma
+EmptyLineAfterAccessModifier: Leave # change to always/never later?
+EmptyLineBeforeAccessModifier: Leave
+#PackConstructorInitializers: BinPack
+BreakBeforeBinaryOperators: NonAssignment
+AlwaysBreakBeforeMultilineStrings: true
+IndentPPDirectives: AfterHash
+PPIndentWidth: 2
+BinPackArguments: false
+BreakBeforeTernaryOperators: true

.clang-tidy

@@ -0,0 +1,3 @@
+# We use pointers to aggregates in a couple of places, intentionally.
+# void * would look weird.
+Checks: '-bugprone-sizeof-expression'

.editorconfig

@@ -4,20 +4,20 @@
 # Top-most EditorConfig file
 root = true
 
-# Unix-style newlines with a newline ending every file, utf-8 charset
+# Unix-style newlines with a newline ending every file, UTF-8 charset
 [*]
 end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 charset = utf-8
 
-# Match nix files, set indent to spaces with width of two
+# Match Nix files, set indent to spaces with width of two
 [*.nix]
 indent_style = space
 indent_size = 2
 
-# Match c++/shell/perl, set indent to spaces with width of four
-[*.{hpp,cc,hh,sh,pl}]
+# Match C++/C/shell/Perl, set indent to spaces with width of four
+[*.{hpp,cc,hh,c,h,sh,pl,xs}]
 indent_style = space
 indent_size = 4
 

.github/CODEOWNERS

@@ -0,0 +1,26 @@
+# 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
+
+# Documentation of built-in functions
+src/libexpr/primops.cc @roberth @fricklerhandwerk
+
+# Documentation of settings
+src/libexpr/eval-settings.hh @fricklerhandwerk
+src/libstore/globals.hh @fricklerhandwerk
+
+# Documentation
+doc/manual @fricklerhandwerk
+maintainers/*.md @fricklerhandwerk
+src/**/*.md @fricklerhandwerk
+
+# Libstore layer
+/src/libstore @ericson2314

.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 -->
+
+## Proposal
+
+<!-- propose a solution -->
+
+## 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/source
+[open documentation issues and pull requests]: https://github.com/NixOS/nix/labels/documentation
+
+## 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,36 @@
+<!--
+
+IMPORTANT
+
+Nix is a non-trivial project, so for your contribution to be successful,
+it really is important to follow the contributing guidelines:
+
+https://github.com/NixOS/nix/blob/master/CONTRIBUTING.md
+
+Even if you've contributed to open source before, take a moment to read it,
+so you understand the process and the expectations.
+
+- what information to include in commit messages
+- proper attribution
+- volunteering contributions effectively
+- how to get help and our review process.
+
+-->
+
+# 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. -->
+
+# Priorities and Process
+
+Add :+1: to [pull requests you find important](https://github.com/NixOS/nix/pulls?q=is%3Aopen+sort%3Areactions-%2B1-desc).
+
+The Nix maintainer team uses a [GitHub project board](https://github.com/orgs/NixOS/projects/19) to [schedule and track reviews](https://github.com/NixOS/nix/tree/master/maintainers#project-board-protocol). 

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -1,7 +0,0 @@
-**Release Notes**
-Please include relevant [release notes](https://github.com/NixOS/nix/blob/master/doc/manual/src/release-notes/rl-next.md) as needed.
-
-
-**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).

.github/labeler.yml

@@ -0,0 +1,43 @@
+"c api":
+  - changed-files:
+    - any-glob-to-any-file: "src/lib*-c/**/*"
+    - any-glob-to-any-file: "src/*test*/**/nix_api_*"
+    - any-glob-to-any-file: "doc/external-api/**/*"
+
+"contributor-experience":
+  - changed-files:
+    - any-glob-to-any-file: "CONTRIBUTING.md"
+    - any-glob-to-any-file: ".github/ISSUE_TEMPLATE/*"
+    - any-glob-to-any-file: ".github/PULL_REQUEST_TEMPLATE.md"
+    - any-glob-to-any-file: "doc/manual/source/contributing/**"
+
+"documentation":
+  - changed-files:
+    - any-glob-to-any-file: "doc/manual/**/*"
+    - any-glob-to-any-file: "src/nix/**/*.md"
+
+"store":
+  - changed-files:
+    - any-glob-to-any-file: "src/libstore/store-api.*"
+    - any-glob-to-any-file: "src/libstore/*-store.*"
+
+"fetching":
+  - changed-files:
+    - any-glob-to-any-file: "src/libfetchers/**/*"
+
+"repl":
+  - changed-files:
+    - any-glob-to-any-file: "src/libcmd/repl.*"
+    - any-glob-to-any-file: "src/nix/repl.*"
+
+"new-cli":
+  - changed-files:
+    - any-glob-to-any-file: "src/nix/**/*"
+
+"with-tests":
+  - changed-files:
+    # Unit tests
+    - any-glob-to-any-file: "src/*/tests/**/*"
+    # Functional and integration tests
+    - any-glob-to-any-file: "tests/functional/**/*"
+

.github/workflows/backport.yml

@@ -1,26 +0,0 @@
-name: Backport
-on:
-  pull_request_target:
-    types: [closed, labeled]
-jobs:
-  backport:
-    name: Backport Pull Request
-    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:
-      - uses: actions/checkout@v3
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          # required to find all branches
-          fetch-depth: 0
-      - name: Create backport PRs
-        # should be kept in sync with `version`
-        uses: zeebe-io/backport-action@v0.0.8
-        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}.
-          # should be kept in sync with `uses`
-          version: v0.0.5

.github/workflows/ci.yml

@@ -9,104 +9,209 @@ permissions: read-all
 jobs:
 
   tests:
-    needs: [check_cachix]
+    needs: [check_secrets]
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     timeout-minutes: 60
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: cachix/install-nix-action@v17
+    - uses: cachix/install-nix-action@v30
+      with:
+        # The sandbox would otherwise be disabled by default on Darwin
+        extra_nix_config: "sandbox = true"
     - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
-    - uses: cachix/cachix-action@v10
-      if: needs.check_cachix.outputs.secret == 'true'
+    - uses: cachix/cachix-action@v15
+      if: needs.check_secrets.outputs.cachix == 'true'
       with:
         name: '${{ env.CACHIX_NAME }}'
         signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
         authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+    - if: matrix.os == 'ubuntu-latest'
+      run: |
+        free -h
+        swapon --show
+        swap=$(swapon --show --noheadings | head -n 1 | awk '{print $1}')
+        echo "Found swap: $swap"
+        sudo swapoff $swap
+        # resize it (fallocate)
+        sudo fallocate -l 10G $swap
+        sudo mkswap $swap
+        sudo swapon $swap
+        free -h
+        (
+          while sleep 60; do
+            free -h
+          done
+        ) &
     - run: nix --experimental-features 'nix-command flakes' flake check -L
+    - run: nix --experimental-features 'nix-command flakes' flake show --all-systems --json
 
-  check_cachix:
+  # Steps to test CI automation in your own fork.
+  # Cachix:
+  # 1. Sign-up for https://www.cachix.org/
+  # 2. Create a cache for $githubuser-nix-install-tests
+  # 3. Create a cachix auth token and save it in https://github.com/$githubuser/nix/settings/secrets/actions in "Repository secrets" as CACHIX_AUTH_TOKEN
+  # Dockerhub:
+  # 1. Sign-up for https://hub.docker.com/
+  # 2. Store your dockerhub username as DOCKERHUB_USERNAME in "Repository secrets" of your fork repository settings (https://github.com/$githubuser/nix/settings/secrets/actions)
+  # 3. Create an access token in https://hub.docker.com/settings/security and store it as DOCKERHUB_TOKEN in "Repository secrets" of your fork
+  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 }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       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@v30
+      with:
+        install_url: https://releases.nixos.org/nix/nix-2.20.3/install
+    - uses: cachix/cachix-action@v15
       with:
         name: '${{ env.CACHIX_NAME }}'
         signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
         authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+        cachixArgs: '-v'
     - id: prepare-installer
       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:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
-    - uses: cachix/install-nix-action@v17
+    - uses: cachix/install-nix-action@v30
       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"
+    - run: exec bash -c "nix-channel --add https://releases.nixos.org/nixos/unstable/nixos-23.05pre466020.60c1d71f2ba nixpkgs"
+    - run: exec bash -c "nix-channel --update && nix-env -iA nixpkgs.hello && hello"
 
   docker_push_image:
-    needs: [check_cachix, tests]
+    needs: [check_secrets, tests]
+    permissions:
+      contents: read
+      packages: write
     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
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: cachix/install-nix-action@v17
+    - uses: cachix/install-nix-action@v30
+      with:
+        install_url: https://releases.nixos.org/nix/nix-2.20.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'
+    - run: echo NIX_VERSION="$(nix --experimental-features 'nix-command flakes' eval .\#nix.version | tr -d \")" >> $GITHUB_ENV
+    - uses: cachix/cachix-action@v15
+      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' build .#dockerImage -L
     - run: docker load -i ./result/image.tar.gz
-    - run: docker tag nix:$NIX_VERSION nixos/nix:$NIX_VERSION
-    - run: docker tag nix:$NIX_VERSION nixos/nix:master
+    - run: docker tag nix:$NIX_VERSION ${{ secrets.DOCKERHUB_USERNAME }}/nix:$NIX_VERSION
+    - run: docker tag nix:$NIX_VERSION ${{ secrets.DOCKERHUB_USERNAME }}/nix:master
+    # We'll deploy the newly built image to both Docker Hub and Github Container Registry.
+    #
+    # Push to Docker Hub first
     - name: Login to Docker Hub
-      uses: docker/login-action@v2
+      uses: docker/login-action@v3
       with:
         username: ${{ secrets.DOCKERHUB_USERNAME }}
         password: ${{ secrets.DOCKERHUB_TOKEN }}
-    - run: docker push nixos/nix:$NIX_VERSION
-    - run: docker push nixos/nix:master
+    - run: docker push ${{ secrets.DOCKERHUB_USERNAME }}/nix:$NIX_VERSION
+    - run: docker push ${{ secrets.DOCKERHUB_USERNAME }}/nix:master
+    # Push to GitHub Container Registry as well
+    - name: Login to GitHub Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    - name: Push image
+      run: |
+        IMAGE_ID=ghcr.io/${{ github.repository_owner }}/nix
+        # Change all uppercase to lowercase
+        IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]')
+
+        docker tag nix:$NIX_VERSION $IMAGE_ID:$NIX_VERSION
+        docker tag nix:$NIX_VERSION $IMAGE_ID:latest
+        docker push $IMAGE_ID:$NIX_VERSION
+        docker push $IMAGE_ID:latest
+        # deprecated 2024-02-24
+        docker tag nix:$NIX_VERSION $IMAGE_ID:master
+        docker push $IMAGE_ID:master
+
+  vm_tests:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - run: nix build -L .#hydraJobs.tests.githubFlakes .#hydraJobs.tests.tarballFlakes .#hydraJobs.tests.functional_user
+
+  flake_regressions:
+    needs: vm_tests
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout nix
+        uses: actions/checkout@v4
+      - name: Checkout flake-regressions
+        uses: actions/checkout@v4
+        with:
+          repository: NixOS/flake-regressions
+          path: flake-regressions
+      - name: Checkout flake-regressions-data
+        uses: actions/checkout@v4
+        with:
+          repository: NixOS/flake-regressions-data
+          path: flake-regressions/tests
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - run: nix build --out-link ./new-nix && PATH=$(pwd)/new-nix/bin:$PATH MAX_FLAKES=25 flake-regressions/eval-all.sh

.github/workflows/hydra_status.yml

@@ -1,20 +0,0 @@
-name: Hydra status
-
-permissions: read-all
-
-on:
-  schedule:
-    - cron: "12,42 * * * *"
-  workflow_dispatch:
-
-jobs:
-  check_hydra_status:
-    name: Check Hydra status
-    if: github.repository_owner == 'NixOS'
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-    - run: bash scripts/check-hydra-status.sh
-

.github/workflows/labels.yml

@@ -0,0 +1,24 @@
+name: "Label PR"
+
+on:
+  pull_request_target:
+    types: [edited, opened, synchronize, reopened]
+
+# WARNING:
+# When extending this action, be aware that $GITHUB_TOKEN allows some write
+# access to the GitHub API. This means that it should not evaluate user input in
+# a way that allows code injection.
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  labels:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'NixOS'
+    steps:
+    - uses: actions/labeler@v5
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        sync-labels: false

.gitignore

@@ -10,6 +10,9 @@ perl/Makefile.config
 /stamp-h1
 /svn-revision
 /libtool
+/config/config.*
+# Default meson build dir
+/build
 
 # /doc/manual/
 /doc/manual/*.1
@@ -18,15 +21,25 @@ perl/Makefile.config
 /doc/manual/generated/*
 /doc/manual/nix.json
 /doc/manual/conf-file.json
-/doc/manual/builtins.json
-/doc/manual/src/SUMMARY.md
-/doc/manual/src/command-ref/new-cli
-/doc/manual/src/command-ref/conf-file.md
-/doc/manual/src/language/builtins.md
+/doc/manual/language.json
+/doc/manual/xp-features.json
+/doc/manual/source/SUMMARY.md
+/doc/manual/source/SUMMARY-rl-next.md
+/doc/manual/source/store/types/*
+!/doc/manual/source/store/types/index.md.in
+/doc/manual/source/command-ref/new-cli
+/doc/manual/source/command-ref/conf-file.md
+/doc/manual/source/command-ref/experimental-features-shortlist.md
+/doc/manual/source/contributing/experimental-feature-descriptions.md
+/doc/manual/source/language/builtins.md
+/doc/manual/source/language/builtin-constants.md
+/doc/manual/source/release-notes/rl-next.md
 
 # /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,17 +48,28 @@ 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
+/src/libexpr-tests/libnixexpr-tests
+
+# /src/libfetchers
+/src/libfetchers-tests/libnixfetchers-tests
+
+# /src/libflake
+/src/libflake-tests/libnixflake-tests
 
 # /src/libstore/
 *.gen.*
-/src/libstore/tests/libstore-tests
+/src/libstore/tests
+/src/libstore-tests/libnixstore-tests
 
 # /src/libutil/
-/src/libutil/tests/libutil-tests
+/src/libutil/tests
+/src/libutil-tests/libnixutil-tests
 
 /src/nix/nix
 
+/src/nix/generated-doc
+
 # /src/nix-env/
 /src/nix-env/nix-env
 
@@ -71,21 +95,25 @@ perl/Makefile.config
 
 /src/build-remote/build-remote
 
-# /tests/
-/tests/test-tmp
-/tests/common.sh
-/tests/result*
-/tests/restricted-innocent
-/tests/shell
-/tests/shell.drv
-/tests/config.nix
-/tests/ca/config.nix
-/tests/repl-result-out
+# /tests/functional/
+/tests/functional/test-tmp
+/tests/functional/common/subst-vars.sh
+/tests/functional/result*
+/tests/functional/restricted-innocent
+/tests/functional/shell
+/tests/functional/shell.drv
+/tests/functional/config.nix
+/tests/functional/ca/config.nix
+/tests/functional/dyn-drv/config.nix
+/tests/functional/repl-result-out
+/tests/functional/debugger-test-out
+/tests/functional/test-libstoreconsumer/test-libstoreconsumer
 
-# /tests/lang/
-/tests/lang/*.out
-/tests/lang/*.out.xml
-/tests/lang/*.ast
+# /tests/functional/lang/
+/tests/functional/lang/*.out
+/tests/functional/lang/*.out.xml
+/tests/functional/lang/*.err
+/tests/functional/lang/*.ast
 
 /perl/lib/Nix/Config.pm
 /perl/lib/Nix/Store.cc
@@ -95,12 +123,11 @@ perl/Makefile.config
 /misc/systemd/nix-daemon.conf
 /misc/upstart/nix-daemon.conf
 
-/src/resolve-system-dependencies/resolve-system-dependencies
-
 outputs/
 
 *.a
 *.o
+*.o.tmp
 *.so
 *.dylib
 *.dll
@@ -121,9 +148,21 @@ GTAGS
 
 # auto-generated compilation database
 compile_commands.json
+*.compile_commands.json
 
 nix-rust/target
 
 result
+result-*
 
+# IDE
 .vscode/
+.idea/
+
+.pre-commit-config.yaml
+
+# clangd and possibly more
+.cache/
+
+# Mac OS
+.DS_Store

.mergify.yml

@@ -0,0 +1,92 @@
+queue_rules:
+  - name: default
+    # all required tests need to go here
+    merge_conditions:
+      - check-success=installer
+      - check-success=installer_test (macos-latest)
+      - check-success=installer_test (ubuntu-latest)
+      - check-success=tests (macos-latest)
+      - check-success=tests (ubuntu-latest)
+      - check-success=vm_tests
+    merge_method: rebase
+    batch_size: 5
+
+pull_request_rules:
+  - name: merge using the merge queue
+    conditions:
+      - base~=master|.+-maintenance
+      - label~=merge-queue|dependencies
+    actions:
+      queue: {}
+
+# The rules below will first create backport pull requests and put those in a merge queue.
+
+  - name: backport patches to 2.18
+    conditions:
+      - label=backport 2.18-maintenance
+    actions:
+      backport:
+        branches:
+          - 2.18-maintenance
+        labels:
+          - merge-queue
+
+  - name: backport patches to 2.19
+    conditions:
+      - label=backport 2.19-maintenance
+    actions:
+      backport:
+        branches:
+          - 2.19-maintenance
+        labels:
+          - merge-queue
+
+  - name: backport patches to 2.20
+    conditions:
+      - label=backport 2.20-maintenance
+    actions:
+      backport:
+        branches:
+          - 2.20-maintenance
+        labels:
+          - merge-queue
+
+  - name: backport patches to 2.21
+    conditions:
+      - label=backport 2.21-maintenance
+    actions:
+      backport:
+        branches:
+          - 2.21-maintenance
+        labels:
+          - merge-queue
+
+  - name: backport patches to 2.22
+    conditions:
+      - label=backport 2.22-maintenance
+    actions:
+      backport:
+        branches:
+          - 2.22-maintenance
+        labels:
+          - merge-queue
+
+  - name: backport patches to 2.23
+    conditions:
+      - label=backport 2.23-maintenance
+    actions:
+      backport:
+        branches:
+          - 2.23-maintenance
+        labels:
+          - merge-queue
+
+  - name: backport patches to 2.24
+    conditions:
+      - label=backport 2.24-maintenance
+    actions:
+      backport:
+        branches:
+          - "2.24-maintenance"
+        labels:
+          - merge-queue

.shellcheckrc

@@ -0,0 +1,4 @@
+external-sources=true
+source-path=SCRIPTDIR
+# Hack for scripts in e.g. tests/functional/ca
+source-path=SCRIPTDIR/..

.version

@@ -1 +1 @@
-2.10.0
+2.25.0

CITATION.cff

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

CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing to Nix
+
+Welcome and thank you for your interest in contributing to Nix!
+We appreciate your support.
+
+Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved.
+
+## Report a bug
+
+1. Check on the [GitHub issue tracker](https://github.com/NixOS/nix/issues) if your bug was already reported.
+
+2. If you were not able to find the bug or feature [open a new issue](https://github.com/NixOS/nix/issues/new/choose)
+
+3. The issue templates will guide you in specifying your issue.
+   The more complete the information you provide, the more likely it can be found by others and the more useful it is in the future.
+   Make sure reported bugs can be reproduced easily.
+
+4. Once submitted, do not expect issues to be picked up or solved right away.
+   The only way to ensure this, is to [work on the issue yourself](#making-changes-to-nix).
+
+## Report a security vulnerability
+
+Check out the [security policy](https://github.com/NixOS/nix/security/policy).
+
+## Making changes to Nix
+
+1. Search for related issues that cover what you're going to work on.
+   It could help to mention there that you will work on the issue.
+
+   We strongly recommend first-time contributors not to propose new features but rather fix tightly-scoped problems in order to build trust and a working relationship with maintainers.
+
+   Issues labeled [good first issue](https://github.com/NixOS/nix/labels/good%20first%20issue) should be relatively easy to fix and are likely to get merged quickly.
+   Pull requests addressing issues labeled [idea approved](https://github.com/NixOS/nix/labels/idea%20approved) or [RFC](https://github.com/NixOS/nix/labels/RFC) are especially welcomed by maintainers and will receive prioritised review.
+
+   If you are proficient with C++, addressing one of the [popular issues](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) will be highly appreciated by maintainers and Nix users all over the world.
+   For far-reaching changes, please investigate possible blockers and design implications, and coordinate with maintainers before investing too much time in writing code that may not end up getting merged.
+
+   If there is no relevant issue yet and you're not sure whether your change is likely to be accepted, [open an issue](https://github.com/NixOS/nix/issues/new/choose) yourself.
+
+2. Check for [pull requests](https://github.com/NixOS/nix/pulls) that might already cover the contribution you are about to make.
+   There are many open pull requests that might already do what you intend to work on.
+   You can use [labels](https://github.com/NixOS/nix/labels) to filter for relevant topics.
+
+3. Check the [Nix reference manual](https://nix.dev/manual/nix/development/development/building.html) for information on building Nix and running its tests.
+
+   For contributions to the command line interface, please check the [CLI guidelines](https://nix.dev/manual/nix/development/development/cli-guideline.html).
+
+4. Make your change!
+
+5. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for your changes.
+   * Clearly explain the problem that you're solving.
+
+     Link related issues to inform interested parties and future contributors about your change.
+     If your pull request closes one or multiple issues, mention that in the description using `Closes: #<number>`, as it will then happen automatically when your change is merged.
+   * Credit original authors when you're reusing or building on their work.
+   * Link to relevant changes in other projects, so that others can understand the full context of the change in the future when you or someone else will change or troubleshoot the code.
+     This is especially important when your change is based on work done in other repositories.
+
+     Example:
+     ```
+     This is based on the work of @user in <url>.
+     This solution took inspiration from <url>.
+
+     Co-authored-by: User Name <user@example.com>
+     ```
+
+     When cherry-picking from a different repository, use the `-x` flag, and then amend the commits to turn the hashes into URLs.
+
+   * Make sure to have [a clean history of commits on your branch by using rebase](https://www.digitalocean.com/community/tutorials/how-to-rebase-and-update-a-pull-request).
+   * [Mark the pull request as draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request) if you're not done with the changes.
+
+6. Do not expect your pull request to be reviewed immediately.
+   Nix maintainers follow a [structured process for reviews and design decisions](https://github.com/NixOS/nix/tree/master/maintainers#project-board-protocol), which may or may not prioritise your work.
+
+   Following this checklist will make the process smoother for everyone:
+
+   - [ ] Fixes an [idea approved](https://github.com/NixOS/nix/labels/idea%20approved) issue
+   - [ ] Tests, as appropriate:
+     - Functional tests – [`tests/functional/**.sh`](./tests/functional)
+     - Unit tests – [`src/*/tests`](./src/)
+     - Integration tests – [`tests/nixos/*`](./tests/nixos)
+   - [ ] User documentation in the [manual](./doc/manual/source)
+   - [ ] API documentation in header files
+   - [ ] Code and comments are self-explanatory
+   - [ ] Commit message explains **why** the change was made
+   - [ ] New feature or incompatible change: [add a release note](https://nix.dev/manual/nix/development/development/contributing.html#add-a-release-note)
+
+7. If you need additional feedback or help to getting pull request into shape, ask other contributors using [@mentions](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams).
+
+## Making changes to the Nix manual
+
+The Nix reference manual is hosted on https://nixos.org/manual/nix.
+The underlying source files are located in [`doc/manual/source`](./doc/manual/source).
+For small changes you can [use GitHub to edit these files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)
+For larger changes see the [Nix reference manual](https://nix.dev/manual/nix/development/development/contributing.html).
+
+## Getting help
+
+Whenever you're stuck or do not know how to proceed, you can always ask for help.
+We invite you to use our [Matrix room](https://matrix.to/#/#nix-dev:nixos.org) to ask questions.

HACKING.md

@@ -0,0 +1 @@
+doc/manual/source/development/building.md

Makefile

@@ -1,29 +1,77 @@
+# External build directory support
+
+include mk/build-dir.mk
+
+-include $(buildprefix)Makefile.config
+clean-files += $(buildprefix)Makefile.config
+
+# List makefiles
+
+include mk/platform.mk
+
+ifeq ($(ENABLE_BUILD), yes)
 makefiles = \
   mk/precompiled-headers.mk \
   local.mk \
   src/libutil/local.mk \
-  src/libutil/tests/local.mk \
   src/libstore/local.mk \
-  src/libstore/tests/local.mk \
   src/libfetchers/local.mk \
   src/libmain/local.mk \
   src/libexpr/local.mk \
-  src/libexpr/tests/local.mk \
+  src/libflake/local.mk \
   src/libcmd/local.mk \
   src/nix/local.mk \
-  src/resolve-system-dependencies/local.mk \
+  src/libutil-c/local.mk \
+  src/libstore-c/local.mk \
+  src/libexpr-c/local.mk
+
+ifdef HOST_UNIX
+makefiles += \
   scripts/local.mk \
+  maintainers/local.mk \
   misc/bash/local.mk \
   misc/fish/local.mk \
   misc/zsh/local.mk \
   misc/systemd/local.mk \
   misc/launchd/local.mk \
-  misc/upstart/local.mk \
-  doc/manual/local.mk \
-  tests/local.mk \
-  tests/plugins/local.mk
+  misc/upstart/local.mk
+endif
+endif
 
--include Makefile.config
+ifeq ($(ENABLE_UNIT_TESTS), yes)
+makefiles += \
+  src/libutil-tests/local.mk \
+  src/libutil-test-support/local.mk \
+  src/libstore-tests/local.mk \
+  src/libstore-test-support/local.mk \
+  src/libfetchers-tests/local.mk \
+  src/libexpr-tests/local.mk \
+  src/libexpr-test-support/local.mk \
+  src/libflake-tests/local.mk
+endif
+
+ifeq ($(ENABLE_FUNCTIONAL_TESTS), yes)
+ifdef HOST_UNIX
+makefiles += \
+  tests/functional/local.mk \
+  tests/functional/flakes/local.mk \
+  tests/functional/ca/local.mk \
+  tests/functional/git-hashing/local.mk \
+  tests/functional/dyn-drv/local.mk \
+  tests/functional/local-overlay-store/local.mk \
+  tests/functional/test-libstoreconsumer/local.mk \
+  tests/functional/plugins/local.mk
+endif
+endif
+
+# Some makefiles require access to built programs and must be included late.
+makefiles-late =
+
+ifeq ($(ENABLE_DOC_GEN), yes)
+makefiles-late += doc/manual/local.mk
+endif
+
+# Miscellaneous global Flags
 
 OPTIMIZE = 1
 
@@ -32,8 +80,50 @@ ifeq ($(OPTIMIZE), 1)
   GLOBAL_LDFLAGS += $(CXXLTO)
 else
   GLOBAL_CXXFLAGS += -O0 -U_FORTIFY_SOURCE
+  unexport NIX_HARDENING_ENABLE
 endif
 
+ifdef HOST_WINDOWS
+  # Windows DLLs are stricter about symbol visibility than Unix shared
+  # objects --- see https://gcc.gnu.org/wiki/Visibility for details.
+  # This is a temporary sledgehammer to export everything like on Unix,
+  # and not detail with this yet.
+  #
+  # TODO do not do this, and instead do fine-grained export annotations.
+  GLOBAL_LDFLAGS += -Wl,--export-all-symbols
+  GLOBAL_CXXFLAGS += -D_WIN32_WINNT=0x0602
+endif
+
+GLOBAL_CXXFLAGS += -g -Wall -Wdeprecated-copy -Wignored-qualifiers -Wimplicit-fallthrough -Werror=unused-result -Werror=suggest-override -include $(buildprefix)config.h -std=c++2a -I src
+
+# Include the main lib, causing rules to be defined
+
 include mk/lib.mk
 
-GLOBAL_CXXFLAGS += -g -Wall -include config.h -std=c++17 -I src
+# Fallback stub rules for better UX when things are disabled
+#
+# These must be defined after `mk/lib.mk`. Otherwise the first rule
+# incorrectly becomes the default target.
+
+ifneq ($(ENABLE_UNIT_TESTS), yes)
+.PHONY: check
+check:
+	@echo "Unit tests are disabled. Configure without '--disable-unit-tests', or avoid calling 'make check'."
+	@exit 1
+endif
+
+ifneq ($(ENABLE_FUNCTIONAL_TESTS), yes)
+.PHONY: installcheck
+installcheck:
+	@echo "Functional tests are disabled. Configure without '--disable-functional-tests', or avoid calling 'make installcheck'."
+	@exit 1
+endif
+
+# Documentation fallback stub rules.
+
+ifneq ($(ENABLE_DOC_GEN), yes)
+.PHONY: manual-html manpages
+manual-html manpages:
+	@echo "Generated docs are disabled. Configure without '--disable-doc-gen', or avoid calling 'make manpages' and 'make manual-html'."
+	@exit 1
+endif

Makefile.config.in

@@ -8,15 +8,21 @@ CXX = @CXX@
 CXXFLAGS = @CXXFLAGS@
 CXXLTO = @CXXLTO@
 EDITLINE_LIBS = @EDITLINE_LIBS@
+ENABLE_BUILD = @ENABLE_BUILD@
+ENABLE_DOC_GEN = @ENABLE_DOC_GEN@
+ENABLE_FUNCTIONAL_TESTS = @ENABLE_FUNCTIONAL_TESTS@
 ENABLE_S3 = @ENABLE_S3@
+ENABLE_UNIT_TESTS = @ENABLE_UNIT_TESTS@
 GTEST_LIBS = @GTEST_LIBS@
 HAVE_LIBCPUID = @HAVE_LIBCPUID@
 HAVE_SECCOMP = @HAVE_SECCOMP@
 HOST_OS = @host_os@
+INSTALL_UNIT_TESTS = @INSTALL_UNIT_TESTS@
 LDFLAGS = @LDFLAGS@
 LIBARCHIVE_LIBS = @LIBARCHIVE_LIBS@
 LIBBROTLI_LIBS = @LIBBROTLI_LIBS@
 LIBCURL_LIBS = @LIBCURL_LIBS@
+LIBGIT2_LIBS = @LIBGIT2_LIBS@
 LIBSECCOMP_LIBS = @LIBSECCOMP_LIBS@
 LOWDOWN_LIBS = @LOWDOWN_LIBS@
 OPENSSL_LIBS = @OPENSSL_LIBS@
@@ -27,9 +33,10 @@ SODIUM_LIBS = @SODIUM_LIBS@
 SQLITE3_LIBS = @SQLITE3_LIBS@
 bash = @bash@
 bindir = @bindir@
+checkbindir = @checkbindir@
+checklibdir = @checklibdir@
 datadir = @datadir@
 datarootdir = @datarootdir@
-doc_generate = @doc_generate@
 docdir = @docdir@
 embedded_sandbox_shell = @embedded_sandbox_shell@
 exec_prefix = @exec_prefix@

README.md

@@ -1,35 +1,37 @@
 # Nix
 
 [![Open Collective supporters](https://opencollective.com/nixos/tiers/supporter/badge.svg?label=Supporters&color=brightgreen)](https://opencollective.com/nixos)
-[![Test](https://github.com/NixOS/nix/workflows/Test/badge.svg)](https://github.com/NixOS/nix/actions)
+[![CI](https://github.com/NixOS/nix/workflows/CI/badge.svg)](https://github.com/NixOS/nix/actions/workflows/ci.yml)
 
 Nix is a powerful package manager for Linux and other Unix systems that makes package
-management reliable and reproducible. Please refer to the [Nix manual](https://nixos.org/nix/manual)
+management reliable and reproducible. Please refer to the [Nix manual](https://nix.dev/reference/nix-manual)
 for more details.
 
-## Installation
+## Installation and first steps
 
-On Linux and macOS the easiest way to install Nix is to run the following shell command
-(as a user other than root):
+Visit [nix.dev](https://nix.dev) for [installation instructions](https://nix.dev/tutorials/install-nix) and [beginner tutorials](https://nix.dev/tutorials/first-steps).
 
-```console
-$ curl -L https://nixos.org/nix/install | sh
-```
+Full reference documentation can be found in the [Nix manual](https://nix.dev/reference/nix-manual).
 
-Information on additional installation methods is available on the [Nix download page](https://nixos.org/download.html).
+## Building and developing
 
-## Building And Developing
+Follow instructions in the Nix reference manual to [set up a development environment and build Nix from source](https://nix.dev/manual/nix/development/development/building.html).
 
-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.
+## Contributing
 
-## Additional Resources
+Check the [contributing guide](./CONTRIBUTING.md) if you want to get involved with developing Nix.
 
-- [Nix manual](https://nixos.org/nix/manual)
-- [Nix jobsets on hydra.nixos.org](https://hydra.nixos.org/project/nix)
-- [NixOS Discourse](https://discourse.nixos.org/)
-- [Matrix - #nix:nixos.org](https://matrix.to/#/#nix:nixos.org)
-- [IRC - #nixos on libera.chat](irc://irc.libera.chat/#nixos)
+## Additional resources
+
+Nix was created by Eelco Dolstra and developed as the subject of his PhD thesis [The Purely Functional Software Deployment Model](https://edolstra.github.io/pubs/phd-thesis.pdf), published 2006.
+Today, a world-wide developer community contributes to Nix and the ecosystem that has grown around it.
+
+- [The Nix, Nixpkgs, NixOS Community on nixos.org](https://nixos.org/)
+- [Official documentation on nix.dev](https://nix.dev)
+- [Nixpkgs](https://github.com/NixOS/nixpkgs) is [the largest, most up-to-date free software repository in the world](https://repology.org/repositories/graphs)
+- [NixOS](https://github.com/NixOS/nixpkgs/tree/master/nixos) is a Linux distribution that can be configured fully declaratively
+- [Discourse](https://discourse.nixos.org/)
+- [Matrix](https://matrix.to/#/#nix:nixos.org)
 
 ## License
 

boehmgc-coroutine-sp-fallback.diff

@@ -1,45 +0,0 @@
-diff --git a/pthread_stop_world.c b/pthread_stop_world.c
-index 4b2c429..1fb4c52 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;
-+    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)
-           hi = p->altstack + p->altstack_size;
-           /* FIXME: Need to scan the normal stack too, but how ? */
-           /* FIXME: Assume stack grows down */
-+        } else {
-+          if (pthread_getattr_np(p->id, &pattr)) {
-+            ABORT("GC_push_all_stacks: pthread_getattr_np failed!");
-+          }
-+          if (pthread_attr_getstacksize(&pattr, &stack_limit)) {
-+            ABORT("GC_push_all_stacks: pthread_attr_getstacksize failed!");
-+          }
-+          if (pthread_attr_destroy(&pattr)) {
-+            ABORT("GC_push_all_stacks: pthread_attr_destroy failed!");
-+          }
-+          // 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.
-+          #ifndef STACK_GROWS_UP
-+            if (lo >= hi || lo < hi - stack_limit) { // sp outside stack
-+              lo = hi - stack_limit;
-+            }
-+          #else
-+          #error "STACK_GROWS_UP not supported in boost_coroutine2 (as of june 2021), so we don't support it in Nix."
-+          #endif
-         }
-         GC_push_all_stack_sections(lo, hi, traced_stack_sect);
- #       ifdef STACK_GROWS_UP

bootstrap.sh

@@ -1,4 +0,0 @@
-#! /bin/sh -e
-rm -f aclocal.m4
-mkdir -p config
-exec autoreconf -vfi

build-utils-meson/deps-lists/meson.build

@@ -0,0 +1,36 @@
+# These are private dependencies with pkg-config files. What private
+# means is that the dependencies are used by the library but they are
+# *not* used (e.g. `#include`-ed) in any installed header file, and only
+# in regular source code (`*.cc`) or private, uninstalled headers. They
+# are thus part of the *implementation* of the library, but not its
+# *interface*.
+#
+# See `man pkg-config` for some details.
+deps_private = [ ]
+
+# These are public dependencies with pkg-config files. Public is the
+# opposite of private: these dependencies are used in installed header
+# files. They are part of the interface (and implementation) of the
+# library.
+#
+# N.B. This concept is mostly unrelated to our own concept of a public
+# (stable) API, for consumption outside of the Nix repository.
+# `libnixutil` is an unstable C++ library, whose public interface is
+# likewise unstable. `libutilc` conversely is a hopefully-soon stable
+# C library, whose public interface --- including public but not private
+# dependencies --- will also likewise soon be stable.
+#
+# N.B. For distributions that care about "ABI" stability and not just
+# "API" stability, the private dependencies also matter as they can
+# potentially affect the public ABI.
+deps_public = [ ]
+
+# These are subproject deps (type == "internal"). They are other
+# packages in `/src` in this repo. The private vs public distinction is
+# the same as above.
+deps_private_subproject = [ ]
+deps_public_subproject = [ ]
+
+# These are dependencencies without pkg-config files. Ideally they are
+# just private, but they may also be public (e.g. boost).
+deps_other = [ ]

build-utils-meson/diagnostics/meson.build

@@ -0,0 +1,11 @@
+add_project_arguments(
+  '-Wdeprecated-copy',
+  '-Werror=suggest-override',
+  '-Werror=switch',
+  '-Werror=switch-enum',
+  '-Werror=unused-result',
+  '-Wignored-qualifiers',
+  '-Wimplicit-fallthrough',
+  '-Wno-deprecated-declarations',
+  language : 'cpp',
+)

build-utils-meson/export-all-symbols/meson.build

@@ -0,0 +1,11 @@
+if host_machine.system() == 'cygwin' or host_machine.system() == 'windows'
+  # Windows DLLs are stricter about symbol visibility than Unix shared
+  # objects --- see https://gcc.gnu.org/wiki/Visibility for details.
+  # This is a temporary sledgehammer to export everything like on Unix,
+  # and not detail with this yet.
+  #
+  # TODO do not do this, and instead do fine-grained export annotations.
+  linker_export_flags = ['-Wl,--export-all-symbols']
+else
+  linker_export_flags = []
+endif

build-utils-meson/export/meson.build

@@ -0,0 +1,33 @@
+requires_private = []
+foreach dep : deps_private_subproject
+  requires_private  += dep.name()
+endforeach
+requires_private += deps_private
+
+requires_public  = []
+foreach dep : deps_public_subproject
+  requires_public  += dep.name()
+endforeach
+requires_public += deps_public
+
+extra_pkg_config_variables = get_variable('extra_pkg_config_variables', {})
+import('pkgconfig').generate(
+  this_library,
+  filebase : meson.project_name(),
+  name : 'Nix',
+  description : 'Nix Package Manager',
+  subdirs : ['nix'],
+  extra_cflags : ['-std=c++2a'],
+  requires : requires_public,
+  requires_private : requires_private,
+  libraries_private : libraries_private,
+  variables : extra_pkg_config_variables,
+)
+
+meson.override_dependency(meson.project_name(), declare_dependency(
+  include_directories : include_dirs,
+  link_with : this_library,
+  compile_args : ['-std=c++2a'],
+  dependencies : deps_public_subproject + deps_public,
+  variables : extra_pkg_config_variables,
+))

build-utils-meson/generate-header/meson.build

@@ -0,0 +1,7 @@
+bash = find_program('bash', native: true)
+
+gen_header = generator(
+  bash,
+  arguments : [ '-c', '{ echo \'R"__NIX_STR(\' && cat @INPUT@ && echo \')__NIX_STR"\'; } > "$1"', '_ignored_argv0', '@OUTPUT@' ],
+  output : '@PLAINNAME@.gen.hh',
+)

build-utils-meson/subprojects/meson.build

@@ -0,0 +1,19 @@
+foreach maybe_subproject_dep : deps_private_maybe_subproject
+  if maybe_subproject_dep.type_name() == 'internal'
+    deps_private_subproject += maybe_subproject_dep
+    # subproject sadly no good for pkg-config module
+    deps_other += maybe_subproject_dep
+  else
+    deps_private += maybe_subproject_dep
+  endif
+endforeach
+
+foreach maybe_subproject_dep : deps_public_maybe_subproject
+  if maybe_subproject_dep.type_name() == 'internal'
+    deps_public_subproject += maybe_subproject_dep
+    # subproject sadly no good for pkg-config module
+    deps_other += maybe_subproject_dep
+  else
+    deps_public += maybe_subproject_dep
+  endif
+endforeach

build-utils-meson/threads/meson.build

@@ -0,0 +1,6 @@
+# This is only conditional to work around
+# https://github.com/mesonbuild/meson/issues/13293. It should be
+# unconditional.
+if not (host_machine.system() == 'windows' and cxx.get_id() == 'gcc')
+  deps_private += dependency('threads')
+endif

build-utils-meson/windows-version/meson.build

@@ -0,0 +1,6 @@
+if host_machine.system() == 'windows'
+  # https://learn.microsoft.com/en-us/cpp/porting/modifying-winver-and-win32-winnt?view=msvc-170
+  # #define _WIN32_WINNT_WIN8 0x0602
+  # We currently don't use any API which requires higher than this.
+  add_project_arguments([ '-D_WIN32_WINNT=0x0602' ], language: 'cpp')
+endif

configure.ac

@@ -5,7 +5,14 @@ AC_CONFIG_AUX_DIR(config)
 
 AC_PROG_SED
 
-# Construct a Nix system name (like "i686-linux").
+# Construct a Nix system name (like "i686-linux"):
+# https://www.gnu.org/software/autoconf/manual/html_node/Canonicalizing.html#index-AC_005fCANONICAL_005fHOST-1
+# The inital value is produced by the `config/config.guess` script:
+# upstream: https://git.savannah.gnu.org/cgit/config.git/tree/config.guess
+# It has the following form, which is not documented anywhere:
+# <cpu>-<vendor>-<os>[<version>][-<abi>]
+# If `./configure` is passed any of the `--host`, `--build`, `--target` options, the value comes from `config/config.sub` instead:
+# upstream: https://git.savannah.gnu.org/cgit/config.git/tree/config.sub
 AC_CANONICAL_HOST
 AC_MSG_CHECKING([for the canonical Nix system name])
 
@@ -40,9 +47,11 @@ AC_DEFINE_UNQUOTED(SYSTEM, ["$system"], [platform identifier ('cpu-os')])
 # State should be stored in /nix/var, unless the user overrides it explicitly.
 test "$localstatedir" = '${prefix}/var' && localstatedir=/nix/var
 
+# Assign a default value to C{,XX}FLAGS as the default configure script sets them
+# to -O2 otherwise, which we don't want to have hardcoded
+CFLAGS=${CFLAGS-""}
+CXXFLAGS=${CXXFLAGS-""}
 
-CFLAGS=
-CXXFLAGS=
 AC_PROG_CC
 AC_PROG_CXX
 AC_PROG_CPP
@@ -53,16 +62,22 @@ AC_CHECK_TOOL([AR], [ar])
 AC_SYS_LARGEFILE
 
 
-# Solaris-specific stuff.
-AC_STRUCT_DIRENT_D_TYPE
+# OS-specific stuff.
 case "$host_os" in
   solaris*)
     # Solaris requires -lsocket -lnsl for network functions
     LDFLAGS="-lsocket -lnsl $LDFLAGS"
     ;;
+  darwin*)
+    # Need to link to libsandbox.
+    LDFLAGS="-lsandbox $LDFLAGS"
+    ;;
 esac
 
 
+ENSURE_NO_GCC_BUG_80431
+
+
 # Check for pubsetbuf.
 AC_MSG_CHECKING([for pubsetbuf])
 AC_LANG_PUSH(C++)
@@ -75,12 +90,13 @@ static char buf[1024];]],
 AC_LANG_POP(C++)
 
 
-AC_CHECK_FUNCS([statvfs pipe2])
+AC_CHECK_FUNCS([statvfs pipe2 close_range])
 
 
-# Check for lutimes, optionally used for changing the mtime of
-# symlinks.
-AC_CHECK_FUNCS([lutimes])
+# Check for lutimes and utimensat, optionally used for changing the
+# mtime of symlinks.
+AC_CHECK_DECLS([AT_SYMLINK_NOFOLLOW], [], [], [[#include <fcntl.h>]])
+AC_CHECK_FUNCS([lutimes utimensat])
 
 
 # Check whether the store optimiser can optimise symlinks.
@@ -114,7 +130,6 @@ AC_PATH_PROG(flex, flex, false)
 AC_PATH_PROG(bison, bison, false)
 AC_PATH_PROG(dot, dot)
 AC_PATH_PROG(lsof, lsof, lsof)
-NEED_PROG(jq, jq)
 
 
 AC_SUBST(coreutils, [$(dirname $(type -p cat))])
@@ -125,6 +140,47 @@ AC_ARG_WITH(store-dir, AS_HELP_STRING([--with-store-dir=PATH],[path of the Nix s
 AC_SUBST(storedir)
 
 
+# Running the functional tests without building Nix is useful for testing
+# different pre-built versions of Nix against each other.
+AC_ARG_ENABLE(build, AS_HELP_STRING([--disable-build],[Do not build nix]),
+  ENABLE_BUILD=$enableval, ENABLE_BUILD=yes)
+AC_SUBST(ENABLE_BUILD)
+
+# Building without unit tests is useful for bootstrapping with a smaller footprint
+# or running the tests in a separate derivation. Otherwise, we do compile and
+# run them.
+
+AC_ARG_ENABLE(unit-tests, AS_HELP_STRING([--disable-unit-tests],[Do not build the tests]),
+  ENABLE_UNIT_TESTS=$enableval, ENABLE_UNIT_TESTS=$ENABLE_BUILD)
+AC_SUBST(ENABLE_UNIT_TESTS)
+
+AS_IF(
+  [test "$ENABLE_BUILD" == "no" && test "$ENABLE_UNIT_TESTS" == "yes"],
+  [AC_MSG_ERROR([Cannot enable unit tests when building overall is disabled. Please do not pass '--enable-unit-tests' or do not pass '--disable-build'.])])
+
+AC_ARG_ENABLE(functional-tests, AS_HELP_STRING([--disable-functional-tests],[Do not build the tests]),
+  ENABLE_FUNCTIONAL_TESTS=$enableval, ENABLE_FUNCTIONAL_TESTS=yes)
+AC_SUBST(ENABLE_FUNCTIONAL_TESTS)
+
+# documentation generation switch
+AC_ARG_ENABLE(doc-gen, AS_HELP_STRING([--disable-doc-gen],[disable documentation generation]),
+  ENABLE_DOC_GEN=$enableval, ENABLE_DOC_GEN=$ENABLE_BUILD)
+AC_SUBST(ENABLE_DOC_GEN)
+
+AS_IF(
+  [test "$ENABLE_BUILD" == "no" && test "$ENABLE_DOC_GEN" == "yes"],
+  [AC_MSG_ERROR([Cannot enable generated docs when building overall is disabled. Please do not pass '--enable-doc-gen' or do not pass '--disable-build'.])])
+
+AS_IF(
+  [test "$ENABLE_FUNCTIONAL_TESTS" == "yes" || test "$ENABLE_DOC_GEN" == "yes"],
+  [NEED_PROG(jq, jq)])
+
+AS_IF(
+  [test "$ENABLE_DOC_GEN" == "yes"],
+  [NEED_PROG(man, man)])
+
+AS_IF([test "$ENABLE_BUILD" == "yes"],[
+
 # Look for boost, a required dependency.
 # Note that AX_BOOST_BASE only exports *CPP* BOOST_CPPFLAGS, no CXX flags,
 # and CPPFLAGS are not passed to the C++ compiler automatically.
@@ -147,6 +203,18 @@ if test "x$GCC_ATOMIC_BUILTINS_NEED_LIBATOMIC" = xyes; then
     LDFLAGS="-latomic $LDFLAGS"
 fi
 
+AC_ARG_ENABLE(install-unit-tests, AS_HELP_STRING([--enable-install-unit-tests],[Install the unit tests for running later (default no)]),
+  INSTALL_UNIT_TESTS=$enableval, INSTALL_UNIT_TESTS=no)
+AC_SUBST(INSTALL_UNIT_TESTS)
+
+AC_ARG_WITH(check-bin-dir, AS_HELP_STRING([--with-check-bin-dir=PATH],[path to install unit tests for running later (defaults to $libexecdir/nix)]),
+  checkbindir=$withval, checkbindir=$libexecdir/nix)
+AC_SUBST(checkbindir)
+
+AC_ARG_WITH(check-lib-dir, AS_HELP_STRING([--with-check-lib-dir=PATH],[path to install unit tests for running later (defaults to $libdir)]),
+  checklibdir=$withval, checklibdir=$libdir)
+AC_SUBST(checklibdir)
+
 # LTO is currently broken with clang for unknown reasons; ld segfaults in the llvm plugin
 AC_ARG_ENABLE(lto, AS_HELP_STRING([--enable-lto],[Enable LTO (only supported with GCC) [default=no]]),
   lto=$enableval, lto=no)
@@ -174,10 +242,10 @@ fi
 
 # Look for OpenSSL, a required dependency. FIXME: this is only (maybe)
 # used by S3BinaryCacheStore.
-PKG_CHECK_MODULES([OPENSSL], [libcrypto], [CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"])
+PKG_CHECK_MODULES([OPENSSL], [libcrypto >= 1.1.1], [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
@@ -190,17 +258,25 @@ PKG_CHECK_MODULES([SQLITE3], [sqlite3 >= 3.6.19], [CXXFLAGS="$SQLITE3_CFLAGS $CX
 # Look for libcurl, a required dependency.
 PKG_CHECK_MODULES([LIBCURL], [libcurl], [CXXFLAGS="$LIBCURL_CFLAGS $CXXFLAGS"])
 
-# Look for editline, a required dependency.
+# Look for editline or readline, a required dependency.
 # The the libeditline.pc file was added only in libeditline >= 1.15.2,
 # see https://github.com/troglobit/editline/commit/0a8f2ef4203c3a4a4726b9dd1336869cd0da8607,
-# but e.g. Ubuntu 16.04 has an older version, so we fall back to searching for
-# editline.h when the pkg-config approach fails.
-PKG_CHECK_MODULES([EDITLINE], [libeditline], [CXXFLAGS="$EDITLINE_CFLAGS $CXXFLAGS"], [
-  AC_CHECK_HEADERS([editline.h], [true],
-    [AC_MSG_ERROR([Nix requires libeditline; it was found neither via pkg-config nor its normal header.])])
-  AC_SEARCH_LIBS([readline read_history], [editline], [],
-    [AC_MSG_ERROR([Nix requires libeditline; it was not found via pkg-config, but via its header, but required functions do not work. Maybe it is too old? >= 1.14 is required.])])
-])
+# Older versions are no longer supported.
+AC_ARG_WITH(
+  [readline-flavor],
+  AS_HELP_STRING([--with-readline-flavor],[Which library to use for nice line editting with the Nix language REPL" [default=editline]]),
+  [readline_flavor=$withval],
+  [readline_flavor=editline])
+AS_CASE(["$readline_flavor"],
+  [editline], [
+    readline_flavor_pc=libeditline
+  ],
+  [readline], [
+    readline_flavor_pc=readline
+    AC_DEFINE([USE_READLINE], [1], [Use readline instead of editline])
+  ],
+  [AC_MSG_ERROR([bad value "$readline_flavor" for --with-readline-flavor, must be one of: editline, readline])])
+PKG_CHECK_MODULES([EDITLINE], [$readline_flavor_pc], [CXXFLAGS="$EDITLINE_CFLAGS $CXXFLAGS"])
 
 # Look for libsodium.
 PKG_CHECK_MODULES([SODIUM], [libsodium], [CXXFLAGS="$SODIUM_CFLAGS $CXXFLAGS"])
@@ -232,9 +308,20 @@ case "$host_os" in
                                 ]))
     if test "x$enable_seccomp_sandboxing" != "xno"; then
       PKG_CHECK_MODULES([LIBSECCOMP], [libseccomp],
-                        [CXXFLAGS="$LIBSECCOMP_CFLAGS $CXXFLAGS"])
+                        [CXXFLAGS="$LIBSECCOMP_CFLAGS $CXXFLAGS" CFLAGS="$LIBSECCOMP_CFLAGS $CFLAGS"])
       have_seccomp=1
       AC_DEFINE([HAVE_SECCOMP], [1], [Whether seccomp is available and should be used for sandboxing.])
+      AC_COMPILE_IFELSE([
+        AC_LANG_SOURCE([[
+          #include <seccomp.h>
+          #ifndef __SNR_fchmodat2
+          # error "Missing support for fchmodat2"
+          #endif
+        ]])
+      ], [], [
+        echo "libseccomp is missing __SNR_fchmodat2. Please provide libseccomp 2.5.5 or later"
+        exit 1
+      ])
     else
       have_seccomp=
     fi
@@ -245,6 +332,14 @@ case "$host_os" in
 esac
 AC_SUBST(HAVE_SECCOMP, [$have_seccomp])
 
+# Optional dependencies for better normalizing file system data
+AC_CHECK_HEADERS([sys/xattr.h])
+AS_IF([test "$ac_cv_header_sys_xattr_h" = "yes"],[
+  AC_CHECK_FUNCS([llistxattr lremovexattr])
+  AS_IF([test "$ac_cv_func_llistxattr" = "yes" && test "$ac_cv_func_lremovexattr" = "yes"],[
+    AC_DEFINE([HAVE_ACL_SUPPORT], [1], [Define if we can manipulate file system Access Control Lists])
+  ])
+])
 
 # Look for aws-cpp-sdk-s3.
 AC_LANG_PUSH(C++)
@@ -254,13 +349,6 @@ AC_CHECK_HEADERS([aws/s3/S3Client.h],
 AC_SUBST(ENABLE_S3, [$enable_s3])
 AC_LANG_POP(C++)
 
-if test -n "$enable_s3"; then
-  declare -a aws_version_tokens=($(printf '#include <aws/core/VersionConfig.h>\nAWS_SDK_VERSION_STRING' | $CPP $CPPFLAGS - | grep -v '^#.*' | sed 's/"//g' | tr '.' ' '))
-  AC_DEFINE_UNQUOTED([AWS_VERSION_MAJOR], ${aws_version_tokens@<:@0@:>@}, [Major version of aws-sdk-cpp.])
-  AC_DEFINE_UNQUOTED([AWS_VERSION_MINOR], ${aws_version_tokens@<:@1@:>@}, [Minor version of aws-sdk-cpp.])
-  AC_DEFINE_UNQUOTED([AWS_VERSION_PATCH], ${aws_version_tokens@<:@2@:>@}, [Patch version of aws-sdk-cpp.])
-fi
-
 
 # Whether to use the Boehm garbage collector.
 AC_ARG_ENABLE(gc, AS_HELP_STRING([--enable-gc],[enable garbage collection in the Nix expression evaluator (requires Boehm GC) [default=yes]]),
@@ -269,24 +357,55 @@ if test "$gc" = yes; then
   PKG_CHECK_MODULES([BDW_GC], [bdw-gc])
   CXXFLAGS="$BDW_GC_CFLAGS $CXXFLAGS"
   AC_DEFINE(HAVE_BOEHMGC, 1, [Whether to use the Boehm garbage collector.])
+
+  # See `fixupBoehmStackPointer`, for the integration between Boehm GC
+  # and Boost coroutines.
+  old_CFLAGS="$CFLAGS"
+  # Temporary set `-pthread` just for the next check
+  CFLAGS="$CFLAGS -pthread"
+  AC_CHECK_FUNCS([pthread_attr_get_np pthread_getattr_np])
+  CFLAGS="$old_CFLAGS"
 fi
 
+AS_IF([test "$ENABLE_UNIT_TESTS" == "yes"],[
 
 # Look for gtest.
-PKG_CHECK_MODULES([GTEST], [gtest_main])
+PKG_CHECK_MODULES([GTEST], [gtest_main gmock_main])
 
+# Look for rapidcheck.
+PKG_CHECK_MODULES([RAPIDCHECK], [rapidcheck rapidcheck_gtest])
+
+])
 
 # Look for nlohmann/json.
 PKG_CHECK_MODULES([NLOHMANN_JSON], [nlohmann_json >= 3.9])
 
 
-# documentation generation switch
-AC_ARG_ENABLE(doc-gen, AS_HELP_STRING([--disable-doc-gen],[disable documentation generation]),
-  doc_generate=$enableval, doc_generate=yes)
-AC_SUBST(doc_generate)
-
 # Look for lowdown library.
-PKG_CHECK_MODULES([LOWDOWN], [lowdown >= 0.9.0], [CXXFLAGS="$LOWDOWN_CFLAGS $CXXFLAGS"])
+AC_ARG_ENABLE([markdown], AS_HELP_STRING([--enable-markdown], [Enable Markdown rendering in the Nix binary (requires lowdown) [default=auto]]),
+  enable_markdown=$enableval, enable_markdown=auto)
+AS_CASE(["$enable_markdown"],
+  [yes | auto], [
+    PKG_CHECK_MODULES([LOWDOWN], [lowdown >= 0.9.0], [
+      CXXFLAGS="$LOWDOWN_CFLAGS $CXXFLAGS"
+      have_lowdown=1
+      AC_DEFINE(HAVE_LOWDOWN, 1, [Whether lowdown is available and should be used for Markdown rendering.])
+    ], [
+      AS_IF([test "x$enable_markdown" == "xyes"], [AC_MSG_ERROR([--enable-markdown was specified, but lowdown was not found.])])
+    ])
+  ],
+  [no], [have_lowdown=],
+  [AC_MSG_ERROR([bad value "$enable_markdown" for --enable-markdown, must be one of: yes, no, auto])])
+
+
+# Look for libgit2.
+PKG_CHECK_MODULES([LIBGIT2], [libgit2])
+
+
+# Look for toml11, a required dependency.
+AC_LANG_PUSH(C++)
+AC_CHECK_HEADER([toml.hpp], [], [AC_MSG_ERROR([toml11 is not found.])])
+AC_LANG_POP(C++)
 
 # Setuid installations.
 AC_CHECK_FUNCS([setresuid setreuid lchown])
@@ -318,6 +437,8 @@ if test "$embedded_sandbox_shell" = yes; then
   AC_DEFINE(HAVE_EMBEDDED_SANDBOX_SHELL, 1, [Include the sandbox shell in the Nix binary.])
 fi
 
+])
+
 
 # Expand all variables in config.status.
 test "$prefix" = NONE && prefix=$ac_default_prefix

default.nix

@@ -1,3 +1,10 @@
-(import (fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz") {
-  src = ./.;
-}).defaultNix
+(import
+  (
+    let lock = builtins.fromJSON (builtins.readFile ./flake.lock); in
+    fetchTarball {
+      url = "https://github.com/edolstra/flake-compat/archive/${lock.nodes.flake-compat.locked.rev}.tar.gz";
+      sha256 = lock.nodes.flake-compat.locked.narHash;
+    }
+  )
+  { src = ./.; }
+).defaultNix

doc/manual/.version

@@ -0,0 +1 @@
+../../.version

doc/manual/book.toml

@@ -1,7 +1,34 @@
+[book]
+title = "Nix Reference Manual"
+src = "source"
+
 [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"
+
+# Handles replacing @docroot@ with a path to ./source relative to that markdown file,
+# {{#include handlebars}}, and the @generated@ syntax used within these. it mostly
+# but not entirely replaces the links preprocessor (which we cannot simply use due
+# to @generated@ files living in a different directory to make meson happy). we do
+# not want to disable the links preprocessor entirely though because that requires
+# disabling *all* built-in preprocessors and selectively reenabling those we want.
+[preprocessor.substitute]
+command = "python3 ./substitute.py"
+before = ["anchors", "links"]
 
 [preprocessor.anchors]
 renderers = ["html"]
-command = "jq --from-file doc/manual/anchors.jq"
+command = "jq --from-file ./anchors.jq"
+
+[output.markdown]
+
+[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

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

doc/manual/generate-builtins.nix

@@ -1,16 +1,45 @@
-with builtins;
-with import ./utils.nix;
+let
+  inherit (builtins) concatStringsSep attrValues mapAttrs;
+  inherit (import <nix/utils.nix>) optionalString squash;
+in
 
-builtins:
+builtinsInfo:
+let
+  showBuiltin = name: { doc, type ? null, args ? [ ], experimental-feature ? null, impure-only ? false }:
+    let
+      type' = optionalString (type != null) " (${type})";
 
-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))
+      experimentalNotice = optionalString (experimental-feature != null) ''
+        > **Note**
+        >
+        > This function is only available if the [`${experimental-feature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimental-feature}) is enabled.
+        >
+        > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
+        >
+        > ```
+        > extra-experimental-features = ${experimental-feature}
+        > ```
+      '';
+
+      impureNotice = optionalString impure-only ''
+        > **Note**
+        >
+        > Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
+      '';
+    in
+    squash ''
+      <dt id="builtins-${name}">
+        <a href="#builtins-${name}"><code>${name}${listArgs args}</code></a>${type'}
+      </dt>
+      <dd>
+
+      ${experimentalNotice}
+
+      ${doc}
+
+      ${impureNotice}
+      </dd>
+    '';
+  listArgs = args: concatStringsSep "" (map (s: " <var>${s}</var>") args);
+in
+concatStringsSep "\n" (attrValues (mapAttrs showBuiltin builtinsInfo))

doc/manual/generate-deps.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+
+import glob
+import sys
+
+# meson expects makefile-style dependency declarations, i.e.
+#
+#   target: dependency...
+#
+# meson seems to pass depfiles straight on to ninja even though
+# it also parses the file itself (or at least has code to do so
+# in its tree), so we must live by ninja's rules: only slashes,
+# spaces and octothorpes can be escaped, anything else is taken
+# literally. since the rules for these aren't even the same for
+# all three we will just fail when we encounter any of them (if
+# asserts are off for some reason the depfile will likely point
+# to nonexistant paths, making everything phony and thus fine.)
+for path in glob.glob(sys.argv[1] + '/**', recursive=True):
+    assert '\\' not in path
+    assert ' ' not in path
+    assert '#' not in path
+    print("ignored:", path)

doc/manual/generate-manpage.nix

@@ -1,99 +1,207 @@
-{ command, renderLinks ? false }:
+let
+  inherit (builtins)
+    attrNames
+    attrValues
+    concatMap
+    concatStringsSep
+    fromJSON
+    groupBy
+    length
+    lessThan
+    listToAttrs
+    mapAttrs
+    match
+    replaceStrings
+    sort
+    ;
+  inherit (import <nix/utils.nix>)
+    attrsToList
+    concatStrings
+    filterAttrs
+    optionalString
+    squash
+    trim
+    unique
+    ;
+  showStoreDocs = import <nix/generate-store-info.nix>;
+in
 
-with builtins;
-with import ./utils.nix;
+inlineHTML: commandDump:
 
 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 "")
-  ;
+  commandInfo = fromJSON commandDump;
+
+  showCommand = { command, details, filename, toplevel }:
+    let
+
+      result = ''
+        > **Warning** \
+        > This program is
+        > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
+        > and its interface is subject to change.
+
+        # Name
+
+        `${command}` - ${details.description}
+
+        # Synopsis
+
+        ${showSynopsis command details.args}
+
+        ${maybeSubcommands}
+
+        ${maybeProse}
+
+        ${maybeOptions}
+      '';
+
+      showSynopsis = command: args:
+        let
+          showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
+          arguments = concatStringsSep " " (map showArgument args);
+        in ''
+          `${command}` [*option*...] ${arguments}
+        '';
+
+      maybeSubcommands = optionalString (details ? commands && details.commands != {})
+        ''
+          where *subcommand* is one of the following:
+
+          ${subcommands}
+        '';
+
+      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}
+      '';
+
+      maybeProse =
+        # FIXME: this is a horrible hack to keep `nix help-stores` working.
+        let
+          help-stores = ''
+            ${index}
+
+            ${allStores}
+          '';
+          index = replaceStrings
+            [ "@store-types@" "./local-store.md" "./local-daemon-store.md" ]
+            [ storesOverview "#local-store" "#local-daemon-store" ]
+            details.doc;
+          storesOverview =
+            let
+              showEntry = store:
+                "- [${store.name}](#${store.slug})";
+            in
+            concatStringsSep "\n" (map showEntry storesList) + "\n";
+          allStores = concatStringsSep "\n" (attrValues storePages);
+          storePages = listToAttrs
+            (map (s: { name = s.filename; value = s.page; }) storesList);
+          storesList = showStoreDocs {
+            storeInfo = commandInfo.stores;
+            inherit inlineHTML;
+          };
+          hasInfix = infix: content:
+            builtins.stringLength content != builtins.stringLength (replaceStrings [ infix ] [ "" ] content);
+        in
+        optionalString (details ? doc) (
+          # An alternate implementation with builtins.match stack overflowed on some systems.
+          if hasInfix "@store-types@" details.doc
+          then help-stores
+          else details.doc
+        );
+
+      maybeOptions =
+        let
+          allVisibleOptions = filterAttrs
+            (_: o: ! o.hiddenCategory)
+            (details.flags // toplevel.flags);
+        in
+        optionalString (allVisibleOptions != { }) ''
+          # Options
+
+          ${showOptions inlineHTML allVisibleOptions}
+
+          > **Note**
+          >
+          > See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.
+        '';
+
+      showOptions = inlineHTML: allOptions:
+        let
+          showCategory = cat: opts: ''
+            ${optionalString (cat != "") "## ${cat}"}
+
+            ${concatStringsSep "\n" (attrValues (mapAttrs showOption opts))}
+          '';
+          showOption = name: option:
+            let
+              result = trim ''
+                - ${item}
+
+                  ${option.description}
+              '';
+              item = if inlineHTML
+                then ''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}''
+                else "`--${name}` ${shortName} ${labels}";
+              shortName = optionalString
+                (option ? shortName)
+                ("/ `-${option.shortName}`");
+              labels = optionalString
+                (option ? labels)
+                (concatStringsSep " " (map (s: "*${s}*") option.labels));
+            in result;
+          categories = mapAttrs
+            # Convert each group from a list of key-value pairs back to an attrset
+            (_: listToAttrs)
+            (groupBy
+              (cmd: cmd.value.category)
+              (attrsToList allOptions));
+        in concatStrings (attrValues (mapAttrs showCategory categories));
+    in squash result;
 
   appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
 
-  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";
+  manpages = processCommand {
+    command = "nix";
+    details = commandInfo.args;
+    filename = "nix";
+    toplevel = commandInfo.args;
+  };
 
-  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 +0,0 @@
-with builtins;
-with import ./utils.nix;
-
-options:
-
-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))

doc/manual/generate-settings.nix

@@ -0,0 +1,67 @@
+let
+  inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
+  inherit (import <nix/utils.nix>) concatStrings indent optionalString squash;
+in
+
+# `inlineHTML` is a hack to accommodate inconsistent output from `lowdown`
+{ prefix, inlineHTML ? true }: settingsInfo:
+
+let
+
+  showSetting = prefix: setting: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
+    let
+      result = squash ''
+          - ${item}
+
+          ${indent "  " body}
+        '';
+      item = if inlineHTML
+        then ''<span id="${prefix}-${setting}">[`${setting}`](#${prefix}-${setting})</span>''
+        else "`${setting}`";
+      # separate body to cleanly handle indentation
+      body = ''
+          ${experimentalFeatureNote}
+
+          ${description}
+
+          **Default:** ${showDefault documentDefault defaultValue}
+
+          ${showAliases aliases}
+        '';
+
+      experimentalFeatureNote = optionalString (experimentalFeature != null) ''
+          > **Warning**
+          >
+          > This setting is part of an
+          > [experimental feature](@docroot@/development/experimental-features.md).
+          >
+          > To change this setting, make sure the
+          > [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
+          > is enabled.
+          > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
+          >
+          > ```
+          > extra-experimental-features = ${experimentalFeature}
+          > ${setting} = ...
+          > ```
+        '';
+
+      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:
+          optionalString (aliases != [])
+            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
+
+    in result;
+
+in concatStrings (attrValues (mapAttrs (showSetting prefix) settingsInfo))

doc/manual/generate-store-info.nix

@@ -0,0 +1,57 @@
+let
+  inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
+  inherit (import <nix/utils.nix>) optionalString filterAttrs trim squash toLower unique indent;
+  showSettings = import <nix/generate-settings.nix>;
+in
+
+{
+  # data structure describing all stores and their parameters
+  storeInfo,
+  # whether to add inline HTML tags
+  # `lowdown` does not eat those for one of the output modes
+  inlineHTML,
+}:
+
+let
+
+  showStore = { name, slug }: { settings, doc, experimentalFeature }:
+    let
+      result = squash ''
+        # ${name}
+
+        ${experimentalFeatureNote}
+
+        ${doc}
+
+        ## Settings
+
+        ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
+      '';
+
+      experimentalFeatureNote = optionalString (experimentalFeature != null) ''
+        > **Warning**
+        >
+        > This store is part of an
+        > [experimental feature](@docroot@/development/experimental-features.md).
+        >
+        > To use this store, make sure the
+        > [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
+        > is enabled.
+        > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
+        >
+        > ```
+        > extra-experimental-features = ${experimentalFeature}
+        > ```
+      '';
+    in result;
+
+  storesList = map
+    (name: rec {
+      inherit name;
+      slug = replaceStrings [ " " ] [ "-" ] (toLower name);
+      filename = "${slug}.md";
+      page = showStore { inherit name slug; } storeInfo.${name};
+    })
+    (attrNames storeInfo);
+
+in storesList

doc/manual/generate-store-types.nix

@@ -0,0 +1,39 @@
+let
+  inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
+  showSettings = import <nix/generate-settings.nix>;
+  showStoreDocs = import <nix/generate-store-info.nix>;
+in
+
+storeInfo:
+
+let
+  storesList = showStoreDocs {
+    inherit storeInfo;
+    inlineHTML = true;
+  };
+
+  index =
+    let
+      showEntry = store:
+        "- [${store.name}](./${store.filename})";
+    in
+    concatStringsSep "\n" (map showEntry storesList);
+
+  "index.md" = replaceStrings
+    [ "@store-types@" ] [ index ]
+    (readFile ./source/store/types/index.md.in);
+
+  tableOfContents =
+    let
+      showEntry = store:
+        "    - [${store.name}](store/types/${store.filename})";
+    in
+    concatStringsSep "\n" (map showEntry storesList) + "\n";
+
+  "SUMMARY.md" = tableOfContents;
+
+  storePages = listToAttrs
+    (map (s: { name = s.filename; value = s.page; }) storesList);
+
+in
+storePages // { inherit "index.md" "SUMMARY.md"; }

doc/manual/generate-xp-features-shortlist.nix

@@ -0,0 +1,9 @@
+with builtins;
+with import <nix/utils.nix>;
+
+let
+  showExperimentalFeature = name: doc:
+    ''
+      - [`${name}`](@docroot@/development/experimental-features.md#xp-feature-${name})
+    '';
+in xps: indent "  " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))

doc/manual/generate-xp-features.nix

@@ -0,0 +1,13 @@
+with builtins;
+with import <nix/utils.nix>;
+
+let
+  showExperimentalFeature = name: doc:
+    squash ''
+      ## [`${name}`]{#xp-feature-${name}}
+
+      ${doc}
+    '';
+in
+
+xps: (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps)))

doc/manual/local.mk

@@ -1,22 +1,33 @@
-ifeq ($(doc_generate),yes)
+# The version of Nix used to generate the doc. Can also be
+# `$(nix_INSTALL_PATH)` or just `nix` (to grap ambient from the `PATH`),
+# if one prefers.
+doc_nix = $(nix_PATH)
 
 MANUAL_SRCS := \
-  $(call rwildcard, $(d)/src, *.md) \
-  $(call rwildcard, $(d)/src, */*.md)
+	$(call rwildcard, $(d)/source, *.md) \
+	$(call rwildcard, $(d)/source, */*.md)
 
-# Generate man pages.
 man-pages := $(foreach n, \
-  nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \
-  nix-collect-garbage.1 \
-  nix-prefetch-url.1 nix-channel.1 \
-  nix-hash.1 nix-copy-closure.1 \
-  nix.conf.5 nix-daemon.8, \
-  $(d)/$(n))
+	nix-env.1 nix-store.1 \
+	nix-build.1 nix-shell.1 nix-instantiate.1 \
+	nix-collect-garbage.1 \
+	nix-prefetch-url.1 nix-channel.1 \
+	nix-hash.1 nix-copy-closure.1 \
+	nix.conf.5 nix-daemon.8 \
+	nix-profiles.5 \
+, $(d)/$(n))
+
+# man pages for subcommands
+# convert from `$(d)/source/command-ref/nix-{1}/{2}.md` to `$(d)/nix-{1}-{2}.1`
+# FIXME: unify with how nix3-cli man pages are generated
+man-pages += $(foreach subcommand, \
+	$(filter-out %opt-common.md %env-common.md, $(wildcard $(d)/source/command-ref/nix-*/*.md)), \
+	$(d)/$(subst /,-,$(subst $(d)/source/command-ref/,,$(subst .md,.1,$(subcommand)))))
 
 clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8
 
 # Provide a dummy environment for nix, so that it will not access files outside the macOS sandbox.
-# Set cores to 0 because otherwise nix show-config resolves the cores based on the current machine
+# Set cores to 0 because otherwise `nix config show` resolves the cores based on the current machine
 dummy-env = env -i \
 	HOME=/dummy \
 	NIX_CONF_DIR=/dummy \
@@ -24,84 +35,202 @@ dummy-env = env -i \
 	NIX_STATE_DIR=/dummy \
 	NIX_CONFIG='cores = 0'
 
-nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw
+nix-eval = $(dummy-env) $(doc_nix) eval --experimental-features nix-command -I nix=doc/manual --store dummy:// --impure --raw
 
-$(d)/%.1: $(d)/src/command-ref/%.md
+# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution
+define process-includes
+	while read -r line; do \
+		set -euo pipefail; \
+		filename="$$(dirname $(1))/$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line)"; \
+		test -f "$$filename" || ( echo "#include-d file '$$filename' does not exist." >&2; exit 1; ); \
+		matchline="$$(sed 's|/|\\/|g' <<< $$line)"; \
+		sed -i "/$$matchline/r $$filename" $(2); \
+		sed -i "s/$$matchline//" $(2); \
+	done < <(grep '{{#include' $(1))
+endef
+
+$(d)/nix-env-%.1: $(d)/source/command-ref/nix-env/%.md
+	@printf "Title: %s\n\n" "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" > $^.tmp
+	$(render-subcommand)
+
+$(d)/nix-store-%.1: $(d)/source/command-ref/nix-store/%.md
+	@printf -- 'Title: %s\n\n' "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" > $^.tmp
+	$(render-subcommand)
+
+# FIXME: there surely is some more deduplication to be achieved here with even darker Make magic
+define render-subcommand
+  @cat $^ >> $^.tmp
+	@$(call process-includes,$^,$^.tmp)
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
+	@# fix up `lowdown`'s automatic escaping of `--`
+	@# https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202
+	@sed -i 's/\e\[u2013\]/--/' $@
+	@rm $^.tmp
+endef
+
+
+$(d)/%.1: $(d)/source/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
 	@cat $^ >> $^.tmp
-	$(trace-gen) lowdown -sT man -M section=1 $^.tmp -o $@
+	@$(call process-includes,$^,$^.tmp)
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
 	@rm $^.tmp
 
-$(d)/%.8: $(d)/src/command-ref/%.md
+$(d)/%.8: $(d)/source/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
+$(d)/nix.conf.5: $(d)/source/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 $@
+	@$(call process-includes,$^,$^.tmp)
+	$(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
-	$(trace-gen) cat doc/manual/src/SUMMARY.md.in | while IFS= read line; do if [[ $$line = @manpages@ ]]; then cat doc/manual/src/command-ref/new-cli/SUMMARY.md; else echo "$$line"; fi; done > $@.tmp
+$(d)/nix-profiles.5: $(d)/source/command-ref/files/profiles.md
+	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
+	@cat $^ >> $^.tmp
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
+	@rm $^.tmp
+
+$(d)/source/SUMMARY.md: $(d)/source/SUMMARY.md.in $(d)/source/SUMMARY-rl-next.md $(d)/source/store/types $(d)/source/command-ref/new-cli $(d)/source/development/experimental-feature-descriptions.md
+	@cp $< $@
+	@$(call process-includes,$@,$@)
+
+$(d)/source/store/types: $(d)/nix.json $(d)/utils.nix $(d)/generate-store-info.nix  $(d)/generate-store-types.nix $(d)/source/store/types/index.md.in $(doc_nix)
+	@# FIXME: build out of tree!
+	@rm -rf $@.tmp
+	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-store-types.nix (builtins.fromJSON (builtins.readFile $<)).stores'
+	@# do not destroy existing contents
+	@mv $@.tmp/* $@/
+
+$(d)/source/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(d)/generate-settings.nix $(d)/generate-store-info.nix $(doc_nix)
+	@rm -rf $@ $@.tmp
+	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
 	@mv $@.tmp $@
 
-$(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; }'
-
-$(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
+$(d)/source/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/generate-settings.nix $(d)/source/command-ref/conf-file-prefix.md $(d)/source/command-ref/experimental-features-shortlist.md $(doc_nix)
+	@cat doc/manual/source/command-ref/conf-file-prefix.md > $@.tmp
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-settings.nix { prefix = "conf"; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
 	@mv $@.tmp $@
 
-$(d)/nix.json: $(bindir)/nix
-	$(trace-gen) $(dummy-env) $(bindir)/nix __dump-args > $@.tmp
+$(d)/nix.json: $(doc_nix)
+	$(trace-gen) $(dummy-env) $(doc_nix) __dump-cli > $@.tmp
 	@mv $@.tmp $@
 
-$(d)/conf-file.json: $(bindir)/nix
-	$(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp
+$(d)/conf-file.json: $(doc_nix)
+	$(trace-gen) $(dummy-env) $(doc_nix) config show --json --experimental-features nix-command > $@.tmp
 	@mv $@.tmp $@
 
-$(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
-	@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
+$(d)/source/development/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
+	@rm -rf $@ $@.tmp
+	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
 	@mv $@.tmp $@
 
-$(d)/builtins.json: $(bindir)/nix
-	$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-builtins > $@.tmp
+$(d)/source/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix)
+	@rm -rf $@ $@.tmp
+	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))'
 	@mv $@.tmp $@
 
+$(d)/xp-features.json: $(doc_nix)
+	$(trace-gen) $(dummy-env) $(doc_nix) __dump-xp-features > $@.tmp
+	@mv $@.tmp $@
+
+$(d)/source/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/source/language/builtins-prefix.md $(doc_nix)
+	@cat doc/manual/source/language/builtins-prefix.md > $@.tmp
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
+	@cat doc/manual/source/language/builtins-suffix.md >> $@.tmp
+	@mv $@.tmp $@
+
+$(d)/language.json: $(doc_nix)
+	$(trace-gen) $(dummy-env) $(doc_nix) __dump-language > $@.tmp
+	@mv $@.tmp $@
+
+# Generate "Upcoming release" notes (or clear it and remove from menu)
+$(d)/source/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
+	@if type -p changelog-d > /dev/null; then \
+		echo "  GEN   " $@; \
+		changelog-d doc/manual/rl-next > $@; \
+	else \
+		echo "  NULL  " $@; \
+		true > $@; \
+	fi
+
+$(d)/source/SUMMARY-rl-next.md: $(d)/source/release-notes/rl-next.md
+	$(trace-gen) true
+	@if [ -s $< ]; then \
+		echo '  - [Upcoming release](release-notes/rl-next.md)' > $@; \
+	else \
+	  true > $@; \
+	fi
+
 # Generate the HTML manual.
-html: $(docdir)/manual/index.html
+.PHONY: manual-html
+manual-html: $(docdir)/manual/index.html
+
+# Open the built HTML manual in the default browser.
+manual-html-open: $(docdir)/manual/index.html
+	@echo "  OPEN  " $<; \
+	  xdg-open $< \
+		  || open $< \
+			|| { \
+		echo "Could not open the manual in a browser. Please open '$<'" >&2; \
+		false; \
+		}
 install: $(docdir)/manual/index.html
 
 # Generate 'nix' manpages.
+.PHONY: manpages
+manpages: $(mandir)/man1/nix3-manpages
 install: $(mandir)/man1/nix3-manpages
 man: doc/manual/generated/man1/nix3-manpages
 all: doc/manual/generated/man1/nix3-manpages
 
+# FIXME: unify with how the other man pages are generated.
+# this one works differently and does not use any of the amenities provided by `/mk/lib.mk`.
 $(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages
 	@mkdir -p $(DESTDIR)$$(dirname $@)
 	$(trace-install) install -m 0644 $$(dirname $<)/* $(DESTDIR)$$(dirname $@)
 
-doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
+doc/manual/generated/man1/nix3-manpages: $(d)/source/command-ref/new-cli
 	@mkdir -p $(DESTDIR)$$(dirname $@)
-	$(trace-gen) for i in doc/manual/src/command-ref/new-cli/*.md; do \
-	  name=$$(basename $$i .md); \
-	  tmpFile=$$(mktemp); \
-	  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; \
-	  rm $$tmpFile; \
+	$(trace-gen) for i in doc/manual/source/command-ref/new-cli/*.md; do \
+		name=$$(basename $$i .md); \
+		tmpFile=$$(mktemp); \
+		if [[ $$name = SUMMARY ]]; then continue; fi; \
+		printf "Title: %s\n\n" "$$name" > $$tmpFile; \
+		cat $$i >> $$tmpFile; \
+		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
-
-endif
+# the `! -name 'documentation.md'` filter excludes the one place where
+# `@docroot@` is to be preserved for documenting the mechanism
+# FIXME: maybe contributing guides should live right next to the code
+# instead of in the manual
+$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/source/SUMMARY.md $(d)/source/store/types $(d)/source/command-ref/new-cli $(d)/source/development/experimental-feature-descriptions.md $(d)/source/command-ref/conf-file.md $(d)/source/language/builtins.md $(d)/source/release-notes/rl-next.md $(d)/source/figures $(d)/source/favicon.png $(d)/source/favicon.svg
+	$(trace-gen) \
+		tmp="$$(mktemp -d)"; \
+		cp -r doc/manual "$$tmp"; \
+		find "$$tmp" -name '*.md' | while read -r file; do \
+			$(call process-includes,$$file,$$file); \
+		done; \
+		find "$$tmp" -name '*.md' ! -name 'documentation.md' | while read -r file; do \
+			docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/source)"; \
+			sed -i "s,@docroot@,$$docroot,g" "$$file"; \
+		done; \
+		set -euo pipefail; \
+		( \
+		    cd "$$tmp/manual"; \
+		    RUST_LOG=warn \
+		        MDBOOK_SUBSTITUTE_SEARCH=$(d)/source \
+		        mdbook build -d $(DESTDIR)$(docdir)/manual.tmp 2>&1 \
+			    | { grep -Fv "because fragment resolution isn't implemented" || :; } \
+		); \
+		rm -rf "$$tmp/manual"
+	@rm -rf $(DESTDIR)$(docdir)/manual
+	@mv $(DESTDIR)$(docdir)/manual.tmp/html $(DESTDIR)$(docdir)/manual
+	@rm -rf $(DESTDIR)$(docdir)/manual.tmp

doc/manual/meson.build

@@ -0,0 +1,353 @@
+project('nix-manual',
+  version : files('.version'),
+  meson_version : '>= 1.1',
+  license : 'LGPL-2.1-or-later',
+)
+
+nix = find_program('nix', native : true)
+
+mdbook = find_program('mdbook', native : true)
+bash = find_program('bash', native : true)
+
+pymod = import('python')
+python = pymod.find_installation('python3')
+
+nix_env_for_docs = {
+  'HOME': '/dummy',
+  'NIX_CONF_DIR': '/dummy',
+  'NIX_SSL_CERT_FILE': '/dummy/no-ca-bundle.crt',
+  'NIX_STATE_DIR': '/dummy',
+  'NIX_CONFIG': 'cores = 0',
+}
+
+nix_for_docs = [nix, '--experimental-features', 'nix-command']
+nix_eval_for_docs_common = nix_for_docs + [
+  'eval',
+  '-I', 'nix=' + meson.current_source_dir(),
+  '--store', 'dummy://',
+  '--impure',
+]
+nix_eval_for_docs = nix_eval_for_docs_common + '--raw'
+
+conf_file_json = custom_target(
+  command : nix_for_docs + ['config', 'show', '--json'],
+  capture : true,
+  output : 'conf-file.json',
+  env : nix_env_for_docs,
+)
+
+language_json = custom_target(
+  command: [nix, '__dump-language'],
+  output : 'language.json',
+  capture : true,
+  env : nix_env_for_docs,
+)
+
+nix3_cli_json = custom_target(
+  command : [nix, '__dump-cli'],
+  capture : true,
+  output : 'nix.json',
+  env : nix_env_for_docs,
+)
+
+generate_manual_deps = files(
+  'generate-deps.py',
+)
+
+# Generates types
+subdir('source/store')
+# Generates builtins.md and builtin-constants.md.
+subdir('source/language')
+# Generates new-cli pages, experimental-features-shortlist.md, and conf-file.md.
+subdir('source/command-ref')
+# Generates experimental-feature-descriptions.md.
+subdir('source/development')
+# Generates rl-next-generated.md.
+subdir('source/release-notes')
+subdir('source')
+
+# Hacky way to figure out if `nix` is an `ExternalProgram` or
+# `Exectuable`. Only the latter can occur in custom target input lists.
+if nix.full_path().startswith(meson.build_root())
+  nix_input = nix
+else
+  nix_input = []
+endif
+
+manual = custom_target(
+  'manual',
+  command : [
+    bash,
+    '-euo', 'pipefail',
+    '-c',
+    '''
+        @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
+        @0@ @INPUT1@ summary @2@ < @CURRENT_SOURCE_DIR@/source/SUMMARY.md.in > @2@/source/SUMMARY.md
+        rsync -r --include='*.md' @CURRENT_SOURCE_DIR@/ @2@/
+        (cd @2@; RUST_LOG=warn @1@ build -d @2@ 3>&2 2>&1 1>&3) | { grep -Fv "because fragment resolution isn't implemented" || :; } 3>&2 2>&1 1>&3
+        rm -rf @2@/manual
+        mv @2@/html @2@/manual
+        find @2@/manual -iname meson.build -delete
+    '''.format(
+      python.full_path(),
+      mdbook.full_path(),
+      meson.current_build_dir(),
+    ),
+  ],
+  input : [
+    generate_manual_deps,
+    'substitute.py',
+    'book.toml',
+    'anchors.jq',
+    'custom.css',
+    nix3_cli_files,
+    experimental_features_shortlist_md,
+    experimental_feature_descriptions_md,
+    types_dir,
+    conf_file_md,
+    builtins_md,
+    rl_next_generated,
+    summary_rl_next,
+    nix_input,
+  ],
+  output : [
+    'manual',
+    'markdown',
+  ],
+  depfile : 'manual.d',
+  env : {
+    'RUST_LOG': 'info',
+    'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'source',
+  },
+)
+manual_html = manual[0]
+manual_md = manual[1]
+
+install_subdir(
+  manual_html.full_path(),
+  install_dir : get_option('datadir') / 'doc/nix',
+)
+
+nix_nested_manpages = [
+  [ 'nix-env',
+    [
+      'delete-generations',
+      'install',
+      'list-generations',
+      'query',
+      'rollback',
+      'set-flag',
+      'set',
+      'switch-generation',
+      'switch-profile',
+      'uninstall',
+      'upgrade',
+    ],
+  ],
+  [ 'nix-store',
+    [
+      'add-fixed',
+      'add',
+      'delete',
+      'dump-db',
+      'dump',
+      'export',
+      'gc',
+      'generate-binary-cache-key',
+      'import',
+      'load-db',
+      'optimise',
+      'print-env',
+      'query',
+      'read-log',
+      'realise',
+      'repair-path',
+      'restore',
+      'serve',
+      'verify',
+      'verify-path',
+    ],
+  ],
+]
+
+foreach command : nix_nested_manpages
+  foreach page : command[1]
+    title = command[0] + ' --' + page
+    section = '1'
+    custom_target(
+      command : [
+        bash,
+        files('./render-manpage.sh'),
+        '--out-no-smarty',
+        title,
+        section,
+        '@INPUT0@/command-ref' / command[0] / (page + '.md'),
+        '@OUTPUT0@',
+      ],
+      input : [
+        manual_md,
+        nix_input,
+      ],
+      output : command[0] + '-' + page + '.1',
+      install : true,
+      install_dir : get_option('mandir') / 'man1',
+    )
+  endforeach
+endforeach
+
+nix3_manpages = [
+  'nix3-build',
+  'nix3-bundle',
+  'nix3-config',
+  'nix3-config-show',
+  'nix3-copy',
+  'nix3-daemon',
+  'nix3-derivation-add',
+  'nix3-derivation',
+  'nix3-derivation-show',
+  'nix3-develop',
+  #'nix3-doctor',
+  'nix3-edit',
+  'nix3-eval',
+  'nix3-flake-archive',
+  'nix3-flake-check',
+  'nix3-flake-clone',
+  'nix3-flake-info',
+  'nix3-flake-init',
+  'nix3-flake-lock',
+  'nix3-flake',
+  'nix3-flake-metadata',
+  'nix3-flake-new',
+  'nix3-flake-prefetch',
+  'nix3-flake-show',
+  'nix3-flake-update',
+  'nix3-fmt',
+  'nix3-hash-file',
+  'nix3-hash',
+  'nix3-hash-path',
+  'nix3-hash-to-base16',
+  'nix3-hash-to-base32',
+  'nix3-hash-to-base64',
+  'nix3-hash-to-sri',
+  'nix3-help',
+  'nix3-help-stores',
+  'nix3-key-convert-secret-to-public',
+  'nix3-key-generate-secret',
+  'nix3-key',
+  'nix3-log',
+  'nix3-nar-cat',
+  'nix3-nar-dump-path',
+  'nix3-nar-ls',
+  'nix3-nar',
+  'nix3-path-info',
+  'nix3-print-dev-env',
+  'nix3-profile-diff-closures',
+  'nix3-profile-history',
+  'nix3-profile-install',
+  'nix3-profile-list',
+  'nix3-profile',
+  'nix3-profile-remove',
+  'nix3-profile-rollback',
+  'nix3-profile-upgrade',
+  'nix3-profile-wipe-history',
+  'nix3-realisation-info',
+  'nix3-realisation',
+  'nix3-registry-add',
+  'nix3-registry-list',
+  'nix3-registry',
+  'nix3-registry-pin',
+  'nix3-registry-remove',
+  'nix3-repl',
+  'nix3-run',
+  'nix3-search',
+  #'nix3-shell',
+  'nix3-store-add-file',
+  'nix3-store-add-path',
+  'nix3-store-cat',
+  'nix3-store-copy-log',
+  'nix3-store-copy-sigs',
+  'nix3-store-delete',
+  'nix3-store-diff-closures',
+  'nix3-store-dump-path',
+  'nix3-store-gc',
+  'nix3-store-ls',
+  'nix3-store-make-content-addressed',
+  'nix3-store',
+  'nix3-store-optimise',
+  'nix3-store-path-from-hash-part',
+  'nix3-store-ping',
+  'nix3-store-prefetch-file',
+  'nix3-store-repair',
+  'nix3-store-sign',
+  'nix3-store-verify',
+  'nix3-upgrade-nix',
+  'nix3-why-depends',
+  'nix',
+]
+
+foreach page : nix3_manpages
+  section = '1'
+  custom_target(
+    command : [
+      bash,
+      '@INPUT0@',
+      page,
+      section,
+      '@INPUT1@/command-ref/new-cli/@0@.md'.format(page),
+      '@OUTPUT@',
+    ],
+    input : [
+      files('./render-manpage.sh'),
+      manual_md,
+      nix_input,
+    ],
+    output : page + '.1',
+    install : true,
+    install_dir : get_option('mandir') / 'man1',
+  )
+endforeach
+
+nix_manpages = [
+  [ 'nix-env', 1 ],
+  [ 'nix-store', 1 ],
+  [ 'nix-build', 1 ],
+  [ 'nix-shell', 1 ],
+  [ 'nix-instantiate', 1 ],
+  [ 'nix-collect-garbage', 1 ],
+  [ 'nix-prefetch-url', 1 ],
+  [ 'nix-channel', 1 ],
+  [ 'nix-hash', 1 ],
+  [ 'nix-copy-closure', 1 ],
+  [ 'nix.conf', 5, conf_file_md.full_path() ],
+  [ 'nix-daemon', 8 ],
+  [ 'nix-profiles', 5, 'files/profiles.md' ],
+]
+
+foreach entry : nix_manpages
+  title = entry[0]
+  # nix.conf.5 and nix-profiles.5 are based off of conf-file.md and files/profiles.md,
+  # rather than a stem identical to its mdbook source.
+  # Therefore we use an optional third element of this array to override the name pattern
+  md_file = entry.get(2, title + '.md')
+  section = entry[1].to_string()
+  md_file_resolved = join_paths('@INPUT1@/command-ref/', md_file)
+  custom_target(
+    command : [
+      bash,
+      '@INPUT0@',
+      title,
+      section,
+      md_file_resolved,
+      '@OUTPUT@',
+    ],
+    input : [
+      files('./render-manpage.sh'),
+      manual_md,
+      entry.get(3, []),
+      nix_input,
+    ],
+    output : '@0@.@1@'.format(entry[0], entry[1]),
+    install : true,
+    install_dir : get_option('mandir') / 'man@0@'.format(entry[1]),
+  )
+endforeach

doc/manual/package.nix

@@ -0,0 +1,71 @@
+{ lib
+, mkMesonDerivation
+
+, meson
+, ninja
+, lowdown
+, mdbook
+, mdbook-linkcheck
+, jq
+, python3
+, rsync
+, nix-cli
+
+# Configuration Options
+
+, version
+}:
+
+let
+  inherit (lib) fileset;
+in
+
+mkMesonDerivation (finalAttrs: {
+  pname = "nix-manual";
+  inherit version;
+
+  workDir = ./.;
+  fileset = fileset.difference
+    (fileset.unions [
+      ../../.version
+      # Too many different types of files to filter for now
+      ../../doc/manual
+      ./.
+    ])
+    # Do a blacklist instead
+    ../../doc/manual/package.nix;
+
+  # TODO the man pages should probably be separate
+  outputs = [ "out" "man" ];
+
+  # Hack for sake of the dev shell
+  passthru.externalNativeBuildInputs = [
+    meson
+    ninja
+    (lib.getBin lowdown)
+    mdbook
+    mdbook-linkcheck
+    jq
+    python3
+    rsync
+  ];
+
+  nativeBuildInputs = finalAttrs.passthru.externalNativeBuildInputs ++ [
+    nix-cli
+  ];
+
+  preConfigure =
+    ''
+      chmod u+w ./.version
+      echo ${finalAttrs.version} > ./.version
+    '';
+
+  postInstall = ''
+    mkdir -p ''$out/nix-support
+    echo "doc manual ''$out/share/doc/nix/manual" >> ''$out/nix-support/hydra-build-products
+  '';
+
+  meta = {
+    platforms = lib.platforms.all;
+  };
+})

doc/manual/redirects.js

@@ -1,330 +1,455 @@
-// 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 URL fragments (client-side) to prevent link rot.
+// this must be done on the client side, as web servers do not see the fragment part of the URL.
+// it will only work with JavaScript enabled in the browser, but this is the best we can do here.
+// see source/_redirects for path redirects (server-side)
+
+// redirects 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/index.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": "command-ref/conf-file.html#conf-builders",
+    "chap-post-build-hook": "advanced-topics/post-build-hook.html",
+    "chap-post-build-hook-caveats": "advanced-topics/post-build-hook.html#implementation-caveats",
+    "chap-writing-nix-expressions": "language/index.html",
+    "part-command-ref": "command-ref/index.html",
+    "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": "development/building.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/syntax.html",
+    "sect-let-language": "language/syntax.html#let-expressions",
+    "ss-functions": "language/syntax.html#functions",
+    "sec-language-operators": "language/operators.html",
+    "table-operators": "language/operators.html",
+    "ssec-values": "language/types.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/index.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": "command-ref/nix-channel.html",
+    "ssec-copy-closure": "command-ref/nix-copy-closure.html",
+    "sec-garbage-collection": "package-management/garbage-collection.html",
+    "ssec-gc-roots": "package-management/garbage-collector-roots.html",
+    "chap-package-management": "package-management/index.html",
+    "sec-profiles": "package-management/profiles.html",
+    "ssec-s3-substituter": "store/types/s3-substituter.html",
+    "ssec-s3-substituter-anonymous-reads": "store/types/s3-substituter.html#anonymous-reads-to-your-s3-compatible-binary-cache",
+    "ssec-s3-substituter-authenticated-reads": "store/types/s3-substituter.html#authenticated-reads-to-your-s3-binary-cache",
+    "ssec-s3-substituter-authenticated-writes": "store/types/s3-substituter.html#authenticated-writes-to-your-s3-compatible-binary-cache",
+    "sec-sharing-packages": "package-management/sharing-packages.html",
+    "ssec-ssh-substituter": "package-management/ssh-substituter.html",
+    "chap-quick-start": "quick-start.html",
+    "sec-relnotes": "release-notes/index.html",
+    "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/types.html": {
+    "simple-values": "#primitives",
+    "lists": "#list",
+    "strings": "#string",
+    "attribute-sets": "#attribute-set",
+    "type-number": "#type-int",
+  },
+  "language/syntax.html": {
+    "scoping-rules": "scoping.html",
+    "string-literal": "string-literals.html",
+  },
+  "installation/installing-binary.html": {
+    "linux": "uninstall.html#linux",
+    "macos": "uninstall.html#macos",
+    "uninstalling": "uninstall.html",
+  },
+  "development/building.html": {
+    "nix-with-flakes": "#building-nix-with-flakes",
+    "classic-nix": "#building-nix",
+    "running-tests": "testing.html#running-tests",
+    "unit-tests": "testing.html#unit-tests",
+    "functional-tests": "testing.html#functional-tests",
+    "debugging-failing-functional-tests": "testing.html#debugging-failing-functional-tests",
+    "integration-tests": "testing.html#integration-tests",
+    "installer-tests": "testing.html#installer-tests",
+    "one-time-setup": "testing.html#one-time-setup",
+    "using-the-ci-generated-installer-for-manual-testing": "testing.html#using-the-ci-generated-installer-for-manual-testing",
+    "characterization-testing": "testing.html#characterisation-testing-unit",
+    "add-a-release-note": "contributing.html#add-a-release-note",
+    "add-an-entry": "contributing.html#add-an-entry",
+    "build-process": "contributing.html#build-process",
+    "reverting": "contributing.html#reverting",
+    "branches": "contributing.html#branches",
+  },
+  "glossary.html": {
+    "gloss-local-store": "store/types/local-store.html",
+    "gloss-chroot-store": "store/types/local-store.html",
+  },
 };
 
-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/remove_before_wrapper.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+
+import os
+import subprocess
+import sys
+import shutil
+import typing as t
+
+def main():
+    if len(sys.argv) < 4 or '--' not in sys.argv:
+        print("Usage: remove-before-wrapper <output> -- <nix command...>")
+        sys.exit(1)
+
+    # Extract the parts
+    output: str = sys.argv[1]
+    nix_command_idx: int = sys.argv.index('--') + 1
+    nix_command: t.List[str] = sys.argv[nix_command_idx:]
+
+    output_temp: str = output + '.tmp'
+
+    # Remove the output and temp output in case they exist
+    shutil.rmtree(output, ignore_errors=True)
+    shutil.rmtree(output_temp, ignore_errors=True)
+
+    # Execute nix command with `--write-to` tempary output
+    nix_command_write_to = nix_command + ['--write-to', output_temp]
+    subprocess.run(nix_command_write_to, check=True)
+
+    # Move the temporary output to the intended location
+    os.rename(output_temp, output)
+
+if __name__ == "__main__":
+    main()

doc/manual/render-manpage.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+lowdown_args=
+
+if [ "$1" = --out-no-smarty ]; then
+    lowdown_args=--out-no-smarty
+    shift
+fi
+
+[ "$#" = 4 ] || {
+    echo "wrong number of args passed" >&2
+    exit 1
+}
+
+title="$1"
+section="$2"
+infile="$3"
+outfile="$4"
+
+(
+    printf "Title: %s\n\n" "$title"
+    cat "$infile"
+) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile"

doc/manual/rl-next/add-nix-state-home.md

@@ -0,0 +1,14 @@
+---
+synopsis: Use envvars NIX_CACHE_HOME, NIX_CONFIG_HOME, NIX_DATA_HOME, NIX_STATE_HOME if defined
+prs: [11351]
+---
+
+Added new environment variables:
+
+- `NIX_CACHE_HOME`
+- `NIX_CONFIG_HOME`
+- `NIX_DATA_HOME`
+- `NIX_STATE_HOME`
+
+Each, if defined, takes precedence over the corresponding [XDG environment variable](@docroot@/command-ref/env-common.md#xdg-base-directories).
+This provides more fine-grained control over where Nix looks for files, and allows to have a stand-alone Nix environment, which only uses files in a specific directory, and doesn't interfere with the user environment.

doc/manual/rl-next/ban-integer-overflow.md

@@ -0,0 +1,21 @@
+---
+synopsis: Define integer overflow in the Nix language as an error
+issues: [10968]
+prs: [11188]
+---
+
+Previously, integer overflow in the Nix language invoked C++ level signed overflow, which was undefined behaviour, but *usually* manifested as wrapping around on overflow.
+
+Since prior to the public release of Lix, Lix had C++ signed overflow defined to crash the process and nobody noticed this having accidentally removed overflow from the Nix language for three months until it was caught by fiddling around.
+Given the significant body of actual Nix code that has been evaluated by Lix in that time, it does not appear that nixpkgs or much of importance depends on integer overflow, so it appears safe to turn into an error.
+
+Some other overflows were fixed:
+- `builtins.fromJSON` of values greater than the maximum representable value in a signed 64-bit integer will generate an error.
+- `nixConfig` in flakes will no longer accept negative values for configuration options.
+
+Integer overflow now looks like the following:
+
+```
+$ nix eval --expr '9223372036854775807 + 1'
+error: integer overflow in adding 9223372036854775807 + 1
+```

doc/manual/rl-next/build-hook-default.md

@@ -0,0 +1,22 @@
+---
+synopsis: |-
+  The `build-hook` setting's default is less useful when using `libnixstore` as a library
+prs:
+- 11178
+---
+
+*This is an obscure issue that only affects usage of the `libnixstore` library outside of the Nix executable.*
+
+As part the ongoing [rewrite of the build system](https://github.com/NixOS/nix/issues/2503) to use [Meson](https://mesonbuild.com/), we are also switching to packaging individual Nix components separately (and building them in separate derivations).
+This means that when building `libnixstore` we do not know where the Nix binaries will be installed --- `libnixstore` doesn't know about downstream consumers like the Nix binaries at all.
+
+*This is also unrelated to the _`post`_-`build-hook`*, which is often used for pushing to a cache.*
+
+This has a small adverse affect on remote building --- the `build-remote` executable that is specified from the [`build-hook`](@docroot@/command-ref/conf-file.md#conf-build-hook) setting will not be gotten from the (presumed) installation location, but instead looked up on the `PATH`.
+This means that other applications linking `libnixstore` that wish to use remote building must arrange for the `nix` command to be on the PATH (or manually overriding `build-hook`) in order for that to work.
+
+Long term we don't envision this being a downside, because we plan to [get rid of `build-remote` and the build hook setting entirely](https://github.com/NixOS/nix/issues/1221).
+There should simply be no need to have an extra, intermediate layer of remote-procedure-calling when we want to connect to a remote builder.
+The build hook protocol did in principle support custom ways of remote building, but that can also be accomplished with a custom service for the ssh or daemon/ssh-ng protocols, or with a custom [store type](@docroot@/store/types/index.md) i.e. `Store` subclass. <!-- we normally don't mention classes, but consider that this release note is about a library use case -->
+
+The Perl bindings no longer expose `getBinDir` either, since the underlying C++ libraries those bindings wrap no longer know the location of installed binaries as described above.

doc/manual/rl-next/config

@@ -0,0 +1,2 @@
+organization: NixOS
+repository: nix

doc/manual/rl-next/filesystem-errors.md

@@ -0,0 +1,14 @@
+---
+synopsis: wrap filesystem exceptions more correctly
+issues: []
+prs: [11378]
+---
+
+
+With the switch to `std::filesystem` in different places, Nix started to throw `std::filesystem::filesystem_error` in many places instead of its own exceptions.
+
+This lead to no longer generating error traces, for example when listing a non-existing directory, and can also lead to crashes inside the Nix REPL.
+
+This version catches these types of exception correctly and wrap them into Nix's own exeception type.
+
+Author: [**@Mic92**](https://github.com/Mic92)

doc/manual/rl-next/fsync-store-paths.md

@@ -0,0 +1,9 @@
+---
+synopsis: Add setting `fsync-store-paths`
+issues: [1218]
+prs: [7126]
+---
+
+Nix now has a setting `fsync-store-paths` that ensures that new store paths are durably written to disk before they are registered as "valid" in Nix's database. This can prevent Nix store corruption if the system crashes or there is a power loss. This setting defaults to `false`.
+
+Author: [**@squalus**](https://github.com/squalus)

doc/manual/rl-next/nix-flake-show-description.md

@@ -0,0 +1,25 @@
+---
+synopsis: Show package descriptions with `nix flake show`
+issues: [10977]
+prs: [10980]
+---
+
+`nix flake show` will now display a package's `meta.description` if it exists. If the description does not fit in the terminal it will be truncated to fit the terminal width. If the size of the terminal width is unknown the description will be capped at 80 characters.
+
+```
+$ nix flake show
+└───packages
+    └───x86_64-linux
+        ├───builderImage: package 'docker-image-ara-builder-image.tar.gz' - 'Docker image hosting the nix build environment'
+        └───runnerImage: package 'docker-image-gitlab-runner.tar.gz' - 'Docker image hosting the gitlab-runner executable'
+```
+
+In a narrower terminal:
+
+```
+$ nix flake show
+└───packages
+    └───x86_64-linux
+        ├───builderImage: package 'docker-image-ara-builder-image.tar.gz' - 'Docker image hosting the nix b...
+        └───runnerImage: package 'docker-image-gitlab-runner.tar.gz' - 'Docker image hosting the gitlab-run...
+```

doc/manual/rl-next/nix-fmt-default-argument.md

@@ -0,0 +1,17 @@
+---
+synopsis: Removing the default argument passed to the `nix fmt` formatter
+issues: []
+prs: [11438]
+---
+
+The underlying formatter no longer receives the ". " default argument when `nix fmt` is called with no arguments.
+
+This change was necessary as the formatter wasn't able to distinguish between
+a user wanting to format the current folder with `nix fmt .` or the generic
+`nix fmt`.
+
+The default behaviour is now the responsibility of the formatter itself, and
+allows tools such as treefmt to format the whole tree instead of only the
+current directory and below.
+
+Author: [**@zimbatm**](https://github.com/zimbatm)

doc/manual/rl-next/no-flake-substitution.md

@@ -0,0 +1,8 @@
+---
+synopsis: Flakes are no longer substituted
+prs: [10612]
+---
+
+Nix will no longer attempt to substitute the source code of flakes from a binary cache. This functionality was broken because it could lead to different evaluation results depending on whether the flake was available in the binary cache, or even depending on whether the flake was already in the local store.
+
+Author: [**@edolstra**](https://github.com/edolstra)

doc/manual/rl-next/verify-tls.md

@@ -0,0 +1,8 @@
+---
+synopsis: "`<nix/fetchurl.nix>` uses TLS verification"
+prs: [11585]
+---
+
+Previously `<nix/fetchurl.nix>` did not do TLS verification. This was because the Nix sandbox in the past did not have access to TLS certificates, and Nix checks the hash of the fetched file anyway. However, this can expose authentication data from `netrc` and URLs to man-in-the-middle attackers. In addition, Nix now in some cases (such as when using impure derivations) does *not* check the hash. Therefore we have now enabled TLS verification. This means that downloads by `<nix/fetchurl.nix>` will now fail if you're fetching from a HTTPS server that does not have a valid certificate.
+
+`<nix/fetchurl.nix>` is also known as the builtin derivation builder `builtin:fetchurl`. It's not to be confused with the evaluation-time function `builtins.fetchurl`, which was not affected by this issue.

doc/manual/source/SUMMARY.md.in

@@ -0,0 +1,188 @@
+# Table of Contents
+
+- [Introduction](introduction.md)
+- [Quick Start](quick-start.md)
+- [Installation](installation/index.md)
+  - [Supported Platforms](installation/supported-platforms.md)
+  - [Installing a Binary Distribution](installation/installing-binary.md)
+  - [Installing Nix from Source](installation/installing-source.md)
+    - [Prerequisites](installation/prerequisites-source.md)
+    - [Obtaining a Source Distribution](installation/obtaining-source.md)
+    - [Building Nix from Source](installation/building-source.md)
+  - [Using Nix within Docker](installation/installing-docker.md)
+  - [Security](installation/nix-security.md)
+    - [Single-User Mode](installation/single-user.md)
+    - [Multi-User Mode](installation/multi-user.md)
+  - [Environment Variables](installation/env-variables.md)
+  - [Upgrading Nix](installation/upgrading.md)
+  - [Uninstalling Nix](installation/uninstall.md)
+- [Nix Store](store/index.md)
+  - [File System Object](store/file-system-object.md)
+    - [Content-Addressing File System Objects](store/file-system-object/content-address.md)
+  - [Store Object](store/store-object.md)
+    - [Content-Addressing Store Objects](store/store-object/content-address.md)
+  - [Store Path](store/store-path.md)
+  - [Store Types](store/types/index.md)
+{{#include ./store/types/SUMMARY.md}}
+- [Nix Language](language/index.md)
+  - [Data Types](language/types.md)
+    - [String context](language/string-context.md)
+  - [Syntax and semantics](language/syntax.md)
+    - [Variables](language/variables.md)
+    - [String literals](language/string-literals.md)
+    - [Identifiers](language/identifiers.md)
+    - [Scoping rules](language/scope.md)
+    - [String interpolation](language/string-interpolation.md)
+    - [Lookup path](language/constructs/lookup-path.md)
+  - [Operators](language/operators.md)
+  - [Built-ins](language/builtins.md)
+    - [Derivations](language/derivations.md)
+      - [Advanced Attributes](language/advanced-attributes.md)
+      - [Import From Derivation](language/import-from-derivation.md)
+- [Package Management](package-management/index.md)
+  - [Profiles](package-management/profiles.md)
+  - [Garbage Collection](package-management/garbage-collection.md)
+    - [Garbage Collector Roots](package-management/garbage-collector-roots.md)
+- [Advanced Topics](advanced-topics/index.md)
+  - [Sharing Packages Between Machines](package-management/sharing-packages.md)
+    - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md)
+    - [Serving a Nix store via SSH](package-management/ssh-substituter.md)
+  - [Remote Builds](advanced-topics/distributed-builds.md)
+  - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)
+  - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
+  - [Using the `post-build-hook`](advanced-topics/post-build-hook.md)
+- [Command Reference](command-ref/index.md)
+  - [Common Options](command-ref/opt-common.md)
+  - [Common Environment Variables](command-ref/env-common.md)
+  - [Main Commands](command-ref/main-commands.md)
+    - [nix-build](command-ref/nix-build.md)
+    - [nix-shell](command-ref/nix-shell.md)
+    - [nix-store](command-ref/nix-store.md)
+      - [nix-store --add-fixed](command-ref/nix-store/add-fixed.md)
+      - [nix-store --add](command-ref/nix-store/add.md)
+      - [nix-store --delete](command-ref/nix-store/delete.md)
+      - [nix-store --dump-db](command-ref/nix-store/dump-db.md)
+      - [nix-store --dump](command-ref/nix-store/dump.md)
+      - [nix-store --export](command-ref/nix-store/export.md)
+      - [nix-store --gc](command-ref/nix-store/gc.md)
+      - [nix-store --generate-binary-cache-key](command-ref/nix-store/generate-binary-cache-key.md)
+      - [nix-store --import](command-ref/nix-store/import.md)
+      - [nix-store --load-db](command-ref/nix-store/load-db.md)
+      - [nix-store --optimise](command-ref/nix-store/optimise.md)
+      - [nix-store --print-env](command-ref/nix-store/print-env.md)
+      - [nix-store --query](command-ref/nix-store/query.md)
+      - [nix-store --read-log](command-ref/nix-store/read-log.md)
+      - [nix-store --realise](command-ref/nix-store/realise.md)
+      - [nix-store --repair-path](command-ref/nix-store/repair-path.md)
+      - [nix-store --restore](command-ref/nix-store/restore.md)
+      - [nix-store --serve](command-ref/nix-store/serve.md)
+      - [nix-store --verify-path](command-ref/nix-store/verify-path.md)
+      - [nix-store --verify](command-ref/nix-store/verify.md)
+    - [nix-env](command-ref/nix-env.md)
+      - [nix-env --delete-generations](command-ref/nix-env/delete-generations.md)
+      - [nix-env --install](command-ref/nix-env/install.md)
+      - [nix-env --list-generations](command-ref/nix-env/list-generations.md)
+      - [nix-env --query](command-ref/nix-env/query.md)
+      - [nix-env --rollback](command-ref/nix-env/rollback.md)
+      - [nix-env --set-flag](command-ref/nix-env/set-flag.md)
+      - [nix-env --set](command-ref/nix-env/set.md)
+      - [nix-env --switch-generation](command-ref/nix-env/switch-generation.md)
+      - [nix-env --switch-profile](command-ref/nix-env/switch-profile.md)
+      - [nix-env --uninstall](command-ref/nix-env/uninstall.md)
+      - [nix-env --upgrade](command-ref/nix-env/upgrade.md)
+  - [Utilities](command-ref/utilities.md)
+    - [nix-channel](command-ref/nix-channel.md)
+    - [nix-collect-garbage](command-ref/nix-collect-garbage.md)
+    - [nix-copy-closure](command-ref/nix-copy-closure.md)
+    - [nix-daemon](command-ref/nix-daemon.md)
+    - [nix-hash](command-ref/nix-hash.md)
+    - [nix-instantiate](command-ref/nix-instantiate.md)
+    - [nix-prefetch-url](command-ref/nix-prefetch-url.md)
+  - [Experimental Commands](command-ref/experimental-commands.md)
+{{#include ./command-ref/new-cli/SUMMARY.md}}
+  - [Files](command-ref/files.md)
+    - [nix.conf](command-ref/conf-file.md)
+    - [Profiles](command-ref/files/profiles.md)
+      - [manifest.nix](command-ref/files/manifest.nix.md)
+      - [manifest.json](command-ref/files/manifest.json.md)
+    - [Channels](command-ref/files/channels.md)
+    - [Default Nix expression](command-ref/files/default-nix-expression.md)
+- [Architecture and Design](architecture/architecture.md)
+- [Formats and Protocols](protocols/index.md)
+  - [JSON Formats](protocols/json/index.md)
+    - [Store Object Info](protocols/json/store-object-info.md)
+    - [Derivation](protocols/json/derivation.md)
+  - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
+  - [Store Path Specification](protocols/store-path.md)
+  - [Nix Archive (NAR) Format](protocols/nix-archive.md)
+  - [Derivation "ATerm" file format](protocols/derivation-aterm.md)
+- [C API](c-api.md)
+- [Glossary](glossary.md)
+- [Development](development/index.md)
+  - [Building](development/building.md)
+  - [Testing](development/testing.md)
+  - [Debugging](development/debugging.md)
+  - [Documentation](development/documentation.md)
+  - [CLI guideline](development/cli-guideline.md)
+  - [JSON guideline](development/json-guideline.md)
+  - [C++ style guide](development/cxx.md)
+  - [Experimental Features](development/experimental-features.md)
+  - [Contributing](development/contributing.md)
+- [Releases](release-notes/index.md)
+{{#include ./SUMMARY-rl-next.md}}
+  - [Release 2.24 (2024-07-31)](release-notes/rl-2.24.md)
+  - [Release 2.23 (2024-06-03)](release-notes/rl-2.23.md)
+  - [Release 2.22 (2024-04-23)](release-notes/rl-2.22.md)
+  - [Release 2.21 (2024-03-11)](release-notes/rl-2.21.md)
+  - [Release 2.20 (2024-01-29)](release-notes/rl-2.20.md)
+  - [Release 2.19 (2023-11-17)](release-notes/rl-2.19.md)
+  - [Release 2.18 (2023-09-20)](release-notes/rl-2.18.md)
+  - [Release 2.17 (2023-07-24)](release-notes/rl-2.17.md)
+  - [Release 2.16 (2023-05-31)](release-notes/rl-2.16.md)
+  - [Release 2.15 (2023-04-11)](release-notes/rl-2.15.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)
+  - [Release 2.8 (2022-04-19)](release-notes/rl-2.8.md)
+  - [Release 2.7 (2022-03-07)](release-notes/rl-2.7.md)
+  - [Release 2.6 (2022-01-24)](release-notes/rl-2.6.md)
+  - [Release 2.5 (2021-12-13)](release-notes/rl-2.5.md)
+  - [Release 2.4 (2021-11-01)](release-notes/rl-2.4.md)
+  - [Release 2.3 (2019-09-04)](release-notes/rl-2.3.md)
+  - [Release 2.2 (2019-01-11)](release-notes/rl-2.2.md)
+  - [Release 2.1 (2018-09-02)](release-notes/rl-2.1.md)
+  - [Release 2.0 (2018-02-22)](release-notes/rl-2.0.md)
+  - [Release 1.11.10 (2017-06-12)](release-notes/rl-1.11.10.md)
+  - [Release 1.11 (2016-01-19)](release-notes/rl-1.11.md)
+  - [Release 1.10 (2015-09-03)](release-notes/rl-1.10.md)
+  - [Release 1.9 (2015-06-12)](release-notes/rl-1.9.md)
+  - [Release 1.8 (2014-12-14)](release-notes/rl-1.8.md)
+  - [Release 1.7 (2014-04-11)](release-notes/rl-1.7.md)
+  - [Release 1.6.1 (2013-10-28)](release-notes/rl-1.6.1.md)
+  - [Release 1.6 (2013-09-10)](release-notes/rl-1.6.md)
+  - [Release 1.5.2 (2013-05-13)](release-notes/rl-1.5.2.md)
+  - [Release 1.5 (2013-02-27)](release-notes/rl-1.5.md)
+  - [Release 1.4 (2013-02-26)](release-notes/rl-1.4.md)
+  - [Release 1.3 (2013-01-04)](release-notes/rl-1.3.md)
+  - [Release 1.2 (2012-12-06)](release-notes/rl-1.2.md)
+  - [Release 1.1 (2012-07-18)](release-notes/rl-1.1.md)
+  - [Release 1.0 (2012-05-11)](release-notes/rl-1.0.md)
+  - [Release 0.16 (2010-08-17)](release-notes/rl-0.16.md)
+  - [Release 0.15 (2010-03-17)](release-notes/rl-0.15.md)
+  - [Release 0.14 (2010-02-04)](release-notes/rl-0.14.md)
+  - [Release 0.13 (2009-11-05)](release-notes/rl-0.13.md)
+  - [Release 0.12 (2008-11-20)](release-notes/rl-0.12.md)
+  - [Release 0.11 (2007-12-31)](release-notes/rl-0.11.md)
+  - [Release 0.10.1 (2006-10-11)](release-notes/rl-0.10.1.md)
+  - [Release 0.10 (2006-10-06)](release-notes/rl-0.10.md)
+  - [Release 0.9.2 (2005-09-21)](release-notes/rl-0.9.2.md)
+  - [Release 0.9.1 (2005-09-20)](release-notes/rl-0.9.1.md)
+  - [Release 0.9 (2005-09-16)](release-notes/rl-0.9.md)
+  - [Release 0.8.1 (2005-04-13)](release-notes/rl-0.8.1.md)
+  - [Release 0.8 (2005-04-11)](release-notes/rl-0.8.md)
+  - [Release 0.7 (2005-01-12)](release-notes/rl-0.7.md)
+  - [Release 0.6 (2004-11-14)](release-notes/rl-0.6.md)
+  - [Release 0.5 and earlier](release-notes/rl-0.5.md)

doc/manual/source/_redirects

@@ -0,0 +1,54 @@
+# redirect rules for paths (server-side) to prevent link rot.
+# see ../redirects.js for redirects based on URL fragments (client-side)
+#
+# concrete user story this supports:
+# - user finds URL to the manual for Nix x.y
+# - Nix x.z (z > y) is the most recent release
+# - updating the version in the URL will show the right thing
+#
+# format documentation:
+# - https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file
+# - https://docs.netlify.com/routing/redirects/redirect-options/
+#
+# conventions:
+# - always force (<CODE>!) since this allows re-using file names
+# - group related paths to ease readability
+# - keep in alphabetical/wildcards-last order, which will reduce version control conflicts
+# - redirects that should have been there but are missing can be inserted where they belong
+
+/advanced-topics/advanced-topics /advanced-topics 301!
+
+/command-ref/command-ref /command-ref 301!
+
+/contributing/contributing /development 301!
+/contributing /development 301!
+/contributing/hacking /development/building 301!
+/contributing/testing /development/testing 301!
+/contributing/documentation /development/documentation 301!
+/contributing/experimental-features /development/experimental-features 301!
+/contributing/cli-guideline /development/cli-guideline 301!
+/contributing/json-guideline /development/json-guideline 301!
+/contributing/cxx /development/cxx 301!
+
+/expressions/expression-language /language/ 301!
+/expressions/language-constructs /language/constructs 301!
+/expressions/language-operators /language/operators 301!
+/expressions/language-values /language/values 301!
+/expressions/* /language/:splat 301!
+/language/values /language/types 301!
+/language/constructs /language/syntax 301!
+/language/builtin-constants /language/builtins 301!
+
+/installation/installation /installation 301!
+
+/package-management/basic-package-mgmt /command-ref/nix-env 301!
+/package-management/channels /command-ref/nix-channel 301!
+/package-management/package-management /package-management 301!
+/package-management/s3-substituter /store/types/s3-binary-cache-store 301!
+
+/protocols/protocols /protocols 301!
+/json/* /protocols/json/:splat 301!
+
+/release-notes/release-notes /release-notes 301!
+
+/package-management/copy-closure /command-ref/nix-copy-closure 301!

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

@@ -48,13 +48,13 @@ If the build passes and is deterministic, Nix will exit with a status
 code of 0:
 
 ```console
-$ nix-build ./deterministic.nix -A stable
+$ nix-build ./deterministic.nix --attr stable
 this derivation will be built:
   /nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv
 building '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'...
 /nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable
 
-$ nix-build ./deterministic.nix -A stable --check
+$ nix-build ./deterministic.nix --attr stable --check
 checking outputs of '/nix/store/z98fasz2jqy9gs0xbvdj939p27jwda38-stable.drv'...
 /nix/store/yyxlzw3vqaas7wfp04g0b1xg51f2czgq-stable
 ```
@@ -63,13 +63,13 @@ If the build is not deterministic, Nix will exit with a status code of
 1:
 
 ```console
-$ nix-build ./deterministic.nix -A unstable
+$ nix-build ./deterministic.nix --attr unstable
 this derivation will be built:
   /nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv
 building '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
 /nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable
 
-$ nix-build ./deterministic.nix -A unstable --check
+$ nix-build ./deterministic.nix --attr unstable --check
 checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
 error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may
 not be deterministic: output '/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable' differs
@@ -89,7 +89,7 @@ Using `--check` with `--keep-failed` will cause Nix to keep the second
 build's output in a special, `.check` path:
 
 ```console
-$ nix-build ./deterministic.nix -A unstable --check --keep-failed
+$ nix-build ./deterministic.nix --attr unstable --check --keep-failed
 checking outputs of '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv'...
 note: keeping build directory '/tmp/nix-build-unstable.drv-0'
 error: derivation '/nix/store/cgl13lbj1w368r5z8gywipl1ifli7dhk-unstable.drv' may
@@ -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/source/advanced-topics/distributed-builds.md

@@ -0,0 +1,108 @@
+# Remote Builds
+
+A local Nix installation can forward Nix builds to other machines,
+this allows multiple builds to be performed in parallel.
+
+Remote builds also allow Nix to perform multi-platform builds in a
+semi-transparent way. For example, if you perform a build for a
+`x86_64-darwin` on an `i686-linux` machine, Nix can automatically
+forward the build to a `x86_64-darwin` machine, if one is available.
+
+## Requirements
+
+For a local machine to forward a build to a remote machine, the remote machine must:
+
+- Have Nix installed
+- Be running an SSH server, e.g. `sshd`
+- Be accessible via SSH from the local machine over the network
+- Have the local machine's public SSH key in `/etc/ssh/authorized_keys.d/<username>`
+- Have the username of the SSH user in the `trusted-users` setting in `nix.conf`
+
+## Testing
+
+To test connecting to a remote Nix instance (in this case `mac`), run:
+
+```console
+nix store info --store ssh://username@mac
+```
+
+To specify an SSH identity file as part of the remote store URI add a
+query paramater, e.g.
+
+```console
+nix store info --store ssh://username@mac?ssh-key=/home/alice/my-key
+```
+
+Since builds should be non-interactive, the key should not have a
+passphrase. Alternatively, you can load identities ahead of time into
+`ssh-agent` or `gpg-agent`.
+
+In a multi-user installation (default), builds are executed by the Nix
+Daemon. The Nix Daemon cannot prompt for a passphrase via the terminal
+or `ssh-agent`, so the SSH key must not have a passphrase.
+
+In addition, the Nix Daemon's user (typically root) needs to have SSH
+access to the remote builder.
+
+Access can be verified by running `sudo su`, and then validating SSH
+access, e.g. by running `ssh mac`. SSH identity files for root users
+are usually stored in `/root/.ssh/` (Linux) or `/var/root/.ssh` (MacOS).
+
+If you get the error
+
+```console
+bash: nix: command not found
+error: cannot connect to 'mac'
+```
+
+then you need to ensure that the `PATH` of non-interactive login shells
+contains Nix.
+
+The [list of remote build machines](@docroot@/command-ref/conf-file.md#conf-builders) can be specified on the command line or in the Nix configuration file.
+For example, the following command allows you to build a derivation for `x86_64-darwin` on a Linux machine:
+
+```console
+uname
+```
+
+```console
+Linux
+```
+
+```console
+nix build --impure \
+ --expr '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \
+ --builders 'ssh://mac x86_64-darwin'
+```
+
+```console
+[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac
+```
+
+```console
+cat ./result
+```
+
+```console
+Darwin
+```
+
+It is possible to specify multiple build machines separated by a semicolon or a newline, e.g.
+
+```console
+  --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
+```
+
+Remote build machines can also be configured in [`nix.conf`](@docroot@/command-ref/conf-file.md), e.g.
+
+    builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
+
+After making changes to `nix.conf`, restart the Nix daemon for changes to take effect.
+
+Finally, remote build machines can be configured in a separate configuration
+file included in `builders` via the syntax `@/path/to/file`. For example,
+
+    builders = @/etc/nix/machines
+
+causes the list of machines in `/etc/nix/machines` to be included.
+(This is the default.)

doc/manual/source/advanced-topics/index.md

@@ -0,0 +1 @@
+This section lists advanced topics related to builds and builds performance

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

@@ -17,9 +17,8 @@ the build loop.
 
 # Prerequisites
 
-This tutorial assumes you have [configured an S3-compatible binary
-cache](../package-management/s3-substituter.md), and that the `root`
-user's default AWS profile can upload to the bucket.
+This tutorial assumes you have configured an [S3-compatible binary cache](@docroot@/command-ref/new-cli/nix3-help-stores.md#s3-binary-cache-store) as a [substituter](../command-ref/conf-file.md#conf-substituters),
+and that the `root` user's default AWS profile can upload to the bucket.
 
 # Set up a Signing Key
 
@@ -33,12 +32,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,20 +56,20 @@ 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
 > store sign`. Nix guarantees the paths will not contain any spaces,
 > however a store path might contain glob characters. The `set -f`
 > disables globbing in the shell.
+> If you want to upload the `.drv` file too, the `$DRV_PATH` variable
+> is also defined for the script and works just like `$OUT_PATHS`.
 
 Then make sure the hook program is executable by the `root` user:
 
@@ -87,7 +91,7 @@ Then, restart the `nix-daemon`.
 Build any derivation, for example:
 
 ```console
-$ nix-build -E '(import <nixpkgs> {}).writeText "example" (builtins.toString builtins.currentTime)'
+$ nix-build --expr '(import <nixpkgs> {}).writeText "example" (builtins.toString builtins.currentTime)'
 this derivation will be built:
   /nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv
 building '/nix/store/s4pnfbkalzy5qz57qs6yybna8wylkig6-example.drv'...

doc/manual/source/architecture/architecture.md

@@ -0,0 +1,116 @@
+# Architecture
+
+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].
+
+[hierarchical layers]: https://en.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.wikipedia.org/wiki/Concept_map
+
+```
+
+   .----------------.
+   | 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/index.md) that drives the underlying layers.
+
+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 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 the command line interface and the Nix language evaluator is the [Nix store](../store/index.md), 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 itself is a series of *build tasks*, together with their build inputs.
+
+> **Important**
+> A build task in Nix is called [derivation](@docroot@/glossary.md#gloss-derivation).
+
+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.wikipedia.org/wiki/Data-flow_diagram
+
+```
++--------------------------------------------------------------------+
+| 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 |---------'                                          |
+| '-------------'                                                    |
+|                                                                    |
++--------------------------------------------------------------------+
+```
+

doc/manual/source/c-api.md

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

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

@@ -0,0 +1,77 @@
+# Name
+
+`nix.conf` - Nix configuration file
+
+# Description
+
+Nix supports a variety of configuration settings, which are read from configuration files or taken as command line flags.
+
+## Configuration file
+
+By default Nix reads settings from the following places, in that order:
+
+1. The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set.
+
+   Values loaded in this file are not forwarded to the Nix daemon.
+   The client assumes that the daemon has already loaded them.
+
+1. If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order.
+
+   Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and [`XDG_CONFIG_HOME`](./env-common.md#env-XDG_CONFIG_HOME).
+   If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+
+1. If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file.
+
+### File format
+
+Configuration files consist of `name = value` pairs, one per line.
+Comments start with a `#` character.
+
+Example:
+
+```
+keep-outputs = true       # Nice for developers
+keep-derivations = true   # Idem
+```
+
+Other files can be included with a line like `include <path>`, where `<path>` is interpreted relative to the current configuration file.
+A missing file is an error unless `!include` is used instead.
+
+A configuration setting usually overrides any previous value.
+However, for settings that take a list of items, you can prefix the name of the setting by `extra-` to *append* to the previous value.
+
+For instance,
+
+```
+substituters = a b
+extra-substituters = c d
+```
+
+defines the `substituters` setting to be `a b c d`.
+
+Unknown option names are not an error, and are simply ignored with a warning.
+
+## Command line flags
+
+Configuration options can be set on the command line, overriding the values set in the [configuration file](#configuration-file):
+
+- Every configuration setting has corresponding command line flag (e.g. `--max-jobs 16`).
+  Boolean settings do not need an argument, and can be explicitly disabled with the `no-` prefix (e.g. `--keep-failed` and `--no-keep-failed`).
+
+  Unknown option names are invalid flags (unless there is already a flag with that name), and are rejected with an error.
+
+- The flag `--option <name> <value>` is interpreted exactly like a `<name> = <value>` in a setting file.
+
+  Unknown option names are ignored with a warning.
+
+The `extra-` prefix is supported for settings that take a list of items (e.g. `--extra-trusted users alice` or `--option extra-trusted-users alice`).
+
+## Integer settings
+
+Settings that have an integer type support the suffixes `K`, `M`, `G`
+and `T`. These cause the specified value to be multiplied by 2^10,
+2^20, 2^30 and 2^40, respectively. For instance, `--min-free 1M` is
+equivalent to `--min-free 1048576`.
+
+# Available settings
+

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

@@ -0,0 +1,156 @@
+# Common Environment Variables
+
+Most Nix commands interpret the following environment variables:
+
+- <span id="env-IN_NIX_SHELL">[`IN_NIX_SHELL`](#env-IN_NIX_SHELL)</span>
+
+  Indicator that tells if the current environment was set up by
+  `nix-shell`. It can have the values `pure` or `impure`.
+
+- <span id="env-NIX_PATH">[`NIX_PATH`](#env-NIX_PATH)</span>
+
+  A colon-separated list of search path entries used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
+
+  This environment variable overrides the value of the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path).
+
+  It can be extended using the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
+
+  > **Example**
+  >
+  > ```bash
+  > $ export NIX_PATH=`/home/eelco/Dev:nixos-config=/etc/nixos
+  > ```
+
+  If `NIX_PATH` is set to an empty string, resolving search paths will always fail.
+
+  > **Example**
+  >
+  > ```bash
+  > $ NIX_PATH= nix-instantiate --eval '<nixpkgs>'
+  > error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)
+  > ```
+
+- <span id="env-NIX_IGNORE_SYMLINK_STORE">[`NIX_IGNORE_SYMLINK_STORE`](#env-NIX_IGNORE_SYMLINK_STORE)</span>
+
+  Normally, the Nix store directory (typically `/nix/store`) is not
+  allowed to contain any symlink components. This is to prevent
+  “impure” builds. Builders sometimes “canonicalise” paths by
+  resolving all symlink components. Thus, builds on different machines
+  (with `/nix/store` resolving to different locations) could yield
+  different results. This is generally not a problem, except when
+  builds are deployed to machines where `/nix/store` resolves
+  differently. If you are sure that you’re not going to do that, you
+  can set `NIX_IGNORE_SYMLINK_STORE` to `1`.
+
+  Note that if you’re symlinking the Nix store so that you can put it
+  on another file system than the root file system, on Linux you’re
+  better off using `bind` mount points, e.g.,
+
+  ```console
+  $ mkdir /nix
+  $ mount -o bind /mnt/otherdisk/nix /nix
+  ```
+
+  Consult the mount 8 manual page for details.
+
+- <span id="env-NIX_STORE_DIR">[`NIX_STORE_DIR`](#env-NIX_STORE_DIR)</span>
+
+  Overrides the location of the Nix store (default `prefix/store`).
+
+- <span id="env-NIX_DATA_DIR">[`NIX_DATA_DIR`](#env-NIX_DATA_DIR)</span>
+
+  Overrides the location of the Nix static data directory (default
+  `prefix/share`).
+
+- <span id="env-NIX_LOG_DIR">[`NIX_LOG_DIR`](#env-NIX_LOG_DIR)</span>
+
+  Overrides the location of the Nix log directory (default
+  `prefix/var/log/nix`).
+
+- <span id="env-NIX_STATE_DIR">[`NIX_STATE_DIR`](#env-NIX_STATE_DIR)</span>
+
+  Overrides the location of the Nix state directory (default
+  `prefix/var/nix`).
+
+- <span id="env-NIX_CONF_DIR">[`NIX_CONF_DIR`](#env-NIX_CONF_DIR)</span>
+
+  Overrides the location of the system Nix configuration directory
+  (default `prefix/etc/nix`).
+
+- <span id="env-NIX_CONFIG">[`NIX_CONFIG`](#env-NIX_CONFIG)</span>
+
+  Applies settings from Nix configuration from the environment.
+  The content is treated as if it was read from a Nix configuration file.
+  Settings are separated by the newline character.
+
+- <span id="env-NIX_USER_CONF_FILES">[`NIX_USER_CONF_FILES`](#env-NIX_USER_CONF_FILES)</span>
+
+  Overrides the location of the Nix user configuration files to load from.
+
+  The default are the locations according to the [XDG Base Directory Specification].
+  See the [XDG Base Directories](#xdg-base-directories) sub-section for details.
+
+  The variable is treated as a list separated by the `:` token.
+
+- <span id="env-TMPDIR">[`TMPDIR`](#env-TMPDIR)</span>
+
+  Use the specified directory to store temporary files. In particular,
+  this includes temporary build directories; these can take up
+  substantial amounts of disk space. The default is `/tmp`.
+
+- <span id="env-NIX_REMOTE">[`NIX_REMOTE`](#env-NIX_REMOTE)</span>
+
+  This variable should be set to `daemon` if you want to use the Nix
+  daemon to execute Nix operations. This is necessary in [multi-user
+  Nix installations](@docroot@/installation/multi-user.md). If the Nix
+  daemon's Unix socket is at some non-standard path, this variable
+  should be set to `unix://path/to/socket`. Otherwise, it should be
+  left unset.
+
+- <span id="env-NIX_SHOW_STATS">[`NIX_SHOW_STATS`](#env-NIX_SHOW_STATS)</span>
+
+  If set to `1`, Nix will print some evaluation statistics, such as
+  the number of values allocated.
+
+- <span id="env-NIX_COUNT_CALLS">[`NIX_COUNT_CALLS`](#env-NIX_COUNT_CALLS)</span>
+
+  If set to `1`, Nix will print how often functions were called during
+  Nix expression evaluation. This is useful for profiling your Nix
+  expressions.
+
+- <span id="env-GC_INITIAL_HEAP_SIZE">[`GC_INITIAL_HEAP_SIZE`](#env-GC_INITIAL_HEAP_SIZE)</span>
+
+  If Nix has been configured to use the Boehm garbage collector, this
+  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 Directories
+
+Nix follows the [XDG Base Directory Specification].
+
+For backwards compatibility, Nix commands will follow the standard only when [`use-xdg-base-directories`] is enabled.
+[New Nix commands](@docroot@/command-ref/new-cli/nix.md) (experimental) conform to the standard by default.
+
+The following environment variables are used 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`)
+
+[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
+
+In addition, setting the following environment variables overrides the XDG base directories:
+
+- [`NIX_CONFIG_HOME`]{#env-NIX_CONFIG_HOME} (default `$XDG_CONFIG_HOME/nix`)
+- [`NIX_STATE_HOME`]{#env-NIX_STATE_HOME} (default `$XDG_STATE_HOME/nix`)
+- [`NIX_CACHE_HOME`]{#env-NIX_CACHE_HOME} (default `$XDG_CACHE_HOME/nix`)
+
+When [`use-xdg-base-directories`] is enabled, the configuration directory is:
+
+1. `$NIX_CONFIG_HOME`, if it is defined
+2. Otherwise, `$XDG_CONFIG_HOME/nix`, if `XDG_CONFIG_HOME` is defined
+3. Otherwise, `~/.config/nix`.
+
+Likewise for the state and cache directories.

doc/manual/source/command-ref/experimental-commands.md

@@ -1,6 +1,6 @@
 # Experimental Commands
 
-This section lists experimental commands.
+This section lists [experimental commands](@docroot@/development/experimental-features.md#xp-feature-nix-command).
 
 > **Warning**
 >

doc/manual/source/command-ref/files/channels.md

@@ -0,0 +1,26 @@
+## Channels
+
+A directory containing symlinks to Nix channels, managed by [`nix-channel`]:
+
+- `$XDG_STATE_HOME/nix/profiles/channels` for regular users
+- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`
+
+[`nix-channel`] uses a [profile](@docroot@/command-ref/files/profiles.md) to store channels.
+This profile contains symlinks to the contents of those channels.
+
+## Subscribed channels
+
+The list of subscribed channels is stored in
+
+- `~/.nix-channels`
+- `$XDG_STATE_HOME/nix/channels` if [`use-xdg-base-directories`] is set to `true`
+
+in the following format:
+
+```
+<url> <name>
+...
+```
+
+[`nix-channel`]: @docroot@/command-ref/nix-channel.md
+[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories

doc/manual/source/command-ref/files/default-nix-expression.md

@@ -0,0 +1,54 @@
+## Default Nix expression
+
+The source for the [Nix expressions](@docroot@/glossary.md#gloss-nix-expression) used by [`nix-env`] by default:
+
+- `~/.nix-defexpr`
+- `$XDG_STATE_HOME/nix/defexpr` if [`use-xdg-base-directories`] is set to `true`.
+
+It is loaded as follows:
+
+- If the default expression is a file, it is loaded as a Nix expression.
+- If the default expression is a directory containing a `default.nix` file, that `default.nix` file is loaded as a Nix expression.
+- If the default expression is a directory without a `default.nix` file, then its contents (both files and subdirectories) are loaded as Nix expressions.
+  The expressions are combined into a single attribute set, each expression under an attribute with the same name as the original file or subdirectory.
+  Subdirectories without a `default.nix` file are traversed recursively in search of more Nix expressions, but the names of these intermediate directories are not added to the attribute paths of the default Nix expression.
+
+Then, the resulting expression is interpreted like this:
+
+- If the expression is an attribute set, it is used as the default Nix expression.
+- If the expression is a function, an empty set is passed as argument and the return value is used as the default Nix expression.
+
+> **Example**
+>
+> If the default expression contains two files, `foo.nix` and `bar.nix`, then the default Nix expression will be equivalent to
+>
+> ```nix
+> {
+>   foo = import ~/.nix-defexpr/foo.nix;
+>   bar = import ~/.nix-defexpr/bar.nix;
+> }
+> ```
+
+The file [`manifest.nix`](@docroot@/command-ref/files/manifest.nix.md) is always ignored.
+
+The command [`nix-channel`] places a symlink to the current user's [channels] in this directory, the [user channel link](#user-channel-link).
+This makes all subscribed channels available as attributes in the default expression.
+
+## User channel link
+
+A symlink that ensures that [`nix-env`] can find the current user's [channels]:
+
+- `~/.nix-defexpr/channels`
+- `$XDG_STATE_HOME/defexpr/channels` if [`use-xdg-base-directories`] is set to `true`.
+
+This symlink points to:
+
+- `$XDG_STATE_HOME/profiles/channels` for regular users
+- `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`
+
+In a multi-user installation, you may also have `~/.nix-defexpr/channels_root`, which links to the channels of the root user.
+
+[`nix-channel`]: @docroot@/command-ref/nix-channel.md
+[`nix-env`]: @docroot@/command-ref/nix-env.md
+[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
+[channels]: @docroot@/command-ref/files/channels.md

doc/manual/source/command-ref/files/manifest.json.md

@@ -0,0 +1,45 @@
+## `manifest.json`
+
+The manifest file records the provenance of the packages that are installed in a [profile](./profiles.md) managed by [`nix profile`](@docroot@/command-ref/new-cli/nix3-profile.md) (experimental).
+
+Here is an example of what the file might look like after installing `zoom-us` from Nixpkgs:
+
+```json
+{
+  "version": 1,
+  "elements": [
+    {
+      "active": true,
+      "attrPath": "legacyPackages.x86_64-linux.zoom-us",
+      "originalUrl": "flake:nixpkgs",
+      "storePaths": [
+        "/nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927"
+      ],
+      "uri": "github:NixOS/nixpkgs/13d0c311e3ae923a00f734b43fd1d35b47d8943a"
+    },
+    …
+  ]
+}
+```
+
+Each object in the array `elements` denotes an installed package and
+has the following fields:
+
+* `originalUrl`: The [flake reference](@docroot@/command-ref/new-cli/nix3-flake.md) specified by
+  the user at the time of installation (e.g. `nixpkgs`). This is also
+  the flake reference that will be used by `nix profile upgrade`.
+
+* `uri`: The locked flake reference to which `originalUrl` resolved.
+
+* `attrPath`: The flake output attribute that provided this
+  package. Note that this is not necessarily the attribute that the
+  user specified, but the one resulting from applying the default
+  attribute paths and prefixes; for instance, `hello` might resolve to
+  `packages.x86_64-linux.hello` and the empty string to
+  `packages.x86_64-linux.default`.
+
+* `storePath`: The paths in the Nix store containing the package.
+
+* `active`: Whether the profile contains symlinks to the files of this
+  package. If set to false, the package is kept in the Nix store, but
+  is not "visible" in the profile's symlink tree.

doc/manual/source/command-ref/files/manifest.nix.md

@@ -0,0 +1,128 @@
+## `manifest.nix`
+
+The manifest file records the provenance of the packages that are installed in a [profile](./profiles.md) managed by [`nix-env`](@docroot@/command-ref/nix-env.md).
+
+Here is an example of how this file might look like after installing `hello` from Nixpkgs:
+
+```nix
+[{
+  meta = {
+    available = true;
+    broken = false;
+    changelog =
+      "https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v2.12.1";
+    description = "A program that produces a familiar, friendly greeting";
+    homepage = "https://www.gnu.org/software/hello/manual/";
+    insecure = false;
+    license = {
+      deprecated = false;
+      free = true;
+      fullName = "GNU General Public License v3.0 or later";
+      redistributable = true;
+      shortName = "gpl3Plus";
+      spdxId = "GPL-3.0-or-later";
+      url = "https://spdx.org/licenses/GPL-3.0-or-later.html";
+    };
+    longDescription = ''
+      GNU Hello is a program that prints "Hello, world!" when you run it.
+      It is fully customizable.
+    '';
+    maintainers = [{
+      email = "edolstra+nixpkgs@gmail.com";
+      github = "edolstra";
+      githubId = 1148549;
+      name = "Eelco Dolstra";
+    }];
+    name = "hello-2.12.1";
+    outputsToInstall = [ "out" ];
+    platforms = [
+      "i686-cygwin"
+      "x86_64-cygwin"
+      "x86_64-darwin"
+      "i686-darwin"
+      "aarch64-darwin"
+      "armv7a-darwin"
+      "i686-freebsd13"
+      "x86_64-freebsd13"
+      "aarch64-genode"
+      "i686-genode"
+      "x86_64-genode"
+      "x86_64-solaris"
+      "js-ghcjs"
+      "aarch64-linux"
+      "armv5tel-linux"
+      "armv6l-linux"
+      "armv7a-linux"
+      "armv7l-linux"
+      "i686-linux"
+      "m68k-linux"
+      "microblaze-linux"
+      "microblazeel-linux"
+      "mipsel-linux"
+      "mips64el-linux"
+      "powerpc64-linux"
+      "powerpc64le-linux"
+      "riscv32-linux"
+      "riscv64-linux"
+      "s390-linux"
+      "s390x-linux"
+      "x86_64-linux"
+      "mmix-mmixware"
+      "aarch64-netbsd"
+      "armv6l-netbsd"
+      "armv7a-netbsd"
+      "armv7l-netbsd"
+      "i686-netbsd"
+      "m68k-netbsd"
+      "mipsel-netbsd"
+      "powerpc-netbsd"
+      "riscv32-netbsd"
+      "riscv64-netbsd"
+      "x86_64-netbsd"
+      "aarch64_be-none"
+      "aarch64-none"
+      "arm-none"
+      "armv6l-none"
+      "avr-none"
+      "i686-none"
+      "microblaze-none"
+      "microblazeel-none"
+      "msp430-none"
+      "or1k-none"
+      "m68k-none"
+      "powerpc-none"
+      "powerpcle-none"
+      "riscv32-none"
+      "riscv64-none"
+      "rx-none"
+      "s390-none"
+      "s390x-none"
+      "vc4-none"
+      "x86_64-none"
+      "i686-openbsd"
+      "x86_64-openbsd"
+      "x86_64-redox"
+      "wasm64-wasi"
+      "wasm32-wasi"
+      "x86_64-windows"
+      "i686-windows"
+    ];
+    position =
+      "/nix/store/7niq32w715567hbph0q13m5lqna64c1s-nixos-unstable.tar.gz/nixos-unstable.tar.gz/pkgs/applications/misc/hello/default.nix:34";
+    unfree = false;
+    unsupported = false;
+  };
+  name = "hello-2.12.1";
+  out = {
+    outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1";
+  };
+  outPath = "/nix/store/260q5867crm1xjs4khgqpl6vr9kywql1-hello-2.12.1";
+  outputs = [ "out" ];
+  system = "x86_64-linux";
+  type = "derivation";
+}]
+```
+
+Each element in this list corresponds to an installed package.
+It incorporates some attributes of the original derivation, including `meta`, `name`, `out`, `outPath`, `outputs`, `system`.
+This information is used by Nix for querying and updating the package.

doc/manual/source/command-ref/files/profiles.md

@@ -0,0 +1,74 @@
+## Profiles
+
+A directory that contains links to profiles managed by [`nix-env`] and [`nix profile`]:
+
+- `$XDG_STATE_HOME/nix/profiles` for regular users
+- `$NIX_STATE_DIR/profiles/per-user/root` if the user is `root`
+
+A profile is a directory of symlinks to files in the Nix store.
+
+### Filesystem layout
+
+Profiles are versioned as follows. When using a profile named *path*, *path* is a symlink to *path*`-`*N*`-link`, where *N* is the version of the profile.
+In turn, *path*`-`*N*`-link` is a symlink to a path in the Nix store.
+For example:
+
+```console
+$ ls -l ~alice/.local/state/nix/profiles/profile*
+lrwxrwxrwx 1 alice users 14 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile -> profile-7-link
+lrwxrwxrwx 1 alice users 51 Oct 28 16:18 /home/alice/.local/state/nix/profiles/profile-5-link -> /nix/store/q69xad13ghpf7ir87h0b2gd28lafjj1j-profile
+lrwxrwxrwx 1 alice users 51 Oct 29 13:20 /home/alice/.local/state/nix/profiles/profile-6-link -> /nix/store/6bvhpysd7vwz7k3b0pndn7ifi5xr32dg-profile
+lrwxrwxrwx 1 alice users 51 Nov 25 14:35 /home/alice/.local/state/nix/profiles/profile-7-link -> /nix/store/mp0x6xnsg0b8qhswy6riqvimai4gm677-profile
+```
+
+Each of these symlinks is a root for the Nix garbage collector.
+
+The contents of the store path corresponding to each version of the
+profile is a tree of symlinks to the files of the installed packages,
+e.g.
+
+```console
+$ ll -R ~eelco/.local/state/nix/profiles/profile-7-link/
+/home/eelco/.local/state/nix/profiles/profile-7-link/:
+total 20
+dr-xr-xr-x 2 root root 4096 Jan  1  1970 bin
+-r--r--r-- 2 root root 1402 Jan  1  1970 manifest.nix
+dr-xr-xr-x 4 root root 4096 Jan  1  1970 share
+
+/home/eelco/.local/state/nix/profiles/profile-7-link/bin:
+total 20
+lrwxrwxrwx 5 root root 79 Jan  1  1970 chromium -> /nix/store/ijm5k0zqisvkdwjkc77mb9qzb35xfi4m-chromium-86.0.4240.111/bin/chromium
+lrwxrwxrwx 7 root root 87 Jan  1  1970 spotify -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/bin/spotify
+lrwxrwxrwx 3 root root 79 Jan  1  1970 zoom-us -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/bin/zoom-us
+
+/home/eelco/.local/state/nix/profiles/profile-7-link/share/applications:
+total 12
+lrwxrwxrwx 4 root root 120 Jan  1  1970 chromium-browser.desktop -> /nix/store/4cf803y4vzfm3gyk3vzhzb2327v0kl8a-chromium-unwrapped-86.0.4240.111/share/applications/chromium-browser.desktop
+lrwxrwxrwx 7 root root 110 Jan  1  1970 spotify.desktop -> /nix/store/w9182874m1bl56smps3m5zjj36jhp3rn-spotify-1.1.26.501.gbe11e53b-15/share/applications/spotify.desktop
+lrwxrwxrwx 3 root root 107 Jan  1  1970 us.zoom.Zoom.desktop -> /nix/store/wbhg2ga8f3h87s9h5k0slxk0m81m4cxl-zoom-us-5.3.469451.0927/share/applications/us.zoom.Zoom.desktop
+
+…
+```
+
+Each profile version contains a manifest file:
+- [`manifest.nix`](@docroot@/command-ref/files/manifest.nix.md) used by [`nix-env`](@docroot@/command-ref/nix-env.md).
+- [`manifest.json`](@docroot@/command-ref/files/manifest.json.md) used by [`nix profile`](@docroot@/command-ref/new-cli/nix3-profile.md) (experimental).
+
+## User profile link
+
+A symbolic link to the user's current profile:
+
+- `~/.nix-profile`
+- `$XDG_STATE_HOME/nix/profile` if [`use-xdg-base-directories`] is set to `true`.
+
+By default, this symlink points to:
+
+- `$XDG_STATE_HOME/nix/profiles/profile` for regular users
+- `$NIX_STATE_DIR/profiles/per-user/root/profile` for `root`
+
+The `PATH` environment variable should include `/bin` subdirectory of the profile link (e.g. `~/.nix-profile/bin`) for the user environment to be visible to the user.
+The [installer](@docroot@/installation/installing-binary.md) sets this up by default, unless you enable [`use-xdg-base-directories`].
+
+[`nix-env`]: @docroot@/command-ref/nix-env.md
+[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md
+[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories

doc/manual/source/command-ref/meson.build

@@ -0,0 +1,63 @@
+xp_features_json = custom_target(
+  command : [nix, '__dump-xp-features'],
+  capture : true,
+  output : 'xp-features.json',
+)
+
+experimental_features_shortlist_md = custom_target(
+  command : nix_eval_for_docs + [
+    '--expr',
+    'import @INPUT0@ (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
+  ],
+  input : [
+    '../../generate-xp-features-shortlist.nix',
+    xp_features_json,
+  ],
+  output : 'experimental-features-shortlist.md',
+  capture : true,
+  env : nix_env_for_docs,
+)
+
+nix3_cli_files = custom_target(
+  command : [
+    python.full_path(),
+    '@INPUT0@',
+    '@OUTPUT@',
+    '--'
+  ] + nix_eval_for_docs + [
+    '--expr',
+    'import @INPUT1@ true (builtins.readFile ./@INPUT2@)',
+  ],
+  input : [
+    '../../remove_before_wrapper.py',
+    '../../generate-manpage.nix',
+    nix3_cli_json,
+  ],
+  output : 'new-cli',
+  env : nix_env_for_docs,
+)
+
+conf_file_md_body = custom_target(
+  command : [
+    nix_eval_for_docs,
+    '--expr',
+    'import @INPUT0@ { prefix = "conf"; } (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
+  ],
+  capture : true,
+  input : [
+    '../../generate-settings.nix',
+    conf_file_json,
+  ],
+  output : 'conf-file.body.md',
+  env : nix_env_for_docs,
+)
+
+conf_file_md = custom_target(
+  command : [ 'cat', '@INPUT0@', '@INPUT1@' ],
+  capture : true,
+  input : [
+    'conf-file-prefix.md',
+    conf_file_md_body,
+  ],
+  output : 'conf-file.md',
+)

doc/manual/source/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
---realise`](nix-store.md#operation---realise) (to build the store
+expression to a low-level [store derivation]) and [`nix-store
+--realise`](@docroot@/command-ref/nix-store/realise.md) (to build the store
 derivation).
 
+[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+
 > **Warning**
 >
 > The result of the build is automatically registered as a root of the
@@ -49,29 +51,35 @@ derivation).
 
 # Options
 
-All options not listed here are passed to `nix-store
---realise`, except for `--arg` and `--attr` / `-A` which are passed to
-`nix-instantiate`.
+All options not listed here are passed to
+[`nix-store --realise`](nix-store/realise.md),
+except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](nix-instantiate.md).
 
-  - [`--no-out-link`]{#opt-no-out-link}\
-    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`.
+- <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
 
-  - [`--dry-run`]{#opt-dry-run}\
-    Show what store paths would be built or downloaded.
+  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`.
 
-  - [`--out-link`]{#opt-out-link} / `-o` *outlink*\
-    Change the name of the symlink to the output path created from
-    `result` to *outlink*.
+- <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
 
-The following common options are supported:
+  Show what store paths would be built or downloaded.
+
+- <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*.
+
+{{#include ./status-build-failure.md}}
+
+{{#include ./opt-common.md}}
+
+{{#include ./env-common.md}}
 
 # Examples
 
 ```console
-$ nix-build '<nixpkgs>' -A firefox
+$ nix-build '<nixpkgs>' --attr firefox
 store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
 /nix/store/d18hyl92g30l...-firefox-1.5.0.7
 
@@ -86,7 +94,7 @@ If a derivation has multiple outputs, `nix-build` will build the default
 (first) output. You can also build all outputs:
 
 ```console
-$ nix-build '<nixpkgs>' -A openssl.all
+$ nix-build '<nixpkgs>' --attr openssl.all
 ```
 
 This will create a symlink for each output named `result-outputname`.
@@ -96,7 +104,7 @@ outputs `out`, `bin` and `man`, `nix-build` will create symlinks
 specific output:
 
 ```console
-$ nix-build '<nixpkgs>' -A openssl.man
+$ nix-build '<nixpkgs>' --attr openssl.man
 ```
 
 This will create a symlink `result-man`.
@@ -104,7 +112,7 @@ This will create a symlink `result-man`.
 Build a Nix expression given on the command line:
 
 ```console
-$ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
+$ nix-build --expr 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
 $ cat ./result
 bar
 ```
@@ -113,5 +121,5 @@ Build the GNU Hello package from the latest revision of the master
 branch of Nixpkgs:
 
 ```console
-$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz --attr hello
 ```

doc/manual/source/command-ref/nix-channel.md

@@ -0,0 +1,112 @@
+# Name
+
+`nix-channel` - manage Nix channels
+
+# Synopsis
+
+`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--list-generations` | `--rollback` [*generation*] }
+
+# Description
+
+Channels are a mechanism for referencing remote Nix expressions and conveniently retrieving their latest version.
+
+The moving parts of channels are:
+- The official channels listed at <https://nixos.org/channels>
+- The user-specific list of [subscribed channels](#subscribed-channels)
+- The [downloaded channel contents](#channels)
+- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-i) or the [`NIX_PATH` environment variable](#env-NIX_PATH)
+
+> **Note**
+>
+> The state of a subscribed channel is external to the Nix expressions relying on it.
+> This may limit reproducibility.
+>
+> Dependencies on other Nix expressions can be declared explicitly with:
+> - [`fetchurl`](@docroot@/language/builtins.md#builtins-fetchurl), [`fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball), or [`fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) in Nix expressions
+> - the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I) in command line invocations
+
+This command has the following operations:
+
+- `--add` *url* \[*name*\]
+
+  Add a channel *name* located at *url* to the list of subscribed channels.
+  If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed.
+
+  > **Note**
+  >
+  > `--add` does not automatically perform an update.
+  > Use `--update` explicitly.
+
+  A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
+  At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.
+
+- `--remove` *name*
+
+  Remove the channel *name* from the list of subscribed channels.
+
+- `--list`
+
+  Print the names and URLs of all subscribed channels on standard output.
+
+- `--update` \[*names*…\]
+
+  Download the Nix expressions of subscribed channels and create a new generation.
+  Update all channels if none is specified, and only those included in *names* otherwise.
+
+- `--list-generations`
+
+  Prints a list of all the current existing generations for the
+  channel profile.
+
+  Works the same way as
+  ```
+  nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
+  ```
+
+- `--rollback` \[*generation*\]
+
+  Revert channels to the state before the last call to `nix-channel --update`.
+  Optionally, you can specify a specific channel *generation* number to restore.
+
+{{#include ./opt-common.md}}
+
+{{#include ./env-common.md}}
+
+# Files
+
+`nix-channel` operates on the following files.
+
+{{#include ./files/channels.md}}
+
+# Examples
+
+Subscribe to the Nixpkgs channel and run `hello` from the GNU Hello package:
+
+```console
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
+$ nix-channel --list
+nixpkgs https://nixos.org/channels/nixpkgs
+$ nix-channel --update
+$ nix-shell -p hello --run hello
+hello
+```
+
+Revert channel updates using `--rollback`:
+
+```console
+$ nix-instantiate --eval '<nixpkgs>' --attr lib.version
+"22.11pre296212.530a53dcbc9"
+
+$ nix-channel --rollback
+switching from generation 483 to 482
+
+$ nix-instantiate --eval '<nixpkgs>' --attr lib.version
+"22.11pre281526.d0419badfad"
+```
+
+Remove a channel:
+
+```console
+$ nix-channel --remove nixpkgs
+$ nix-channel --list
+```

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

@@ -0,0 +1,79 @@
+# Name
+
+`nix-collect-garbage` - delete unreachable [store objects]
+
+# Synopsis
+
+`nix-collect-garbage` [`--delete-old`] [`-d`] [`--delete-older-than` *period*] [`--max-freed` *bytes*] [`--dry-run`]
+
+# Description
+
+The command `nix-collect-garbage` is mostly an alias of [`nix-store --gc`](@docroot@/command-ref/nix-store/gc.md).
+That is, it deletes all unreachable [store objects] in the Nix store to clean up your system.
+
+However, it provides two additional options,
+[`--delete-old`](#opt-delete-old) and [`--delete-older-than`](#opt-delete-older-than),
+which also delete old [profiles], allowing potentially more [store objects] to be deleted because profiles are also garbage collection roots.
+These options are the equivalent of running
+[`nix-env --delete-generations`](@docroot@/command-ref/nix-env/delete-generations.md)
+with various augments on multiple profiles,
+prior to running `nix-collect-garbage` (or just `nix-store --gc`) without any flags.
+
+> **Note**
+>
+> Deleting previous configurations makes rollbacks to them impossible.
+
+These flags should be used with care, because they potentially delete generations of profiles used by other users on the system.
+
+## Locations searched for profiles
+
+`nix-collect-garbage` cannot know about all profiles; that information doesn't exist.
+Instead, it looks in a few locations, and acts on all profiles it finds there:
+
+1. The default profile locations as specified in the [profiles] section of the manual.
+
+2. > **NOTE**
+   >
+   > Not stable; subject to change
+   >
+   > Do not rely on this functionality; it just exists for migration purposes and is may change in the future.
+   > These deprecated paths remain a private implementation detail of Nix.
+
+   `$NIX_STATE_DIR/profiles` and `$NIX_STATE_DIR/profiles/per-user`.
+
+   With the exception of `$NIX_STATE_DIR/profiles/per-user/root` and `$NIX_STATE_DIR/profiles/default`, these directories are no longer used by other commands.
+   `nix-collect-garbage` looks there anyways in order to clean up profiles from older versions of Nix.
+
+# Options
+
+These options are for deleting old [profiles] prior to deleting unreachable [store objects].
+
+- <span id="opt-delete-old">[`--delete-old`](#opt-delete-old)</span> / `-d`
+
+  Delete all old generations of profiles.
+
+  This is the equivalent of invoking [`nix-env --delete-generations old`](@docroot@/command-ref/nix-env/delete-generations.md#generations-old) on each found profile.
+
+- <span id="opt-delete-older-than">[`--delete-older-than`](#opt-delete-older-than)</span> *period*
+
+  Delete all generations of profiles older than the specified amount (except for the generations that were active at that point in time).
+  *period* is a value such as `30d`, which would mean 30 days.
+
+  This is the equivalent of invoking [`nix-env --delete-generations <period>`](@docroot@/command-ref/nix-env/delete-generations.md#generations-time) on each found profile.
+  See the documentation of that command for additional information about the *period* argument.
+
+{{#include ./opt-common.md}}
+
+{{#include ./env-common.md}}
+
+# Example
+
+To delete from the Nix store everything that is not used by the current
+generations of each profile, do
+
+```console
+$ nix-collect-garbage -d
+```
+
+[profiles]: @docroot@/command-ref/files/profiles.md
+[store objects]: @docroot@/store/store-object.md

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

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

doc/manual/source/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/source/command-ref/nix-env.md

@@ -0,0 +1,134 @@
+# Name
+
+`nix-env` - manipulate or query Nix user environments
+
+# Synopsis
+
+`nix-env` *operation* [*options*] [*arguments…*]
+  [`--option` *name* *value*]
+  [`--arg` *name* *value*]
+  [`--argstr` *name* *value*]
+  [{`--file` | `-f`} *path*]
+  [{`--profile` | `-p`} *path*]
+  [`--system-filter` *system*]
+  [`--dry-run`]
+
+# Description
+
+The command `nix-env` is used to manipulate Nix user environments. User
+environments are sets of software packages available to a user at some
+point in time. In other words, they are a synthesised view of the
+programs available in the Nix store. There may be many user
+environments: different users can have different environments, and
+individual users can switch between different environments.
+
+`nix-env` takes exactly one *operation* flag which indicates the
+subcommand to be performed. The following operations are available:
+
+- [`--install`](./nix-env/install.md)
+- [`--upgrade`](./nix-env/upgrade.md)
+- [`--uninstall`](./nix-env/uninstall.md)
+- [`--set`](./nix-env/set.md)
+- [`--set-flag`](./nix-env/set-flag.md)
+- [`--query`](./nix-env/query.md)
+- [`--switch-profile`](./nix-env/switch-profile.md)
+- [`--list-generations`](./nix-env/list-generations.md)
+- [`--delete-generations`](./nix-env/delete-generations.md)
+- [`--switch-generation`](./nix-env/switch-generation.md)
+- [`--rollback`](./nix-env/rollback.md)
+
+These pages can be viewed offline:
+
+- `man nix-env-<operation>`.
+
+  Example: `man nix-env-install`
+
+- `nix-env --help --<operation>`
+
+  Example: `nix-env --help --install`
+
+# Package sources
+
+`nix-env` can obtain packages from multiple sources:
+
+- An attribute set of derivations from:
+  - The [default Nix expression](@docroot@/command-ref/files/default-nix-expression.md) (by default)
+  - A Nix file, specified via `--file`
+  - A [profile](@docroot@/command-ref/files/profiles.md), specified via `--from-profile`
+  - A Nix expression that is a function which takes default expression as argument, specified via `--from-expression`
+- A [store path](@docroot@/store/store-path.md)
+
+# Selectors
+
+Several operations, such as [`nix-env --query`](./nix-env/query.md) and [`nix-env --install`](./nix-env/install.md), take a list of *arguments* that specify the packages on which to operate.
+
+Packages are identified based on a `name` part and a `version` part of a [symbolic derivation name](@docroot@/language/derivations.md#attr-name):
+
+- `name`: Everything up to but not including the first dash (`-`) that is *not* followed by a letter.
+- `version`: The rest, excluding the separating dash.
+
+> **Example**
+>
+> `nix-env` parses the symbolic derivation name `apache-httpd-2.0.48` as:
+>
+> ```json
+> {
+>   "name": "apache-httpd",
+>   "version": "2.0.48"
+> }
+> ```
+
+> **Example**
+>
+> `nix-env` parses the symbolic derivation name `firefox.*` as:
+>
+> ```json
+> {
+>   "name": "firefox.*",
+>   "version": ""
+> }
+> ```
+
+The `name` parts of the *arguments* to `nix-env` are treated as extended regular expressions and matched against the `name` parts of derivation names in the package source.
+The match is case-sensitive.
+The regular expression can optionally be followed by a dash (`-`) and a version number; if omitted, any version of the package will match.
+For details on regular expressions, see [**regex**(7)](https://linux.die.net/man/7/regex).
+
+> **Example**
+>
+> Common patterns for finding package names with `nix-env`:
+>
+> - `firefox`
+>
+>   Matches the package name `firefox` and any version.
+>
+> - `firefox-32.0`
+>
+>   Matches the package name `firefox` and version `32.0`.
+>
+> - `gtk\\+`
+>
+>   Matches the package name `gtk+`.
+>   The `+` character must be escaped using a backslash (`\`) to prevent it from being interpreted as a quantifier, and the backslash must be escaped in turn with another backslash to ensure that the shell passes it on.
+>
+> - `.\*`
+>
+>   Matches any package name.
+>   This is the default for most commands.
+>
+> - `'.*zip.*'`
+>
+>   Matches any package name containing the string `zip`.
+>   Note the dots: `'*zip*'` does not work, because in a regular expression, the character `*` is interpreted as a quantifier.
+>
+> - `'.*(firefox|chromium).*'`
+>
+>   Matches any package name containing the strings `firefox` or `chromium`.
+
+# Files
+
+`nix-env` operates on the following files.
+
+{{#include ./files/default-nix-expression.md}}
+
+{{#include ./files/profiles.md}}

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

@@ -0,0 +1,98 @@
+# Name
+
+`nix-env --delete-generations` - delete profile generations
+
+# Synopsis
+
+`nix-env` `--delete-generations` *generations*
+
+# Description
+
+This operation deletes the specified generations of the current profile.
+
+*generations* can be a one of the following:
+
+- <span id="generations-list">[`<number>...`](#generations-list)</span>
+
+  A list of generation numbers, each one a separate command-line argument.
+
+  Delete exactly the profile generations given by their generation number.
+  Deleting the current generation is not allowed.
+
+- <span id="generations-old">[The special value `old`](#generations-old)</span>
+
+  Delete all generations except the current one.
+
+  > **WARNING**
+  >
+  > Older *and newer* generations will be deleted by this operation.
+  >
+  > One might expect this to just delete older generations than the curent one, but that is only true if the current generation is also the latest.
+  > Because one can roll back to a previous generation, it is possible to have generations newer than the current one.
+  > They will also be deleted.
+
+- <span id="generations-time">[`<number>d`](#generations-time)</span>
+
+  The last *number* days
+
+  *Example*: `30d`
+
+  Delete all generations created more than *number* days ago, except the most recent one of them.
+  This allows rolling back to generations that were available within the specified period.
+
+- <span id="generations-count">[`+<number>`](#generations-count)</span>
+
+  The last *number* generations up to the present
+
+  *Example*: `+5`
+
+  Keep the last *number* generations, along with any newer than current.
+
+Periodically deleting old generations is important to make garbage collection
+effective.
+The is because profiles are also garbage collection roots — any [store object] reachable from a profile is "alive" and ineligible for deletion.
+
+[store object]: @docroot@/store/store-object.md
+
+{{#include ./opt-common.md}}
+
+{{#include ../opt-common.md}}
+
+{{#include ./env-common.md}}
+
+{{#include ../env-common.md}}
+
+# Examples
+
+## Delete explicit generation numbers
+
+```console
+$ nix-env --delete-generations 3 4 8
+```
+
+Delete the generations numbered 3, 4, and 8, so long as the current active generation is not any of those.
+
+## Keep most-recent by count (number of generations)
+
+```console
+$ nix-env --delete-generations +5
+```
+
+Suppose `30` is the current generation, and we currently have generations numbered `20` through `32`.
+
+Then this command will delete generations `20` through `25` (`<= 30 - 5`),
+and keep generations `26` through `31` (`> 30 - 5`).
+
+## Keep most-recent by time (number of days)
+
+```console
+$ nix-env --delete-generations 30d
+```
+
+This command will delete all generations older than 30 days, except for the generation that was active 30 days ago (if it currently exists).
+
+## Delete all older
+
+```console
+$ nix-env --profile other_profile --delete-generations old
+```

doc/manual/source/command-ref/nix-env/env-common.md

@@ -0,0 +1,7 @@
+# Environment variables
+
+- `NIX_PROFILE`
+
+  Location of the Nix profile. Defaults to the target of the symlink
+  `~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
+  otherwise.

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

@@ -0,0 +1,238 @@
+# Name
+
+`nix-env --install` - add packages to user environment
+
+# Synopsis
+
+`nix-env` {`--install` | `-i`} *args…*
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`}]
+  [`--from-expression`] [`-E`]
+  [`--from-profile` *path*]
+  [`--preserve-installed` | `-P`]
+  [`--remove-all` | `-r`]
+
+# Description
+
+The `--install` operation creates a new user environment.
+It is based on the current generation of the active [profile](@docroot@/command-ref/files/profiles.md), to which a set of [store paths] described by *args* is added.
+
+[store paths]: @docroot@/store/store-path.md
+
+The arguments *args* map to store paths in a number of possible ways:
+
+- By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression].
+  These are [realised], and the resulting output paths are installed.
+  Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
+
+  [derivation]: @docroot@/glossary.md#gloss-derivation
+  [default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
+  [realised]: @docroot@/glossary.md#gloss-realise
+
+  If there are multiple derivations matching a name in *args* that
+  have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
+  derivation with the highest *priority* is used. A derivation can
+  define a priority by declaring the `meta.priority` attribute. This
+  attribute should be a number, with a higher value denoting a lower
+  priority. The default priority is `5`.
+
+  If there are multiple matching derivations with the same priority,
+  then the derivation with the highest version will be installed.
+
+  You can force the installation of multiple derivations with the same
+  name by being specific about the versions. For instance, `nix-env --install
+  gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
+  probably cause a user environment conflict\!).
+
+- If [`--attr`](#opt-attr) / `-A` is specified, the arguments are *attribute paths* that select attributes from the [default Nix expression].
+  This is faster than using derivation names and unambiguous.
+  Show the attribute paths of available packages with [`nix-env --query`](./query.md):
+
+  ```console
+  nix-env --query --available --attr-path
+  ```
+
+- If `--from-profile` *path* is given, *args* is a set of names
+  denoting installed [store paths] in the profile *path*. This is an
+  easy way to copy user environment elements from one profile to
+  another.
+
+- If `--from-expression` is given, *args* are [Nix language functions](@docroot@/language/syntax.md#functions) that are called with the [default Nix expression] as their single argument.
+  The derivations returned by those function calls are installed.
+  This allows derivations to be specified in an unambiguous way, which is necessary if there are multiple derivations with the same name.
+
+- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
+
+- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
+
+- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
+  This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
+
+  Example:
+
+  The file `example.nix` defines a derivation with two outputs `foo` and `bar`, each containing a file.
+
+  ```nix
+  # example.nix
+  let
+    pkgs = import <nixpkgs> {};
+    command = ''
+      ${pkgs.coreutils}/bin/mkdir -p $foo $bar
+      echo foo > $foo/foo-file
+      echo bar > $bar/bar-file
+    '';
+  in
+  derivation {
+    name = "example";
+    builder = "${pkgs.bash}/bin/bash";
+    args = [ "-c" command ];
+    outputs = [ "foo" "bar" ];
+    system = builtins.currentSystem;
+  }
+  ```
+
+  Installing from this Nix expression will make files from both outputs appear in the current profile.
+
+  ```console
+  $ nix-env --install --file example.nix
+  installing 'example'
+  $ ls ~/.nix-profile
+  foo-file
+  bar-file
+  manifest.nix
+  ```
+
+  Adding `meta.outputsToInstall` to that derivation will make `nix-env` only install files from the specified outputs.
+
+  ```nix
+  # example-outputs.nix
+  import ./example.nix // { meta.outputsToInstall = [ "bar" ]; }
+  ```
+
+  ```console
+  $ nix-env --install --file example-outputs.nix
+  installing 'example'
+  $ ls ~/.nix-profile
+  bar-file
+  manifest.nix
+  ```
+
+# Options
+
+- `--prebuilt-only` / `-b`
+
+  Use only derivations for which a substitute is registered, i.e.,
+  there is a pre-built binary available that can be downloaded in lieu
+  of building the derivation. Thus, no packages will be built from
+  source.
+
+- `--preserve-installed` / `-P`
+
+  Do not remove derivations with a name matching one of the
+  derivations being installed. Usually, trying to have two versions of
+  the same package installed in the same generation of a profile will
+  lead to an error in building the generation, due to file name
+  clashes between the two versions. However, this is not the case for
+  all packages.
+
+- `--remove-all` / `-r`
+
+  Remove all previously installed packages first. This is equivalent
+  to running `nix-env --uninstall '.*'` first, except that everything happens
+  in a single transaction.
+
+{{#include ./opt-common.md}}
+
+{{#include ../opt-common.md}}
+
+{{#include ./env-common.md}}
+
+{{#include ../env-common.md}}
+
+# Examples
+
+To install a package using a specific attribute path from the active Nix expression:
+
+```console
+$ nix-env --install --attr gcc40mips
+installing `gcc-4.0.2'
+$ nix-env --install --attr xorg.xorgserver
+installing `xorg-server-1.2.0'
+```
+
+To install a specific version of `gcc` using the derivation name:
+
+```console
+$ nix-env --install gcc-3.3.2
+installing `gcc-3.3.2'
+uninstalling `gcc-3.1'
+```
+
+Using attribute path for selecting a package is preferred,
+as it is much faster and there will not be multiple matches.
+
+Note the previously installed version is removed, since
+`--preserve-installed` was not specified.
+
+To install an arbitrary version:
+
+```console
+$ nix-env --install gcc
+installing `gcc-3.3.2'
+```
+
+To install all derivations in the Nix expression `foo.nix`:
+
+```console
+$ nix-env --file ~/foo.nix --install '.*'
+```
+
+To copy the store path with symbolic name `gcc` from another profile:
+
+```console
+$ nix-env --install --from-profile /nix/var/nix/profiles/foo gcc
+```
+
+To install a specific [store derivation] (typically created by
+`nix-instantiate`):
+
+```console
+$ nix-env --install /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
+```
+
+To install a specific output path:
+
+```console
+$ nix-env --install /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
+```
+
+To install from a Nix expression specified on the command-line:
+
+```console
+$ nix-env --file ./foo.nix --install --expr \
+    'f: (f {system = "i686-linux";}).subversionWithJava'
+```
+
+I.e., this evaluates to `(f: (f {system =
+"i686-linux";}).subversionWithJava) (import ./foo.nix)`, thus selecting
+the `subversionWithJava` attribute from the set returned by calling the
+function defined in `./foo.nix`.
+
+A dry-run tells you which paths will be downloaded or built from source:
+
+```console
+$ nix-env --file '<nixpkgs>' --install --attr hello --dry-run
+(dry run; not doing anything)
+installing ‘hello-2.10’
+this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
+  /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
+  ...
+```
+
+To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12
+channel:
+
+```console
+$ nix-env --file https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz --install --attr firefox
+```
+

doc/manual/source/command-ref/nix-env/list-generations.md

@@ -0,0 +1,33 @@
+# Name
+
+`nix-env --list-generations` - list profile generations
+
+# Synopsis
+
+`nix-env` `--list-generations`
+
+# Description
+
+This operation print a list of all the currently existing generations
+for the active profile. These may be switched to using the
+`--switch-generation` operation. It also prints the creation date of the
+generation, and indicates the current generation.
+
+{{#include ./opt-common.md}}
+
+{{#include ../opt-common.md}}
+
+{{#include ./env-common.md}}
+
+{{#include ../env-common.md}}
+
+# Examples
+
+```console
+$ nix-env --list-generations
+  95   2004-02-06 11:48:24
+  96   2004-02-06 11:49:01
+  97   2004-02-06 16:22:45
+  98   2004-02-06 16:24:33   (current)
+```
+

doc/manual/source/command-ref/nix-env/opt-common.md

@@ -0,0 +1,38 @@
+# Options
+
+The following options are allowed for all `nix-env` operations, but may not always have an effect.
+
+- `--file` / `-f` *path*
+
+  Specifies the Nix expression (designated below as the *active Nix
+  expression*) used by the `--install`, `--upgrade`, and `--query
+  --available` operations to obtain derivations. The default is
+  `~/.nix-defexpr`.
+
+  If the argument 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 include a single
+  top-level directory containing at least a file named `default.nix`.
+
+- `--profile` / `-p` *path*
+
+  Specifies the profile to be used by those operations that operate on
+  a profile (designated below as the *active profile*). A profile is a
+  sequence of user environments called *generations*, one of which is
+  the *current generation*.
+
+- `--dry-run`
+
+  For the `--install`, `--upgrade`, `--uninstall`,
+  `--switch-generation`, `--delete-generations` and `--rollback`
+  operations, this flag will cause `nix-env` to print what *would* be
+  done if this flag had not been specified, without actually doing it.
+
+  `--dry-run` also prints out which paths will be
+  [substituted](@docroot@/glossary.md) (i.e., downloaded) and which paths
+  will be built from source (because no substitute is available).
+
+- `--system-filter` *system*
+
+  By default, operations such as `--query --available` show derivations matching any platform. This option
+  allows you to use derivations for the specified platform *system*.

doc/manual/source/command-ref/nix-env/query.md

@@ -0,0 +1,233 @@
+# Name
+
+`nix-env --query` - display information about packages
+
+# Synopsis
+
+`nix-env` {`--query` | `-q`} *names…*
+  [`--installed` | `--available` | `-a`]
+  [{`--status` | `-s`}]
+  [{`--attr-path` | `-P`}]
+  [`--no-name`]
+  [{`--compare-versions` | `-c`}]
+  [`--system`]
+  [`--drv-path`]
+  [`--out-path`]
+  [`--description`]
+  [`--meta`]
+  [`--xml`]
+  [`--json`]
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`} *attribute-path*]
+
+# Description
+
+The query operation displays information about either the store paths
+that are installed in the current generation of the active profile
+(`--installed`), or the derivations that are available for installation
+in the active Nix expression (`--available`). It only prints information
+about derivations whose symbolic name matches one of *names*.
+
+The derivations are sorted by their `name` attributes.
+
+# Source selection
+
+The following flags specify the set of things on which the query
+operates.
+
+  - `--installed`
+
+    The query operates on the store paths that are installed in the
+    current generation of the active profile. This is the default.
+
+  - `--available` / `-a`
+
+    The query operates on the derivations that are available in the
+    active Nix expression.
+
+# Queries
+
+The following flags specify what information to display about the
+selected derivations. Multiple flags may be specified, in which case the
+information is shown in the order given here. Note that the name of the
+derivation is shown unless `--no-name` is specified.
+
+  - `--xml`
+
+    Print the result in an XML representation suitable for automatic
+    processing by other tools. The root element is called `items`, which
+    contains a `item` element for each available or installed
+    derivation. The fields discussed below are all stored in attributes
+    of the `item` elements.
+
+  - `--json`
+
+    Print the result in a JSON representation suitable for automatic
+    processing by other tools.
+
+  - `--prebuilt-only` / `-b`
+
+    Show only derivations for which a substitute is registered, i.e.,
+    there is a pre-built binary available that can be downloaded in lieu
+    of building the derivation. Thus, this shows all packages that
+    probably can be installed quickly.
+
+  - `--status` / `-s`
+
+    Print the *status* of the derivation. The status consists of three
+    characters. The first is `I` or `-`, indicating whether the
+    derivation is currently installed in the current generation of the
+    active profile. This is by definition the case for `--installed`,
+    but not for `--available`. The second is `P` or `-`, indicating
+    whether the derivation is present on the system. This indicates
+    whether installation of an available derivation will require the
+    derivation to be built. The third is `S` or `-`, indicating whether
+    a substitute is available for the derivation.
+
+  - `--attr-path` / `-P`
+
+    Print the *attribute path* of the derivation, which can be used to
+    unambiguously select it using the `--attr` option available in
+    commands that install derivations like `nix-env --install`. This
+    option only works together with `--available`
+
+  - `--no-name`
+
+    Suppress printing of the `name` attribute of each derivation.
+
+  - `--compare-versions` / `-c`
+
+    Compare installed versions to available versions, or vice versa (if
+    `--available` is given). This is useful for quickly seeing whether
+    upgrades for installed packages are available in a Nix expression. A
+    column is added with the following meaning:
+
+      - `<` *version*
+
+        A newer version of the package is available or installed.
+
+      - `=` *version*
+
+        At most the same version of the package is available or
+        installed.
+
+      - `>` *version*
+
+        Only older versions of the package are available or installed.
+
+      - `- ?`
+
+        No version of the package is available or installed.
+
+  - `--system`
+
+    Print the `system` attribute of the derivation.
+
+  - `--drv-path`
+
+    Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
+
+  - `--out-path`
+
+    Print the output path of the derivation.
+
+  - `--description`
+
+    Print a short (one-line) description of the derivation, if
+    available. The description is taken from the `meta.description`
+    attribute of the derivation.
+
+  - `--meta`
+
+    Print all of the meta-attributes of the derivation. This option is
+    only available with `--xml` or `--json`.
+
+{{#include ./opt-common.md}}
+
+{{#include ../opt-common.md}}
+
+{{#include ./env-common.md}}
+
+{{#include ../env-common.md}}
+
+# Examples
+
+To show installed packages:
+
+```console
+$ nix-env --query
+bison-1.875c
+docbook-xml-4.2
+firefox-1.0.4
+MPlayer-1.0pre7
+ORBit2-2.8.3
+…
+```
+
+To show available packages:
+
+```console
+$ nix-env --query --available
+firefox-1.0.7
+GConf-2.4.0.1
+MPlayer-1.0pre7
+ORBit2-2.8.3
+…
+```
+
+To show the status of available packages:
+
+```console
+$ nix-env --query --available --status
+-P- firefox-1.0.7   (not installed but present)
+--S GConf-2.4.0.1   (not present, but there is a substitute for fast installation)
+--S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
+IP- ORBit2-2.8.3    (installed and by definition present)
+…
+```
+
+To show available packages in the Nix expression `foo.nix`:
+
+```console
+$ nix-env --file ./foo.nix --query --available
+foo-1.2.3
+```
+
+To compare installed versions to what’s available:
+
+```console
+$ nix-env --query --compare-versions
+...
+acrobat-reader-7.0 - ?      (package is not available at all)
+autoconf-2.59      = 2.59   (same version)
+firefox-1.0.4      < 1.0.7  (a more recent version is available)
+...
+```
+
+To show all packages with “`zip`” in the name:
+
+```console
+$ nix-env --query --available '.*zip.*'
+bzip2-1.0.6
+gzip-1.6
+zip-3.0
+…
+```
+
+To show all packages with “`firefox`” or “`chromium`” in the name:
+
+```console
+$ nix-env --query --available '.*(firefox|chromium).*'
+chromium-37.0.2062.94
+chromium-beta-38.0.2125.24
+firefox-32.0.3
+firefox-with-plugins-13.0.1
+…
+```
+
+To show all packages in the latest revision of the Nixpkgs repository:
+
+```console
+$ nix-env --file https://github.com/NixOS/nixpkgs/archive/master.tar.gz --query --available
+```
+