Mark stable release

.clang-format

@@ -8,7 +8,7 @@ BraceWrapping:
   AfterUnion: true
   SplitEmptyRecord: false
 PointerAlignment: Middle
-FixNamespaceComments: true
+FixNamespaceComments: false
 SortIncludes: Never
 #IndentPPDirectives: BeforeHash
 SpaceAfterCStyleCast: true
@@ -32,4 +32,3 @@ IndentPPDirectives: AfterHash
 PPIndentWidth: 2
 BinPackArguments: false
 BreakBeforeTernaryOperators: true
-SeparateDefinitionBlocks: Always

.coderabbit.yaml

@@ -1,18 +0,0 @@
-# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
-# Disable CodeRabbit auto-review to prevent verbose comments on PRs.
-# When enabled: false, CodeRabbit won't attempt reviews and won't post
-# "Review skipped" or other automated comments.
-reviews:
-  auto_review:
-    enabled: false
-  review_status: false
-  high_level_summary: false
-  poem: false
-  sequence_diagrams: false
-  changed_files_summary: false
-  tools:
-    github-checks:
-      enabled: false
-chat:
-  art: false
-  auto_reply: false

.git-blame-ignore-revs

@@ -1,6 +0,0 @@
-# bulk initial re-formatting with clang-format
-e4f62e46088919428a68bd8014201dc8e379fed7 # !autorebase ./maintainers/format.sh --until-stable
-# meson re-formatting
-385e2c3542c707d95e3784f7f6d623f67e77ab61 # !autorebase ./maintainers/format.sh --until-stable
-# nixfmt 1.0.0
-1d943f581908f35075a84a3d89c2eba3ff35067f # !autorebase ./maintainers/format.sh --until-stable

.github/CODEOWNERS

@@ -11,7 +11,16 @@
 .github/CODEOWNERS @edolstra
 
 # Documentation of built-in functions
-src/libexpr/primops.cc @roberth
+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

@@ -1,54 +1,36 @@
 ---
 name: Bug report
-about: Report unexpected or incorrect behaviour
+about: Create a report to help us improve
 title: ''
 labels: bug
 assignees: ''
 
 ---
 
-## Describe the bug
+**Describe the bug**
 
-<!--
-  A clear and concise description of what the bug is.
+A clear and concise description of what the bug is.
 
-  If you have a problem with a specific package or NixOS,
-  you probably want to file an issue at https://github.com/NixOS/nixpkgs/issues.
--->
+If you have a problem with a specific package or NixOS,
+you probably want to file an issue at https://github.com/NixOS/nixpkgs/issues. 
 
-## Steps To Reproduce
+**Steps To Reproduce**
 
-<!--
-  Example:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
 
-  1. Clone this repository: ...
-  2. Run `nix-... ...`
-  3. Observe unexpected behaviour
--->
+**Expected behavior**
 
-## Expected behavior
+A clear and concise description of what you expected to happen.
 
-<!-- A clear and concise description of what you expected to happen. -->
+**`nix-env --version` output**
 
-## Metadata
+**Additional context**
 
-<!-- Please insert the output of running `nix-env --version` below this line -->
+Add any other context about the problem here.
 
-## Additional context
-
-<!-- Add any other context about the problem here. -->
-
-## Checklist
-
-<!-- make sure this issue is not redundant or obsolete -->
-
-- [ ] checked [latest Nix manual] \([source])
-- [ ] checked [open bug issues and pull requests] for possible duplicates
-
-[latest Nix manual]: https://nix.dev/manual/nix/development/
-[source]: https://github.com/NixOS/nix/tree/master/doc/manual/source
-[open bug issues and pull requests]: https://github.com/NixOS/nix/labels/bug
-
----
+**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

@@ -1,39 +1,24 @@
 ---
 name: Feature request
-about: Suggest a new feature
+about: Suggest an idea for this project
 title: ''
 labels: feature
 assignees: ''
 
 ---
 
-## Is your feature request related to a problem?
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 
-<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
 
-## Proposed solution
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
 
-<!-- A clear and concise description of what you want to happen. -->
+**Additional context**
+Add any other context or screenshots about the feature request here.
 
-## Alternative solutions
-
-<!-- A clear and concise description of any alternative solutions or features you've considered. -->
-
-## Additional context
-
-<!-- Add any other context or screenshots about the feature request here. -->
-
-## Checklist
-
-<!-- make sure this issue is not redundant or obsolete -->
-
-- [ ] checked [latest Nix manual] \([source])
-- [ ] checked [open feature issues and pull requests] for possible duplicates
-
-[latest Nix manual]: https://nix.dev/manual/nix/development/
-[source]: https://github.com/NixOS/nix/tree/master/doc/manual/source
-[open feature issues and pull requests]: https://github.com/NixOS/nix/labels/feature
-
----
+**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

@@ -23,25 +23,14 @@ assignees: ''
 
 <details><summary>Output</summary>
 
-<!-- paste console output inside the below code block -->
-
 ```log
 
+<!-- paste console output here and remove this comment -->
+
 ```
 
 </details>
 
-## Checklist
-
-<!-- make sure this issue is not redundant or obsolete -->
-
-- [ ] checked [latest Nix manual] \([source])
-- [ ] checked [open installer issues and pull requests] for possible duplicates
-
-[latest Nix manual]: https://nix.dev/manual/nix/development/
-[source]: https://github.com/NixOS/nix/tree/master/doc/manual/source
-[open installer issues and pull requests]: https://github.com/NixOS/nix/labels/installer
-
----
+## 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

@@ -22,10 +22,10 @@ assignees: ''
 - [ ] checked [latest Nix manual] \([source])
 - [ ] checked [open documentation issues and pull requests] for possible duplicates
 
-[latest Nix manual]: https://nix.dev/manual/nix/development/
+[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

@@ -15,18 +15,12 @@ so you understand the process and the expectations.
 - volunteering contributions effectively
 - how to get help and our review process.
 
-PR stuck in review? We have two Nix team meetings per week online that are open for everyone in a jitsi conference:
-
-- https://calendar.google.com/calendar/u/0/embed?src=b9o52fobqjak8oq8lfkhg3t0qg@group.calendar.google.com
-
 -->
 
-## Motivation
-
+# Motivation
 <!-- Briefly explain what the change is about and why it is desirable. -->
 
-## Context
-
+# Context
 <!-- Provide context. Reference open issues if available. -->
 
 <!-- Non-trivial change: Briefly outline the implementation strategy. -->
@@ -35,7 +29,7 @@ PR stuck in review? We have two Nix team meetings per week online that are open
 
 <!-- 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).
 

.github/STALE-BOT.md

@@ -3,7 +3,7 @@
 - Thanks for your contribution!
 - To remove the stale label, just leave a new comment.
 - _How to find the right people to ping?_ → [`git blame`](https://git-scm.com/docs/git-blame) to the rescue! (or GitHub's history and blame buttons.)
-- You can always ask for help on [our Discourse Forum](https://discourse.nixos.org/) or on [Matrix - #users:nixos.org](https://matrix.to/#/#users:nixos.org).
+- You can always ask for help on [our Discourse Forum](https://discourse.nixos.org/) or on [Matrix - #nix:nixos.org](https://matrix.to/#/#nix:nixos.org).
 
 ## Suggestions for PRs
 

.github/actions/install-nix-action/action.yaml

@@ -1,131 +0,0 @@
-name: "Install Nix"
-description: "Helper action for installing Nix with support for dogfooding from master"
-inputs:
-  dogfood:
-    description: "Whether to use Nix installed from the latest artifact from master branch"
-    required: true # Be explicit about the fact that we are using unreleased artifacts
-  experimental-installer:
-    description: "Whether to use the experimental installer to install Nix"
-    default: false
-  experimental-installer-version:
-    description: "Version of the experimental installer to use. If `latest`, the newest artifact from the default branch is used."
-    # TODO: This should probably be pinned to a release after https://github.com/NixOS/experimental-nix-installer/pull/49 lands in one
-    default: "latest"
-  extra_nix_config:
-    description: "Gets appended to `/etc/nix/nix.conf` if passed."
-  install_url:
-    description: "URL of the Nix installer"
-    required: false
-    default: "https://releases.nixos.org/nix/nix-2.32.1/install"
-  tarball_url:
-    description: "URL of the Nix tarball to use with the experimental installer"
-    required: false
-  github_token:
-    description: "Github token"
-    required: true
-  use_cache:
-    description: "Whether to setup magic-nix-cache"
-    default: true
-    required: false
-runs:
-  using: "composite"
-  steps:
-    - name: "Download nix install artifact from master"
-      shell: bash
-      id: download-nix-installer
-      if: inputs.dogfood == 'true'
-      run: |
-        RUN_ID=$(gh run list --repo "$DOGFOOD_REPO" --workflow ci.yml --branch master --status success --json databaseId --jq ".[0].databaseId")
-
-        if [ "$RUNNER_OS" == "Linux" ]; then
-          INSTALLER_ARTIFACT="installer-linux"
-        elif [ "$RUNNER_OS" == "macOS" ]; then
-          INSTALLER_ARTIFACT="installer-darwin"
-        else
-          echo "::error ::Unsupported RUNNER_OS: $RUNNER_OS"
-          exit 1
-        fi
-
-        INSTALLER_DOWNLOAD_DIR="$GITHUB_WORKSPACE/$INSTALLER_ARTIFACT"
-        mkdir -p "$INSTALLER_DOWNLOAD_DIR"
-
-        gh run download "$RUN_ID" --repo "$DOGFOOD_REPO" -n "$INSTALLER_ARTIFACT" -D "$INSTALLER_DOWNLOAD_DIR"
-        echo "installer-path=file://$INSTALLER_DOWNLOAD_DIR" >> "$GITHUB_OUTPUT"
-        TARBALL_PATH="$(find "$INSTALLER_DOWNLOAD_DIR" -name 'nix*.tar.xz' -print | head -n 1)"
-        echo "tarball-path=file://$TARBALL_PATH" >> "$GITHUB_OUTPUT"
-
-        echo "::notice ::Dogfooding Nix installer from master (https://github.com/$DOGFOOD_REPO/actions/runs/$RUN_ID)"
-      env:
-        GH_TOKEN: ${{ inputs.github_token }}
-        DOGFOOD_REPO: "NixOS/nix"
-    - name: "Gather system info for experimental installer"
-      shell: bash
-      if: ${{ inputs.experimental-installer == 'true' }}
-      run: |
-        echo "::notice Using experimental installer from $EXPERIMENTAL_INSTALLER_REPO (https://github.com/$EXPERIMENTAL_INSTALLER_REPO)"
-
-        if [ "$RUNNER_OS" == "Linux" ]; then
-          EXPERIMENTAL_INSTALLER_SYSTEM="linux"
-          echo "EXPERIMENTAL_INSTALLER_SYSTEM=$EXPERIMENTAL_INSTALLER_SYSTEM" >> "$GITHUB_ENV"
-        elif [ "$RUNNER_OS" == "macOS" ]; then
-          EXPERIMENTAL_INSTALLER_SYSTEM="darwin"
-          echo "EXPERIMENTAL_INSTALLER_SYSTEM=$EXPERIMENTAL_INSTALLER_SYSTEM" >> "$GITHUB_ENV"
-        else
-          echo "::error ::Unsupported RUNNER_OS: $RUNNER_OS"
-          exit 1
-        fi
-
-        if [ "$RUNNER_ARCH" == "X64" ]; then
-          EXPERIMENTAL_INSTALLER_ARCH=x86_64
-          echo "EXPERIMENTAL_INSTALLER_ARCH=$EXPERIMENTAL_INSTALLER_ARCH" >> "$GITHUB_ENV"
-        elif [ "$RUNNER_ARCH" == "ARM64" ]; then
-          EXPERIMENTAL_INSTALLER_ARCH=aarch64
-          echo "EXPERIMENTAL_INSTALLER_ARCH=$EXPERIMENTAL_INSTALLER_ARCH" >> "$GITHUB_ENV"
-        else
-          echo "::error ::Unsupported RUNNER_ARCH: $RUNNER_ARCH"
-          exit 1
-        fi
-
-        echo "EXPERIMENTAL_INSTALLER_ARTIFACT=nix-installer-$EXPERIMENTAL_INSTALLER_ARCH-$EXPERIMENTAL_INSTALLER_SYSTEM" >> "$GITHUB_ENV"
-      env:
-        EXPERIMENTAL_INSTALLER_REPO: "NixOS/experimental-nix-installer"
-    - name: "Download latest experimental installer"
-      shell: bash
-      id: download-latest-experimental-installer
-      if: ${{ inputs.experimental-installer == 'true' && inputs.experimental-installer-version == 'latest' }}
-      run: |
-        RUN_ID=$(gh run list --repo "$EXPERIMENTAL_INSTALLER_REPO" --workflow ci.yml --branch main --status success --json databaseId --jq ".[0].databaseId")
-
-        EXPERIMENTAL_INSTALLER_DOWNLOAD_DIR="$GITHUB_WORKSPACE/$EXPERIMENTAL_INSTALLER_ARTIFACT"
-        mkdir -p "$EXPERIMENTAL_INSTALLER_DOWNLOAD_DIR"
-
-        gh run download "$RUN_ID" --repo "$EXPERIMENTAL_INSTALLER_REPO" -n "$EXPERIMENTAL_INSTALLER_ARTIFACT" -D "$EXPERIMENTAL_INSTALLER_DOWNLOAD_DIR"
-        # Executable permissions are lost in artifacts
-        find $EXPERIMENTAL_INSTALLER_DOWNLOAD_DIR -type f -exec chmod +x {} +
-        echo "installer-path=$EXPERIMENTAL_INSTALLER_DOWNLOAD_DIR" >> "$GITHUB_OUTPUT"
-      env:
-        GH_TOKEN: ${{ inputs.github_token }}
-        EXPERIMENTAL_INSTALLER_REPO: "NixOS/experimental-nix-installer"
-    - uses: cachix/install-nix-action@c134e4c9e34bac6cab09cf239815f9339aaaf84e # v31.5.1
-      if: ${{ inputs.experimental-installer != 'true' }}
-      with:
-        # Ternary operator in GHA: https://www.github.com/actions/runner/issues/409#issuecomment-752775072
-        install_url: ${{ inputs.dogfood == 'true' && format('{0}/install', steps.download-nix-installer.outputs.installer-path) || inputs.install_url }}
-        install_options: ${{ inputs.dogfood == 'true' && format('--tarball-url-prefix {0}', steps.download-nix-installer.outputs.installer-path) || '' }}
-        extra_nix_config: ${{ inputs.extra_nix_config }}
-    - uses: DeterminateSystems/nix-installer-action@786fff0690178f1234e4e1fe9b536e94f5433196 # v20
-      if: ${{ inputs.experimental-installer == 'true' }}
-      with:
-        diagnostic-endpoint: ""
-        # TODO: It'd be nice to use `artifacts.nixos.org` for both of these, maybe through an `/experimental-installer/latest` endpoint? or `/commit/<hash>`?
-        local-root: ${{ inputs.experimental-installer-version == 'latest' && steps.download-latest-experimental-installer.outputs.installer-path || '' }}
-        source-url: ${{ inputs.experimental-installer-version != 'latest' && 'https://artifacts.nixos.org/experimental-installer/tag/${{ inputs.experimental-installer-version }}/${{ env.EXPERIMENTAL_INSTALLER_ARTIFACT }}' || '' }}
-        nix-package-url: ${{ inputs.dogfood == 'true' && steps.download-nix-installer.outputs.tarball-path || (inputs.tarball_url || '') }}
-        extra-conf: ${{ inputs.extra_nix_config }}
-    - uses: DeterminateSystems/magic-nix-cache-action@565684385bcd71bad329742eefe8d12f2e765b39 # v13
-      if: ${{ inputs.use_cache == 'true' }}
-      with:
-        diagnostic-endpoint: ''
-        use-flakehub: false
-        use-gha-cache: true
-        source-revision: 92d9581367be2233c2d5714a2640e1339f4087d8 # main

.github/workflows/backport.yml

@@ -1,37 +0,0 @@
-name: Backport
-on:
-  pull_request_target:
-    types: [closed, labeled]
-permissions:
-  contents: read
-jobs:
-  backport:
-    name: Backport Pull Request
-    permissions:
-      # for korthout/backport-action
-      contents: write
-      pull-requests: write
-    if: github.repository_owner == 'NixOS' && github.event.pull_request.merged == true && (github.event_name != 'labeled' || startsWith('backport', github.event.label.name))
-    runs-on: ubuntu-24.04-arm
-    steps:
-      - name: Generate GitHub App token
-        id: generate-token
-        uses: actions/create-github-app-token@v2
-        with:
-          app-id: ${{ vars.CI_APP_ID }}
-          private-key: ${{ secrets.CI_APP_PRIVATE_KEY }}
-      - uses: actions/checkout@v5
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          # required to find all branches
-          fetch-depth: 0
-      - name: Create backport PRs
-        uses: korthout/backport-action@d07416681cab29bf2661702f925f020aaa962997 # v3.4.1
-        id: backport
-        with:
-          # Config README: https://github.com/korthout/backport-action#backport-action
-          github_token: ${{ steps.generate-token.outputs.token }}
-          github_workspace: ${{ github.workspace }}
-          auto_merge_enabled: true
-          pull_description: |-
-            Automatic backport to `${target_branch}`, triggered by a label in #${pull_number}.

.github/workflows/ci.yml

@@ -2,194 +2,124 @@ name: "CI"
 
 on:
   pull_request:
-  merge_group:
   push:
-    branches:
-      - master
-  workflow_dispatch:
-    inputs:
-      dogfood:
-        description: 'Use dogfood Nix build'
-        required: false
-        default: true
-        type: boolean
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
 
 permissions: read-all
 
 jobs:
-  eval:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v5
-      with:
-        fetch-depth: 0
-    - uses: ./.github/actions/install-nix-action
-      with:
-        dogfood: ${{ github.event_name == 'workflow_dispatch' && inputs.dogfood || github.event_name != 'workflow_dispatch' }}
-        extra_nix_config:
-          experimental-features = nix-command flakes
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        use_cache: false
-    - run: nix flake show --all-systems --json
-
-  pre-commit-checks:
-    name: pre-commit checks
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v5
-      - uses: ./.github/actions/install-nix-action
-        with:
-          dogfood: ${{ github.event_name == 'workflow_dispatch' && inputs.dogfood || github.event_name != 'workflow_dispatch' }}
-          extra_nix_config: experimental-features = nix-command flakes
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-      - run: ./ci/gha/tests/pre-commit-checks
-
-  basic-checks:
-    name: aggregate basic checks
-    if: ${{ always() }}
-    runs-on: ubuntu-24.04
-    needs: [pre-commit-checks, eval]
-    steps:
-      - name: Exit with any errors
-        if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
-        run: |
-          exit 1
 
   tests:
-    needs: basic-checks
+    needs: [check_secrets]
     strategy:
       fail-fast: false
       matrix:
-        include:
-          - scenario: on ubuntu
-            runs-on: ubuntu-24.04
-            os: linux
-            instrumented: false
-            primary: true
-            stdenv: stdenv
-          - scenario: on macos
-            runs-on: macos-14
-            os: darwin
-            instrumented: false
-            primary: true
-            stdenv: stdenv
-          - scenario: on ubuntu (with sanitizers / coverage)
-            runs-on: ubuntu-24.04
-            os: linux
-            instrumented: true
-            primary: false
-            stdenv: clangStdenv
-    name: tests ${{ matrix.scenario }}
-    runs-on: ${{ matrix.runs-on }}
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
     timeout-minutes: 60
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: ./.github/actions/install-nix-action
+    - uses: cachix/install-nix-action@v30
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        dogfood: ${{ github.event_name == 'workflow_dispatch' && inputs.dogfood || github.event_name != 'workflow_dispatch' }}
         # The sandbox would otherwise be disabled by default on Darwin
         extra_nix_config: "sandbox = true"
-    # Since ubuntu 22.30, unprivileged usernamespaces are no longer allowed to map to the root user:
-    # https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces
-    - run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
-      if: matrix.os == 'linux'
-    - name: Run component tests
-      run: |
-        nix build --file ci/gha/tests/wrapper.nix componentTests -L \
-          --arg withInstrumentation ${{ matrix.instrumented }} \
-          --argstr stdenv "${{ matrix.stdenv }}"
-    - name: Run VM tests
-      run: |
-        nix build --file ci/gha/tests/wrapper.nix vmTests -L \
-          --arg withInstrumentation ${{ matrix.instrumented }} \
-          --argstr stdenv "${{ matrix.stdenv }}"
-      if: ${{ matrix.os == 'linux' }}
-    - name: Run flake checks and prepare the installer tarball
-      run: |
-        ci/gha/tests/build-checks
-        ci/gha/tests/prepare-installer-for-github-actions
-      if: ${{ matrix.primary }}
-    - name: Collect code coverage
-      run: |
-        nix build --file ci/gha/tests/wrapper.nix codeCoverage.coverageReports -L \
-          --arg withInstrumentation ${{ matrix.instrumented }} \
-          --argstr stdenv "${{ matrix.stdenv }}" \
-          --out-link coverage-reports
-        cat coverage-reports/index.txt >> $GITHUB_STEP_SUMMARY
-      if: ${{ matrix.instrumented }}
-    - name: Upload coverage reports
-      uses: actions/upload-artifact@v5
+    - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
+    - uses: cachix/cachix-action@v15
+      if: needs.check_secrets.outputs.cachix == 'true'
       with:
-        name: coverage-reports
-        path: coverage-reports/
-      if: ${{ matrix.instrumented }}
-    - name: Upload installer tarball
-      uses: actions/upload-artifact@v5
+        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
+
+  # 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: Check Cachix and Docker secrets present for installer tests
+    runs-on: ubuntu-latest
+    outputs:
+      cachix: ${{ steps.secret.outputs.cachix }}
+      docker: ${{ steps.secret.outputs.docker }}
+    steps:
+      - name: Check for secrets
+        id: secret
+        env:
+          _CACHIX_SECRETS: ${{ secrets.CACHIX_SIGNING_KEY }}${{ secrets.CACHIX_AUTH_TOKEN }}
+          _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_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@v4
       with:
-        name: installer-${{matrix.os}}
-        path: out/*
-      if: ${{ matrix.primary }}
+        fetch-depth: 0
+    - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
+    - 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: [tests]
+    needs: [installer, check_secrets]
+    if: github.event_name == 'push' && needs.check_secrets.outputs.cachix == 'true'
     strategy:
       fail-fast: false
       matrix:
-        include:
-          - scenario: on ubuntu
-            runs-on: ubuntu-24.04
-            os: linux
-            experimental-installer: false
-          - scenario: on macos
-            runs-on: macos-14
-            os: darwin
-            experimental-installer: false
-          - scenario: on ubuntu (experimental)
-            runs-on: ubuntu-24.04
-            os: linux
-            experimental-installer: true
-          - scenario: on macos (experimental)
-            runs-on: macos-14
-            os: darwin
-            experimental-installer: true
-    name: installer test ${{ matrix.scenario }}
-    runs-on: ${{ matrix.runs-on }}
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v5
-    - name: Download installer tarball
-      uses: actions/download-artifact@v6
+    - 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@v30
       with:
-        name: installer-${{matrix.os}}
-        path: out
-    - name: Looking up the installer tarball URL
-      id: installer-tarball-url
-      run: |
-        echo "installer-url=file://$GITHUB_WORKSPACE/out" >> "$GITHUB_OUTPUT"
-        TARBALL_PATH="$(find "$GITHUB_WORKSPACE/out" -name 'nix*.tar.xz' -print | head -n 1)"
-        echo "tarball-path=file://$TARBALL_PATH" >> "$GITHUB_OUTPUT"
-    - uses: cachix/install-nix-action@0b0e072294b088b73964f1d72dfdac0951439dbd # v31.8.4
-      if: ${{ !matrix.experimental-installer }}
-      with:
-        install_url: ${{ format('{0}/install', steps.installer-tarball-url.outputs.installer-url) }}
-        install_options: ${{ format('--tarball-url-prefix {0}', steps.installer-tarball-url.outputs.installer-url) }}
-    - uses: ./.github/actions/install-nix-action
-      if: ${{ matrix.experimental-installer }}
-      with:
-        dogfood: false
-        experimental-installer: true
-        tarball_url: ${{ steps.installer-tarball-url.outputs.tarball-path }}
-        github_token: ${{ secrets.GITHUB_TOKEN }}
+        install_url: '${{needs.installer.outputs.installerURL}}'
+        install_options: "--tarball-url-prefix https://${{ env.CACHIX_NAME }}.cachix.org/serve"
     - run: sudo apt install fish zsh
-      if: matrix.os == 'linux'
+      if: matrix.os == 'ubuntu-latest'
     - run: brew install fish
-      if: matrix.os == 'darwin'
+      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"
@@ -197,46 +127,33 @@ jobs:
     - 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"
 
-  # Steps to test CI automation in your own fork.
-  # 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: Check presence of secrets
-    runs-on: ubuntu-24.04
-    outputs:
-      docker: ${{ steps.secret.outputs.docker }}
-    steps:
-      - name: Check for DockerHub secrets
-        id: secret
-        env:
-          _DOCKER_SECRETS: ${{ secrets.DOCKERHUB_USERNAME }}${{ secrets.DOCKERHUB_TOKEN }}
-        run: |
-          echo "docker=${{ env._DOCKER_SECRETS != '' }}" >> $GITHUB_OUTPUT
-
   docker_push_image:
-    needs: [tests, check_secrets]
+    needs: [check_secrets, tests]
     permissions:
       contents: read
       packages: write
     if: >-
-      needs.check_secrets.outputs.docker == 'true' &&
       github.event_name == 'push' &&
-      github.ref_name == 'master'
-    runs-on: ubuntu-24.04
+      github.ref_name == 'master' &&
+      needs.check_secrets.outputs.cachix == 'true' &&
+      needs.check_secrets.outputs.docker == 'true'
+    runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: ./.github/actions/install-nix-action
+    - uses: cachix/install-nix-action@v30
       with:
-        dogfood: false
-        extra_nix_config: |
-          experimental-features = flakes nix-command
-    - run: echo NIX_VERSION="$(nix eval .\#nix.version | tr -d \")" >> $GITHUB_ENV
-    - run: nix build .#dockerImage -L
+        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 .\#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 ${{ secrets.DOCKERHUB_USERNAME }}/nix:$NIX_VERSION
     - run: docker tag nix:$NIX_VERSION ${{ secrets.DOCKERHUB_USERNAME }}/nix:master
@@ -271,48 +188,30 @@ jobs:
         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: tests
-    runs-on: ubuntu-24.04
+    needs: vm_tests
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout nix
-        uses: actions/checkout@v5
+        uses: actions/checkout@v4
       - name: Checkout flake-regressions
-        uses: actions/checkout@v5
+        uses: actions/checkout@v4
         with:
           repository: NixOS/flake-regressions
           path: flake-regressions
       - name: Checkout flake-regressions-data
-        uses: actions/checkout@v5
+        uses: actions/checkout@v4
         with:
           repository: NixOS/flake-regressions-data
           path: flake-regressions/tests
-      - uses: ./.github/actions/install-nix-action
-        with:
-          dogfood: ${{ github.event_name == 'workflow_dispatch' && inputs.dogfood || github.event_name != 'workflow_dispatch' }}
-          extra_nix_config:
-            experimental-features = nix-command flakes
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-      - run: nix build -L --out-link ./new-nix && PATH=$(pwd)/new-nix/bin:$PATH MAX_FLAKES=25 flake-regressions/eval-all.sh
-
-  profile_build:
-    needs: tests
-    runs-on: ubuntu-24.04
-    timeout-minutes: 60
-    if: >-
-      github.event_name == 'push' &&
-      github.ref_name == 'master'
-    steps:
-    - uses: actions/checkout@v5
-      with:
-        fetch-depth: 0
-    - uses: ./.github/actions/install-nix-action
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        dogfood: ${{ github.event_name == 'workflow_dispatch' && inputs.dogfood || github.event_name != 'workflow_dispatch' }}
-        extra_nix_config: |
-          experimental-features = flakes nix-command ca-derivations impure-derivations
-          max-jobs = 1
-    - run: |
-        nix build -L --file ./ci/gha/profile-build buildTimeReport --out-link build-time-report.md
-        cat build-time-report.md >> $GITHUB_STEP_SUMMARY
+      - 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/labels.yml

@@ -15,10 +15,10 @@ permissions:
 
 jobs:
   labels:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     if: github.repository_owner == 'NixOS'
     steps:
-    - uses: actions/labeler@v6
+    - uses: actions/labeler@v5
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         sync-labels: false

.gitignore

@@ -1,12 +1,113 @@
+Makefile.config
+perl/Makefile.config
+
+# /
+/aclocal.m4
+/autom4te.cache
+/precompiled-headers.h.gch
+/config.*
+/configure
+/stamp-h1
+/svn-revision
+/libtool
+/config/config.*
 # Default meson build dir
 /build
 
+# /doc/manual/
+/doc/manual/*.1
+/doc/manual/*.5
+/doc/manual/*.8
+/doc/manual/generated/*
+/doc/manual/nix.json
+/doc/manual/conf-file.json
+/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
+/src/libexpr/lexer-tab.hh
+/src/libexpr/parser-tab.cc
+/src/libexpr/parser-tab.hh
+/src/libexpr/parser-tab.output
+/src/libexpr/nix.tbl
+/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
+/src/libstore-tests/libnixstore-tests
+
+# /src/libutil/
+/src/libutil/tests
+/src/libutil-tests/libnixutil-tests
+
+/src/nix/nix
+
+/src/nix/generated-doc
+
+# /src/nix-env/
+/src/nix-env/nix-env
+
+# /src/nix-instantiate/
+/src/nix-instantiate/nix-instantiate
+
+# /src/nix-store/
+/src/nix-store/nix-store
+
+/src/nix-prefetch-url/nix-prefetch-url
+
+/src/nix-collect-garbage/nix-collect-garbage
+
+# /src/nix-channel/
+/src/nix-channel/nix-channel
+
+# /src/nix-build/
+/src/nix-build/nix-build
+
+/src/nix-copy-closure/nix-copy-closure
+
+/src/error-demo/error-demo
+
+/src/build-remote/build-remote
+
 # /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/functional/nix-shell
 
 # /tests/functional/lang/
 /tests/functional/lang/*.out
@@ -14,9 +115,27 @@
 /tests/functional/lang/*.err
 /tests/functional/lang/*.ast
 
-/outputs
+/perl/lib/Nix/Config.pm
+/perl/lib/Nix/Store.cc
 
+/misc/systemd/nix-daemon.service
+/misc/systemd/nix-daemon.socket
+/misc/systemd/nix-daemon.conf
+/misc/upstart/nix-daemon.conf
+
+outputs/
+
+*.a
+*.o
+*.o.tmp
+*.so
+*.dylib
+*.dll
+*.exe
+*.dep
 *~
+*.pc
+*.plist
 
 # GNU Global
 GPATH
@@ -31,6 +150,8 @@ GTAGS
 compile_commands.json
 *.compile_commands.json
 
+nix-rust/target
+
 result
 result-*
 
@@ -45,8 +166,3 @@ result-*
 
 # Mac OS
 .DS_Store
-
-flake-regressions
-
-# direnv
-.direnv/

.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

.version

@@ -1 +1 @@
-2.33.0
+2.25.0

CONTRIBUTING.md

@@ -89,7 +89,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
 
 ## Making changes to the Nix manual
 
-The Nix reference manual is hosted on https://nix.dev/manual/nix.
+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).

COPYING

@@ -1,8 +1,8 @@
-                  GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 2.1, February 1999
+		  GNU LESSER GENERAL PUBLIC LICENSE
+		       Version 2.1, February 1999
 
  Copyright (C) 1991, 1999 Free Software Foundation, Inc.
- <https://fsf.org/>
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 
@@ -10,7 +10,7 @@
  as the successor of the GNU Library Public License, version 2, hence
  the version number 2.1.]
 
-                            Preamble
+			    Preamble
 
   The licenses for most software are designed to take away your
 freedom to share and change it.  By contrast, the GNU General Public
@@ -112,7 +112,7 @@ modification follow.  Pay close attention to the difference between a
 former contains code derived from the library, whereas the latter must
 be combined with the library in order to run.
 
-                  GNU LESSER GENERAL PUBLIC LICENSE
+		  GNU LESSER GENERAL PUBLIC LICENSE
    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
   0. This License Agreement applies to any software library or other
@@ -146,7 +146,7 @@ such a program is covered only if its contents constitute a work based
 on the Library (independent of the use of the Library in a tool for
 writing it).  Whether that is true depends on what the Library does
 and what the program that uses the Library does.
-
+  
   1. You may copy and distribute verbatim copies of the Library's
 complete source code as you receive it, in any medium, provided that
 you conspicuously and appropriately publish on each copy an
@@ -432,7 +432,7 @@ decision will be guided by the two goals of preserving the free status
 of all derivatives of our free software and of promoting the sharing
 and reuse of software generally.
 
-                            NO WARRANTY
+			    NO WARRANTY
 
   15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
@@ -455,7 +455,7 @@ FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
 DAMAGES.
 
-                     END OF TERMS AND CONDITIONS
+		     END OF TERMS AND CONDITIONS
 
            How to Apply These Terms to Your New Libraries
 
@@ -484,7 +484,8 @@ convey the exclusion of warranty; and each file should have at least the
     Lesser General Public License for more details.
 
     You should have received a copy of the GNU Lesser General Public
-    License along with this library; if not, see <https://www.gnu.org/licenses/>.
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 Also add information on how to contact you by electronic and paper mail.
 
@@ -495,7 +496,9 @@ necessary.  Here is a sample; alter the names:
   Yoyodyne, Inc., hereby disclaims all copyright interest in the
   library `Frob' (a library for tweaking knobs) written by James Random Hacker.
 
-  <signature of Moe Ghoul>, 1 April 1990
-  Moe Ghoul, President of Vice
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
 
 That's all there is to it!
+
+

Makefile

@@ -0,0 +1,129 @@
+# 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/libstore/local.mk \
+  src/libfetchers/local.mk \
+  src/libmain/local.mk \
+  src/libexpr/local.mk \
+  src/libflake/local.mk \
+  src/libcmd/local.mk \
+  src/nix/local.mk \
+  src/libutil-c/local.mk \
+  src/libstore-c/local.mk \
+  src/libexpr-c/local.mk
+
+ifdef HOST_UNIX
+makefiles += \
+  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
+endif
+endif
+
+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
+
+ifeq ($(OPTIMIZE), 1)
+  GLOBAL_CXXFLAGS += -O3 $(CXXLTO)
+  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
+
+# 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

@@ -0,0 +1,54 @@
+AR = @AR@
+BDW_GC_LIBS = @BDW_GC_LIBS@
+BOOST_LDFLAGS = @BOOST_LDFLAGS@
+BUILD_SHARED_LIBS = @BUILD_SHARED_LIBS@
+CC = @CC@
+CFLAGS = @CFLAGS@
+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@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+SHELL = @bash@
+SODIUM_LIBS = @SODIUM_LIBS@
+SQLITE3_LIBS = @SQLITE3_LIBS@
+bash = @bash@
+bindir = @bindir@
+checkbindir = @checkbindir@
+checklibdir = @checklibdir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+embedded_sandbox_shell = @embedded_sandbox_shell@
+exec_prefix = @exec_prefix@
+includedir = @includedir@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localstatedir = @localstatedir@
+lsof = @lsof@
+mandir = @mandir@
+pkglibdir = $(libdir)/$(PACKAGE_NAME)
+prefix = @prefix@
+sandbox_shell = @sandbox_shell@
+storedir = @storedir@
+sysconfdir = @sysconfdir@
+system = @system@

README.md

@@ -31,7 +31,7 @@ Today, a world-wide developer community contributes to Nix and the ecosystem tha
 - [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: [#users:nixos.org](https://matrix.to/#/#users:nixos.org) for user support and [#nix-dev:nixos.org](https://matrix.to/#/#nix-dev:nixos.org) for development
+- [Matrix](https://matrix.to/#/#nix:nixos.org)
 
 ## License
 

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

@@ -6,7 +6,7 @@
 # *interface*.
 #
 # See `man pkg-config` for some details.
-deps_private = []
+deps_private = [ ]
 
 # These are public dependencies with pkg-config files. Public is the
 # opposite of private: these dependencies are used in installed header
@@ -23,14 +23,14 @@ deps_private = []
 # 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 = []
+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 = []
+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 = []
+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

@@ -5,7 +5,7 @@ if host_machine.system() == 'cygwin' or host_machine.system() == 'windows'
   # 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' ]
+  linker_export_flags = ['-Wl,--export-all-symbols']
 else
   linker_export_flags = []
 endif

build-utils-meson/export/meson.build

@@ -1,41 +1,33 @@
 requires_private = []
 foreach dep : deps_private_subproject
-  requires_private += dep.name()
+  requires_private  += dep.name()
 endforeach
 requires_private += deps_private
 
-requires_public = []
+requires_public  = []
 foreach dep : deps_public_subproject
-  requires_public += dep.name()
+  requires_public  += dep.name()
 endforeach
 requires_public += deps_public
 
 extra_pkg_config_variables = get_variable('extra_pkg_config_variables', {})
-
-extra_cflags = []
-if not meson.project_name().endswith('-c')
-  extra_cflags += [ '-std=c++23' ]
-endif
-
 import('pkgconfig').generate(
   this_library,
   filebase : meson.project_name(),
   name : 'Nix',
   description : 'Nix Package Manager',
-  extra_cflags : extra_cflags,
+  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++23' ],
-    dependencies : deps_public_subproject + deps_public,
-    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/libatomic/meson.build

@@ -3,6 +3,6 @@
 # This is needed for std::atomic on some platforms
 # We did not manage to test this reliably on all platforms, so we hardcode
 # it for now.
-if host_machine.cpu_family() in [ 'arm', 'ppc' ]
+if host_machine.cpu_family() == 'arm'
   deps_other += cxx.find_library('atomic')
 endif

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

@@ -2,5 +2,5 @@ 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')
+  add_project_arguments([ '-D_WIN32_WINNT=0x0602' ], language: 'cpp')
 endif

ci/gha/profile-build/default.nix

@@ -1,101 +0,0 @@
-{
-  nixFlake ? builtins.getFlake ("git+file://" + toString ../../..),
-  system ? builtins.currentSystem,
-  pkgs ? nixFlake.inputs.nixpkgs.legacyPackages.${system},
-}:
-
-let
-  inherit (pkgs) lib;
-
-  nixComponentsInstrumented =
-    (nixFlake.lib.makeComponents {
-      inherit pkgs;
-      getStdenv = p: p.clangStdenv;
-    }).overrideScope
-      (
-        _: _: {
-          mesonComponentOverrides = finalAttrs: prevAttrs: {
-            outputs = (prevAttrs.outputs or [ "out" ]) ++ [ "buildprofile" ];
-            nativeBuildInputs = [ pkgs.clangbuildanalyzer ] ++ prevAttrs.nativeBuildInputs or [ ];
-            __impure = true;
-
-            env = {
-              CFLAGS = "-ftime-trace";
-              CXXFLAGS = "-ftime-trace";
-            };
-
-            preBuild = ''
-              ClangBuildAnalyzer --start $PWD
-            '';
-
-            postBuild = ''
-              ClangBuildAnalyzer --stop $PWD $buildprofile
-            '';
-          };
-        }
-      );
-
-  componentsToProfile = {
-    "nix-util" = { };
-    "nix-util-c" = { };
-    "nix-util-test-support" = { };
-    "nix-util-tests" = { };
-    "nix-store" = { };
-    "nix-store-c" = { };
-    "nix-store-test-support" = { };
-    "nix-store-tests" = { };
-    "nix-fetchers" = { };
-    "nix-fetchers-c" = { };
-    "nix-fetchers-tests" = { };
-    "nix-expr" = { };
-    "nix-expr-c" = { };
-    "nix-expr-test-support" = { };
-    "nix-expr-tests" = { };
-    "nix-flake" = { };
-    "nix-flake-c" = { };
-    "nix-flake-tests" = { };
-    "nix-main" = { };
-    "nix-main-c" = { };
-    "nix-cmd" = { };
-    "nix-cli" = { };
-  };
-
-  componentDerivationsToProfile = builtins.intersectAttrs componentsToProfile nixComponentsInstrumented;
-  componentBuildProfiles = lib.mapAttrs (
-    n: v: lib.getOutput "buildprofile" v
-  ) componentDerivationsToProfile;
-
-  buildTimeReport =
-    pkgs.runCommand "build-time-report"
-      {
-        __impure = true;
-        __structuredAttrs = true;
-        nativeBuildInputs = [ pkgs.clangbuildanalyzer ];
-        inherit componentBuildProfiles;
-      }
-      ''
-        {
-          echo "# Build time performance profile for components:"
-          echo
-          echo "This reports the build profile collected via \`-ftime-trace\` for each component."
-          echo
-        } >> $out
-
-        for name in "''\${!componentBuildProfiles[@]}"; do
-          {
-            echo "<details><summary><strong>$name</strong></summary>"
-            echo
-            echo '````'
-            ClangBuildAnalyzer --analyze "''\${componentBuildProfiles[$name]}"
-            echo '````'
-            echo
-            echo "</details>"
-          } >> $out
-        done
-      '';
-in
-
-{
-  inherit buildTimeReport;
-  inherit componentDerivationsToProfile;
-}

ci/gha/tests/build-checks

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-system=$(nix eval --raw --impure --expr builtins.currentSystem)
-nix eval --json ".#checks.$system" --apply builtins.attrNames | \
-  jq -r '.[]' | \
-  xargs -P0 -I '{}' sh -c "nix build -L .#checks.$system.{} || { echo 'FAILED: \033[0;31mnix build -L .#checks.$system.{}\\033[0m'; kill 0; }"

ci/gha/tests/default.nix

@@ -1,257 +0,0 @@
-{
-  nixFlake ? builtins.getFlake ("git+file://" + toString ../../..),
-  system ? builtins.currentSystem,
-  pkgs ? nixFlake.inputs.nixpkgs.legacyPackages.${system},
-  nixComponents ? (
-    nixFlake.lib.makeComponents {
-      inherit pkgs;
-      inherit getStdenv;
-    }
-  ),
-  getStdenv ? p: p.stdenv,
-  componentTestsPrefix ? "",
-  withSanitizers ? false,
-  withCoverage ? false,
-  ...
-}:
-
-let
-  inherit (pkgs) lib;
-  hydraJobs = nixFlake.hydraJobs;
-  packages' = nixFlake.packages.${system};
-  stdenv = (getStdenv pkgs);
-
-  collectCoverageLayer = finalAttrs: prevAttrs: {
-    env =
-      let
-        # https://clang.llvm.org/docs/SourceBasedCodeCoverage.html#the-code-coverage-workflow
-        coverageFlags = [
-          "-fprofile-instr-generate"
-          "-fcoverage-mapping"
-        ];
-      in
-      {
-        CFLAGS = toString coverageFlags;
-        CXXFLAGS = toString coverageFlags;
-      };
-
-    # Done in a pre-configure hook, because $NIX_BUILD_TOP needs to be substituted.
-    preConfigure = prevAttrs.preConfigure or "" + ''
-      mappingFlag=" -fcoverage-prefix-map=$NIX_BUILD_TOP/${finalAttrs.src.name}=${finalAttrs.src}"
-      CFLAGS+="$mappingFlag"
-      CXXFLAGS+="$mappingFlag"
-    '';
-  };
-
-  componentOverrides = (lib.optional withCoverage collectCoverageLayer);
-in
-
-rec {
-  nixComponentsInstrumented = nixComponents.overrideScope (
-    final: prev: {
-      withASan = withSanitizers;
-      withUBSan = withSanitizers;
-
-      nix-store-tests = prev.nix-store-tests.override { withBenchmarks = true; };
-      # Boehm is incompatible with ASAN.
-      nix-expr = prev.nix-expr.override { enableGC = !withSanitizers; };
-
-      mesonComponentOverrides = lib.composeManyExtensions componentOverrides;
-      # Unclear how to make Perl bindings work with a dynamically linked ASAN.
-      nix-perl-bindings = if withSanitizers then null else prev.nix-perl-bindings;
-    }
-  );
-
-  # Import NixOS tests using the instrumented components
-  nixosTests = import ../../../tests/nixos {
-    inherit lib pkgs;
-    nixComponents = nixComponentsInstrumented;
-    nixpkgs = nixFlake.inputs.nixpkgs;
-    inherit (nixFlake.inputs) nixpkgs-23-11;
-  };
-
-  /**
-    Top-level tests for the flake outputs, as they would be built by hydra.
-    These tests generally can't be overridden to run with sanitizers.
-  */
-  topLevel = {
-    installerScriptForGHA = hydraJobs.installerScriptForGHA.${system};
-    installTests = hydraJobs.installTests.${system};
-    nixpkgsLibTests = hydraJobs.tests.nixpkgsLibTests.${system};
-    rl-next = pkgs.buildPackages.runCommand "test-rl-next-release-notes" { } ''
-      LANG=C.UTF-8 ${pkgs.changelog-d}/bin/changelog-d ${../../../doc/manual/rl-next} >$out
-    '';
-    repl-completion = pkgs.callPackage ../../../tests/repl-completion.nix { inherit (packages') nix; };
-
-    /**
-      Checks for our packaging expressions.
-      This shouldn't build anything significant; just check that things
-      (including derivations) are _set up_ correctly.
-    */
-    packaging-overriding =
-      let
-        nix = packages'.nix;
-      in
-      assert (nix.appendPatches [ pkgs.emptyFile ]).libs.nix-util.src.patches == [ pkgs.emptyFile ];
-      if pkgs.stdenv.buildPlatform.isDarwin then
-        lib.warn "packaging-overriding check currently disabled because of a permissions issue on macOS" pkgs.emptyFile
-      else
-        # If this fails, something might be wrong with how we've wired the scope,
-        # or something could be broken in Nixpkgs.
-        pkgs.testers.testEqualContents {
-          assertion = "trivial patch does not change source contents";
-          expected = "${../../..}";
-          actual =
-            # Same for all components; nix-util is an arbitrary pick
-            (nix.appendPatches [ pkgs.emptyFile ]).libs.nix-util.src;
-        };
-  };
-
-  disable =
-    let
-      inherit (pkgs.stdenv) hostPlatform;
-    in
-    args@{
-      pkgName,
-      testName,
-      test,
-    }:
-    lib.any (b: b) [
-      # FIXME: Nix manual is impure and does not produce all settings on darwin
-      (hostPlatform.isDarwin && pkgName == "nix-manual" && testName == "linkcheck")
-    ];
-
-  componentTests =
-    (lib.concatMapAttrs (
-      pkgName: pkg:
-      lib.concatMapAttrs (
-        testName: test:
-        lib.optionalAttrs (!disable { inherit pkgName testName test; }) {
-          "${componentTestsPrefix}${pkgName}-${testName}" = test;
-        }
-      ) (pkg.tests or { })
-    ) nixComponentsInstrumented)
-    // lib.optionalAttrs (pkgs.stdenv.hostPlatform == pkgs.stdenv.buildPlatform) {
-      "${componentTestsPrefix}nix-functional-tests" = nixComponentsInstrumented.nix-functional-tests;
-      "${componentTestsPrefix}nix-json-schema-checks" = nixComponentsInstrumented.nix-json-schema-checks;
-    };
-
-  codeCoverage =
-    let
-      componentsTestsToProfile =
-        (builtins.mapAttrs (n: v: nixComponentsInstrumented.${n}.tests.run) {
-          "nix-util-tests" = { };
-          "nix-store-tests" = { };
-          "nix-fetchers-tests" = { };
-          "nix-expr-tests" = { };
-          "nix-flake-tests" = { };
-        })
-        // {
-          inherit (nixComponentsInstrumented) nix-functional-tests;
-        };
-
-      coverageProfileDrvs = lib.mapAttrs (
-        n: v:
-        v.overrideAttrs (
-          finalAttrs: prevAttrs: {
-            outputs = (prevAttrs.outputs or [ "out" ]) ++ [ "profraw" ];
-            env = {
-              LLVM_PROFILE_FILE = "${placeholder "profraw"}/%m";
-            };
-          }
-        )
-      ) componentsTestsToProfile;
-
-      coverageProfiles = lib.mapAttrsToList (n: v: lib.getOutput "profraw" v) coverageProfileDrvs;
-
-      mergedProfdata =
-        pkgs.runCommand "merged-profdata"
-          {
-            __structuredAttrs = true;
-            nativeBuildInputs = [ pkgs.llvmPackages.libllvm ];
-            inherit coverageProfiles;
-          }
-          ''
-            rawProfiles=()
-            for dir in "''\${coverageProfiles[@]}"; do
-              rawProfiles+=($dir/*)
-            done
-            llvm-profdata merge -sparse -output $out "''\${rawProfiles[@]}"
-          '';
-
-      coverageReports =
-        let
-          nixComponentDrvs = lib.filter (lib.isDerivation) (lib.attrValues nixComponentsInstrumented);
-        in
-        pkgs.runCommand "code-coverage-report"
-          {
-            nativeBuildInputs = [
-              pkgs.llvmPackages.libllvm
-              pkgs.jq
-            ];
-            __structuredAttrs = true;
-            nixComponents = nixComponentDrvs;
-          }
-          ''
-            # ${toString (lib.map (v: v.src) nixComponentDrvs)}
-
-            binaryFiles=()
-            for dir in "''\${nixComponents[@]}"; do
-              readarray -t filesInDir < <(find "$dir" -type f -executable)
-              binaryFiles+=("''\${filesInDir[@]}")
-            done
-
-            arguments=$(concatStringsSep " -object " binaryFiles)
-            llvm-cov show $arguments -instr-profile ${mergedProfdata} -output-dir $out -format=html
-
-            {
-              echo "# Code coverage summary (generated via \`llvm-cov\`):"
-              echo
-              echo '```'
-              llvm-cov report $arguments -instr-profile ${mergedProfdata} -format=text -use-color=false
-              echo '```'
-              echo
-            } >> $out/index.txt
-
-            llvm-cov export $arguments -instr-profile ${mergedProfdata} -format=text > $out/coverage.json
-
-            mkdir -p $out/nix-support
-
-            coverageTotals=$(jq ".data[0].totals" $out/coverage.json)
-
-            # Mostly inline from pkgs/build-support/setup-hooks/make-coverage-analysis-report.sh [1],
-            # which we can't use here, because we rely on LLVM's infra for source code coverage collection.
-            # [1]: https://github.com/NixOS/nixpkgs/blob/67bb48c4c8e327417d6d5aa7e538244b209e852b/pkgs/build-support/setup-hooks/make-coverage-analysis-report.sh#L16
-            declare -A metricsArray=(["lineCoverage"]="lines" ["functionCoverage"]="functions" ["branchCoverage"]="branches")
-
-            for metricName in "''\${!metricsArray[@]}"; do
-              key="''\${metricsArray[$metricName]}"
-              metric=$(echo "$coverageTotals" | jq ".$key.percent * 10 | round / 10")
-              echo "$metricName $metric %" >> $out/nix-support/hydra-metrics
-            done
-
-            echo "report coverage $out" >> $out/nix-support/hydra-build-products
-          '';
-    in
-    assert withCoverage;
-    assert stdenv.cc.isClang;
-    {
-      inherit coverageProfileDrvs mergedProfdata coverageReports;
-    };
-
-  vmTests = {
-    inherit (nixosTests) s3-binary-cache-store;
-  }
-  // lib.optionalAttrs (!withSanitizers && !withCoverage) {
-    # evalNixpkgs uses non-instrumented components from hydraJobs, so only run it
-    # when not testing with sanitizers to avoid rebuilding nix
-    inherit (hydraJobs.tests) evalNixpkgs;
-    # FIXME: CI times out when building vm tests instrumented
-    inherit (nixosTests)
-      functional_user
-      githubFlakes
-      nix-docker
-      tarballFlakes
-      ;
-  };
-}

ci/gha/tests/pre-commit-checks

@@ -1,24 +0,0 @@
-#!/usr/bin/env bash
-
-set -euo pipefail
-
-system=$(nix eval --raw --impure --expr builtins.currentSystem)
-
-echo "::group::Running pre-commit checks"
-
-if nix build ".#checks.$system.pre-commit" -L; then
-    echo "::endgroup::"
-    exit 0
-fi
-
-echo "::error ::Changes do not pass pre-commit checks"
-
-cat <<EOF
-The code isn't formatted or doesn't pass lints. You can run pre-commit locally with:
-
-    nix develop -c ./maintainers/format.sh
-EOF
-
-echo "::endgroup::"
-
-exit 1

ci/gha/tests/prepare-installer-for-github-actions

@@ -1,11 +0,0 @@
-#!/usr/bin/env bash
-
-set -euo pipefail
-
-nix build -L ".#installerScriptForGHA" ".#binaryTarball"
-
-mkdir -p out
-cp ./result/install "out/install"
-name="$(basename "$(realpath ./result-1)")"
-# everything before the first dash
-cp -r ./result-1 "out/${name%%-*}"

ci/gha/tests/wrapper.nix

@@ -1,16 +0,0 @@
-{
-  nixFlake ? builtins.getFlake ("git+file://" + toString ../../..),
-  system ? builtins.currentSystem,
-  pkgs ? nixFlake.inputs.nixpkgs.legacyPackages.${system},
-  stdenv ? "stdenv",
-  componentTestsPrefix ? "",
-  withInstrumentation ? false,
-}@args:
-import ./. (
-  args
-  // {
-    getStdenv = p: p.${stdenv};
-    withSanitizers = withInstrumentation;
-    withCoverage = withInstrumentation;
-  }
-)

config/install-sh

@@ -0,0 +1,527 @@
+#!/bin/sh
+# install - install a program, script, or datafile
+
+scriptversion=2011-11-20.07; # UTC
+
+# This originates from X11R5 (mit/util/scripts/install.sh), which was
+# later released in X11R6 (xc/config/util/install.sh) with the
+# following copyright and license.
+#
+# Copyright (C) 1994 X Consortium
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+# X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+# AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNEC-
+# TION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# Except as contained in this notice, the name of the X Consortium shall not
+# be used in advertising or otherwise to promote the sale, use or other deal-
+# ings in this Software without prior written authorization from the X Consor-
+# tium.
+#
+#
+# FSF changes to this file are in the public domain.
+#
+# Calling this script install-sh is preferred over install.sh, to prevent
+# 'make' implicit rules from creating a file called install from it
+# when there is no Makefile.
+#
+# This script is compatible with the BSD install script, but was written
+# from scratch.
+
+nl='
+'
+IFS=" ""	$nl"
+
+# set DOITPROG to echo to test this script
+
+# Don't use :- since 4.3BSD and earlier shells don't like it.
+doit=${DOITPROG-}
+if test -z "$doit"; then
+  doit_exec=exec
+else
+  doit_exec=$doit
+fi
+
+# Put in absolute file names if you don't have them in your path;
+# or use environment vars.
+
+chgrpprog=${CHGRPPROG-chgrp}
+chmodprog=${CHMODPROG-chmod}
+chownprog=${CHOWNPROG-chown}
+cmpprog=${CMPPROG-cmp}
+cpprog=${CPPROG-cp}
+mkdirprog=${MKDIRPROG-mkdir}
+mvprog=${MVPROG-mv}
+rmprog=${RMPROG-rm}
+stripprog=${STRIPPROG-strip}
+
+posix_glob='?'
+initialize_posix_glob='
+  test "$posix_glob" != "?" || {
+    if (set -f) 2>/dev/null; then
+      posix_glob=
+    else
+      posix_glob=:
+    fi
+  }
+'
+
+posix_mkdir=
+
+# Desired mode of installed file.
+mode=0755
+
+chgrpcmd=
+chmodcmd=$chmodprog
+chowncmd=
+mvcmd=$mvprog
+rmcmd="$rmprog -f"
+stripcmd=
+
+src=
+dst=
+dir_arg=
+dst_arg=
+
+copy_on_change=false
+no_target_directory=
+
+usage="\
+Usage: $0 [OPTION]... [-T] SRCFILE DSTFILE
+   or: $0 [OPTION]... SRCFILES... DIRECTORY
+   or: $0 [OPTION]... -t DIRECTORY SRCFILES...
+   or: $0 [OPTION]... -d DIRECTORIES...
+
+In the 1st form, copy SRCFILE to DSTFILE.
+In the 2nd and 3rd, copy all SRCFILES to DIRECTORY.
+In the 4th, create DIRECTORIES.
+
+Options:
+     --help     display this help and exit.
+     --version  display version info and exit.
+
+  -c            (ignored)
+  -C            install only if different (preserve the last data modification time)
+  -d            create directories instead of installing files.
+  -g GROUP      $chgrpprog installed files to GROUP.
+  -m MODE       $chmodprog installed files to MODE.
+  -o USER       $chownprog installed files to USER.
+  -s            $stripprog installed files.
+  -t DIRECTORY  install into DIRECTORY.
+  -T            report an error if DSTFILE is a directory.
+
+Environment variables override the default commands:
+  CHGRPPROG CHMODPROG CHOWNPROG CMPPROG CPPROG MKDIRPROG MVPROG
+  RMPROG STRIPPROG
+"
+
+while test $# -ne 0; do
+  case $1 in
+    -c) ;;
+
+    -C) copy_on_change=true;;
+
+    -d) dir_arg=true;;
+
+    -g) chgrpcmd="$chgrpprog $2"
+	shift;;
+
+    --help) echo "$usage"; exit $?;;
+
+    -m) mode=$2
+	case $mode in
+	  *' '* | *'	'* | *'
+'*	  | *'*'* | *'?'* | *'['*)
+	    echo "$0: invalid mode: $mode" >&2
+	    exit 1;;
+	esac
+	shift;;
+
+    -o) chowncmd="$chownprog $2"
+	shift;;
+
+    -s) stripcmd=$stripprog;;
+
+    -t) dst_arg=$2
+	# Protect names problematic for 'test' and other utilities.
+	case $dst_arg in
+	  -* | [=\(\)!]) dst_arg=./$dst_arg;;
+	esac
+	shift;;
+
+    -T) no_target_directory=true;;
+
+    --version) echo "$0 $scriptversion"; exit $?;;
+
+    --)	shift
+	break;;
+
+    -*)	echo "$0: invalid option: $1" >&2
+	exit 1;;
+
+    *)  break;;
+  esac
+  shift
+done
+
+if test $# -ne 0 && test -z "$dir_arg$dst_arg"; then
+  # When -d is used, all remaining arguments are directories to create.
+  # When -t is used, the destination is already specified.
+  # Otherwise, the last argument is the destination.  Remove it from $@.
+  for arg
+  do
+    if test -n "$dst_arg"; then
+      # $@ is not empty: it contains at least $arg.
+      set fnord "$@" "$dst_arg"
+      shift # fnord
+    fi
+    shift # arg
+    dst_arg=$arg
+    # Protect names problematic for 'test' and other utilities.
+    case $dst_arg in
+      -* | [=\(\)!]) dst_arg=./$dst_arg;;
+    esac
+  done
+fi
+
+if test $# -eq 0; then
+  if test -z "$dir_arg"; then
+    echo "$0: no input file specified." >&2
+    exit 1
+  fi
+  # It's OK to call 'install-sh -d' without argument.
+  # This can happen when creating conditional directories.
+  exit 0
+fi
+
+if test -z "$dir_arg"; then
+  do_exit='(exit $ret); exit $ret'
+  trap "ret=129; $do_exit" 1
+  trap "ret=130; $do_exit" 2
+  trap "ret=141; $do_exit" 13
+  trap "ret=143; $do_exit" 15
+
+  # Set umask so as not to create temps with too-generous modes.
+  # However, 'strip' requires both read and write access to temps.
+  case $mode in
+    # Optimize common cases.
+    *644) cp_umask=133;;
+    *755) cp_umask=22;;
+
+    *[0-7])
+      if test -z "$stripcmd"; then
+	u_plus_rw=
+      else
+	u_plus_rw='% 200'
+      fi
+      cp_umask=`expr '(' 777 - $mode % 1000 ')' $u_plus_rw`;;
+    *)
+      if test -z "$stripcmd"; then
+	u_plus_rw=
+      else
+	u_plus_rw=,u+rw
+      fi
+      cp_umask=$mode$u_plus_rw;;
+  esac
+fi
+
+for src
+do
+  # Protect names problematic for 'test' and other utilities.
+  case $src in
+    -* | [=\(\)!]) src=./$src;;
+  esac
+
+  if test -n "$dir_arg"; then
+    dst=$src
+    dstdir=$dst
+    test -d "$dstdir"
+    dstdir_status=$?
+  else
+
+    # Waiting for this to be detected by the "$cpprog $src $dsttmp" command
+    # might cause directories to be created, which would be especially bad
+    # if $src (and thus $dsttmp) contains '*'.
+    if test ! -f "$src" && test ! -d "$src"; then
+      echo "$0: $src does not exist." >&2
+      exit 1
+    fi
+
+    if test -z "$dst_arg"; then
+      echo "$0: no destination specified." >&2
+      exit 1
+    fi
+    dst=$dst_arg
+
+    # If destination is a directory, append the input filename; won't work
+    # if double slashes aren't ignored.
+    if test -d "$dst"; then
+      if test -n "$no_target_directory"; then
+	echo "$0: $dst_arg: Is a directory" >&2
+	exit 1
+      fi
+      dstdir=$dst
+      dst=$dstdir/`basename "$src"`
+      dstdir_status=0
+    else
+      # Prefer dirname, but fall back on a substitute if dirname fails.
+      dstdir=`
+	(dirname "$dst") 2>/dev/null ||
+	expr X"$dst" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \
+	     X"$dst" : 'X\(//\)[^/]' \| \
+	     X"$dst" : 'X\(//\)$' \| \
+	     X"$dst" : 'X\(/\)' \| . 2>/dev/null ||
+	echo X"$dst" |
+	    sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{
+		   s//\1/
+		   q
+		 }
+		 /^X\(\/\/\)[^/].*/{
+		   s//\1/
+		   q
+		 }
+		 /^X\(\/\/\)$/{
+		   s//\1/
+		   q
+		 }
+		 /^X\(\/\).*/{
+		   s//\1/
+		   q
+		 }
+		 s/.*/./; q'
+      `
+
+      test -d "$dstdir"
+      dstdir_status=$?
+    fi
+  fi
+
+  obsolete_mkdir_used=false
+
+  if test $dstdir_status != 0; then
+    case $posix_mkdir in
+      '')
+	# Create intermediate dirs using mode 755 as modified by the umask.
+	# This is like FreeBSD 'install' as of 1997-10-28.
+	umask=`umask`
+	case $stripcmd.$umask in
+	  # Optimize common cases.
+	  *[2367][2367]) mkdir_umask=$umask;;
+	  .*0[02][02] | .[02][02] | .[02]) mkdir_umask=22;;
+
+	  *[0-7])
+	    mkdir_umask=`expr $umask + 22 \
+	      - $umask % 100 % 40 + $umask % 20 \
+	      - $umask % 10 % 4 + $umask % 2
+	    `;;
+	  *) mkdir_umask=$umask,go-w;;
+	esac
+
+	# With -d, create the new directory with the user-specified mode.
+	# Otherwise, rely on $mkdir_umask.
+	if test -n "$dir_arg"; then
+	  mkdir_mode=-m$mode
+	else
+	  mkdir_mode=
+	fi
+
+	posix_mkdir=false
+	case $umask in
+	  *[123567][0-7][0-7])
+	    # POSIX mkdir -p sets u+wx bits regardless of umask, which
+	    # is incompatible with FreeBSD 'install' when (umask & 300) != 0.
+	    ;;
+	  *)
+	    tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$
+	    trap 'ret=$?; rmdir "$tmpdir/d" "$tmpdir" 2>/dev/null; exit $ret' 0
+
+	    if (umask $mkdir_umask &&
+		exec $mkdirprog $mkdir_mode -p -- "$tmpdir/d") >/dev/null 2>&1
+	    then
+	      if test -z "$dir_arg" || {
+		   # Check for POSIX incompatibilities with -m.
+		   # HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or
+		   # other-writable bit of parent directory when it shouldn't.
+		   # FreeBSD 6.1 mkdir -m -p sets mode of existing directory.
+		   ls_ld_tmpdir=`ls -ld "$tmpdir"`
+		   case $ls_ld_tmpdir in
+		     d????-?r-*) different_mode=700;;
+		     d????-?--*) different_mode=755;;
+		     *) false;;
+		   esac &&
+		   $mkdirprog -m$different_mode -p -- "$tmpdir" && {
+		     ls_ld_tmpdir_1=`ls -ld "$tmpdir"`
+		     test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1"
+		   }
+		 }
+	      then posix_mkdir=:
+	      fi
+	      rmdir "$tmpdir/d" "$tmpdir"
+	    else
+	      # Remove any dirs left behind by ancient mkdir implementations.
+	      rmdir ./$mkdir_mode ./-p ./-- 2>/dev/null
+	    fi
+	    trap '' 0;;
+	esac;;
+    esac
+
+    if
+      $posix_mkdir && (
+	umask $mkdir_umask &&
+	$doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir"
+      )
+    then :
+    else
+
+      # The umask is ridiculous, or mkdir does not conform to POSIX,
+      # or it failed possibly due to a race condition.  Create the
+      # directory the slow way, step by step, checking for races as we go.
+
+      case $dstdir in
+	/*) prefix='/';;
+	[-=\(\)!]*) prefix='./';;
+	*)  prefix='';;
+      esac
+
+      eval "$initialize_posix_glob"
+
+      oIFS=$IFS
+      IFS=/
+      $posix_glob set -f
+      set fnord $dstdir
+      shift
+      $posix_glob set +f
+      IFS=$oIFS
+
+      prefixes=
+
+      for d
+      do
+	test X"$d" = X && continue
+
+	prefix=$prefix$d
+	if test -d "$prefix"; then
+	  prefixes=
+	else
+	  if $posix_mkdir; then
+	    (umask=$mkdir_umask &&
+	     $doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir") && break
+	    # Don't fail if two instances are running concurrently.
+	    test -d "$prefix" || exit 1
+	  else
+	    case $prefix in
+	      *\'*) qprefix=`echo "$prefix" | sed "s/'/'\\\\\\\\''/g"`;;
+	      *) qprefix=$prefix;;
+	    esac
+	    prefixes="$prefixes '$qprefix'"
+	  fi
+	fi
+	prefix=$prefix/
+      done
+
+      if test -n "$prefixes"; then
+	# Don't fail if two instances are running concurrently.
+	(umask $mkdir_umask &&
+	 eval "\$doit_exec \$mkdirprog $prefixes") ||
+	  test -d "$dstdir" || exit 1
+	obsolete_mkdir_used=true
+      fi
+    fi
+  fi
+
+  if test -n "$dir_arg"; then
+    { test -z "$chowncmd" || $doit $chowncmd "$dst"; } &&
+    { test -z "$chgrpcmd" || $doit $chgrpcmd "$dst"; } &&
+    { test "$obsolete_mkdir_used$chowncmd$chgrpcmd" = false ||
+      test -z "$chmodcmd" || $doit $chmodcmd $mode "$dst"; } || exit 1
+  else
+
+    # Make a couple of temp file names in the proper directory.
+    dsttmp=$dstdir/_inst.$$_
+    rmtmp=$dstdir/_rm.$$_
+
+    # Trap to clean up those temp files at exit.
+    trap 'ret=$?; rm -f "$dsttmp" "$rmtmp" && exit $ret' 0
+
+    # Copy the file name to the temp name.
+    (umask $cp_umask && $doit_exec $cpprog "$src" "$dsttmp") &&
+
+    # and set any options; do chmod last to preserve setuid bits.
+    #
+    # If any of these fail, we abort the whole thing.  If we want to
+    # ignore errors from any of these, just make sure not to ignore
+    # errors from the above "$doit $cpprog $src $dsttmp" command.
+    #
+    { test -z "$chowncmd" || $doit $chowncmd "$dsttmp"; } &&
+    { test -z "$chgrpcmd" || $doit $chgrpcmd "$dsttmp"; } &&
+    { test -z "$stripcmd" || $doit $stripcmd "$dsttmp"; } &&
+    { test -z "$chmodcmd" || $doit $chmodcmd $mode "$dsttmp"; } &&
+
+    # If -C, don't bother to copy if it wouldn't change the file.
+    if $copy_on_change &&
+       old=`LC_ALL=C ls -dlL "$dst"	2>/dev/null` &&
+       new=`LC_ALL=C ls -dlL "$dsttmp"	2>/dev/null` &&
+
+       eval "$initialize_posix_glob" &&
+       $posix_glob set -f &&
+       set X $old && old=:$2:$4:$5:$6 &&
+       set X $new && new=:$2:$4:$5:$6 &&
+       $posix_glob set +f &&
+
+       test "$old" = "$new" &&
+       $cmpprog "$dst" "$dsttmp" >/dev/null 2>&1
+    then
+      rm -f "$dsttmp"
+    else
+      # Rename the file to the real destination.
+      $doit $mvcmd -f "$dsttmp" "$dst" 2>/dev/null ||
+
+      # The rename failed, perhaps because mv can't rename something else
+      # to itself, or perhaps because mv is so ancient that it does not
+      # support -f.
+      {
+	# Now remove or move aside any old file at destination location.
+	# We try this two ways since rm can't unlink itself on some
+	# systems and the destination file might be busy for other
+	# reasons.  In this case, the final cleanup might fail but the new
+	# file should still install successfully.
+	{
+	  test ! -f "$dst" ||
+	  $doit $rmcmd -f "$dst" 2>/dev/null ||
+	  { $doit $mvcmd -f "$dst" "$rmtmp" 2>/dev/null &&
+	    { $doit $rmcmd -f "$rmtmp" 2>/dev/null; :; }
+	  } ||
+	  { echo "$0: cannot unlink or rename $dst" >&2
+	    (exit 1); exit 1
+	  }
+	} &&
+
+	# Now rename the file to the real destination.
+	$doit $mvcmd "$dsttmp" "$dst"
+      }
+    fi || exit 1
+
+    trap '' 0
+  fi
+done
+
+# Local variables:
+# eval: (add-hook 'write-file-hooks 'time-stamp)
+# time-stamp-start: "scriptversion="
+# time-stamp-format: "%:y-%02m-%02d.%02H"
+# time-stamp-time-zone: "UTC"
+# time-stamp-end: "; # UTC"
+# End:

configure.ac

@@ -0,0 +1,456 @@
+AC_INIT([nix],[m4_esyscmd(bash -c "echo -n $(cat ./.version)$VERSION_SUFFIX")])
+AC_CONFIG_MACRO_DIRS([m4])
+AC_CONFIG_SRCDIR(README.md)
+AC_CONFIG_AUX_DIR(config)
+
+AC_PROG_SED
+
+# 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])
+
+AC_ARG_WITH(system, AS_HELP_STRING([--with-system=SYSTEM],[Platform identifier (e.g., `i686-linux').]),
+  [system=$withval],
+  [case "$host_cpu" in
+     i*86)
+        machine_name="i686";;
+     amd64)
+        machine_name="x86_64";;
+     armv6|armv7)
+        machine_name="${host_cpu}l";;
+     *)
+        machine_name="$host_cpu";;
+   esac
+
+   case "$host_os" in
+     linux-gnu*|linux-musl*)
+        # For backward compatibility, strip the `-gnu' part.
+        system="$machine_name-linux";;
+     *)
+        # Strip the version number from names such as `gnu0.3',
+        # `darwin10.2.0', etc.
+        system="$machine_name-`echo $host_os | "$SED" -e's/@<:@0-9.@:>@*$//g'`";;
+   esac])
+
+AC_MSG_RESULT($system)
+AC_SUBST(system)
+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-""}
+
+AC_PROG_CC
+AC_PROG_CXX
+AC_PROG_CPP
+
+AC_CHECK_TOOL([AR], [ar])
+
+# Use 64-bit file system calls so that we can support files > 2 GiB.
+AC_SYS_LARGEFILE
+
+
+# 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++)
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <iostream>
+using namespace std;
+static char buf[1024];]],
+    [[cerr.rdbuf()->pubsetbuf(buf, sizeof(buf));]])],
+    [AC_MSG_RESULT(yes) AC_DEFINE(HAVE_PUBSETBUF, 1, [Whether pubsetbuf is available.])],
+    AC_MSG_RESULT(no))
+AC_LANG_POP(C++)
+
+
+AC_CHECK_FUNCS([statvfs pipe2 close_range])
+
+
+# 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.
+AC_MSG_CHECKING([whether it is possible to create a link to a symlink])
+ln -s bla tmp_link
+if ln tmp_link tmp_link2 2> /dev/null; then
+    AC_MSG_RESULT(yes)
+    AC_DEFINE(CAN_LINK_SYMLINK, 1, [Whether link() works on symlinks.])
+else
+    AC_MSG_RESULT(no)
+fi
+rm -f tmp_link tmp_link2
+
+
+# Check for <locale>.
+AC_LANG_PUSH(C++)
+AC_CHECK_HEADERS([locale])
+AC_LANG_POP(C++)
+
+
+AC_DEFUN([NEED_PROG],
+[
+AC_PATH_PROG($1, $2)
+if test -z "$$1"; then
+    AC_MSG_ERROR([$2 is required])
+fi
+])
+
+NEED_PROG(bash, bash)
+AC_PATH_PROG(flex, flex, false)
+AC_PATH_PROG(bison, bison, false)
+AC_PATH_PROG(dot, dot)
+AC_PATH_PROG(lsof, lsof, lsof)
+
+
+AC_SUBST(coreutils, [$(dirname $(type -p cat))])
+
+
+AC_ARG_WITH(store-dir, AS_HELP_STRING([--with-store-dir=PATH],[path of the Nix store (defaults to /nix/store)]),
+  storedir=$withval, storedir='/nix/store')
+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.
+# Thus we append the returned CPPFLAGS to the CXXFLAGS here.
+AX_BOOST_BASE([1.66], [CXXFLAGS="$BOOST_CPPFLAGS $CXXFLAGS"], [AC_MSG_ERROR([Nix requires boost.])])
+# For unknown reasons, setting this directly in the ACTION-IF-FOUND above
+# ends up with LDFLAGS being empty, so we set it afterwards.
+LDFLAGS="$BOOST_LDFLAGS $LDFLAGS"
+
+# On some platforms, new-style atomics need a helper library
+AC_MSG_CHECKING(whether -latomic is needed)
+AC_LINK_IFELSE([AC_LANG_SOURCE([[
+#include <stdint.h>
+uint64_t v;
+int main() {
+    return (int)__atomic_load_n(&v, __ATOMIC_ACQUIRE);
+}]])], GCC_ATOMIC_BUILTINS_NEED_LIBATOMIC=no, GCC_ATOMIC_BUILTINS_NEED_LIBATOMIC=yes)
+AC_MSG_RESULT($GCC_ATOMIC_BUILTINS_NEED_LIBATOMIC)
+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)
+if test "$lto" = yes; then
+    if $CXX --version | grep -q GCC; then
+        AC_SUBST(CXXLTO, [-flto=jobserver])
+    else
+        echo "error: LTO is only supported with GCC at the moment" >&2
+        exit 1
+    fi
+else
+    AC_SUBST(CXXLTO, [""])
+fi
+
+PKG_PROG_PKG_CONFIG
+
+AC_ARG_ENABLE(shared, AS_HELP_STRING([--enable-shared],[Build shared libraries for Nix [default=yes]]),
+  shared=$enableval, shared=yes)
+if test "$shared" = yes; then
+  AC_SUBST(BUILD_SHARED_LIBS, 1, [Whether to build shared libraries.])
+else
+  AC_SUBST(BUILD_SHARED_LIBS, 0, [Whether to build shared libraries.])
+  PKG_CONFIG="$PKG_CONFIG --static"
+fi
+
+# Look for OpenSSL, a required dependency. FIXME: this is only (maybe)
+# used by S3BinaryCacheStore.
+PKG_CHECK_MODULES([OPENSSL], [libcrypto >= 1.1.1], [CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"])
+
+
+# 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
+    LIBARCHIVE_LIBS+=' -lz'
+fi
+
+# Look for SQLite, a required dependency.
+PKG_CHECK_MODULES([SQLITE3], [sqlite3 >= 3.6.19], [CXXFLAGS="$SQLITE3_CFLAGS $CXXFLAGS"])
+
+# Look for libcurl, a required dependency.
+PKG_CHECK_MODULES([LIBCURL], [libcurl], [CXXFLAGS="$LIBCURL_CFLAGS $CXXFLAGS"])
+
+# 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,
+# 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"])
+
+# Look for libbrotli{enc,dec}.
+PKG_CHECK_MODULES([LIBBROTLI], [libbrotlienc libbrotlidec], [CXXFLAGS="$LIBBROTLI_CFLAGS $CXXFLAGS"])
+
+# Look for libcpuid.
+have_libcpuid=
+if test "$machine_name" = "x86_64"; then
+    AC_ARG_ENABLE([cpuid],
+                  AS_HELP_STRING([--disable-cpuid], [Do not determine microarchitecture levels with libcpuid (relevant to x86_64 only)]))
+    if test "x$enable_cpuid" != "xno"; then
+      PKG_CHECK_MODULES([LIBCPUID], [libcpuid],
+        [CXXFLAGS="$LIBCPUID_CFLAGS $CXXFLAGS"
+         have_libcpuid=1
+         AC_DEFINE([HAVE_LIBCPUID], [1], [Use libcpuid])]
+      )
+    fi
+fi
+AC_SUBST(HAVE_LIBCPUID, [$have_libcpuid])
+
+
+# Look for libseccomp, required for Linux sandboxing.
+case "$host_os" in
+  linux*)
+    AC_ARG_ENABLE([seccomp-sandboxing],
+                  AS_HELP_STRING([--disable-seccomp-sandboxing],[Don't build support for seccomp sandboxing (only recommended if your arch doesn't support libseccomp yet!)
+                                ]))
+    if test "x$enable_seccomp_sandboxing" != "xno"; then
+      PKG_CHECK_MODULES([LIBSECCOMP], [libseccomp],
+                        [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
+    ;;
+  *)
+    have_seccomp=
+    ;;
+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++)
+AC_CHECK_HEADERS([aws/s3/S3Client.h],
+  [AC_DEFINE([ENABLE_S3], [1], [Whether to enable S3 support via aws-sdk-cpp.]) enable_s3=1],
+  [AC_DEFINE([ENABLE_S3], [0], [Whether to enable S3 support via aws-sdk-cpp.]) enable_s3=])
+AC_SUBST(ENABLE_S3, [$enable_s3])
+AC_LANG_POP(C++)
+
+
+# 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]]),
+  gc=$enableval, gc=yes)
+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 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])
+
+
+# Look for lowdown library.
+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])
+
+
+# Nice to have, but not essential.
+AC_CHECK_FUNCS([strsignal posix_fallocate sysconf])
+
+
+AC_ARG_WITH(sandbox-shell, AS_HELP_STRING([--with-sandbox-shell=PATH],[path of a statically-linked shell to use as /bin/sh in sandboxes]),
+  sandbox_shell=$withval)
+AC_SUBST(sandbox_shell)
+if test ${cross_compiling:-no} = no && ! test -z ${sandbox_shell+x}; then
+  AC_MSG_CHECKING([whether sandbox-shell has the standalone feature])
+  # busybox shell sometimes allows executing other busybox applets,
+  # even if they are not in the path, breaking our sandbox
+  if PATH= $sandbox_shell -c "busybox" 2>&1 | grep -qv "not found"; then
+    AC_MSG_RESULT(enabled)
+    AC_MSG_ERROR([Please disable busybox FEATURE_SH_STANDALONE])
+  else
+    AC_MSG_RESULT(disabled)
+  fi
+fi
+
+AC_ARG_ENABLE(embedded-sandbox-shell, AS_HELP_STRING([--enable-embedded-sandbox-shell],[include the sandbox shell in the Nix binary [default=no]]),
+  embedded_sandbox_shell=$enableval, embedded_sandbox_shell=no)
+AC_SUBST(embedded_sandbox_shell)
+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
+test "$exec_prefix" = NONE && exec_prefix='${prefix}'
+for name in $ac_subst_vars; do
+    declare $name="$(eval echo "${!name}")"
+    declare $name="$(eval echo "${!name}")"
+    declare $name="$(eval echo "${!name}")"
+done
+
+rm -f Makefile.config
+
+AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_FILES([])
+AC_OUTPUT

default.nix

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

doc/manual/anchors.jq

@@ -3,7 +3,7 @@
 
 
 def transform_anchors_html:
-    . | gsub($empty_anchor_regex; "<a id=\"" + .anchor + "\"></a>")
+    . | gsub($empty_anchor_regex; "<a name=\"" + .anchor + "\"></a>")
       | gsub($anchor_regex; "<a href=\"#" + .anchor + "\" id=\"" + .anchor + "\">" + .text + "</a>");
 
 

doc/manual/book.toml

@@ -1,5 +1,5 @@
 [book]
-title = "Nix @version@ Reference Manual"
+title = "Nix Reference Manual"
 src = "source"
 
 [output.html]
@@ -7,7 +7,6 @@ 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"
-mathjax-support = true
 
 # Handles replacing @docroot@ with a path to ./source relative to that markdown file,
 # {{#include handlebars}}, and the @generated@ syntax used within these. it mostly

doc/manual/generate-builtins.nix

@@ -5,15 +5,7 @@ in
 
 builtinsInfo:
 let
-  showBuiltin =
-    name:
-    {
-      doc,
-      type ? null,
-      args ? [ ],
-      experimental-feature ? null,
-      impure-only ? false,
-    }:
+  showBuiltin = name: { doc, type ? null, args ? [ ], experimental-feature ? null, impure-only ? false }:
     let
       type' = optionalString (type != null) " (${type})";
 

doc/manual/generate-deps.py

@@ -14,7 +14,7 @@ import sys
 # 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 nonexistent paths, making everything phony and thus fine.)
+# 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

doc/manual/generate-manpage.nix

@@ -32,13 +32,7 @@ let
 
   commandInfo = fromJSON commandDump;
 
-  showCommand =
-    {
-      command,
-      details,
-      filename,
-      toplevel,
-    }:
+  showCommand = { command, details, filename, toplevel }:
     let
 
       result = ''
@@ -62,27 +56,26 @@ let
         ${maybeOptions}
       '';
 
-      showSynopsis =
-        command: args:
+      showSynopsis = command: args:
         let
-          showArgument = arg: "*${arg.label}*" + optionalString (!arg ? arity) "...";
+          showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
           arguments = concatStringsSep " " (map showArgument args);
-        in
-        ''
+        in ''
           `${command}` [*option*...] ${arguments}
         '';
 
-      maybeSubcommands = optionalString (details ? commands && details.commands != { }) ''
-        where *subcommand* is one of the following:
+      maybeSubcommands = optionalString (details ? commands && details.commands != {})
+        ''
+          where *subcommand* is one of the following:
 
-        ${subcommands}
-      '';
+          ${subcommands}
+        '';
 
-      subcommands = if length categories > 1 then listCategories else listSubcommands details.commands;
+      subcommands = if length categories > 1
+        then listCategories
+        else listSubcommands details.commands;
 
-      categories = sort (x: y: x.id < y.id) (
-        unique (map (cmd: cmd.category) (attrValues details.commands))
-      );
+      categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands)));
 
       listCategories = concatStrings (map showCategory categories);
 
@@ -106,39 +99,38 @@ let
 
             ${allStores}
           '';
-          index =
-            replaceStrings
-              [ "@store-types@" "./local-store.md" "./local-daemon-store.md" ]
-              [ storesOverview "#local-store" "#local-daemon-store" ]
-              details.doc;
+          index = replaceStrings
+            [ "@store-types@" "./local-store.md" "./local-daemon-store.md" ]
+            [ storesOverview "#local-store" "#local-daemon-store" ]
+            details.doc;
           storesOverview =
             let
-              showEntry = store: "- [${store.name}](#${store.slug})";
+              showEntry = store:
+                "- [${store.name}](#${store.slug})";
             in
             concatStringsSep "\n" (map showEntry storesList) + "\n";
           allStores = concatStringsSep "\n" (attrValues storePages);
-          storePages = listToAttrs (
-            map (s: {
-              name = s.filename;
-              value = s.page;
-            }) storesList
-          );
+          storePages = listToAttrs
+            (map (s: { name = s.filename; value = s.page; }) storesList);
           storesList = showStoreDocs {
             storeInfo = commandInfo.stores;
             inherit inlineHTML;
           };
-          hasInfix =
-            infix: content:
+          hasInfix = infix: content:
             builtins.stringLength content != builtins.stringLength (replaceStrings [ infix ] [ "" ] content);
         in
         optionalString (details ? doc) (
           # An alternate implementation with builtins.match stack overflowed on some systems.
-          if hasInfix "@store-types@" details.doc then help-stores else details.doc
+          if hasInfix "@store-types@" details.doc
+          then help-stores
+          else details.doc
         );
 
       maybeOptions =
         let
-          allVisibleOptions = filterAttrs (_: o: !o.hiddenCategory) (details.flags // toplevel.flags);
+          allVisibleOptions = filterAttrs
+            (_: o: ! o.hiddenCategory)
+            (details.flags // toplevel.flags);
         in
         optionalString (allVisibleOptions != { }) ''
           # Options
@@ -150,73 +142,55 @@ let
           > See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.
         '';
 
-      showOptions =
-        inlineHTML: allOptions:
+      showOptions = inlineHTML: allOptions:
         let
           showCategory = cat: opts: ''
             ${optionalString (cat != "") "## ${cat}"}
 
             ${concatStringsSep "\n" (attrValues (mapAttrs showOption opts))}
           '';
-          showOption =
-            name: option:
+          showOption = name: option:
             let
               result = trim ''
                 - ${item}
 
                   ${option.description}
               '';
-              item =
-                if inlineHTML then
-                  ''<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;
+              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;
 
-  processCommand =
-    {
-      command,
-      details,
-      filename,
-      toplevel,
-    }:
+  processCommand = { command, details, filename, toplevel }:
     let
       cmd = {
         inherit command;
         name = filename + ".md";
-        value = showCommand {
-          inherit
-            command
-            details
-            filename
-            toplevel
-            ;
-        };
+        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 { });
+      subcommand = subCmd: processCommand {
+        command = command + " " + subCmd;
+        details = details.commands.${subCmd};
+        filename = appendName filename subCmd;
+        inherit toplevel;
+      };
+    in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
 
   manpages = processCommand {
     command = "nix";
@@ -225,11 +199,9 @@ let
     toplevel = commandInfo.args;
   };
 
-  tableOfContents =
-    let
-      showEntry = page: "    - [${page.command}](command-ref/new-cli/${page.name})";
-    in
-    concatStringsSep "\n" (map showEntry manpages) + "\n";
+  tableOfContents = let
+    showEntry = page:
+      "    - [${page.command}](command-ref/new-cli/${page.name})";
+    in concatStringsSep "\n" (map showEntry manpages) + "\n";
 
-in
-(listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
+in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }

doc/manual/generate-settings.nix

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

doc/manual/generate-store-info.nix

@@ -1,20 +1,6 @@
 let
-  inherit (builtins)
-    attrNames
-    listToAttrs
-    concatStringsSep
-    readFile
-    replaceStrings
-    ;
-  inherit (import <nix/utils.nix>)
-    optionalString
-    filterAttrs
-    trim
-    squash
-    toLower
-    unique
-    indent
-    ;
+  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
 
@@ -28,14 +14,7 @@ in
 
 let
 
-  showStore =
-    { name, slug }:
-    {
-      settings,
-      doc,
-      uri-schemes,
-      experimentalFeature,
-    }:
+  showStore = { name, slug }: { settings, doc, experimentalFeature }:
     let
       result = squash ''
         # ${name}
@@ -46,10 +25,7 @@ let
 
         ## Settings
 
-        ${showSettings {
-          prefix = "store-${slug}";
-          inherit inlineHTML;
-        } settings}
+        ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
       '';
 
       experimentalFeatureNote = optionalString (experimentalFeature != null) ''
@@ -67,15 +43,15 @@ let
         > extra-experimental-features = ${experimentalFeature}
         > ```
       '';
-    in
-    result;
+    in result;
 
-  storesList = map (name: rec {
-    inherit name;
-    slug = replaceStrings [ " " ] [ "-" ] (toLower name);
-    filename = "${slug}.md";
-    page = showStore { inherit name slug; } storeInfo.${name};
-  }) (attrNames storeInfo);
+  storesList = map
+    (name: rec {
+      inherit name;
+      slug = replaceStrings [ " " ] [ "-" ] (toLower name);
+      filename = "${slug}.md";
+      page = showStore { inherit name slug; } storeInfo.${name};
+    })
+    (attrNames storeInfo);
 
-in
-storesList
+in storesList

doc/manual/generate-store-types.nix

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

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

@@ -2,8 +2,8 @@ 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)))
+  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

@@ -2,8 +2,7 @@ with builtins;
 with import <nix/utils.nix>;
 
 let
-  showExperimentalFeature =
-    name: doc:
+  showExperimentalFeature = name: doc:
     squash ''
       ## [`${name}`]{#xp-feature-${name}}
 

doc/manual/local.mk

@@ -0,0 +1,236 @@
+# 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)/source, *.md) \
+	$(call rwildcard, $(d)/source, */*.md)
+
+man-pages := $(foreach 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 config show` resolves the cores based on the current machine
+dummy-env = env -i \
+	HOME=/dummy \
+	NIX_CONF_DIR=/dummy \
+	NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt \
+	NIX_STATE_DIR=/dummy \
+	NIX_CONFIG='cores = 0'
+
+nix-eval = $(dummy-env) $(doc_nix) eval --experimental-features nix-command -I nix=doc/manual --store dummy:// --impure --raw
+
+# 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
+	@$(call process-includes,$^,$^.tmp)
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
+	@rm $^.tmp
+
+$(d)/%.8: $(d)/source/command-ref/%.md
+	@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
+	@cat $^ >> $^.tmp
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
+	@rm $^.tmp
+
+$(d)/nix.conf.5: $(d)/source/command-ref/conf-file.md
+	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
+	@cat $^ >> $^.tmp
+	@$(call process-includes,$^,$^.tmp)
+	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
+	@rm $^.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)/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: $(doc_nix)
+	$(trace-gen) $(dummy-env) $(doc_nix) __dump-cli > $@.tmp
+	@mv $@.tmp $@
+
+$(d)/conf-file.json: $(doc_nix)
+	$(trace-gen) $(dummy-env) $(doc_nix) config show --json --experimental-features nix-command > $@.tmp
+	@mv $@.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)/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.
+.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)/source/command-ref/new-cli
+	@mkdir -p $(DESTDIR)$$(dirname $@)
+	$(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 $@
+
+# 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

@@ -1,5 +1,4 @@
-project(
-  'nix-manual',
+project('nix-manual',
   version : files('.version'),
   meson_version : '>= 1.1',
   license : 'LGPL-2.1-or-later',
@@ -9,45 +8,43 @@ nix = find_program('nix', native : true)
 
 mdbook = find_program('mdbook', native : true)
 bash = find_program('bash', native : true)
-rsync = find_program('rsync', required : true, 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',
+  '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_for_docs = [nix, '--experimental-features', 'nix-command']
 nix_eval_for_docs_common = nix_for_docs + [
   'eval',
-  '-I',
-  'nix=' + meson.current_source_dir(),
+  '-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' ],
+  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' ],
+  command: [nix, '__dump-language'],
   output : 'language.json',
   capture : true,
   env : nix_env_for_docs,
 )
 
 nix3_cli_json = custom_target(
-  command : [ nix, '__dump-cli' ],
+  command : [nix, '__dump-cli'],
   capture : true,
   output : 'nix.json',
   env : nix_env_for_docs,
@@ -70,7 +67,7 @@ subdir('source/release-notes')
 subdir('source')
 
 # Hacky way to figure out if `nix` is an `ExternalProgram` or
-# `Executable`. Only the latter can occur in custom target input lists.
+# `Exectuable`. Only the latter can occur in custom target input lists.
 if nix.full_path().startswith(meson.build_root())
   nix_input = nix
 else
@@ -81,32 +78,26 @@ manual = custom_target(
   'manual',
   command : [
     bash,
-    '-euo',
-    'pipefail',
+    '-euo', 'pipefail',
     '-c',
     '''
         @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
         @0@ @INPUT1@ summary @2@ < @CURRENT_SOURCE_DIR@/source/SUMMARY.md.in > @2@/source/SUMMARY.md
-        sed -e 's|@version@|@3@|g' < @INPUT2@ > @2@/book.toml
-        @4@ -r -L --include='*.md' @CURRENT_SOURCE_DIR@/ @2@/
+        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
-        # Remove Mathjax 2.7, because we will actually use MathJax 3.x
-        find @2@/manual | grep .html | xargs sed -i -e '/2.7.1.MathJax.js/d'
         find @2@/manual -iname meson.build -delete
     '''.format(
       python.full_path(),
       mdbook.full_path(),
       meson.current_build_dir(),
-      meson.project_version(),
-      rsync.full_path(),
     ),
   ],
   input : [
     generate_manual_deps,
     'substitute.py',
-    'book.toml.in',
+    'book.toml',
     'anchors.jq',
     'custom.css',
     nix3_cli_files,
@@ -117,7 +108,6 @@ manual = custom_target(
     builtins_md,
     rl_next_generated,
     summary_rl_next,
-    json_schema_generated_files,
     nix_input,
   ],
   output : [
@@ -126,8 +116,8 @@ manual = custom_target(
   ],
   depfile : 'manual.d',
   env : {
-    'RUST_LOG' : 'info',
-    'MDBOOK_SUBSTITUTE_SEARCH' : meson.current_build_dir() / 'source',
+    'RUST_LOG': 'info',
+    'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'source',
   },
 )
 manual_html = manual[0]
@@ -139,8 +129,7 @@ install_subdir(
 )
 
 nix_nested_manpages = [
-  [
-    'nix-env',
+  [ 'nix-env',
     [
       'delete-generations',
       'install',
@@ -155,8 +144,7 @@ nix_nested_manpages = [
       'upgrade',
     ],
   ],
-  [
-    'nix-store',
+  [ 'nix-store',
     [
       'add-fixed',
       'add',
@@ -211,7 +199,6 @@ nix3_manpages = [
   'nix3-build',
   'nix3-bundle',
   'nix3-config',
-  'nix3-config-check',
   'nix3-config-show',
   'nix3-copy',
   'nix3-daemon',
@@ -219,8 +206,8 @@ nix3_manpages = [
   'nix3-derivation',
   'nix3-derivation-show',
   'nix3-develop',
+  #'nix3-doctor',
   'nix3-edit',
-  'nix3-env-shell',
   'nix3-eval',
   'nix3-flake-archive',
   'nix3-flake-check',
@@ -237,7 +224,6 @@ nix3_manpages = [
   'nix3-fmt',
   'nix3-hash-file',
   'nix3-hash',
-  'nix3-hash-convert',
   'nix3-hash-path',
   'nix3-hash-to-base16',
   'nix3-hash-to-base32',
@@ -252,15 +238,14 @@ nix3_manpages = [
   'nix3-nar-cat',
   'nix3-nar-dump-path',
   'nix3-nar-ls',
-  'nix3-nar-pack',
   'nix3-nar',
   'nix3-path-info',
   'nix3-print-dev-env',
-  'nix3-profile',
-  'nix3-profile-add',
   'nix3-profile-diff-closures',
   'nix3-profile-history',
+  'nix3-profile-install',
   'nix3-profile-list',
+  'nix3-profile',
   'nix3-profile-remove',
   'nix3-profile-rollback',
   'nix3-profile-upgrade',
@@ -275,7 +260,7 @@ nix3_manpages = [
   'nix3-repl',
   'nix3-run',
   'nix3-search',
-  'nix3-store-add',
+  #'nix3-shell',
   'nix3-store-add-file',
   'nix3-store-add-path',
   'nix3-store-cat',
@@ -285,12 +270,12 @@ nix3_manpages = [
   'nix3-store-diff-closures',
   'nix3-store-dump-path',
   'nix3-store-gc',
-  'nix3-store-info',
   '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',

doc/manual/package.nix

@@ -1,26 +1,19 @@
-{
-  lib,
-  mkMesonDerivation,
+{ lib
+, mkMesonDerivation
 
-  meson,
-  ninja,
-  lowdown-unsandboxed,
-  mdbook,
-  mdbook-linkcheck,
-  jq,
-  python3,
-  rsync,
-  nix-cli,
-  changelog-d,
-  json-schema-for-humans,
-  officialRelease,
+, meson
+, ninja
+, lowdown
+, mdbook
+, mdbook-linkcheck
+, jq
+, python3
+, rsync
+, nix-cli
 
-  # Configuration Options
+# Configuration Options
 
-  version,
-
-  # `tests` attribute
-  testers,
+, version
 }:
 
 let
@@ -32,85 +25,46 @@ mkMesonDerivation (finalAttrs: {
   inherit version;
 
   workDir = ./.;
-  fileset =
-    fileset.difference
-      (fileset.unions [
-        ../../.version
-        # For example JSON
-        ../../src/libutil-tests/data/hash
-        ../../src/libstore-tests/data/content-address
-        ../../src/libstore-tests/data/store-path
-        ../../src/libstore-tests/data/realisation
-        ../../src/libstore-tests/data/derived-path
-        ../../src/libstore-tests/data/path-info
-        ../../src/libstore-tests/data/nar-info
-        ../../src/libstore-tests/data/build-result
-        # Too many different types of files to filter for now
-        ../../doc/manual
-        ./.
-      ])
-      # Do a blacklist instead
-      ../../doc/manual/package.nix;
+  fileset = fileset.difference
+    (fileset.unions [
+      ../../.version
+      # Too many different types of files to filter for now
+      ../../doc/manual
+      ./.
+    ])
+    # Do a blacklist instead
+    ../../doc/manual/package.nix;
 
   # TODO the man pages should probably be separate
-  outputs = [
-    "out"
-    "man"
-  ];
+  outputs = [ "out" "man" ];
 
-  nativeBuildInputs = [
-    nix-cli
+  # Hack for sake of the dev shell
+  passthru.externalNativeBuildInputs = [
     meson
     ninja
-    (lib.getBin lowdown-unsandboxed)
+    (lib.getBin lowdown)
     mdbook
     mdbook-linkcheck
     jq
     python3
     rsync
-    json-schema-for-humans
-    changelog-d
-  ]
-  ++ lib.optionals (!officialRelease) [
-    # When not an official release, we likely have changelog entries that have
-    # yet to be rendered.
-    # When released, these are rendered into a committed file to save a dependency.
-    changelog-d
   ];
 
-  preConfigure = ''
-    chmod u+w ./.version
-    echo ${finalAttrs.version} > ./.version
-  '';
+  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
   '';
 
-  /**
-    The root of the HTML manual.
-    E.g. "${nix-manual.site}/index.html" exists.
-  */
-  passthru.site = finalAttrs.finalPackage + "/share/doc/nix/manual";
-
-  passthru.tests = {
-    # https://nixos.org/manual/nixpkgs/stable/index.html#tester-lycheeLinkCheck
-    linkcheck = testers.lycheeLinkCheck {
-      inherit (finalAttrs.finalPackage) site;
-      extraConfig = {
-        exclude = [
-          # Exclude auto-generated JSON schema documentation which has
-          # auto-generated fragment IDs that don't match the link references
-          ".*/protocols/json/.*\\.html"
-          # Exclude undocumented builtins
-          ".*/language/builtins\\.html#builtins-addErrorContext"
-          ".*/language/builtins\\.html#builtins-appendContext"
-        ];
-      };
-    };
-  };
-
   meta = {
     platforms = lib.platforms.all;
   };

doc/manual/redirects.js

@@ -346,9 +346,6 @@ const redirects = {
     "scoping-rules": "scoping.html",
     "string-literal": "string-literals.html",
   },
-  "language/derivations.md": {
-    "builder-execution": "store/drv/building.md#builder-execution",
-  },
   "installation/installing-binary.html": {
     "linux": "uninstall.html#linux",
     "macos": "uninstall.html#macos",
@@ -374,9 +371,7 @@ const redirects = {
   },
   "glossary.html": {
     "gloss-local-store": "store/types/local-store.html",
-    "package-attribute-set": "#package",
     "gloss-chroot-store": "store/types/local-store.html",
-    "gloss-content-addressed-derivation": "#gloss-content-addressing-derivation",
   },
 };
 

doc/manual/rl-next/channels-subdomain.md

@@ -1,9 +0,0 @@
----
-synopsis: Channel URLs migrated to channels.nixos.org subdomain
-prs: [14518]
-issues: [14517]
----
-
-Channel URLs have been updated from `https://nixos.org/channels/` to `https://channels.nixos.org/` throughout Nix.
-
-The subdomain provides better reliability with IPv6 support and improved CDN distribution. The old domain apex (`nixos.org/channels/`) currently redirects to the new location but may be deprecated in the future.

doc/manual/rl-next/json-format-changes.md

@@ -1,55 +0,0 @@
----
-synopsis: "JSON format changes for store path info and derivations"
-prs: []
-issues: []
----
-
-JSON formats for store path info and derivations have been updated with new versions and structured fields.
-
-## Store Path Info JSON (Version 2)
-
-The store path info JSON format has been updated from version 1 to version 2:
-
-- **Added `version` field**:
-
-  All store path info JSON now includes `"version": 2`.
-
-- **Structured `ca` field**:
-
-  Content address is now a structured JSON object instead of a string:
-
-  - Old: `"ca": "fixed:r:sha256:1abc..."`
-  - New: `"ca": {"method": "nar", "hash": {"algorithm": "sha256", "format": "base64", "hash": "EMIJ+giQ..."}}`
-  - Still `null` values for input-addressed store objects
-
-- **Structured hash fields**:
-
-  Hash values (`narHash` and `downloadHash`) are now structured JSON objects instead of strings:
-
-  - Old: `"narHash": "sha256:FePFYIlMuycIXPZbWi7LGEiMmZSX9FMbaQenWBzm1Sc="`
-  - New: `"narHash": {"algorithm": "sha256", "format": "base64", "hash": "FePFYIlM..."}`
-  - Same structure applies to `downloadHash` in NAR info contexts
-
-Nix currently only produces, and doesn't consume this format.
-
-**Affected command**: `nix path-info --json`
-
-## Derivation JSON (Version 4)
-
-The derivation JSON format has been updated from version 3 to version 4:
-
-- **Restructured inputs**:
-
-  Inputs are now nested under an `inputs` object:
-
-  - Old: `"inputSrcs": [...], "inputDrvs": {...}`
-  - New: `"inputs": {"srcs": [...], "drvs": {...}}`
-
-- **Consistent content addresses**:
-
-  Floating content-addressed outputs now use structured JSON format.
-  This is the same format as `ca` in in store path info (after the new version).
-
-Version 3 and earlier formats are *not* accepted when reading.
-
-**Affected command**: `nix derivation`, namely it's `show` and `add` sub-commands.

doc/manual/rl-next/s3-curl-implementation.md

@@ -1,40 +0,0 @@
----
-synopsis: "Improved S3 binary cache support via HTTP"
-prs: [13752, 13823, 14026, 14120, 14131, 14135, 14144, 14170, 14190, 14198, 14206, 14209, 14222, 14223, 14330, 14333, 14335, 14336, 14337, 14350, 14356, 14357, 14374, 14375, 14376, 14377, 14391, 14393, 14420, 14421]
-issues: [13084, 12671, 11748, 12403]
----
-
-S3 binary cache operations now happen via HTTP, leveraging `libcurl`'s native
-AWS SigV4 authentication instead of the AWS C++ SDK, providing significant
-improvements:
-
-- **Reduced memory usage**: Eliminates memory buffering issues that caused
-  segfaults with large files
-- **Fixed upload reliability**: Resolves AWS SDK chunking errors
-  (`InvalidChunkSizeError`)
-- **Lighter dependencies**: Uses lightweight `aws-crt-cpp` instead of full
-  `aws-cpp-sdk`, reducing build complexity
-
-The new implementation requires curl >= 7.75.0 and `aws-crt-cpp` for credential
-management.
-
-All existing S3 URL formats and parameters remain supported, however the store
-settings for configuring multipart uploads have changed:
-
-- **`multipart-upload`** (default: `false`): Enable multipart uploads for large
-  files. When enabled, files exceeding the multipart threshold will be uploaded
-  in multiple parts.
-
-- **`multipart-threshold`** (default: `100 MiB`): Minimum file size for using
-  multipart uploads. Files smaller than this will use regular PUT requests.
-  Only takes effect when `multipart-upload` is enabled.
-
-- **`multipart-chunk-size`** (default: `5 MiB`): Size of each part in multipart
-  uploads. Must be at least 5 MiB (AWS S3 requirement). Larger chunk sizes
-  reduce the number of requests but use more memory.
-
-- **`buffer-size`**: Has been replaced by `multipart-chunk-size` and is now an alias to it.
-
-Note that this change also means Nix now supports S3 binary cache stores even
-if built without `aws-crt-cpp`, but only for public buckets which do not
-require authentication.

doc/manual/rl-next/s3-object-versioning.md

@@ -1,14 +0,0 @@
----
-synopsis: "S3 URLs now support object versioning via versionId parameter"
-prs: [14274]
-issues: [13955]
----
-
-S3 URLs now support a `versionId` query parameter to fetch specific versions
-of objects from S3 buckets with versioning enabled. This allows pinning to
-exact object versions for reproducibility and protection against unexpected
-changes:
-
-```
-s3://bucket/key?region=us-east-1&versionId=abc123def456
-```

doc/manual/rl-next/s3-storage-class.md

@@ -1,21 +0,0 @@
----
-synopsis: "S3 binary cache stores now support storage class configuration"
-prs: [14464]
-issues: [7015]
----
-
-S3 binary cache stores now support configuring the storage class for uploaded objects via the `storage-class` parameter. This allows users to optimize costs by selecting appropriate storage tiers based on access patterns.
-
-Example usage:
-
-```bash
-# Use Glacier storage for long-term archival
-nix copy --to 's3://my-bucket?storage-class=GLACIER' /nix/store/...
-
-# Use Intelligent Tiering for automatic cost optimization
-nix copy --to 's3://my-bucket?storage-class=INTELLIGENT_TIERING' /nix/store/...
-```
-
-The storage class applies to both regular uploads and multipart uploads. When not specified, objects use the bucket's default storage class.
-
-See the [S3 storage classes documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html) for available storage classes and their characteristics.

doc/manual/source/SUMMARY.md.in

@@ -22,22 +22,12 @@
   - [Store Object](store/store-object.md)
     - [Content-Addressing Store Objects](store/store-object/content-address.md)
   - [Store Path](store/store-path.md)
-  - [Store Derivation and Deriving Path](store/derivation/index.md)
-    - [Derivation Outputs and Types of Derivations](store/derivation/outputs/index.md)
-      - [Content-addressing derivation outputs](store/derivation/outputs/content-address.md)
-      - [Input-addressing derivation outputs](store/derivation/outputs/input-address.md)
-  - [Build Trace](store/build-trace.md)
-  - [Derivation Resolution](store/resolution.md)
-  - [Building](store/building.md)
-  - [Secrets](store/secrets.md)
   - [Store Types](store/types/index.md)
 {{#include ./store/types/SUMMARY.md}}
-  - [Appendix: Math notation](store/math-notation.md)
 - [Nix Language](language/index.md)
   - [Data Types](language/types.md)
     - [String context](language/string-context.md)
   - [Syntax and semantics](language/syntax.md)
-    - [Evaluation](language/evaluation.md)
     - [Variables](language/variables.md)
     - [String literals](language/string-literals.md)
     - [Identifiers](language/identifiers.md)
@@ -61,7 +51,6 @@
   - [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)
-  - [Evaluation profiler](advanced-topics/eval-profiler.md)
 - [Command Reference](command-ref/index.md)
   - [Common Options](command-ref/opt-common.md)
   - [Common Environment Variables](command-ref/env-common.md)
@@ -121,24 +110,17 @@
 - [Architecture and Design](architecture/architecture.md)
 - [Formats and Protocols](protocols/index.md)
   - [JSON Formats](protocols/json/index.md)
-    - [Hash](protocols/json/hash.md)
-    - [Content Address](protocols/json/content-address.md)
-    - [Store Path](protocols/json/store-path.md)
     - [Store Object Info](protocols/json/store-object-info.md)
     - [Derivation](protocols/json/derivation.md)
-    - [Deriving Path](protocols/json/deriving-path.md)
-    - [Build Trace Entry](protocols/json/build-trace-entry.md)
-    - [Build Result](protocols/json/build-result.md)
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
   - [Store Path Specification](protocols/store-path.md)
-  - [Nix Archive (NAR) Format](protocols/nix-archive/index.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)
-  - [Benchmarking](development/benchmarking.md)
   - [Debugging](development/debugging.md)
   - [Documentation](development/documentation.md)
   - [CLI guideline](development/cli-guideline.md)
@@ -148,13 +130,6 @@
   - [Contributing](development/contributing.md)
 - [Releases](release-notes/index.md)
 {{#include ./SUMMARY-rl-next.md}}
-  - [Release 2.32 (2025-10-06)](release-notes/rl-2.32.md)
-  - [Release 2.31 (2025-08-21)](release-notes/rl-2.31.md)
-  - [Release 2.30 (2025-07-07)](release-notes/rl-2.30.md)
-  - [Release 2.29 (2025-05-14)](release-notes/rl-2.29.md)
-  - [Release 2.28 (2025-04-02)](release-notes/rl-2.28.md)
-  - [Release 2.27 (2025-03-03)](release-notes/rl-2.27.md)
-  - [Release 2.26 (2025-01-22)](release-notes/rl-2.26.md)
   - [Release 2.25 (2024-11-07)](release-notes/rl-2.25.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)

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

@@ -20,14 +20,14 @@ For a local machine to forward a build to a remote machine, the remote machine m
 
 ## Testing
 
-To test connecting to a remote [Nix instance] (in this case `mac`), run:
+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 parameter, e.g.
+query paramater, e.g.
 
 ```console
 nix store info --store ssh://username@mac?ssh-key=/home/alice/my-key
@@ -106,5 +106,3 @@ file included in `builders` via the syntax `@/path/to/file`. For example,
 
 causes the list of machines in `/etc/nix/machines` to be included.
 (This is the default.)
-
-[Nix instance]: @docroot@/glossary.md#gloss-nix-instance

doc/manual/source/advanced-topics/eval-profiler.md

@@ -1,33 +0,0 @@
-# Using the `eval-profiler`
-
-Nix evaluator supports [evaluation](@docroot@/language/evaluation.md)
-[profiling](<https://en.wikipedia.org/wiki/Profiling_(computer_programming)>)
-compatible with `flamegraph.pl`. The profiler samples the nix
-function call stack at regular intervals. It can be enabled with the
-[`eval-profiler`](@docroot@/command-ref/conf-file.md#conf-eval-profiler)
-setting:
-
-```console
-$ nix-instantiate "<nixpkgs>" -A hello --eval-profiler flamegraph
-```
-
-Stack sampling frequency and the output file path can be configured with
-[`eval-profile-file`](@docroot@/command-ref/conf-file.md#conf-eval-profile-file)
-and [`eval-profiler-frequency`](@docroot@/command-ref/conf-file.md#conf-eval-profiler-frequency).
-By default the collected profile is saved to `nix.profile` file in the current working directory.
-
-The collected profile can be directly consumed by `flamegraph.pl`:
-
-```console
-$ flamegraph.pl nix.profile > flamegraph.svg
-```
-
-The line information in the profile contains the location of the [call
-site](https://en.wikipedia.org/wiki/Call_site) position and the name of the
-function being called (when available). For example:
-
-```
-/nix/store/x9wnkly3k1gkq580m90jjn32q9f05q2v-source/pkgs/top-level/default.nix:167:5:primop import
-```
-
-Here `import` primop is called at `/nix/store/x9wnkly3k1gkq580m90jjn32q9f05q2v-source/pkgs/top-level/default.nix:167:5`.

doc/manual/source/architecture/architecture.md

@@ -22,9 +22,9 @@ The following [concept map] shows its main components (rectangles), the objects
            |                   |
 +----------|-------------------|--------------------------------+
 | Nix      |                   V                                |
-|          |       +------------------------+                   |
-|          |       | command line interface |------.            |
-|          |       +------------------------+      |            |
+|          |      +-------------------------+                   |
+|          |      | commmand line interface |------.            |
+|          |      +-------------------------+      |            |
 |          |                   |                   |            |
 |    evaluated by            calls              manages         |
 |          |                   |                   |            |
@@ -69,7 +69,7 @@ It can also execute build plans to produce new data, which are made available to
 A build plan itself is a series of *build tasks*, together with their build inputs.
 
 > **Important**
-> A build task in Nix is called [store derivation](@docroot@/glossary.md#gloss-store-derivation).
+> 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.

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

@@ -75,7 +75,7 @@ Most Nix commands interpret the following environment variables:
 - <span id="env-NIX_CONF_DIR">[`NIX_CONF_DIR`](#env-NIX_CONF_DIR)</span>
 
   Overrides the location of the system Nix configuration directory
-  (default `sysconfdir/nix`, i.e. `/etc/nix` on most systems).
+  (default `prefix/etc/nix`).
 
 - <span id="env-NIX_CONFIG">[`NIX_CONFIG`](#env-NIX_CONFIG)</span>
 

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

@@ -1,13 +1,13 @@
 xp_features_json = custom_target(
-  command : [ nix, '__dump-xp-features' ],
+  command : [nix, '__dump-xp-features'],
   capture : true,
   output : 'xp-features.json',
-  env : nix_env_for_docs,
 )
 
 experimental_features_shortlist_md = custom_target(
   command : nix_eval_for_docs + [
-    '--expr', 'import @INPUT0@ (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
+    '--expr',
+    'import @INPUT0@ (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
   ],
   input : [
     '../../generate-xp-features-shortlist.nix',
@@ -19,8 +19,14 @@ experimental_features_shortlist_md = custom_target(
 )
 
 nix3_cli_files = custom_target(
-  command : [ python.full_path(), '@INPUT0@', '@OUTPUT@', '--' ] + nix_eval_for_docs + [
-    '--expr', 'import @INPUT1@ true (builtins.readFile ./@INPUT2@)',
+  command : [
+    python.full_path(),
+    '@INPUT0@',
+    '@OUTPUT@',
+    '--'
+  ] + nix_eval_for_docs + [
+    '--expr',
+    'import @INPUT1@ true (builtins.readFile ./@INPUT2@)',
   ],
   input : [
     '../../remove_before_wrapper.py',
@@ -34,7 +40,8 @@ nix3_cli_files = custom_target(
 conf_file_md_body = custom_target(
   command : [
     nix_eval_for_docs,
-    '--expr', 'import @INPUT0@ { prefix = "conf"; } (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
+    '--expr',
+    'import @INPUT0@ { prefix = "conf"; } (builtins.fromJSON (builtins.readFile ./@INPUT1@))',
   ],
   capture : true,
   input : [

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

@@ -36,7 +36,7 @@ to a temporary location. The tarball must include a single top-level
 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
+[`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix
 expression to a low-level [store derivation]) and [`nix-store
 --realise`](@docroot@/command-ref/nix-store/realise.md) (to build the store
 derivation).
@@ -52,8 +52,8 @@ derivation).
 # Options
 
 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).
+[`nix-store --realise`](nix-store/realise.md),
+except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](nix-instantiate.md).
 
 - <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
 

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

@@ -11,10 +11,10 @@
 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://channels.nixos.org>
+- 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)
+- 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**
 >
@@ -53,11 +53,6 @@ This command has the following operations:
   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.
 
-  > **Note**
-  >
-  > Downloaded channel contents are cached.
-  > Use `--tarball-ttl` or the [`tarball-ttl` configuration option](@docroot@/command-ref/conf-file.md#conf-tarball-ttl) to change the validity period of cached downloads.
-
 - `--list-generations`
 
   Prints a list of all the current existing generations for the
@@ -88,9 +83,9 @@ This command has the following operations:
 Subscribe to the Nixpkgs channel and run `hello` from the GNU Hello package:
 
 ```console
-$ nix-channel --add https://channels.nixos.org/nixpkgs-unstable
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
 $ nix-channel --list
-nixpkgs https://channels.nixos.org/nixpkgs
+nixpkgs https://nixos.org/channels/nixpkgs
 $ nix-channel --update
 $ nix-shell -p hello --run hello
 hello

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

@@ -36,7 +36,7 @@ Instead, it looks in a few locations, and acts on all profiles it finds there:
    >
    > Not stable; subject to change
    >
-   > Do not rely on this functionality; it just exists for migration purposes and may change in the future.
+   > 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`.
@@ -62,15 +62,6 @@ These options are for deleting old [profiles] prior to deleting unreachable [sto
   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.
 
-  - <span id="opt-max-freed">[`--max-freed`](#opt-max-freed)</span> *bytes*
-
-<!-- duplication from https://github.com/NixOS/nix/blob/442a2623e48357ff72c77bb11cf2cf06d94d2f90/doc/manual/source/command-ref/nix-store/gc.md?plain=1#L39-L44 -->
-
-  Keep deleting paths until at least *bytes* bytes have been deleted,
-  then stop. The argument *bytes* can be followed by the
-  multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB
-  or TiB units.
-  
 {{#include ./opt-common.md}}
 
 {{#include ./env-common.md}}

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

@@ -84,7 +84,7 @@ When using public key authentication, you can avoid typing the passphrase with `
 > Copy GNU Hello from a remote machine using a known store path, and run it:
 >
 > ```shell-session
-> $ storePath="$(nix-instantiate --eval --raw '<nixpkgs>' -I nixpkgs=channel:nixpkgs-unstable -A hello.outPath)"
+> $ 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-env/delete-generations.md

@@ -27,7 +27,7 @@ This operation deletes the specified generations of the current profile.
   >
   > Older *and newer* generations will be deleted by this operation.
   >
-  > One might expect this to just delete older generations than the current one, but that is only true if the current generation is also the latest.
+  > 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.
 

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

@@ -11,7 +11,6 @@
   [`--from-profile` *path*]
   [`--preserve-installed` | `-P`]
   [`--remove-all` | `-r`]
-  [`--priority` *priority*]
 
 # Description
 
@@ -22,11 +21,11 @@ It is based on the current generation of the active [profile](@docroot@/command-
 
 The arguments *args* map to store paths in a number of possible ways:
 
-- By default, *args* is a set of names denoting derivations in the [default Nix expression].
+- 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 expression]: @docroot@/glossary.md#gloss-derivation-expression
+  [derivation]: @docroot@/glossary.md#gloss-derivation
   [default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
   [realised]: @docroot@/glossary.md#gloss-realise
 
@@ -62,15 +61,11 @@ The arguments *args* map to store paths in a number of possible ways:
   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 `--priority` *priority* is given, the priority of the derivations being installed is set to *priority*.
-  This can be used to override the priority of the derivations being installed.
-  This is useful if *args* are [store paths], which don't have any priority information.
+- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
 
-- If *args* are [store paths] that point to [store derivations][store derivation], then those store derivations are [realised], and the resulting output paths are installed.
+- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
 
-- If *args* are [store paths] that do not point to store derivations, then these are [realised] and installed.
-
-- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [store derivation].
+- 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:
@@ -122,8 +117,6 @@ The arguments *args* map to store paths in a number of possible ways:
   manifest.nix
   ```
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
-
 # Options
 
 - `--prebuilt-only` / `-b`
@@ -242,3 +235,4 @@ 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/query.md

@@ -125,10 +125,7 @@ derivation is shown unless `--no-name` is specified.
 
   - `--drv-path`
 
-    Print the [store path] to the [store derivation].
-
-    [store path]: @docroot@/glossary.md#gloss-store-path
-    [store derivation]: @docroot@/glossary.md#gloss-derivation
+    Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
 
   - `--out-path`
 

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

@@ -22,7 +22,7 @@ left untouched; this is not an error. It is also not an error if an
 element of *args* matches no installed derivations.
 
 For a description of how *args* is mapped to a set of store paths, see
-[`--install`](./install.md). If *args* describes multiple
+[`--install`](#operation---install). If *args* describes multiple
 store paths with the same symbolic name, only the one with the highest
 version is installed.
 

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

@@ -67,7 +67,7 @@ md5sum`.
 - `--type` *hashAlgo*
 
   Use the specified cryptographic hash algorithm, which can be one of
-  `blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
+  `md5`, `sha1`, `sha256`, and `sha512`.
 
 - `--to-base16`
 

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

@@ -5,7 +5,7 @@
 # Synopsis
 
 `nix-instantiate`
-  [`--parse` | `--eval` [`--strict`] [`--raw` | `--json` | `--xml`] ]
+  [`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ]
   [`--read-write-mode`]
   [`--arg` *name* *value*]
   [{`--attr`| `-A`} *attrPath*]
@@ -32,7 +32,7 @@ standard input.
 
 - `--add-root` *path*
 
-  See the [corresponding option](./nix-store.md) in `nix-store`.
+  See the [corresponding option](nix-store.md) in `nix-store`.
 
 - `--parse`
 
@@ -42,8 +42,8 @@ standard input.
 - `--eval`
 
   Just parse and evaluate the input files, and print the resulting
-  values on standard output.
-  Store derivations are not serialized and written to the store, but instead just hashed and discarded.
+  values on standard output. No instantiation of store derivations
+  takes place.
 
   > **Warning**
   >
@@ -102,11 +102,6 @@ standard input.
   > This option can cause non-termination, because lazy data
   > structures can be infinitely large.
 
-- `--raw`
-
-  When used with `--eval`, the evaluation result must be a string,
-  which is printed verbatim, without quoting, escaping or trailing newline.
-
 - `--json`
 
   When used with `--eval`, print the resulting value as an JSON

doc/manual/source/command-ref/nix-prefetch-url.md

@@ -42,7 +42,7 @@ the path of the downloaded file in the Nix store is also printed.
 - `--type` *hashAlgo*
 
   Use the specified cryptographic hash algorithm,
-  which can be one of `blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
+  which can be one of `md5`, `sha1`, `sha256`, and `sha512`.
   The default is `sha256`.
 
 - `--print-path`

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

@@ -19,7 +19,7 @@
 
 This man page describes the command `nix-shell`, which is distinct from `nix
 shell`. For documentation on the latter, run `nix shell --help` or see `man
-nix3-env-shell`.
+nix3-shell`.
 
 # Description
 
@@ -88,9 +88,7 @@ All options not listed here are passed to `nix-store
   cleared before the interactive shell is started, so you get an
   environment that more closely corresponds to the “real” Nix build. A
   few variables, in particular `HOME`, `USER` and `DISPLAY`, are
-  retained.  Note that the shell used to run commands is obtained from
-  [`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL) / `<nixpkgs>` from
-  `NIX_PATH`, and therefore not affected by `--pure`.
+  retained.
 
 - `--packages` / `-p` *packages*…
 
@@ -114,30 +112,11 @@ All options not listed here are passed to `nix-store
 
 # Environment variables
 
-- <span id="env-NIX_BUILD_SHELL">[`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL)</span>
+- `NIX_BUILD_SHELL`
 
-  Shell used to start the interactive environment.
-  Defaults to the `bash` from `bashInteractive` found in `<nixpkgs>`, falling back to the `bash` found in `PATH` if not found.
-
-  > **Note**
-  >
-  > The shell obtained using this method may not necessarily be the same as any shells requested in *path*.
-
-  <!-- -->
-
-  > **Example
-  >
-  >  Despite `--pure`, this invocation will not result in a fully reproducible shell environment:
-  >
-  > ```nix
-  > #!/usr/bin/env -S nix-shell --pure
-  > let
-  >   pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/854fdc68881791812eddd33b2fed94b954979a8e.tar.gz") {};
-  > in
-  > pkgs.mkShell {
-  >   buildInputs = pkgs.bashInteractive;
-  > }
-  > ```
+  Shell used to start the interactive environment. Defaults to the
+  `bash` found in `<nixpkgs>`, falling back to the `bash` found in
+  `PATH` if not found.
 
 {{#include ./env-common.md}}
 
@@ -242,21 +221,16 @@ print(t)
 ```
 
 Similarly, the following is a Perl script that specifies that it
-requires Perl and the `HTML::TokeParser::Simple`, `LWP` and
-`LWP::Protocol::Https` packages:
+requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:
 
 ```perl
 #! /usr/bin/env nix-shell
-#! nix-shell -i perl 
-#! nix-shell --packages perl 
-#! nix-shell --packages perlPackages.HTMLTokeParserSimple 
-#! nix-shell --packages perlPackages.LWP
-#! nix-shell --packages perlPackages.LWPProtocolHttps
+#! nix-shell -i perl --packages perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
 
 use HTML::TokeParser::Simple;
 
 # Fetch nixos.org and print all hrefs.
-my $p = HTML::TokeParser::Simple->new(url => 'https://nixos.org/');
+my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
 
 while (my $token = $p->get_tag("a")) {
     my $href = $token->get_attr("href");
@@ -321,7 +295,7 @@ contains:
 ```nix
 with import <nixpkgs> {};
 
-runCommand "dummy" { buildInputs = [ python3 python3Packages.prettytable ]; } ""
+runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
 ```
 
 The script's file name is passed as the first argument to the interpreter specified by the `-i` flag.

doc/manual/source/command-ref/nix-store/add-fixed.md

@@ -21,9 +21,6 @@ This operation has the following options:
   Use recursive instead of flat hashing mode, used when adding
   directories to the store.
 
-  *paths* that refer to symlinks are not dereferenced, but added to the store
-  as symlinks with the same target.
-
 {{#include ./opt-common.md}}
 
 {{#include ../opt-common.md}}

doc/manual/source/command-ref/nix-store/add.md

@@ -11,9 +11,6 @@
 The operation `--add` adds the specified paths to the Nix store. It
 prints the resulting paths in the Nix store on standard output.
 
-*paths* that refer to symlinks are not dereferenced, but added to the store
-as symlinks with the same target.
-
 {{#include ./opt-common.md}}
 
 {{#include ../opt-common.md}}

doc/manual/source/command-ref/nix-store/gc.md

@@ -48,7 +48,8 @@ The behaviour of the collector is also influenced by the
 configuration file.
 
 By default, the collector prints the total number of freed bytes when it
-finishes (or when it is interrupted).
+finishes (or when it is interrupted). With `--print-dead`, it prints the
+number of bytes that would be freed.
 
 {{#include ./opt-common.md}}
 

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

@@ -45,19 +45,10 @@ symlink.
 
   [output paths]: @docroot@/glossary.md#gloss-output-path
 
-- `--references`
-
-  Prints the set of [references] of the store paths
-  *paths*, that is, their immediate dependencies. (For *all*
-  dependencies, use `--requisites`.)
-
-  [references]: @docroot@/glossary.md#gloss-reference
-
 - `--requisites` / `-R`
 
-  Prints out the set of [*requisites*][requisite] (better known as the [closure]) of the store path *paths*.
+  Prints out the [closure] of the store path *paths*.
 
-  [requisite]: @docroot@/glossary.md#gloss-requisite
   [closure]: @docroot@/glossary.md#gloss-closure
 
   This query has one option:
@@ -74,25 +65,29 @@ symlink.
   dependencies) is obtained by distributing the closure of a store
   derivation and specifying the option `--include-outputs`.
 
+- `--references`
+
+  Prints the set of [references] of the store paths
+  *paths*, that is, their immediate dependencies. (For *all*
+  dependencies, use `--requisites`.)
+
+  [references]: @docroot@/glossary.md#gloss-reference
+
 - `--referrers`
 
-  Prints the set of [*referrers*][referrer] of the store paths *paths*, that is,
+  Prints the set of *referrers* of the store paths *paths*, that is,
   the store paths currently existing in the Nix store that refer to
   one of *paths*. Note that contrary to the references, the set of
   referrers is not constant; it can change as store paths are added or
   removed.
 
-  [referrer]: @docroot@/glossary.md#gloss-referrer
-
 - `--referrers-closure`
 
   Prints the closure of the set of store paths *paths* under the
-  [referrers relation][referrer]; that is, all store paths that directly or
+  referrers relation; that is, all store paths that directly or
   indirectly refer to one of *paths*. These are all the path currently
   in the Nix store that are dependent on *paths*.
 
-  [referrer]: @docroot@/glossary.md#gloss-referrer
-
 - `--deriver` / `-d`
 
   Prints the [deriver] that was used to build the store paths *paths*. If

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

@@ -15,7 +15,7 @@ Each of *paths* is processed as follows:
   1. If it is not [valid], substitute the store derivation file itself.
   2. Realise its [output paths]:
     - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure].
-      - With [content-addressing derivations] (experimental):
+      - With [content-addressed derivations] (experimental):
         Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database].
     - For any store paths that cannot be substituted, produce the required store objects:
       1. Realise all outputs of the derivation's dependencies
@@ -32,7 +32,7 @@ If no substitutes are available and no store derivation is given, realisation fa
 [store objects]: @docroot@/store/store-object.md
 [closure]: @docroot@/glossary.md#gloss-closure
 [substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
-[content-addressing derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
+[content-addressed derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
 [Nix database]: @docroot@/glossary.md#gloss-nix-database
 
 The resulting paths are printed on standard output.

doc/manual/source/development/benchmarking.md

@@ -1,187 +0,0 @@
-# Running Benchmarks
-
-This guide explains how to build and run performance benchmarks in the Nix codebase.
-
-## Overview
-
-Nix uses the [Google Benchmark](https://github.com/google/benchmark) framework for performance testing. Benchmarks help measure and track the performance of critical operations like derivation parsing.
-
-## Building Benchmarks
-
-Benchmarks are disabled by default and must be explicitly enabled during the build configuration. For accurate results, use a debug-optimized release build.
-
-### Development Environment Setup
-
-First, enter the development shell which includes the necessary dependencies:
-
-```bash
-nix develop .#native-ccacheStdenv
-```
-
-### Configure Build with Benchmarks
-
-From the project root, configure the build with benchmarks enabled and optimization:
-
-```bash
-cd build
-meson configure -Dbenchmarks=true -Dbuildtype=debugoptimized
-```
-
-The `debugoptimized` build type provides:
-- Compiler optimizations for realistic performance measurements
-- Debug symbols for profiling and analysis
-- Balance between performance and debuggability
-
-### Build the Benchmarks
-
-Build the project including benchmarks:
-
-```bash
-ninja
-```
-
-This will create benchmark executables in the build directory. Currently available:
-- `build/src/libstore-tests/nix-store-benchmarks` - Store-related performance benchmarks
-
-Additional benchmark executables will be created as more benchmarks are added to the codebase.
-
-## Running Benchmarks
-
-### Basic Usage
-
-Run benchmark executables directly. For example, to run store benchmarks:
-
-```bash
-./build/src/libstore-tests/nix-store-benchmarks
-```
-
-As more benchmark executables are added, run them similarly from their respective build directories.
-
-### Filtering Benchmarks
-
-Run specific benchmarks using regex patterns:
-
-```bash
-# Run only derivation parser benchmarks
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_filter="derivation.*"
-
-# Run only benchmarks for hello.drv
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_filter=".*hello.*"
-```
-
-### Output Formats
-
-Generate benchmark results in different formats:
-
-```bash
-# JSON output
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_format=json > results.json
-
-# CSV output
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_format=csv > results.csv
-```
-
-### Advanced Options
-
-```bash
-# Run benchmarks multiple times for better statistics
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_repetitions=10
-
-# Set minimum benchmark time (useful for micro-benchmarks)
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_min_time=2
-
-# Compare against baseline
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_baseline=baseline.json
-
-# Display time in custom units
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_time_unit=ms
-```
-
-## Writing New Benchmarks
-
-To add new benchmarks:
-
-1. Create a new `.cc` file in the appropriate `*-tests` directory
-2. Include the benchmark header:
-   ```cpp
-   #include <benchmark/benchmark.h>
-   ```
-
-3. Write benchmark functions:
-   ```cpp
-   static void BM_YourBenchmark(benchmark::State & state)
-   {
-       // Setup code here
-
-       for (auto _ : state) {
-           // Code to benchmark
-       }
-   }
-   BENCHMARK(BM_YourBenchmark);
-   ```
-
-4. Add the file to the corresponding `meson.build`:
-   ```meson
-   benchmarks_sources = files(
-       'your-benchmark.cc',
-       # existing benchmarks...
-   )
-   ```
-
-## Profiling with Benchmarks
-
-For deeper performance analysis, combine benchmarks with profiling tools:
-
-```bash
-# Using Linux perf
-perf record ./build/src/libstore-tests/nix-store-benchmarks
-perf report
-```
-
-### Using Valgrind Callgrind
-
-Valgrind's callgrind tool provides detailed profiling information that can be visualized with kcachegrind:
-
-```bash
-# Profile with callgrind
-valgrind --tool=callgrind ./build/src/libstore-tests/nix-store-benchmarks
-
-# Visualize the results with kcachegrind
-kcachegrind callgrind.out.*
-```
-
-This provides:
-- Function call graphs
-- Instruction-level profiling
-- Source code annotation
-- Interactive visualization of performance bottlenecks
-
-## Continuous Performance Testing
-
-```bash
-# Save baseline results
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_format=json > baseline.json
-
-# Compare against baseline in CI
-./build/src/libstore-tests/nix-store-benchmarks --benchmark_baseline=baseline.json
-```
-
-## Troubleshooting
-
-### Benchmarks not building
-
-Ensure benchmarks are enabled:
-```bash
-meson configure build | grep benchmarks
-# Should show: benchmarks true
-```
-
-### Inconsistent results
-
-- Ensure your system is not under heavy load
-- Disable CPU frequency scaling for consistent results
-- Run benchmarks multiple times with `--benchmark_repetitions`
-
-## See Also
-
-- [Google Benchmark documentation](https://github.com/google/benchmark/blob/main/docs/user_guide.md)

doc/manual/source/development/building.md

@@ -23,32 +23,32 @@ $ nix-shell
 To get a shell with one of the other [supported compilation environments](#compilation-environments):
 
 ```console
-$ nix-shell --attr devShells.x86_64-linux.native-clangStdenv
+$ nix-shell --attr devShells.x86_64-linux.native-clangStdenvPackages
 ```
 
 > **Note**
 >
-> You can use `native-ccacheStdenv` to drastically improve rebuild time.
+> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time.
 > By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
 
 To build Nix itself in this shell:
 
 ```console
-[nix-shell]$ out="$(pwd)/outputs/out" dev=$out debug=$out mesonFlags+=" --prefix=${out}"
-[nix-shell]$ dontAddPrefix=1 configurePhase
-[nix-shell]$ buildPhase
+[nix-shell]$ mesonFlags+=" --prefix=$(pwd)/outputs/out"
+[nix-shell]$ dontAddPrefix=1 mesonConfigurePhase
+[nix-shell]$ ninjaBuildPhase
 ```
 
 To test it:
 
 ```console
-[nix-shell]$ checkPhase
+[nix-shell]$ mesonCheckPhase
 ```
 
 To install it in `$(pwd)/outputs`:
 
 ```console
-[nix-shell]$ installPhase
+[nix-shell]$ ninjaInstallPhase
 [nix-shell]$ ./outputs/out/bin/nix --version
 nix (Nix) 2.12
 ```
@@ -66,7 +66,7 @@ You can also build Nix for one of the [supported platforms](#platforms).
 This section assumes you are using Nix with the [`flakes`] and [`nix-command`] experimental features enabled.
 
 [`flakes`]: @docroot@/development/experimental-features.md#xp-feature-flakes
-[`nix-command`]: @docroot@/development/experimental-features.md#xp-feature-nix-command
+[`nix-command`]: @docroot@/development/experimental-features.md#xp-nix-command
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
 
@@ -79,7 +79,7 @@ This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` im
 To get a shell with one of the other [supported compilation environments](#compilation-environments):
 
 ```console
-$ nix develop .#native-clangStdenv
+$ nix develop .#native-clangStdenvPackages
 ```
 
 > **Note**
@@ -90,20 +90,20 @@ $ nix develop .#native-clangStdenv
 To build Nix itself in this shell:
 
 ```console
-[nix-shell]$ configurePhase
-[nix-shell]$ buildPhase
+[nix-shell]$ mesonConfigurePhase
+[nix-shell]$ ninjaBuildPhase
 ```
 
 To test it:
 
 ```console
-[nix-shell]$ checkPhase
+[nix-shell]$ mesonCheckPhase
 ```
 
 To install it in `$(pwd)/outputs`:
 
 ```console
-[nix-shell]$ installPhase
+[nix-shell]$ ninjaInstallPhase
 [nix-shell]$ nix --version
 nix (Nix) 2.12
 ```
@@ -167,26 +167,36 @@ It is useful to perform multiple cross and native builds on the same source tree
 for example to ensure that better support for one platform doesn't break the build for another.
 Meson thankfully makes this very easy by confining all build products to the build directory --- one simple shares the source directory between multiple build directories, each of which contains the build for Nix to a different platform.
 
-Here's how to do that:
+Nixpkgs's `mesonConfigurePhase` always chooses `build` in the current directory as the name and location of the build.
+This makes having multiple build directories slightly more inconvenient.
+The good news is that Meson/Ninja seem to cope well with relocating the build directory after it is created.
 
-1. Instruct Nixpkgs's infra where we want Meson to put its build directory
-
-   ```bash
-   mesonBuildDir=build-my-variant-name
-   ```
+Here's how to do that
 
 1. Configure as usual
 
    ```bash
-   configurePhase
+   mesonConfigurePhase
+   ```
+
+2. Rename the build directory
+
+   ```bash
+   cd .. # since `mesonConfigurePhase` cd'd inside
+   mv build build-linux # or whatever name we want
+   cd build-linux
    ```
 
 3. Build as usual
 
    ```bash
-   buildPhase
+   ninjaBuildPhase
    ```
 
+> **N.B.**
+> [`nixpkgs#335818`](https://github.com/NixOS/nixpkgs/issues/335818) tracks giving `mesonConfigurePhase` proper support for custom build directories.
+> When it is fixed, we can simplify these instructions and then remove this notice.
+
 ## System type
 
 Nix uses a string with the following format to identify the *system type* or *platform* it runs on:
@@ -195,38 +205,28 @@ Nix uses a string with the following format to identify the *system type* or *pl
 <cpu>-<os>[-<abi>]
 ```
 
-It is set when Nix is compiled for the given system, and based on the output of Meson's [`host_machine` information](https://mesonbuild.com/Reference-manual_builtin_host_machine.html)>
+It is set when Nix is compiled for the given system, and based on the output of [`config.guess`](https://github.com/nixos/nix/blob/master/config/config.guess) ([upstream](https://git.savannah.gnu.org/cgit/config.git/tree/config.guess)):
 
 ```
 <cpu>-<vendor>-<os>[<version>][-<abi>]
 ```
 
-When cross-compiling Nix with Meson for local development, you need to specify a [cross-file](https://mesonbuild.com/Cross-compilation.html) using the `--cross-file` option. Cross-files define the target architecture and toolchain. When cross-compiling Nix with Nix, Nixpkgs takes care of this for you.
-
-In the nix flake we also have some cross-compilation targets available:
+When Nix is built such that `./configure` is passed any of the `--host`, `--build`, `--target` options, the value is based on the output of [`config.sub`](https://github.com/nixos/nix/blob/master/config/config.sub) ([upstream](https://git.savannah.gnu.org/cgit/config.git/tree/config.sub)):
 
 ```
-nix build .#nix-everything-riscv64-unknown-linux-gnu
-nix build .#nix-everything-armv7l-unknown-linux-gnueabihf
-nix build .#nix-everything-armv7l-unknown-linux-gnueabihf
-nix build .#nix-everything-x86_64-unknown-freebsd
-nix build .#nix-everything-x86_64-w64-mingw32
+<cpu>-<vendor>[-<kernel>]-<os>
 ```
 
-For historic reasons and backward-compatibility, some CPU and OS identifiers are translated as follows:
+For historic reasons and backward-compatibility, some CPU and OS identifiers are translated from the GNU Autotools naming convention in [`configure.ac`](https://github.com/nixos/nix/blob/master/configure.ac) as follows:
 
-| `host_machine.cpu_family()` | `host_machine.endian()` | Nix                 |
-|-----------------------------|-------------------------|---------------------|
-| `x86`                       |                         | `i686`              |
-| `arm`                       |                         | `host_machine.cpu()`|
-| `ppc`                       | `little`                | `powerpcle`         |
-| `ppc64`                     | `little`                | `powerpc64le`       |
-| `ppc`                       | `big`                   | `powerpc`           |
-| `ppc64`                     | `big`                   | `powerpc64`         |
-| `mips`                      | `little`                | `mipsel`            |
-| `mips64`                    | `little`                | `mips64el`          |
-| `mips`                      | `big`                   | `mips`              |
-| `mips64`                    | `big`                   | `mips64`            |
+| `config.guess`             | Nix                 |
+|----------------------------|---------------------|
+| `amd64`                    | `x86_64`            |
+| `i*86`                     | `i686`              |
+| `arm6`                     | `arm6l`             |
+| `arm7`                     | `arm7l`             |
+| `linux-gnu*`               | `linux`             |
+| `linux-musl*`              | `linux`             |
 
 ## Compilation environments
 
@@ -240,29 +240,28 @@ Nix can be compiled using multiple environments:
 To build with one of those environments, you can use
 
 ```console
-$ nix build .#nix-cli-ccacheStdenv
+$ nix build .#nix-ccacheStdenv
 ```
 
 for flake-enabled Nix, or
 
 ```console
-$ nix-build --attr nix-cli-ccacheStdenv
+$ nix-build --attr nix-ccacheStdenv
 ```
 
 for classic Nix.
 
-You can use any of the other supported environments in place of `nix-cli-ccacheStdenv`.
+You can use any of the other supported environments in place of `nix-ccacheStdenv`.
 
 ## Editor integration
 
 The `clangd` LSP server is installed by default on the `clang`-based `devShell`s.
-See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#building-nix-with-flakes) or in [classic Nix](#building-nix).
+See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#nix-with-flakes) or in [classic Nix](#classic-nix).
 
 To use the LSP with your editor, you will want a `compile_commands.json` file telling `clangd` how we are compiling the code.
 Meson's configure always produces this inside the build directory.
 
-Configure your editor to use the `clangd` from the `.#native-clangStdenv` shell.
-You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
+Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages` shell. You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
 
 > **Note**
 >
@@ -278,8 +277,6 @@ You may run the formatters as a one-off using:
 ./maintainers/format.sh
 ```
 
-### Pre-commit hooks
-
 If you'd like to run the formatters before every commit, install the hooks:
 
 ```
@@ -294,30 +291,3 @@ If it fails, run `git add --patch` to approve the suggestions _and commit again_
 To refresh pre-commit hook's config file, do the following:
 1. Exit the development shell and start it again by running `nix develop`.
 2. If you also use the pre-commit hook, also run `pre-commit-hooks-install` again.
-
-### VSCode
-
-Insert the following json into your `.vscode/settings.json` file to configure `nixfmt`.
-This will be picked up by the _Format Document_ command, `"editor.formatOnSave"`, etc.
-
-```json
-{
-  "nix.formatterPath": "nixfmt",
-  "nix.serverSettings": {
-    "nixd": {
-      "formatting": {
-        "command": [
-          "nixfmt"
-        ],
-      },
-    },
-    "nil": {
-      "formatting": {
-        "command": [
-          "nixfmt"
-        ],
-      },
-    },
-  },
-}
-```

doc/manual/source/development/cli-guideline.md

@@ -170,9 +170,9 @@ sensitive.
 
 
 ```shell
-$ nix init --template=template#python
+$ nix init --template=template#pyton
 ------------------------------------------------------------------------
-  Error! Template `template#python` not found.
+  Error! Template `template#pyton` not found.
 ------------------------------------------------------------------------
 Initializing Nix project at `/path/to/here`.
       Select a template for you new project:

doc/manual/source/development/contributing.md

@@ -20,9 +20,8 @@ prs: 1238
 Here's one or more paragraphs that describe the change.
 
 - It's markdown
-- Add references to the manual using [links like this](@_at_docroot@/example.md)
+- Add references to the manual using @docroot@
 ```
-<!-- for the raw markdown readers: that means using @docroot@ -->
 
 Significant changes should add the following header, which moves them to the top.
 

doc/manual/source/development/debugging.md

@@ -2,8 +2,6 @@
 
 This section shows how to build and debug Nix with debug symbols enabled.
 
-Additionally, see [Testing Nix](./testing.md) for further instructions on how to debug Nix in the context of a unit test or functional test.
-
 ## Building Nix with Debug Symbols
 
 In the development shell, set the `mesonBuildType` environment variable to `debug` before configuring the build:
@@ -15,28 +13,6 @@ In the development shell, set the `mesonBuildType` environment variable to `debu
 Then, proceed to build Nix as described in [Building Nix](./building.md).
 This will build Nix with debug symbols, which are essential for effective debugging.
 
-It is also possible to build without debugging for faster build:
-
-```console
-[nix-shell]$ NIX_HARDENING_ENABLE=$(printLines $NIX_HARDENING_ENABLE | grep -v fortify)
-[nix-shell]$ export mesonBuildType=debug
-```
-
-(The first line is needed because `fortify` hardening requires at least some optimization.)
-
-## Building Nix with sanitizers
-
-Nix can be built with [Address](https://clang.llvm.org/docs/AddressSanitizer.html) and
-[UB](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) sanitizers using LLVM
-or GCC. This is useful when debugging memory corruption issues.
-
-```console
-[nix-shell]$ export mesonBuildType=debugoptimized
-[nix-shell]$ appendToVar mesonFlags "-Dlibexpr:gc=disabled" # Disable Boehm
-[nix-shell]$ appendToVar mesonFlags "-Dbindings=false" # Disable nix-perl
-[nix-shell]$ appendToVar mesonFlags "-Db_sanitize=address,undefined"
-```
-
 ## Debugging the Nix Binary
 
 Obtain your preferred debugger within the development shell:

doc/manual/source/development/documentation.md

@@ -19,37 +19,25 @@ nix-build -E '(import ./.).packages.${builtins.currentSystem}.nix.doc'
 or
 
 ```console
-nix build .#nix-manual
+nix build .#nix^doc
 ```
 
-and open `./result/share/doc/nix/manual/index.html`.
+and open `./result-doc/share/doc/nix/manual/index.html`.
 
-
-To build the manual incrementally, [enter the development shell](./building.md) and configure with `doc-gen` enabled:
-
-**If using interactive `nix develop`:**
+To build the manual incrementally, [enter the development shell](./building.md) and run:
 
 ```console
-$ nix develop
-$ mesonFlags="$mesonFlags -Ddoc-gen=true" mesonConfigurePhase
+make manual-html-open -j $NIX_BUILD_CORES
 ```
 
-**If using direnv:**
+In order to reflect changes to the [Makefile for the manual], clear all generated files before re-building:
+
+[Makefile for the manual]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
 
 ```console
-$ direnv allow
-$ bash -c 'source $stdenv/setup && mesonFlags="$mesonFlags -Ddoc-gen=true" mesonConfigurePhase'
+rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/source/command-ref/new-cli && make manual-html -j $NIX_BUILD_CORES
 ```
 
-Then build the manual:
-
-```console
-$ cd build
-$ meson compile manual
-```
-
-The HTML manual will be generated at `build/src/nix-manual/manual/index.html`.
-
 ## Style guide
 
 The goal of this style guide is to make it such that
@@ -215,7 +203,7 @@ $ xdg-open ./result/share/doc/nix/internal-api/html/index.html
 or inside `nix-shell` or `nix develop`:
 
 ```console
-$ configurePhase
+$ mesonConfigurePhase
 $ ninja src/internal-api-docs/html
 $ xdg-open src/internal-api-docs/html/index.html
 ```
@@ -236,13 +224,7 @@ $ xdg-open ./result/share/doc/nix/external-api/html/index.html
 or inside `nix-shell` or `nix develop`:
 
 ```
-$ configurePhase
+$ mesonConfigurePhase
 $ ninja src/external-api-docs/html
 $ xdg-open src/external-api-docs/html/index.html
 ```
-
-If you use direnv, or otherwise want to run `configurePhase` in a transient shell, use:
-
-```bash
-nix-shell -A devShells.x86_64-linux.native-clangStdenv --command 'appendToVar mesonFlags "-Ddoc-gen=true"; mesonConfigurePhase'
-```

doc/manual/source/development/meson.build

@@ -1,12 +1,12 @@
 experimental_feature_descriptions_md = custom_target(
   command : nix_eval_for_docs + [
-    '--expr', 'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))',
+    '--expr',
+    'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))',
   ],
   input : [
     '../../generate-xp-features.nix',
     xp_features_json,
   ],
   capture : true,
-  env : nix_env_for_docs,
   output : 'experimental-feature-descriptions.md',
 )

doc/manual/source/development/testing.md

@@ -30,7 +30,7 @@ The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
 > src
 > ├── libexpr
 > │   ├── meson.build
-> │   ├── include/nix/expr/value/context.hh
+> │   ├── value/context.hh
 > │   ├── value/context.cc
 > │   …
 > │
@@ -46,12 +46,8 @@ The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
 > │   │
 > │   ├── libexpr-test-support
 > │   │   ├── meson.build
-> │   │   ├── include/nix/expr
-> │   │   │   ├── meson.build
-> │   │   │   └── tests
-> │   │   │       ├── value/context.hh
-> │   │   │       …
 > │   │   └── tests
+> │   │       ├── value/context.hh
 > │   │       ├── value/context.cc
 > │   │       …
 > │   │
@@ -63,7 +59,7 @@ The unit tests are defined using the [googletest] and [rapidcheck] frameworks.
 > ```
 
 The tests for each Nix library (`libnixexpr`, `libnixstore`, etc..) live inside a directory `src/${library_name_without-nix}-test`.
-Given an interface (header) and implementation pair in the original library, say, `src/libexpr/include/nix/expr/value/context.hh` and `src/libexpr/value/context.cc`, we write tests for it in `src/libexpr-tests/value/context.cc`, and (possibly) declare/define additional interfaces for testing purposes in `src/libexpr-test-support/include/nix/expr/tests/value/context.hh` and `src/libexpr-test-support/tests/value/context.cc`.
+Given an interface (header) and implementation pair in the original library, say, `src/libexpr/value/context.{hh,cc}`, we write tests for it in `src/libexpr-tests/value/context.cc`, and (possibly) declare/define additional interfaces for testing purposes in `src/libexpr-test-support/tests/value/context.{hh,cc}`.
 
 Data for unit tests is stored in a `data` subdir of the directory for each unit test executable.
 For example, `libnixstore` code is in `src/libstore`, and its test data is in `src/libstore-tests/data`.
@@ -71,7 +67,7 @@ The path to the `src/${library_name_without-nix}-test/data` directory is passed
 Note that each executable only gets the data for its tests.
 
 The unit test libraries are in `src/${library_name_without-nix}-test-support`.
-All headers are in a `tests` subdirectory so they are included with `#include "nix/tests/"`.
+All headers are in a `tests` subdirectory so they are included with `#include "tests/"`.
 
 The use of all these separate directories for the unit tests might seem inconvenient, as for example the tests are not "right next to" the part of the code they are testing.
 But organizing the tests this way has one big benefit:
@@ -91,11 +87,7 @@ A environment variables that Google Test accepts are also worth knowing:
 
    This is used to avoid logging passing tests.
 
-3. [`GTEST_BREAK_ON_FAILURE`](https://google.github.io/googletest/advanced.html#turning-assertion-failures-into-break-points)
-
-   This is used to create a debugger breakpoint when an assertion failure occurs.
-
-Putting the first two together, one might run
+Putting the two together, one might run
 
 ```bash
 GTEST_BRIEF=1 GTEST_FILTER='ErrorTraceTest.*' meson test nix-expr-tests -v
@@ -103,23 +95,7 @@ GTEST_BRIEF=1 GTEST_FILTER='ErrorTraceTest.*' meson test nix-expr-tests -v
 
 for short but comprensive output.
 
-### Debugging tests
-
-For debugging, it is useful to combine the third option above with Meson's [`--gdb`](https://mesonbuild.com/Unit-tests.html#other-test-options) flag:
-
-```bash
-GTEST_BRIEF=1 GTEST_FILTER='Group.my-failing-test' meson test nix-expr-tests --gdb
-```
-
-This will:
-
-1. Run the unit test with GDB
-
-2. Run just `Group.my-failing-test`
-
-3. Stop the program when the test fails, allowing the user to then issue arbitrary commands to GDB.
-
-### Characterisation testing { #characterisation-testing-unit }
+### Characterisation testing { #characaterisation-testing-unit }
 
 See [functional characterisation testing](#characterisation-testing-functional) for a broader discussion of characterisation testing.
 
@@ -161,14 +137,14 @@ Functional tests are run during `installCheck` in the `nix` package build, as we
 The whole test suite (functional and unit tests) can be run with:
 
 ```shell-session
-$ checkPhase
+$ mesonCheckPhase
 ```
 
 ### Grouping tests
 
 Sometimes it is useful to group related tests so they can be easily run together without running the entire test suite.
 Each test group is in a subdirectory of `tests`.
-For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressing derivation outputs.
+For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressed derivation outputs.
 
 That test group can be run like this:
 
@@ -237,10 +213,10 @@ edit it like so:
  bar
 ```
 
-Then, running the test with [`--interactive`](https://mesonbuild.com/Unit-tests.html#other-test-options) will prevent Meson from hijacking the terminal so you can drop you into GDB once the script reaches that point:
+Then, running the test with `./mk/debug-test.sh` will drop you into GDB once the script reaches that point:
 
 ```shell-session
-$ meson test ${testName} --interactive
+$ ./mk/debug-test.sh tests/functional/${testName}.sh
 ...
 + gdb blash blub
 GNU gdb (GDB) 12.1
@@ -321,7 +297,7 @@ Creating a Cachix cache for your installer tests and adding its authorisation to
   - `armv7l-linux`
   - `x86_64-darwin`
 
-- The `installer_test` job (which runs on `ubuntu-24.04` and `macos-14`) will try to install Nix with the cached installer and run a trivial Nix command.
+- The `installer_test` job (which runs on `ubuntu-latest` and `macos-latest`) will try to install Nix with the cached installer and run a trivial Nix command.
 
 ### One-time setup
 

doc/manual/source/glossary.md

@@ -1,13 +1,5 @@
 # Glossary
 
-- [build system]{#gloss-build-system}
-
-  Generic term for software that facilitates the building of software by automating the invocation of compilers, linkers, and other tools.
-
-  Nix can be used as a generic build system.
-  It has no knowledge of any particular programming language or toolchain.
-  These details are specified in [derivation expressions](#gloss-derivation-expression).
-
 - [content address]{#gloss-content-address}
 
   A
@@ -21,62 +13,37 @@
 
     - [Content-Addressing File System Objects](@docroot@/store/file-system-object/content-address.md)
     - [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md)
-    - [content-addressing derivation](#gloss-content-addressing-derivation)
+    - [content-addressed derivation](#gloss-content-addressed-derivation)
 
   Software Heritage's writing on [*Intrinsic and Extrinsic identifiers*](https://www.softwareheritage.org/2020/07/09/intrinsic-vs-extrinsic-identifiers) is also a good introduction to the value of content-addressing over other referencing schemes.
 
   Besides content addressing, the Nix store also uses [input addressing](#gloss-input-addressed-store-object).
 
-- [content-addressed storage]{#gloss-content-addressed-store}
-
-  The industry term for storage and retrieval systems using [content addressing](#gloss-content-address). A Nix store also has [input addressing](#gloss-input-addressed-store-object), and metadata.
-
 - [derivation]{#gloss-derivation}
 
-  A derivation can be thought of as a [pure function](https://en.wikipedia.org/wiki/Pure_function) that produces new [store objects][store object] from existing store objects.
-
-  Derivations are implemented as [operating system processes that run in a sandbox](@docroot@/store/building.md#builder-execution).
-  This sandbox by default only allows reading from store objects specified as inputs, and only allows writing to designated [outputs][output] to be [captured as store objects](@docroot@/store/building.md#processing-outputs).
-
-  A derivation is typically specified as a [derivation expression] in the [Nix language], and [instantiated][instantiate] to a [store derivation].
-  There are multiple ways of obtaining store objects from store derivatons, collectively called [realisation][realise].
+  A description of a build task. The result of a derivation is a
+  store object. Derivations declared in Nix expressions are specified
+  using the [`derivation` primitive](./language/derivations.md). These are
+  translated into low-level *store derivations* (implicitly by
+  `nix-build`, or explicitly by `nix-instantiate`).
 
   [derivation]: #gloss-derivation
 
 - [store derivation]{#gloss-store-derivation}
 
-  A [derivation] represented as a [store object].
+  A [derivation] represented as a `.drv` file in the [store].
+  It has a [store path], like any [store object].
+  It is the [instantiated][instantiate] form of a derivation.
 
-  See [Store Derivation](@docroot@/store/derivation/index.md#store-derivation) for details.
+  Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
+
+  See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations.
 
   [store derivation]: #gloss-store-derivation
 
-- [directed acyclic graph]{#gloss-directed-acyclic-graph}
-
-  A [directed acyclic graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph) (DAG) is graph whose edges are given a direction ("a to b" is not the same edge as "b to a"), and for which no possible path (created by joining together edges) forms a cycle.
-
-  DAGs are very important to Nix.
-  In particular, the non-self-[references][reference] of [store object][store object] form a cycle.
-
-- [derivation path]{#gloss-derivation-path}
-
-  A [store path] which uniquely identifies a [store derivation].
-
-  See [Referencing Store Derivations](@docroot@/store/derivation/index.md#derivation-path) for details.
-
-  Not to be confused with [deriving path].
-
-  [derivation path]: #gloss-derivation-path
-
-- [derivation expression]{#gloss-derivation-expression}
-
-  A description of a [store derivation] using the [`derivation` primitive](./language/derivations.md) in the [Nix language].
-
-  [derivation expression]: #gloss-derivation-expression
-
 - [instantiate]{#gloss-instantiate}, instantiation
 
-  Translate a [derivation expression] into a [store derivation].
+  Save an evaluated [derivation] as a [store derivation] in the Nix [store].
 
   See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation.
 
@@ -88,8 +55,9 @@
 
   This can be achieved by:
   - Fetching a pre-built [store object] from a [substituter]
-  - [Building](@docroot@/store/building.md) the corresponding [store derivation]
+  - Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation]
   - Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs
+  <!-- TODO: link [running] to build process page, #8888 -->
 
   See [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md) for a detailed description of the algorithm.
 
@@ -97,7 +65,7 @@
 
   [realise]: #gloss-realise
 
-- [content-addressing derivation]{#gloss-content-addressing-derivation}
+- [content-addressed derivation]{#gloss-content-addressed-derivation}
 
   A derivation which has the
   [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
@@ -105,7 +73,7 @@
 
 - [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD)
 
-  A [store derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
+  A [derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
 
 - [store]{#gloss-store}
 
@@ -116,12 +84,6 @@
 
   [store]: #gloss-store
 
-- [Nix instance]{#gloss-nix-instance}
-  <!-- ambiguous -->
-  1. An installation of Nix, which includes the presence of a [store], and the Nix package manager which operates on that store.
-     A local Nix installation and a [remote builder](@docroot@/advanced-topics/distributed-builds.md) are two examples of Nix instances.
-  2. A running Nix process, such as the `nix` command.
-
 - [binary cache]{#gloss-binary-cache}
 
   A *binary cache* is a Nix store which uses a different format: its
@@ -168,17 +130,15 @@
 - [input-addressed store object]{#gloss-input-addressed-store-object}
 
   A store object produced by building a
-  non-[content-addressed](#gloss-content-addressing-derivation),
+  non-[content-addressed](#gloss-content-addressed-derivation),
   non-[fixed-output](#gloss-fixed-output-derivation)
   derivation.
 
-  See [input-addressing derivation outputs](store/derivation/outputs/input-address.md) for details.
-
 - [content-addressed store object]{#gloss-content-addressed-store-object}
 
   A [store object] which is [content-addressed](#gloss-content-address),
   i.e. whose [store path] is determined by its contents.
-  This includes derivations, the outputs of [content-addressing derivations](#gloss-content-addressing-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
+  This includes derivations, the outputs of [content-addressed derivations](#gloss-content-addressed-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
 
   See [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md) for details.
 
@@ -208,7 +168,7 @@
 
 - [impure derivation]{#gloss-impure-derivation}
 
-  [An experimental feature](@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
+  [An experimental feature](#@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
   so that they are always rebuilt, and their outputs not reused by subsequent calls to realise them.
 
 - [Nix database]{#gloss-nix-database}
@@ -228,37 +188,35 @@
   >
   > The contents of a `.nix` file form a Nix expression.
 
-  Nix expressions specify [derivation expressions][derivation expression], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
+  Nix expressions specify [derivations][derivation], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
   These derivations can then be [realised][realise] to produce [outputs][output].
 
   > **Example**
   >
-  > Building and deploying software using Nix entails writing Nix expressions to describe [packages][package] and compositions thereof.
+  > Building and deploying software using Nix entails writing Nix expressions as a high-level description of packages and compositions thereof.
 
 - [reference]{#gloss-reference}
 
-  An edge from one [store object] to another.
+  A [store object] `O` is said to have a *reference* to a store object `P` if a [store path] to `P` appears in the contents of `O`.
 
-  See [References](@docroot@/store/store-object.md#references) for details.
+  Store objects can refer to both other store objects and themselves.
+  References from a store object to itself are called *self-references*.
+  References other than a self-reference must not form a cycle.
 
   [reference]: #gloss-reference
 
-  See [References](@docroot@/store/store-object.md#references) for details.
-
 - [reachable]{#gloss-reachable}
 
   A store path `Q` is reachable from another store path `P` if `Q`
   is in the *closure* of the *references* relation.
 
-  See [References](@docroot@/store/store-object.md#references) for details.
-
 - [closure]{#gloss-closure}
 
   The closure of a store path is the set of store paths that are
   directly or indirectly “reachable” from that store path; that is,
   it’s the closure of the path under the *references* relation. For
   a package, the closure of its derivation is equivalent to the
-  build-time dependencies, while the closure of its [output path] is
+  build-time dependencies, while the closure of its output path is
   equivalent to its runtime dependencies. For correct deployment it
   is necessary to deploy whole closures, since otherwise at runtime
   files could be missing. The command `nix-store --query --requisites ` prints out
@@ -268,31 +226,18 @@
   to a store object at path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
   references `R` then `R` is also in the closure of `P`.
 
-  See [References](@docroot@/store/store-object.md#references) for details.
-
   [closure]: #gloss-closure
 
-- [requisite]{#gloss-requisite}
-
-  A store object [reachable] by a path (chain of references) from a given [store object].
-  The [closure] is the set of requisites.
-
-  See [References](@docroot@/store/store-object.md#references) for details.
-
-- [referrer]{#gloss-referrer}
-
-  A reversed edge from one [store object] to another.
-
 - [output]{#gloss-output}
 
-  A [store object] produced by a [store derivation].
+  A [store object] produced by a [derivation].
   See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details.
 
   [output]: #gloss-output
 
 - [output path]{#gloss-output-path}
 
-  The [store path] to the [output] of a [store derivation].
+  The [store path] to the [output] of a [derivation].
 
   [output path]: #gloss-output-path
 
@@ -301,11 +246,14 @@
 
 - [deriving path]{#gloss-deriving-path}
 
-  Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
+  Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
+  This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
+  There are two forms:
 
-  See [Deriving Path](./store/derivation/index.md#deriving-path) for details.
+  - *constant*: just a [store path]
+    It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
 
-  Not to be confused with [derivation path].
+  - *output*: a pair of a [store path] to a [derivation] and an [output] name.
 
 - [deriver]{#gloss-deriver}
 
@@ -353,7 +301,7 @@
 
   See [Nix Archive](store/file-system-object/content-address.html#serial-nix-archive) for details.
 
-- [`∅`]{#gloss-empty-set}
+- [`∅`]{#gloss-emtpy-set}
 
   The empty set symbol. In the context of profile history, this denotes a package is not present in a particular version of the profile.
 
@@ -363,17 +311,18 @@
 
 - [package]{#package}
 
-  A software package; files that belong together for a particular purpose, and metadata.
+  1. A software package; a collection of files and other data.
 
-  Nix represents files as [file system objects][file system object], and how they belong together is encoded as [references][reference] between [store objects][store object] that contain these file system objects.
+  2. A [package attribute set].
 
-  The [Nix language] allows denoting packages in terms of [attribute sets](@docroot@/language/types.md#type-attrs) containing:
-  - attributes that refer to the files of a package, typically in the form of [derivation outputs](#gloss-output),
-  - attributes with metadata, such as information about how the package is supposed to be used.
+- [package attribute set]{#package-attribute-set}
 
-  The exact shape of these attribute sets is up to convention.
+  An [attribute set](@docroot@/language/types.md#attribute-set) containing the attribute `type = "derivation";` (derivation for historical reasons), as well as other attributes, such as
+  - attributes that refer to the files of a [package], typically in the form of [derivation outputs](#output),
+  - attributes that declare something about how the package is supposed to be installed or used,
+  - other metadata or arbitrary attributes.
 
-  [package]: #package
+  [package attribute set]: #package-attribute-set
 
 - [string interpolation]{#gloss-string-interpolation}
 
@@ -383,7 +332,7 @@
 
   [string]: ./language/types.md#type-string
   [path]: ./language/types.md#type-path
-  [attribute name]: ./language/types.md#type-attrs
+  [attribute name]: ./language/types.md#attribute-set
 
 - [base directory]{#gloss-base-directory}
 

doc/manual/source/installation/index.md

@@ -30,8 +30,6 @@ $ curl -L https://nixos.org/nix/install | sh -s -- --daemon
 
 > Single-user is not supported on Mac.
 
-> `warning: installing Nix as root is not supported by this script!`
-
 This installation has less requirements than the multi-user install, however it
 cannot offer equivalent sharing, isolation, or security.
 

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

@@ -25,7 +25,7 @@ This performs the default type of installation for your platform:
 
 We recommend the multi-user installation if it supports your platform and you can authenticate with `sudo`.
 
-The installer can be configured with various command line arguments and environment variables.
+The installer can configured with various command line arguments and environment variables.
 To show available command line flags:
 
 ```console

doc/manual/source/installation/installing-docker.md

@@ -3,21 +3,19 @@
 To run the latest stable release of Nix with Docker run the following command:
 
 ```console
-$ docker run -ti docker.io/nixos/nix
-Unable to find image 'docker.io/nixos/nix:latest' locally
-latest: Pulling from docker.io/nixos/nix
+$ docker run -ti ghcr.io/nixos/nix
+Unable to find image 'ghcr.io/nixos/nix:latest' locally
+latest: Pulling from ghcr.io/nixos/nix
 5843afab3874: Pull complete
 b52bf13f109c: Pull complete
 1e2415612aa3: Pull complete
 Digest: sha256:27f6e7f60227e959ee7ece361f75d4844a40e1cc6878b6868fe30140420031ff
-Status: Downloaded newer image for docker.io/nixos/nix:latest
+Status: Downloaded newer image for ghcr.io/nixos/nix:latest
 35ca4ada6e96:/# nix --version
 nix (Nix) 2.3.12
 35ca4ada6e96:/# exit
 ```
 
-> If you want the latest pre-release you can use ghcr.io/nixos/nix and view them at https://github.com/nixos/nix/pkgs/container/nix
-
 # What is included in Nix's Docker image?
 
 The official Docker image is created using `pkgs.dockerTools.buildLayeredImage`
@@ -59,21 +57,3 @@ $ nix build ./\#hydraJobs.dockerImage.x86_64-linux
 $ docker load -i ./result/image.tar.gz
 $ docker run -ti nix:2.5pre20211105
 ```
-
-# Docker image with non-root Nix
-
-If you would like to run Nix in a container under a user other than `root`,
-you can build an image with a non-root single-user installation of Nix
-by specifying the `uid`, `gid`, `uname`, and `gname` arguments to `docker.nix`:
-
-```console
-$ nix build --file docker.nix \
-    --arg uid 1000 \
-    --arg gid 1000 \
-    --argstr uname user \
-    --argstr gname user \
-    --argstr name nix-user \
-    --out-link nix-user.tar.gz
-$ docker load -i nix-user.tar.gz
-$ docker run -ti nix-user
-```

doc/manual/source/installation/prerequisites-source.md

@@ -10,7 +10,7 @@
   - Bash Shell. The `./configure` script relies on bashisms, so Bash is
     required.
 
-  - A version of GCC or Clang that supports C++23.
+  - A version of GCC or Clang that supports C++20.
 
   - `pkg-config` to locate dependencies. If your distribution does not
     provide it, you can get it from

doc/manual/source/installation/uninstall.md

@@ -41,38 +41,6 @@ There may also be references to Nix in
 
 which you may remove.
 
-### FreeBSD
-
-1. Stop and remove the Nix daemon service:
-
-   ```console
-   sudo service nix-daemon stop
-   sudo rm -f /usr/local/etc/rc.d/nix-daemon
-   sudo sysrc -x nix_daemon_enable
-   ```
-
-2. Remove files created by Nix:
-
-   ```console
-   sudo rm -rf /etc/nix /usr/local/etc/profile.d/nix.sh /nix ~root/.nix-channels ~root/.nix-defexpr ~root/.nix-profile ~root/.cache/nix
-   ```
-
-3. Remove build users and their group:
-
-   ```console
-   for i in $(seq 1 32); do
-     sudo pw userdel nixbld$i
-   done
-   sudo pw groupdel nixbld
-   ```
-
-4. There may also be references to Nix in:
-   - `/usr/local/etc/bashrc`
-   - `/usr/local/etc/zshrc`
-   - Shell configuration files in users' home directories
-
-   which you may remove.
-
 ### macOS
 
 > **Updating to macOS 15 Sequoia**
@@ -192,6 +160,6 @@ which you may remove.
 To remove a [single-user installation](./installing-binary.md#single-user-installation) of Nix, run:
 
 ```console
-rm -rf /nix ~/.nix-channels ~/.nix-defexpr ~/.nix-profile
+$ rm -rf /nix ~/.nix-channels ~/.nix-defexpr ~/.nix-profile
 ```
 You might also want to manually remove references to Nix from your `~/.profile`.

doc/manual/source/introduction.md

@@ -1,8 +1,8 @@
 # Introduction
 
 Nix is a _purely functional package manager_.  This means that it
-treats packages like values in a purely functional programming language
-— packages are built by functions that don’t have
+treats packages like values in purely functional programming languages
+such as Haskell — they are built by functions that don’t have
 side-effects, and they never change after they have been built.  Nix
 stores packages in the _Nix store_, usually the directory
 `/nix/store`, where each package has its own unique subdirectory such

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

@@ -2,75 +2,6 @@
 
 Derivations can declare some infrequently used optional attributes.
 
-## Inputs
-
-  - [`exportReferencesGraph`]{#adv-attr-exportReferencesGraph}\
-    This attribute allows builders access to the references graph of
-    their inputs. The attribute is a list of inputs in the Nix store
-    whose references graph the builder needs to know. The value of
-    this attribute should be a list of pairs `[ name1 path1 name2
-    path2 ...  ]`. The references graph of each *pathN* will be stored
-    in a text file *nameN* in the temporary build directory. The text
-    files have the format used by `nix-store --register-validity`
-    (with the deriver fields left empty). For example, when the
-    following derivation is built:
-
-    ```nix
-    derivation {
-      ...
-      exportReferencesGraph = [ "libfoo-graph" libfoo ];
-    };
-    ```
-
-    the references graph of `libfoo` is placed in the file
-    `libfoo-graph` in the temporary build directory.
-
-    `exportReferencesGraph` is useful for builders that want to do
-    something with the closure of a store path. Examples include the
-    builders in NixOS that generate the initial ramdisk for booting
-    Linux (a `cpio` archive containing the closure of the boot script)
-    and the ISO-9660 image for the installation CD (which is populated
-    with a Nix store containing the closure of a bootable NixOS
-    configuration).
-
-  - [`passAsFile`]{#adv-attr-passAsFile}\
-    A list of names of attributes that should be passed via files rather
-    than environment variables. For example, if you have
-
-    ```nix
-    passAsFile = ["big"];
-    big = "a very long string";
-    ```
-
-    then when the builder runs, the environment variable `bigPath`
-    will contain the absolute path to a temporary file containing `a
-    very long string`. That is, for any attribute *x* listed in
-    `passAsFile`, Nix will pass an environment variable `xPath`
-    holding the path of the file containing the value of attribute
-    *x*. This is useful when you need to pass large strings to a
-    builder, since most operating systems impose a limit on the size
-    of the environment (typically, a few hundred kilobyte).
-
-  - [`__structuredAttrs`]{#adv-attr-structuredAttrs}\
-    If the special attribute `__structuredAttrs` is set to `true`, the other derivation
-    attributes are serialised into a file in JSON format.
-
-    This obviates the need for [`passAsFile`](#adv-attr-passAsFile) since JSON files have no size restrictions, unlike process environments.
-    It also makes it possible to tweak derivation settings in a structured way;
-    see [`outputChecks`](#adv-attr-outputChecks) for example.
-
-    See the [corresponding section in the derivation page](@docroot@/store/derivation/index.md#structured-attrs) for further details.
-
-    > **Warning**
-    >
-    > If set to `true`, other advanced attributes such as [`allowedReferences`](#adv-attr-allowedReferences), [`allowedRequisites`](#adv-attr-allowedRequisites),
-    [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites), maxSize, and maxClosureSize.
-    will have no effect.
-
-## Output checks
-
-See the [corresponding section in the derivation output page](@docroot@/store/derivation/outputs/index.md).
-
   - [`allowedReferences`]{#adv-attr-allowedReferences}\
     The optional attribute `allowedReferences` specifies a list of legal
     references (dependencies) of the output of the builder. For example,
@@ -124,6 +55,259 @@ See the [corresponding section in the derivation output page](@docroot@/store/de
     dependency on `foobar` or any other derivation depending recursively
     on `foobar`.
 
+  - [`exportReferencesGraph`]{#adv-attr-exportReferencesGraph}\
+    This attribute allows builders access to the references graph of
+    their inputs. The attribute is a list of inputs in the Nix store
+    whose references graph the builder needs to know. The value of
+    this attribute should be a list of pairs `[ name1 path1 name2
+    path2 ...  ]`. The references graph of each *pathN* will be stored
+    in a text file *nameN* in the temporary build directory. The text
+    files have the format used by `nix-store --register-validity`
+    (with the deriver fields left empty). For example, when the
+    following derivation is built:
+
+    ```nix
+    derivation {
+      ...
+      exportReferencesGraph = [ "libfoo-graph" libfoo ];
+    };
+    ```
+
+    the references graph of `libfoo` is placed in the file
+    `libfoo-graph` in the temporary build directory.
+
+    `exportReferencesGraph` is useful for builders that want to do
+    something with the closure of a store path. Examples include the
+    builders in NixOS that generate the initial ramdisk for booting
+    Linux (a `cpio` archive containing the closure of the boot script)
+    and the ISO-9660 image for the installation CD (which is populated
+    with a Nix store containing the closure of a bootable NixOS
+    configuration).
+
+  - [`impureEnvVars`]{#adv-attr-impureEnvVars}\
+    This attribute allows you to specify a list of environment variables
+    that should be passed from the environment of the calling user to
+    the builder. Usually, the environment is cleared completely when the
+    builder is executed, but with this attribute you can allow specific
+    environment variables to be passed unmodified. For example,
+    `fetchurl` in Nixpkgs has the line
+
+    ```nix
+    impureEnvVars = [ "http_proxy" "https_proxy" ... ];
+    ```
+
+    to make it use the proxy server configuration specified by the user
+    in the environment variables `http_proxy` and friends.
+
+    This attribute is only allowed in *fixed-output derivations* (see
+    below), where impurities such as these are okay since (the hash
+    of) the output is known in advance. It is ignored for all other
+    derivations.
+
+    > **Warning**
+    >
+    > `impureEnvVars` implementation takes environment variables from
+    > the current builder process. When a daemon is building its
+    > environmental variables are used. Without the daemon, the
+    > environmental variables come from the environment of the
+    > `nix-build`.
+
+    If the [`configurable-impure-env` experimental
+    feature](@docroot@/development/experimental-features.md#xp-feature-configurable-impure-env)
+    is enabled, these environment variables can also be controlled
+    through the
+    [`impure-env`](@docroot@/command-ref/conf-file.md#conf-impure-env)
+    configuration setting.
+
+  - [`outputHash`]{#adv-attr-outputHash}; [`outputHashAlgo`]{#adv-attr-outputHashAlgo}; [`outputHashMode`]{#adv-attr-outputHashMode}\
+    These attributes declare that the derivation is a so-called *fixed-output derivation* (FOD), which means that a cryptographic hash of the output is already known in advance.
+
+    As opposed to regular derivations, the [`builder`] executable of a fixed-output derivation has access to the network.
+    Nix computes a cryptographic hash of its output and compares that to the hash declared with these attributes.
+    If there is a mismatch, the derivation fails.
+
+    The rationale for fixed-output derivations is derivations such as
+    those produced by the `fetchurl` function. This function downloads a
+    file from a given URL. To ensure that the downloaded file has not
+    been modified, the caller must also specify a cryptographic hash of
+    the file. For example,
+
+    ```nix
+    fetchurl {
+      url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
+      sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+    }
+    ```
+
+    It sometimes happens that the URL of the file changes, e.g., because
+    servers are reorganised or no longer available. We then must update
+    the call to `fetchurl`, e.g.,
+
+    ```nix
+    fetchurl {
+      url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
+      sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+    }
+    ```
+
+    If a `fetchurl` derivation was treated like a normal derivation, the
+    output paths of the derivation and *all derivations depending on it*
+    would change. For instance, if we were to change the URL of the
+    Glibc source distribution in Nixpkgs (a package on which almost all
+    other packages depend) massive rebuilds would be needed. This is
+    unfortunate for a change which we know cannot have a real effect as
+    it propagates upwards through the dependency graph.
+
+    For fixed-output derivations, on the other hand, the name of the
+    output path only depends on the `outputHash*` and `name` attributes,
+    while all other attributes are ignored for the purpose of computing
+    the output path. (The `name` attribute is included because it is
+    part of the path.)
+
+    As an example, here is the (simplified) Nix expression for
+    `fetchurl`:
+
+    ```nix
+    { stdenv, curl }: # The curl program is used for downloading.
+
+    { url, sha256 }:
+
+    stdenv.mkDerivation {
+      name = baseNameOf (toString url);
+      builder = ./builder.sh;
+      buildInputs = [ curl ];
+
+      # This is a fixed-output derivation; the output must be a regular
+      # file with SHA256 hash sha256.
+      outputHashMode = "flat";
+      outputHashAlgo = "sha256";
+      outputHash = sha256;
+
+      inherit url;
+    }
+    ```
+
+    The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
+    The "nix32" encoding is an adaptation of base-32 encoding.
+    The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings, and the [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
+
+    The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
+    It can currently be `"sha1"`, `"sha256"`, `"sha512"`, or `null`.
+    `outputHashAlgo` can only be `null` when `outputHash` follows the SRI format.
+
+    The `outputHashMode` attribute determines how the hash is computed.
+    It must be one of the following values:
+
+      - [`"flat"`](@docroot@/store/store-object/content-address.md#method-flat)
+
+        This is the default.
+
+      - [`"recursive"` or `"nar"`](@docroot@/store/store-object/content-address.md#method-nix-archive)
+
+        > **Compatibility**
+        >
+        > `"recursive"` is the traditional way of indicating this,
+        > and is supported since 2005 (virtually the entire history of Nix).
+        > `"nar"` is more clear, and consistent with other parts of Nix (such as the CLI),
+        > however support for it is only added in Nix version 2.21.
+
+      - [`"text"`](@docroot@/store/store-object/content-address.md#method-text)
+
+        > **Warning**
+        >
+        > The use of this method for derivation outputs is part of the [`dynamic-derivations`][xp-feature-dynamic-derivations] experimental feature.
+
+      - [`"git"`](@docroot@/store/store-object/content-address.md#method-git)
+
+        > **Warning**
+        >
+        > This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
+
+  - [`__contentAddressed`]{#adv-attr-__contentAddressed}
+
+    > **Warning**
+    > This attribute is part of an [experimental feature](@docroot@/development/experimental-features.md).
+    >
+    > To use this attribute, you must enable the
+    > [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
+    > For example, in [nix.conf](../command-ref/conf-file.md) you could add:
+    >
+    > ```
+    > extra-experimental-features = ca-derivations
+    > ```
+
+    If this attribute is set to `true`, then the derivation
+    outputs will be stored in a content-addressed location rather than the
+    traditional input-addressed one.
+
+    Setting this attribute also requires setting
+    [`outputHashMode`](#adv-attr-outputHashMode)
+    and
+    [`outputHashAlgo`](#adv-attr-outputHashAlgo)
+    like for *fixed-output derivations* (see above).
+
+    It also implicitly requires that the machine to build the derivation must have the `ca-derivations` [system feature](@docroot@/command-ref/conf-file.md#conf-system-features).
+
+  - [`passAsFile`]{#adv-attr-passAsFile}\
+    A list of names of attributes that should be passed via files rather
+    than environment variables. For example, if you have
+
+    ```nix
+    passAsFile = ["big"];
+    big = "a very long string";
+    ```
+
+    then when the builder runs, the environment variable `bigPath`
+    will contain the absolute path to a temporary file containing `a
+    very long string`. That is, for any attribute *x* listed in
+    `passAsFile`, Nix will pass an environment variable `xPath`
+    holding the path of the file containing the value of attribute
+    *x*. This is useful when you need to pass large strings to a
+    builder, since most operating systems impose a limit on the size
+    of the environment (typically, a few hundred kilobyte).
+
+  - [`preferLocalBuild`]{#adv-attr-preferLocalBuild}\
+    If this attribute is set to `true` and [distributed building is enabled](@docroot@/command-ref/conf-file.md#conf-builders), then, if possible, the derivation will be built locally instead of being forwarded to a remote machine.
+    This is useful for derivations that are cheapest to build locally.
+
+  - [`allowSubstitutes`]{#adv-attr-allowSubstitutes}\
+    If this attribute is set to `false`, then Nix will always build this derivation (locally or remotely); it will not try to substitute its outputs.
+    This is useful for derivations that are cheaper to build than to substitute.
+
+    This attribute can be ignored by setting [`always-allow-substitutes`](@docroot@/command-ref/conf-file.md#conf-always-allow-substitutes) to `true`.
+
+    > **Note**
+    >
+    > If set to `false`, the [`builder`] should be able to run on the system type specified in the [`system` attribute](./derivations.md#attr-system), since the derivation cannot be substituted.
+
+    [`builder`]: ./derivations.md#attr-builder
+
+  - [`__structuredAttrs`]{#adv-attr-structuredAttrs}\
+    If the special attribute `__structuredAttrs` is set to `true`, the other derivation
+    attributes are serialised into a file in JSON format. The environment variable
+    `NIX_ATTRS_JSON_FILE` points to the exact location of that file both in a build
+    and a [`nix-shell`](../command-ref/nix-shell.md). This obviates the need for
+    [`passAsFile`](#adv-attr-passAsFile) since JSON files have no size restrictions,
+    unlike process environments.
+
+    It also makes it possible to tweak derivation settings in a structured way; see
+    [`outputChecks`](#adv-attr-outputChecks) for example.
+
+    As a convenience to Bash builders,
+    Nix writes a script that initialises shell variables
+    corresponding to all attributes that are representable in Bash. The
+    environment variable `NIX_ATTRS_SH_FILE` points to the exact
+    location of the script, both in a build and a
+    [`nix-shell`](../command-ref/nix-shell.md). This includes non-nested
+    (associative) arrays. For example, the attribute `hardening.format = true`
+    ends up as the Bash associative array element `${hardening[format]}`.
+
+    > **Warning**
+    >
+    > If set to `true`, other advanced attributes such as [`allowedReferences`](#adv-attr-allowedReferences), [`allowedReferences`](#adv-attr-allowedReferences), [`allowedRequisites`](#adv-attr-allowedRequisites),
+    [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites), maxSize, and maxClosureSize.
+    will have no effect.
+
   - [`outputChecks`]{#adv-attr-outputChecks}\
     When using [structured attributes](#adv-attr-structuredAttrs), the `outputChecks`
     attribute allows defining checks per-output.
@@ -157,9 +341,8 @@ See the [corresponding section in the derivation output page](@docroot@/store/de
     };
     ```
 
-## Other output modifications
-
   - [`unsafeDiscardReferences`]{#adv-attr-unsafeDiscardReferences}\
+
     When using [structured attributes](#adv-attr-structuredAttrs), the
     attribute `unsafeDiscardReferences` is an attribute set with a boolean value for each output name.
     If set to `true`, it disables scanning the output for runtime dependencies.
@@ -175,25 +358,8 @@ See the [corresponding section in the derivation output page](@docroot@/store/de
     their own embedded Nix store: hashes found inside such an image refer
     to the embedded store and not to the host's Nix store.
 
-## Build scheduling
-
-  - [`preferLocalBuild`]{#adv-attr-preferLocalBuild}\
-    If this attribute is set to `true` and [distributed building is enabled](@docroot@/command-ref/conf-file.md#conf-builders), then, if possible, the derivation will be built locally instead of being forwarded to a remote machine.
-    This is useful for derivations that are cheapest to build locally.
-
-  - [`allowSubstitutes`]{#adv-attr-allowSubstitutes}\
-    If this attribute is set to `false`, then Nix will always build this derivation (locally or remotely); it will not try to substitute its outputs.
-    This is useful for derivations that are cheaper to build than to substitute.
-
-    This attribute can be ignored by setting [`always-allow-substitutes`](@docroot@/command-ref/conf-file.md#conf-always-allow-substitutes) to `true`.
-
-    > **Note**
-    >
-    > If set to `false`, the [`builder`] should be able to run on the system type specified in the [`system` attribute](./derivations.md#attr-system), since the derivation cannot be substituted.
-
-    [`builder`]: ./derivations.md#attr-builder
-
 - [`requiredSystemFeatures`]{#adv-attr-requiredSystemFeatures}\
+
   If a derivation has the `requiredSystemFeatures` attribute, then Nix will only build it on a machine that has the corresponding features set in its [`system-features` configuration](@docroot@/command-ref/conf-file.md#conf-system-features).
 
   For example, setting
@@ -204,171 +370,6 @@ See the [corresponding section in the derivation output page](@docroot@/store/de
 
   ensures that the derivation can only be built on a machine with the `kvm` feature.
 
-# Impure builder configuration
-
-  - [`impureEnvVars`]{#adv-attr-impureEnvVars}\
-    This attribute allows you to specify a list of environment variables
-    that should be passed from the environment of the calling user to
-    the builder. Usually, the environment is cleared completely when the
-    builder is executed, but with this attribute you can allow specific
-    environment variables to be passed unmodified. For example,
-    `fetchurl` in Nixpkgs has the line
-
-    ```nix
-    impureEnvVars = [ "http_proxy" "https_proxy" ... ];
-    ```
-
-    to make it use the proxy server configuration specified by the user
-    in the environment variables `http_proxy` and friends.
-
-    This attribute is only allowed in [fixed-output derivations][fixed-output derivation],
-    where impurities such as these are okay since (the hash
-    of) the output is known in advance. It is ignored for all other
-    derivations.
-
-    > **Warning**
-    >
-    > `impureEnvVars` implementation takes environment variables from
-    > the current builder process. When a daemon is building its
-    > environmental variables are used. Without the daemon, the
-    > environmental variables come from the environment of the
-    > `nix-build`.
-
-    If the [`configurable-impure-env` experimental
-    feature](@docroot@/development/experimental-features.md#xp-feature-configurable-impure-env)
-    is enabled, these environment variables can also be controlled
-    through the
-    [`impure-env`](@docroot@/command-ref/conf-file.md#conf-impure-env)
-    configuration setting.
-
-## Setting the derivation type
-
-As discussed in [Derivation Outputs and Types of Derivations](@docroot@/store/derivation/outputs/index.md), there are multiples kinds of derivations / kinds of derivation outputs.
-The choice of the following attributes determines which kind of derivation we are making.
-
-- [`__contentAddressed`]
-
-- [`outputHash`]
-
-- [`outputHashAlgo`]
-
-- [`outputHashMode`]
-
-The three types of derivations are chosen based on the following combinations of these attributes.
-All other combinations are invalid.
-
-- [Input-addressing derivations](@docroot@/store/derivation/outputs/input-address.md)
-
-  This is the default for `builtins.derivation`.
-  Nix only currently supports one kind of input-addressing, so no other information is needed.
-
-  `__contentAddressed = false;` may also be included, but is not needed, and will trigger the experimental feature check.
-
-- [Fixed-output derivations][fixed-output derivation]
-
-  All of [`outputHash`], [`outputHashAlgo`], and [`outputHashMode`].
-
-  <!--
-
-  `__contentAddressed` is ignored, because fixed-output derivations always content-address their outputs, by definition.
-
-  **TODO CHECK**
-
-  -->
-
-- [(Floating) content-addressing derivations](@docroot@/store/derivation/outputs/content-address.md)
-
-  Both [`outputHashAlgo`] and [`outputHashMode`], `__contentAddressed = true;`, and *not* `outputHash`.
-
-  If an output hash was given, then the derivation output would be "fixed" not "floating".
-
-Here is more information on the `output*` attributes, and what values they may be set to:
-
-  - [`outputHashMode`]{#adv-attr-outputHashMode}
-
-    This specifies how the files of a content-addressing derivation output are digested to produce a content address.
-
-    This works in conjunction with [`outputHashAlgo`](#adv-attr-outputHashAlgo).
-    Specifying one without the other is an error (unless [`outputHash` is also specified and includes its own hash algorithm as described below).
-
-    The `outputHashMode` attribute determines how the hash is computed.
-    It must be one of the following values:
-
-      - [`"flat"`](@docroot@/store/store-object/content-address.md#method-flat)
-
-        This is the default.
-
-      - [`"recursive"` or `"nar"`](@docroot@/store/store-object/content-address.md#method-nix-archive)
-
-        > **Compatibility**
-        >
-        > `"recursive"` is the traditional way of indicating this,
-        > and is supported since 2005 (virtually the entire history of Nix).
-        > `"nar"` is more clear, and consistent with other parts of Nix (such as the CLI),
-        > however support for it is only added in Nix version 2.21.
-
-      - [`"text"`](@docroot@/store/store-object/content-address.md#method-text)
-
-        > **Warning**
-        >
-        > The use of this method for derivation outputs is part of the [`dynamic-derivations`][xp-feature-dynamic-derivations] experimental feature.
-
-      - [`"git"`](@docroot@/store/store-object/content-address.md#method-git)
-
-        > **Warning**
-        >
-        > This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
-
-    See [content-addressing store objects](@docroot@/store/store-object/content-address.md) for more information about the process this flag controls.
-
-  - [`outputHashAlgo`]{#adv-attr-outputHashAlgo}
-
-    This specifies the hash algorithm used to digest the [file system object] data of a content-addressing derivation output.
-
-    This works in conjunction with [`outputHashMode`](#adv-attr-outputHashAlgo).
-    Specifying one without the other is an error (unless `outputHash` is also specified and includes its own hash algorithm as described below).
-
-    The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
-    It can currently be `"blake3"`, `"sha1"`, `"sha256"`, `"sha512"`, or `null`.
-
-    `outputHashAlgo` can only be `null` when `outputHash` follows the SRI format, because in that case the choice of hash algorithm is determined by `outputHash`.
-
-  - [`outputHash`]{#adv-attr-outputHash}
-
-    This will specify the output hash of the single output of a [fixed-output derivation].
-
-    The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
-    The "nix32" encoding is an adaptation of base-32 encoding.
-
-    > **Note**
-    >
-    > The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings.
-    > The [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
-
-  - [`__contentAddressed`]{#adv-attr-__contentAddressed}
-
-    > **Warning**
-    >
-    > This attribute is part of an [experimental feature](@docroot@/development/experimental-features.md).
-    >
-    > To use this attribute, you must enable the
-    > [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
-    > For example, in [nix.conf](../command-ref/conf-file.md) you could add:
-    >
-    > ```
-    > extra-experimental-features = ca-derivations
-    > ```
-
-    This is a boolean with a default of `false`.
-    It determines whether the derivation is floating content-addressing.
-
-[`__contentAddressed`]: #adv-attr-__contentAddressed
-[`outputHash`]: #adv-attr-outputHash
-[`outputHashAlgo`]: #adv-attr-outputHashAlgo
-[`outputHashMode`]: #adv-attr-outputHashMode
-
-[fixed-output derivation]: @docroot@/glossary.md#gloss-fixed-output-derivation
-[file system object]: @docroot@/store/file-system-object.md
-[store object]: @docroot@/store/store-object.md
+[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
 [xp-feature-dynamic-derivations]: @docroot@/development/experimental-features.md#xp-feature-dynamic-derivations
 [xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing

doc/manual/source/language/builtins-prefix.md

@@ -5,28 +5,12 @@ All built-ins are available through the global [`builtins`](#builtins-builtins)
 
 Some built-ins are also exposed directly in the global scope:
 
+<!-- TODO(@rhendric, #10970): this list is incomplete -->
+
 - [`derivation`](#builtins-derivation)
-- `derivationStrict`
-- [`abort`](#builtins-abort)
-- [`baseNameOf`](#builtins-baseNameOf)
-- [`break`](#builtins-break)
-- [`dirOf`](#builtins-dirOf)
-- [`false`](#builtins-false)
-- [`fetchGit`](#builtins-fetchGit)
-- `fetchMercurial`
-- [`fetchTarball`](#builtins-fetchTarball)
-- [`fetchTree`](#builtins-fetchTree)
-- [`fromTOML`](#builtins-fromTOML)
 - [`import`](#builtins-import)
-- [`isNull`](#builtins-isNull)
-- [`map`](#builtins-map)
-- [`null`](#builtins-null)
-- [`placeholder`](#builtins-placeholder)
-- [`removeAttrs`](#builtins-removeAttrs)
-- `scopedImport`
+- [`abort`](#builtins-abort)
 - [`throw`](#builtins-throw)
-- [`toString`](#builtins-toString)
-- [`true`](#builtins-true)
 
 <dl>
   <dt id="builtins-derivation"><a href="#builtins-derivation"><code>derivation <var>attrs</var></code></a></dt>

doc/manual/source/language/derivations.md

@@ -1,10 +1,9 @@
 # Derivations
 
-The most important built-in function is `derivation`, which is used to describe a single store-layer [store derivation].
-Consult the [store chapter](@docroot@/store/derivation/index.md) for what a store derivation is;
-this section just concerns how to create one from the Nix language.
+The most important built-in function is `derivation`, which is used to describe a single derivation:
+a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths.
 
-This builtin function takes as input an attribute set, the attributes of which specify the inputs to the process.
+It takes as input an attribute set, the attributes of which specify the inputs to the process.
 It outputs an attribute set, and produces a [store derivation] as a side effect of evaluation.
 
 [store derivation]: @docroot@/glossary.md#gloss-store-derivation
@@ -16,7 +15,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
 - [`name`]{#attr-name} ([String](@docroot@/language/types.md#type-string))
 
   A symbolic name for the derivation.
-  See [derivation outputs](@docroot@/store/derivation/outputs/index.md#outputs) for what this is affects.
+  It is added to the [store path] of the corresponding [store derivation] as well as to its [output paths](@docroot@/glossary.md#gloss-output-path).
 
   [store path]: @docroot@/store/store-path.md
 
@@ -29,12 +28,17 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
   > }
   > ```
   >
-  > The derivation's path will be `/nix/store/<hash>-hello.drv`.
+  > The store derivation's path will be `/nix/store/<hash>-hello.drv`.
   > The [output](#attr-outputs) paths will be of the form `/nix/store/<hash>-hello[-<output>]`
 
 - [`system`]{#attr-system} ([String](@docroot@/language/types.md#type-string))
 
-  See [system](@docroot@/store/derivation/index.md#system).
+  The system type on which the [`builder`](#attr-builder) executable is meant to be run.
+
+  A necessary condition for Nix to build derivations locally is that the `system` attribute matches the current [`system` configuration option].
+  It can automatically [build on other platforms](@docroot@/language/derivations.md#attr-builder) by forwarding build requests to other machines.
+
+  [`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system
 
   > **Example**
   >
@@ -64,7 +68,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
 
 - [`builder`]{#attr-builder} ([Path](@docroot@/language/types.md#type-path) | [String](@docroot@/language/types.md#type-string))
 
-  See [builder](@docroot@/store/derivation/index.md#builder).
+  Path to an executable that will perform the build.
 
   > **Example**
   >
@@ -113,7 +117,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
 
   Default: `[ ]`
 
-  See [args](@docroot@/store/derivation/index.md#args).
+  Command-line arguments to be passed to the [`builder`](#attr-builder) executable.
 
   > **Example**
   >
@@ -235,3 +239,77 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
       passed as an empty string.
 
 <!-- FIXME: add a section on output attributes -->
+
+## Builder execution
+
+The [`builder`](#attr-builder) is executed as follows:
+
+- A temporary directory is created under the directory specified by
+  `TMPDIR` (default `/tmp`) where the build will take place. The
+  current directory is changed to this directory.
+
+- The environment is cleared and set to the derivation attributes, as
+  specified above.
+
+- In addition, the following variables are set:
+
+  - `NIX_BUILD_TOP` contains the path of the temporary directory for
+    this build.
+
+  - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
+    temporary directory. This is to prevent the builder from
+    accidentally writing temporary files anywhere else. Doing so
+    might cause interference by other processes.
+
+  - `PATH` is set to `/path-not-set` to prevent shells from
+    initialising it to their built-in default value.
+
+  - `HOME` is set to `/homeless-shelter` to prevent programs from
+    using `/etc/passwd` or the like to find the user's home
+    directory, which could cause impurity. Usually, when `HOME` is
+    set, it is used as the location of the home directory, even if
+    it points to a non-existent path.
+
+  - `NIX_STORE` is set to the path of the top-level Nix store
+    directory (typically, `/nix/store`).
+
+  - `NIX_ATTRS_JSON_FILE` & `NIX_ATTRS_SH_FILE` if `__structuredAttrs`
+    is set to `true` for the derivation. A detailed explanation of this
+    behavior can be found in the
+    [section about structured attrs](./advanced-attributes.md#adv-attr-structuredAttrs).
+
+  - For each output declared in `outputs`, the corresponding
+    environment variable is set to point to the intended path in the
+    Nix store for that output. Each output path is a concatenation
+    of the cryptographic hash of all build inputs, the `name`
+    attribute and the output name. (The output name is omitted if
+    it’s `out`.)
+
+- If an output path already exists, it is removed. Also, locks are
+  acquired to prevent multiple Nix instances from performing the same
+  build at the same time.
+
+- A log of the combined standard output and error is written to
+  `/nix/var/log/nix`.
+
+- The builder is executed with the arguments specified by the
+  attribute `args`. If it exits with exit code 0, it is considered to
+  have succeeded.
+
+- The temporary directory is removed (unless the `-K` option was
+  specified).
+
+- If the build was successful, Nix scans each output path for
+  references to input paths by looking for the hash parts of the input
+  paths. Since these are potential runtime dependencies, Nix registers
+  them as dependencies of the output paths.
+
+- After the build, Nix sets the last-modified timestamp on all files
+  in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
+  the default group, and sets the mode of the file to 0444 or 0555
+  (i.e., read-only, with execute permission enabled if the file was
+  originally executable). Note that possible `setuid` and `setgid`
+  bits are cleared. Setuid and setgid programs are not currently
+  supported by Nix. This is because the Nix archives used in
+  deployment have no concept of ownership information, and because it
+  makes the build result dependent on the user performing the build.