diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index a9ca74c17cc..763c5f27ee6 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -11,16 +11,7 @@
.github/CODEOWNERS @edolstra
# Documentation of built-in functions
-src/libexpr/primops.cc @roberth @fricklerhandwerk
-
-# Documentation of settings
-src/libexpr/eval-settings.hh @fricklerhandwerk
-src/libstore/globals.hh @fricklerhandwerk
-
-# Documentation
-doc/manual @fricklerhandwerk
-maintainers/*.md @fricklerhandwerk
-src/**/*.md @fricklerhandwerk
+src/libexpr/primops.cc @roberth
# Libstore layer
/src/libstore @ericson2314
diff --git a/.github/STALE-BOT.md b/.github/STALE-BOT.md
index 383717bfc1d..bc0005413f1 100644
--- a/.github/STALE-BOT.md
+++ b/.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 - #nix:nixos.org](https://matrix.to/#/#nix:nixos.org).
+- 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).
## Suggestions for PRs
diff --git a/.github/actions/install-nix-action/action.yaml b/.github/actions/install-nix-action/action.yaml
new file mode 100644
index 00000000000..28103f5891c
--- /dev/null
+++ b/.github/actions/install-nix-action/action.yaml
@@ -0,0 +1,50 @@
+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
+ 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.30.1/install"
+ github_token:
+ description: "Github token"
+ required: true
+runs:
+ using: "composite"
+ steps:
+ - name: "Download nix install artifact from master"
+ shell: bash
+ id: download-nix-installer
+ if: ${{ inputs.dogfood }}
+ 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"
+
+ 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"
+ - uses: cachix/install-nix-action@c134e4c9e34bac6cab09cf239815f9339aaaf84e # v31.5.1
+ with:
+ # Ternary operator in GHA: https://www.github.com/actions/runner/issues/409#issuecomment-752775072
+ install_url: ${{ inputs.dogfood && format('{0}/install', steps.download-nix-installer.outputs.installer-path) || inputs.install_url }}
+ install_options: ${{ inputs.dogfood && format('--tarball-url-prefix {0}', steps.download-nix-installer.outputs.installer-path) || '' }}
+ extra_nix_config: ${{ inputs.extra_nix_config }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index be96bb48469..da6f3590771 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -7,154 +7,142 @@ on:
permissions: read-all
jobs:
+ eval:
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ - uses: ./.github/actions/install-nix-action
+ with:
+ dogfood: true
+ extra_nix_config:
+ experimental-features = nix-command flakes
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ - run: nix flake show --all-systems --json
tests:
- needs: [check_secrets]
strategy:
fail-fast: false
matrix:
- os: [ubuntu-latest, macos-latest]
- runs-on: ${{ matrix.os }}
+ include:
+ - scenario: on ubuntu
+ runs-on: ubuntu-24.04
+ os: linux
+ - scenario: on macos
+ runs-on: macos-14
+ os: darwin
+ name: tests ${{ matrix.scenario }}
+ runs-on: ${{ matrix.runs-on }}
timeout-minutes: 60
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- - uses: cachix/install-nix-action@v30
+ - uses: ./.github/actions/install-nix-action
with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ dogfood: true
# The sandbox would otherwise be disabled by default on Darwin
extra_nix_config: |
sandbox = true
max-jobs = 1
- - 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'
+ - uses: DeterminateSystems/magic-nix-cache-action@main
+ # 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'
+ - run: scripts/build-checks
+ - run: scripts/prepare-installer-for-github-actions
+ - name: Upload installer tarball
+ uses: actions/upload-artifact@v4
with:
- name: '${{ env.CACHIX_NAME }}'
- signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'
- authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
- - if: matrix.os == 'ubuntu-latest'
- run: |
- free -h
- swapon --show
- swap=$(swapon --show --noheadings | head -n 1 | awk '{print $1}')
- echo "Found swap: $swap"
- sudo swapoff $swap
- # resize it (fallocate)
- sudo fallocate -l 10G $swap
- sudo mkswap $swap
- sudo swapon $swap
- free -h
- (
- while sleep 60; do
- free -h
- done
- ) &
- - run: nix --experimental-features 'nix-command flakes' flake check -L
- - run: nix --experimental-features 'nix-command flakes' flake show --all-systems --json
+ name: installer-${{matrix.os}}
+ path: out/*
+
+ installer_test:
+ needs: [tests]
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - scenario: on ubuntu
+ runs-on: ubuntu-24.04
+ os: linux
+ - scenario: on macos
+ runs-on: macos-14
+ os: darwin
+ name: installer test ${{ matrix.scenario }}
+ runs-on: ${{ matrix.runs-on }}
+ steps:
+ - uses: actions/checkout@v4
+ - name: Download installer tarball
+ uses: actions/download-artifact@v4
+ with:
+ name: installer-${{matrix.os}}
+ path: out
+ - name: Serving installer
+ id: serving_installer
+ run: ./scripts/serve-installer-for-github-actions
+ - uses: cachix/install-nix-action@v31
+ with:
+ install_url: 'http://localhost:8126/install'
+ install_options: "--tarball-url-prefix http://localhost:8126/"
+ - run: sudo apt install fish zsh
+ if: matrix.os == 'linux'
+ - run: brew install fish
+ if: matrix.os == 'darwin'
+ - run: exec bash -c "nix-instantiate -E 'builtins.currentTime' --eval"
+ - run: exec sh -c "nix-instantiate -E 'builtins.currentTime' --eval"
+ - run: exec zsh -c "nix-instantiate -E 'builtins.currentTime' --eval"
+ - run: exec fish -c "nix-instantiate -E 'builtins.currentTime' --eval"
+ - run: exec bash -c "nix-channel --add https://releases.nixos.org/nixos/unstable/nixos-23.05pre466020.60c1d71f2ba nixpkgs"
+ - run: exec bash -c "nix-channel --update && nix-env -iA nixpkgs.hello && hello"
# 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
+ name: Check Docker secrets present for installer tests
+ runs-on: ubuntu-24.04
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:
- 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: [installer, check_secrets]
- if: github.event_name == 'push' && needs.check_secrets.outputs.cachix == 'true'
- strategy:
- fail-fast: false
- matrix:
- os: [ubuntu-latest, macos-latest]
- runs-on: ${{ matrix.os }}
- steps:
- - uses: actions/checkout@v4
- - 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: '${{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 == 'ubuntu-latest'
- - run: brew install fish
- if: matrix.os == 'macos-latest'
- - run: exec bash -c "nix-instantiate -E 'builtins.currentTime' --eval"
- - run: exec sh -c "nix-instantiate -E 'builtins.currentTime' --eval"
- - run: exec zsh -c "nix-instantiate -E 'builtins.currentTime' --eval"
- - run: exec fish -c "nix-instantiate -E 'builtins.currentTime' --eval"
- - run: exec bash -c "nix-channel --add https://releases.nixos.org/nixos/unstable/nixos-23.05pre466020.60c1d71f2ba nixpkgs"
- - run: exec bash -c "nix-channel --update && nix-env -iA nixpkgs.hello && hello"
-
docker_push_image:
- needs: [check_secrets, tests, vm_tests]
+ needs: [tests, vm_tests, check_secrets]
permissions:
contents: read
packages: write
if: >-
+ needs.check_secrets.outputs.docker == 'true' &&
github.event_name == 'push' &&
- github.ref_name == 'master' &&
- needs.check_secrets.outputs.cachix == 'true' &&
- needs.check_secrets.outputs.docker == 'true'
- runs-on: ubuntu-latest
+ github.ref_name == 'master'
+ runs-on: ubuntu-24.04
steps:
+ - name: Check for secrets
+ id: secret
+ env:
+ _DOCKER_SECRETS: ${{ secrets.DOCKERHUB_USERNAME }}${{ secrets.DOCKERHUB_TOKEN }}
+ run: |
+ echo "::set-output name=docker::${{ env._DOCKER_SECRETS != '' }}"
- uses: actions/checkout@v4
with:
fetch-depth: 0
- - uses: cachix/install-nix-action@v30
+ - uses: cachix/install-nix-action@v31
with:
install_url: https://releases.nixos.org/nix/nix-2.20.3/install
- - run: echo CACHIX_NAME="$(echo $GITHUB_REPOSITORY-install-tests | tr "[A-Z]/" "[a-z]-")" >> $GITHUB_ENV
+ - uses: DeterminateSystems/magic-nix-cache-action@main
- 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
@@ -191,10 +179,15 @@ jobs:
docker push $IMAGE_ID:master
vm_tests:
- runs-on: ubuntu-22.04
+ runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- - uses: DeterminateSystems/nix-installer-action@main
+ - uses: ./.github/actions/install-nix-action
+ with:
+ dogfood: true
+ extra_nix_config:
+ experimental-features = nix-command flakes
+ github_token: ${{ secrets.GITHUB_TOKEN }}
- uses: DeterminateSystems/magic-nix-cache-action@main
- run: |
nix build -L \
@@ -206,7 +199,7 @@ jobs:
flake_regressions:
needs: vm_tests
- runs-on: ubuntu-22.04
+ runs-on: ubuntu-24.04
steps:
- name: Checkout nix
uses: actions/checkout@v4
@@ -220,6 +213,11 @@ jobs:
with:
repository: NixOS/flake-regressions-data
path: flake-regressions/tests
- - uses: DeterminateSystems/nix-installer-action@main
+ - uses: ./.github/actions/install-nix-action
+ with:
+ dogfood: true
+ extra_nix_config:
+ experimental-features = nix-command flakes
+ github_token: ${{ secrets.GITHUB_TOKEN }}
- uses: DeterminateSystems/magic-nix-cache-action@main
- run: nix build -L --out-link ./new-nix && PATH=$(pwd)/new-nix/bin:$PATH MAX_FLAKES=25 flake-regressions/eval-all.sh
diff --git a/.github/workflows/labels.yml b/.github/workflows/labels.yml
index 34aa4e6bdf0..23a5d9e51fc 100644
--- a/.github/workflows/labels.yml
+++ b/.github/workflows/labels.yml
@@ -15,7 +15,7 @@ permissions:
jobs:
labels:
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04
if: github.repository_owner == 'NixOS'
steps:
- uses: actions/labeler@v5
diff --git a/.gitignore b/.gitignore
index de1183977b3..4782bfbafd2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,110 +1,12 @@
-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/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
@@ -112,27 +14,9 @@ perl/Makefile.config
/tests/functional/lang/*.err
/tests/functional/lang/*.ast
-/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/
+/outputs
-*.a
-*.o
-*.o.tmp
-*.so
-*.dylib
-*.dll
-*.exe
-*.dep
*~
-*.pc
-*.plist
# GNU Global
GPATH
@@ -147,8 +31,6 @@ GTAGS
compile_commands.json
*.compile_commands.json
-nix-rust/target
-
result
result-*
@@ -163,3 +45,8 @@ result-*
# Mac OS
.DS_Store
+
+flake-regressions
+
+# direnv
+.direnv/
diff --git a/.mergify.yml b/.mergify.yml
index c545bbe6a24..f49144113da 100644
--- a/.mergify.yml
+++ b/.mergify.yml
@@ -2,10 +2,11 @@ queue_rules:
- name: default
# all required tests need to go here
merge_conditions:
- - check-success=tests (macos-latest)
- - check-success=tests (ubuntu-latest)
+ - check-success=tests on macos
+ - check-success=tests on ubuntu
+ - check-success=installer test on macos
+ - check-success=installer test on ubuntu
- check-success=vm_tests
- merge_method: rebase
batch_size: 5
pull_request_rules:
@@ -26,6 +27,7 @@ pull_request_rules:
branches:
- 2.18-maintenance
labels:
+ - automatic backport
- merge-queue
- name: backport patches to 2.19
@@ -36,6 +38,7 @@ pull_request_rules:
branches:
- 2.19-maintenance
labels:
+ - automatic backport
- merge-queue
- name: backport patches to 2.20
@@ -46,6 +49,7 @@ pull_request_rules:
branches:
- 2.20-maintenance
labels:
+ - automatic backport
- merge-queue
- name: backport patches to 2.21
@@ -56,6 +60,7 @@ pull_request_rules:
branches:
- 2.21-maintenance
labels:
+ - automatic backport
- merge-queue
- name: backport patches to 2.22
@@ -66,6 +71,7 @@ pull_request_rules:
branches:
- 2.22-maintenance
labels:
+ - automatic backport
- merge-queue
- name: backport patches to 2.23
@@ -76,6 +82,7 @@ pull_request_rules:
branches:
- 2.23-maintenance
labels:
+ - automatic backport
- merge-queue
- name: backport patches to 2.24
@@ -86,6 +93,7 @@ pull_request_rules:
branches:
- "2.24-maintenance"
labels:
+ - automatic backport
- merge-queue
- name: backport patches to 2.25
@@ -96,4 +104,60 @@ pull_request_rules:
branches:
- "2.25-maintenance"
labels:
+ - automatic backport
+ - merge-queue
+
+ - name: backport patches to 2.26
+ conditions:
+ - label=backport 2.26-maintenance
+ actions:
+ backport:
+ branches:
+ - "2.26-maintenance"
+ labels:
+ - automatic backport
+ - merge-queue
+
+ - name: backport patches to 2.27
+ conditions:
+ - label=backport 2.27-maintenance
+ actions:
+ backport:
+ branches:
+ - "2.27-maintenance"
+ labels:
+ - automatic backport
+ - merge-queue
+
+ - name: backport patches to 2.28
+ conditions:
+ - label=backport 2.28-maintenance
+ actions:
+ backport:
+ branches:
+ - "2.28-maintenance"
+ labels:
+ - automatic backport
+ - merge-queue
+
+ - name: backport patches to 2.29
+ conditions:
+ - label=backport 2.29-maintenance
+ actions:
+ backport:
+ branches:
+ - "2.29-maintenance"
+ labels:
+ - automatic backport
+ - merge-queue
+
+ - name: backport patches to 2.30
+ conditions:
+ - label=backport 2.30-maintenance
+ actions:
+ backport:
+ branches:
+ - "2.30-maintenance"
+ labels:
+ - automatic backport
- merge-queue
diff --git a/.version b/.version
index 7a25c70f90c..bafceb320ec 100644
--- a/.version
+++ b/.version
@@ -1 +1 @@
-2.26.0
+2.31.0
diff --git a/README.md b/README.md
index 54a6fcc3949..02498944cdb 100644
--- a/README.md
+++ b/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](https://matrix.to/#/#nix: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
## License
diff --git a/default.nix b/default.nix
index 2cccff28d51..6466507b714 100644
--- a/default.nix
+++ b/default.nix
@@ -1,10 +1,9 @@
-(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
diff --git a/doc/manual/book.toml b/doc/manual/book.toml.in
similarity index 96%
rename from doc/manual/book.toml
rename to doc/manual/book.toml.in
index 213739174b9..34acf642edb 100644
--- a/doc/manual/book.toml
+++ b/doc/manual/book.toml.in
@@ -1,5 +1,5 @@
[book]
-title = "Nix Reference Manual"
+title = "Nix @version@ Reference Manual"
src = "source"
[output.html]
diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix
index 37ed12a4330..3649560f7c6 100644
--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@@ -5,7 +5,15 @@ 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})";
diff --git a/doc/manual/generate-deps.py b/doc/manual/generate-deps.py
index 297bd39390e..8d6b5a2678f 100755
--- a/doc/manual/generate-deps.py
+++ b/doc/manual/generate-deps.py
@@ -14,7 +14,7 @@
# literally. since the rules for these aren't even the same for
# all three we will just fail when we encounter any of them (if
# asserts are off for some reason the depfile will likely point
-# to nonexistant paths, making everything phony and thus fine.)
+# to nonexistent 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
diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 791bfd2c756..31e74e17d26 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -32,7 +32,13 @@ let
commandInfo = fromJSON commandDump;
- showCommand = { command, details, filename, toplevel }:
+ showCommand =
+ {
+ command,
+ details,
+ filename,
+ toplevel,
+ }:
let
result = ''
@@ -56,26 +62,27 @@ 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);
@@ -99,38 +106,39 @@ 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
@@ -142,55 +150,73 @@ 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 ''[`--${name}`](#opt-${name}) ${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
+ ''[`--${name}`](#opt-${name}) ${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; };
- };
- subcommand = subCmd: processCommand {
- command = command + " " + subCmd;
- details = details.commands.${subCmd};
- filename = appendName filename subCmd;
- inherit toplevel;
+ value = showCommand {
+ inherit
+ command
+ details
+ filename
+ 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";
@@ -199,9 +225,11 @@ 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; }
diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
index 93a8e093e48..35ae73e5d1f 100644
--- a/doc/manual/generate-settings.nix
+++ b/doc/manual/generate-settings.nix
@@ -1,67 +1,99 @@
let
- inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
- inherit (import ) concatStrings indent optionalString squash;
+ inherit (builtins)
+ attrValues
+ concatStringsSep
+ isAttrs
+ isBool
+ mapAttrs
+ ;
+ inherit (import )
+ 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 ''[`${setting}`](#${prefix}-${setting})''
- else "`${setting}`";
+ ${indent " " body}
+ '';
+ item =
+ if inlineHTML then
+ ''[`${setting}`](#${prefix}-${setting})''
+ 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))
diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
index cc370412414..e66611affe0 100644
--- a/doc/manual/generate-store-info.nix
+++ b/doc/manual/generate-store-info.nix
@@ -1,6 +1,20 @@
let
- inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
- inherit (import ) optionalString filterAttrs trim squash toLower unique indent;
+ inherit (builtins)
+ attrNames
+ listToAttrs
+ concatStringsSep
+ readFile
+ replaceStrings
+ ;
+ inherit (import )
+ optionalString
+ filterAttrs
+ trim
+ squash
+ toLower
+ unique
+ indent
+ ;
showSettings = import ;
in
@@ -14,7 +28,14 @@ in
let
- showStore = { name, slug }: { settings, doc, experimentalFeature }:
+ showStore =
+ { name, slug }:
+ {
+ settings,
+ doc,
+ uri-schemes,
+ experimentalFeature,
+ }:
let
result = squash ''
# ${name}
@@ -25,7 +46,10 @@ let
## Settings
- ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
+ ${showSettings {
+ prefix = "store-${slug}";
+ inherit inlineHTML;
+ } settings}
'';
experimentalFeatureNote = optionalString (experimentalFeature != null) ''
@@ -43,15 +67,15 @@ let
> extra-experimental-features = ${experimentalFeature}
> ```
'';
- in result;
-
- storesList = map
- (name: rec {
- inherit name;
- slug = replaceStrings [ " " ] [ "-" ] (toLower name);
- filename = "${slug}.md";
- page = showStore { inherit name slug; } storeInfo.${name};
- })
- (attrNames storeInfo);
-
-in storesList
+ in
+ result;
+
+ storesList = map (name: rec {
+ inherit name;
+ slug = replaceStrings [ " " ] [ "-" ] (toLower name);
+ filename = "${slug}.md";
+ page = showStore { inherit name slug; } storeInfo.${name};
+ }) (attrNames storeInfo);
+
+in
+storesList
diff --git a/doc/manual/generate-store-types.nix b/doc/manual/generate-store-types.nix
index 46179abc5bf..a03d3d6216e 100644
--- a/doc/manual/generate-store-types.nix
+++ b/doc/manual/generate-store-types.nix
@@ -1,5 +1,11 @@
let
- inherit (builtins) attrNames listToAttrs concatStringsSep readFile replaceStrings;
+ inherit (builtins)
+ attrNames
+ listToAttrs
+ concatStringsSep
+ readFile
+ replaceStrings
+ ;
showSettings = import ;
showStoreDocs = import ;
in
@@ -14,26 +20,28 @@ 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"; }
diff --git a/doc/manual/generate-xp-features-shortlist.nix b/doc/manual/generate-xp-features-shortlist.nix
index eb735ba5f7a..1520fc2f815 100644
--- a/doc/manual/generate-xp-features-shortlist.nix
+++ b/doc/manual/generate-xp-features-shortlist.nix
@@ -2,8 +2,8 @@ with builtins;
with import ;
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)))
diff --git a/doc/manual/generate-xp-features.nix b/doc/manual/generate-xp-features.nix
index 0eec0e1da23..468d253bafd 100644
--- a/doc/manual/generate-xp-features.nix
+++ b/doc/manual/generate-xp-features.nix
@@ -2,7 +2,8 @@ with builtins;
with import ;
let
- showExperimentalFeature = name: doc:
+ showExperimentalFeature =
+ name: doc:
squash ''
## [`${name}`]{#xp-feature-${name}}
diff --git a/doc/manual/meson.build b/doc/manual/meson.build
index 3630e2dc828..6fe2374a764 100644
--- a/doc/manual/meson.build
+++ b/doc/manual/meson.build
@@ -67,7 +67,7 @@ subdir('source/release-notes')
subdir('source')
# Hacky way to figure out if `nix` is an `ExternalProgram` or
-# `Exectuable`. Only the latter can occur in custom target input lists.
+# `Executable`. Only the latter can occur in custom target input lists.
if nix.full_path().startswith(meson.build_root())
nix_input = nix
else
@@ -83,6 +83,7 @@ manual = custom_target(
'''
@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
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
@@ -92,12 +93,13 @@ manual = custom_target(
python.full_path(),
mdbook.full_path(),
meson.current_build_dir(),
+ meson.project_version(),
),
],
input : [
generate_manual_deps,
'substitute.py',
- 'book.toml',
+ 'book.toml.in',
'anchors.jq',
'custom.css',
nix3_cli_files,
@@ -199,6 +201,7 @@ nix3_manpages = [
'nix3-build',
'nix3-bundle',
'nix3-config',
+ 'nix3-config-check',
'nix3-config-show',
'nix3-copy',
'nix3-daemon',
@@ -206,8 +209,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',
@@ -224,6 +227,7 @@ nix3_manpages = [
'nix3-fmt',
'nix3-hash-file',
'nix3-hash',
+ 'nix3-hash-convert',
'nix3-hash-path',
'nix3-hash-to-base16',
'nix3-hash-to-base32',
@@ -238,14 +242,15 @@ 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',
@@ -260,7 +265,7 @@ nix3_manpages = [
'nix3-repl',
'nix3-run',
'nix3-search',
- #'nix3-shell',
+ 'nix3-store-add',
'nix3-store-add-file',
'nix3-store-add-path',
'nix3-store-cat',
@@ -270,12 +275,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',
diff --git a/doc/manual/package.nix b/doc/manual/package.nix
index 2e6fcede3f7..af6d46a2a00 100644
--- a/doc/manual/package.nix
+++ b/doc/manual/package.nix
@@ -1,19 +1,22 @@
-{ lib
-, mkMesonDerivation
+{
+ lib,
+ mkMesonDerivation,
-, meson
-, ninja
-, lowdown
-, mdbook
-, mdbook-linkcheck
-, jq
-, python3
-, rsync
-, nix-cli
+ meson,
+ ninja,
+ lowdown-unsandboxed,
+ mdbook,
+ mdbook-linkcheck,
+ jq,
+ python3,
+ rsync,
+ nix-cli,
+ changelog-d,
+ officialRelease,
-# Configuration Options
+ # Configuration Options
-, version
+ version,
}:
let
@@ -25,40 +28,51 @@ mkMesonDerivation (finalAttrs: {
inherit version;
workDir = ./.;
- fileset = fileset.difference
- (fileset.unions [
- ../../.version
- # Too many different types of files to filter for now
- ../../doc/manual
- ./.
- ])
- # Do a blacklist instead
- ../../doc/manual/package.nix;
+ 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"
+ ];
# Hack for sake of the dev shell
- passthru.externalNativeBuildInputs = [
- meson
- ninja
- (lib.getBin lowdown)
- mdbook
- mdbook-linkcheck
- jq
- python3
- rsync
- ];
+ passthru.externalNativeBuildInputs =
+ [
+ meson
+ ninja
+ (lib.getBin lowdown-unsandboxed)
+ mdbook
+ mdbook-linkcheck
+ jq
+ python3
+ rsync
+ 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
+ ];
nativeBuildInputs = finalAttrs.passthru.externalNativeBuildInputs ++ [
nix-cli
];
- preConfigure =
- ''
- chmod u+w ./.version
- echo ${finalAttrs.version} > ./.version
- '';
+ preConfigure = ''
+ chmod u+w ./.version
+ echo ${finalAttrs.version} > ./.version
+ '';
postInstall = ''
mkdir -p ''$out/nix-support
diff --git a/doc/manual/redirects.js b/doc/manual/redirects.js
index dea141391df..9612438481f 100644
--- a/doc/manual/redirects.js
+++ b/doc/manual/redirects.js
@@ -346,6 +346,9 @@ 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",
@@ -371,7 +374,9 @@ 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",
},
};
diff --git a/doc/manual/rl-next/build-cores-auto-detect.md b/doc/manual/rl-next/build-cores-auto-detect.md
new file mode 100644
index 00000000000..67ab6995b4c
--- /dev/null
+++ b/doc/manual/rl-next/build-cores-auto-detect.md
@@ -0,0 +1,6 @@
+---
+synopsis: "`build-cores = 0` now auto-detects CPU cores"
+prs: [13402]
+---
+
+When `build-cores` is set to `0`, nix now automatically detects the number of available CPU cores and passes this value via `NIX_BUILD_CORES`, instead of passing `0` directly. This matches the behavior when `build-cores` is unset. This prevents the builder from having to detect the number of cores.
diff --git a/doc/manual/rl-next/nix-copy-flags.md b/doc/manual/rl-next/nix-copy-flags.md
deleted file mode 100644
index f5b2b9716a4..00000000000
--- a/doc/manual/rl-next/nix-copy-flags.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-synopsis: "`nix copy` supports `--profile` and `--out-link`"
-prs: [11657]
----
-
-The `nix copy` command now has flags `--profile` and `--out-link`, similar to `nix build`. `--profile` makes a profile point to the
-top-level store path, while `--out-link` create symlinks to the top-level store paths.
-
-For example, when updating the local NixOS system profile from a NixOS system closure on a remote machine, instead of
-```
-# nix copy --from ssh://server $path
-# nix build --profile /nix/var/nix/profiles/system $path
-```
-you can now do
-```
-# nix copy --from ssh://server --profile /nix/var/nix/profiles/system $path
-```
-The advantage is that this avoids a time window where *path* is not a garbage collector root, and so could be deleted by a concurrent `nix store gc` process.
diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in
index 244bf582d09..bfb921567c3 100644
--- a/doc/manual/source/SUMMARY.md.in
+++ b/doc/manual/source/SUMMARY.md.in
@@ -22,12 +22,18 @@
- [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)
+ - [Building](store/building.md)
- [Store Types](store/types/index.md)
{{#include ./store/types/SUMMARY.md}}
- [Nix Language](language/index.md)
- [Data Types](language/types.md)
- [String context](language/string-context.md)
- [Syntax and semantics](language/syntax.md)
+ - [Evaluation](language/evaluation.md)
- [Variables](language/variables.md)
- [String literals](language/string-literals.md)
- [Identifiers](language/identifiers.md)
@@ -51,6 +57,7 @@
- [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)
@@ -130,6 +137,11 @@
- [Contributing](development/contributing.md)
- [Releases](release-notes/index.md)
{{#include ./SUMMARY-rl-next.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)
diff --git a/doc/manual/source/advanced-topics/distributed-builds.md b/doc/manual/source/advanced-topics/distributed-builds.md
index 66e37188840..08a980643e8 100644
--- a/doc/manual/source/advanced-topics/distributed-builds.md
+++ b/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 paramater, e.g.
+query parameter, e.g.
```console
nix store info --store ssh://username@mac?ssh-key=/home/alice/my-key
@@ -106,3 +106,5 @@ 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
\ No newline at end of file
diff --git a/doc/manual/source/advanced-topics/eval-profiler.md b/doc/manual/source/advanced-topics/eval-profiler.md
new file mode 100644
index 00000000000..ed3848bb2db
--- /dev/null
+++ b/doc/manual/source/advanced-topics/eval-profiler.md
@@ -0,0 +1,33 @@
+# Using the `eval-profiler`
+
+Nix evaluator supports [evaluation](@docroot@/language/evaluation.md)
+[profiling]()
+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 "" -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`.
diff --git a/doc/manual/source/architecture/architecture.md b/doc/manual/source/architecture/architecture.md
index 867a9c992d3..0c8677a6a56 100644
--- a/doc/manual/source/architecture/architecture.md
+++ b/doc/manual/source/architecture/architecture.md
@@ -22,9 +22,9 @@ The following [concept map] shows its main components (rectangles), the objects
| |
+----------|-------------------|--------------------------------+
| Nix | V |
-| | +-------------------------+ |
-| | | commmand line interface |------. |
-| | +-------------------------+ | |
+| | +------------------------+ |
+| | | command 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 [derivation](@docroot@/glossary.md#gloss-derivation).
+> A build task in Nix is called [store derivation](@docroot@/glossary.md#gloss-store-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.
diff --git a/doc/manual/source/command-ref/nix-channel.md b/doc/manual/source/command-ref/nix-channel.md
index 8b58392b7b5..ed9cbb41fbf 100644
--- a/doc/manual/source/command-ref/nix-channel.md
+++ b/doc/manual/source/command-ref/nix-channel.md
@@ -53,6 +53,11 @@ 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
diff --git a/doc/manual/source/command-ref/nix-collect-garbage.md b/doc/manual/source/command-ref/nix-collect-garbage.md
index bd05f28164e..763179b8ee1 100644
--- a/doc/manual/source/command-ref/nix-collect-garbage.md
+++ b/doc/manual/source/command-ref/nix-collect-garbage.md
@@ -62,6 +62,15 @@ These options are for deleting old [profiles] prior to deleting unreachable [sto
This is the equivalent of invoking [`nix-env --delete-generations `](@docroot@/command-ref/nix-env/delete-generations.md#generations-time) on each found profile.
See the documentation of that command for additional information about the *period* argument.
+ - [`--max-freed`](#opt-max-freed) *bytes*
+
+
+
+ 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}}
diff --git a/doc/manual/source/command-ref/nix-copy-closure.md b/doc/manual/source/command-ref/nix-copy-closure.md
index 8cfd6ebad56..b7e31d93bfc 100644
--- a/doc/manual/source/command-ref/nix-copy-closure.md
+++ b/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 '' -I nixpkgs=channel:nixpkgs-unstable -A hello.outPath | tr -d '"')"
+> $ storePath="$(nix-instantiate --eval --raw '' -I nixpkgs=channel:nixpkgs-unstable -A hello.outPath)"
> $ nix-copy-closure --from alice@itchy.example.org "$storePath"
> $ "$storePath"/bin/hello
> Hello, world!
diff --git a/doc/manual/source/command-ref/nix-env/delete-generations.md b/doc/manual/source/command-ref/nix-env/delete-generations.md
index b1ff0bb6941..b769790fd45 100644
--- a/doc/manual/source/command-ref/nix-env/delete-generations.md
+++ b/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 curent 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 current 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.
diff --git a/doc/manual/source/command-ref/nix-env/install.md b/doc/manual/source/command-ref/nix-env/install.md
index 748dd1e7a39..527fd8f90d8 100644
--- a/doc/manual/source/command-ref/nix-env/install.md
+++ b/doc/manual/source/command-ref/nix-env/install.md
@@ -11,6 +11,7 @@
[`--from-profile` *path*]
[`--preserve-installed` | `-P`]
[`--remove-all` | `-r`]
+ [`--priority` *priority*]
# Description
@@ -21,11 +22,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 [derivation] names denoting derivations in the [default Nix expression].
+- By default, *args* is a set of names denoting derivations in the [default Nix expression].
These are [realised], and the resulting output paths are installed.
Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
- [derivation]: @docroot@/glossary.md#gloss-derivation
+ [derivation expression]: @docroot@/glossary.md#gloss-derivation-expression
[default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
[realised]: @docroot@/glossary.md#gloss-realise
@@ -61,11 +62,15 @@ 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 *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
+- 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 paths] that are not store derivations, then these are [realised] and 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.
-- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
+- 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].
This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
Example:
@@ -117,6 +122,8 @@ 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`
@@ -235,4 +242,3 @@ channel:
```console
$ nix-env --file https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz --install --attr firefox
```
-
diff --git a/doc/manual/source/command-ref/nix-env/query.md b/doc/manual/source/command-ref/nix-env/query.md
index c67794ed58e..bde9b38202c 100644
--- a/doc/manual/source/command-ref/nix-env/query.md
+++ b/doc/manual/source/command-ref/nix-env/query.md
@@ -125,7 +125,10 @@ derivation is shown unless `--no-name` is specified.
- `--drv-path`
- Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
+ Print the [store path] to the [store derivation].
+
+ [store path]: @docroot@/glossary.md#gloss-store-path
+ [store derivation]: @docroot@/glossary.md#gloss-derivation
- `--out-path`
diff --git a/doc/manual/source/command-ref/nix-hash.md b/doc/manual/source/command-ref/nix-hash.md
index f249c2b84d6..0860f312d94 100644
--- a/doc/manual/source/command-ref/nix-hash.md
+++ b/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
- `md5`, `sha1`, `sha256`, and `sha512`.
+ `blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
- `--to-base16`
diff --git a/doc/manual/source/command-ref/nix-instantiate.md b/doc/manual/source/command-ref/nix-instantiate.md
index 6f6fcdc1f66..38454515d57 100644
--- a/doc/manual/source/command-ref/nix-instantiate.md
+++ b/doc/manual/source/command-ref/nix-instantiate.md
@@ -5,7 +5,7 @@
# Synopsis
`nix-instantiate`
- [`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ]
+ [`--parse` | `--eval` [`--strict`] [`--raw` | `--json` | `--xml`] ]
[`--read-write-mode`]
[`--arg` *name* *value*]
[{`--attr`| `-A`} *attrPath*]
@@ -42,8 +42,8 @@ standard input.
- `--eval`
Just parse and evaluate the input files, and print the resulting
- values on standard output. No instantiation of store derivations
- takes place.
+ values on standard output.
+ Store derivations are not serialized and written to the store, but instead just hashed and discarded.
> **Warning**
>
@@ -102,6 +102,11 @@ 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
diff --git a/doc/manual/source/command-ref/nix-prefetch-url.md b/doc/manual/source/command-ref/nix-prefetch-url.md
index ffab94b8afa..19322ec8e04 100644
--- a/doc/manual/source/command-ref/nix-prefetch-url.md
+++ b/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 `md5`, `sha1`, `sha256`, and `sha512`.
+ which can be one of `blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
The default is `sha256`.
- `--print-path`
diff --git a/doc/manual/source/command-ref/nix-shell.md b/doc/manual/source/command-ref/nix-shell.md
index e95db9bea5d..f2e2e35936e 100644
--- a/doc/manual/source/command-ref/nix-shell.md
+++ b/doc/manual/source/command-ref/nix-shell.md
@@ -242,16 +242,21 @@ print(t)
```
Similarly, the following is a Perl script that specifies that it
-requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:
+requires Perl and the `HTML::TokeParser::Simple`, `LWP` and
+`LWP::Protocol::Https` packages:
```perl
#! /usr/bin/env nix-shell
-#! nix-shell -i perl --packages perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
+#! nix-shell -i perl
+#! nix-shell --packages perl
+#! nix-shell --packages perlPackages.HTMLTokeParserSimple
+#! nix-shell --packages perlPackages.LWP
+#! nix-shell --packages perlPackages.LWPProtocolHttps
use HTML::TokeParser::Simple;
# Fetch nixos.org and print all hrefs.
-my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
+my $p = HTML::TokeParser::Simple->new(url => 'https://nixos.org/');
while (my $token = $p->get_tag("a")) {
my $href = $token->get_attr("href");
@@ -316,7 +321,7 @@ contains:
```nix
with import {};
-runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
+runCommand "dummy" { buildInputs = [ python3 python3Packages.prettytable ]; } ""
```
The script's file name is passed as the first argument to the interpreter specified by the `-i` flag.
diff --git a/doc/manual/source/command-ref/nix-store/add-fixed.md b/doc/manual/source/command-ref/nix-store/add-fixed.md
index bebf15026a6..2ea90a13592 100644
--- a/doc/manual/source/command-ref/nix-store/add-fixed.md
+++ b/doc/manual/source/command-ref/nix-store/add-fixed.md
@@ -21,6 +21,9 @@ 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}}
diff --git a/doc/manual/source/command-ref/nix-store/add.md b/doc/manual/source/command-ref/nix-store/add.md
index 87d504cd333..ab474072311 100644
--- a/doc/manual/source/command-ref/nix-store/add.md
+++ b/doc/manual/source/command-ref/nix-store/add.md
@@ -11,6 +11,9 @@
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}}
diff --git a/doc/manual/source/command-ref/nix-store/query.md b/doc/manual/source/command-ref/nix-store/query.md
index 601f46af6b2..b5ba63adae2 100644
--- a/doc/manual/source/command-ref/nix-store/query.md
+++ b/doc/manual/source/command-ref/nix-store/query.md
@@ -45,10 +45,19 @@ 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 [closure] of the store path *paths*.
+ Prints out the set of [*requisites*][requisite] (better known as the [closure]) of the store path *paths*.
+ [requisite]: @docroot@/glossary.md#gloss-requisite
[closure]: @docroot@/glossary.md#gloss-closure
This query has one option:
@@ -65,29 +74,25 @@ 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* of the store paths *paths*, that is,
+ Prints the set of [*referrers*][referrer] 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; that is, all store paths that directly or
+ [referrers relation][referrer]; 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
diff --git a/doc/manual/source/command-ref/nix-store/realise.md b/doc/manual/source/command-ref/nix-store/realise.md
index a899758dfab..240685ce5c7 100644
--- a/doc/manual/source/command-ref/nix-store/realise.md
+++ b/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-addressed derivations] (experimental):
+ - With [content-addressing 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-addressed derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
+[content-addressing 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.
diff --git a/doc/manual/source/development/building.md b/doc/manual/source/development/building.md
index 409294682e9..16746383704 100644
--- a/doc/manual/source/development/building.md
+++ b/doc/manual/source/development/building.md
@@ -28,7 +28,7 @@ $ nix-shell --attr devShells.x86_64-linux.native-clangStdenvPackages
> **Note**
>
-> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time.
+> You can use `native-ccacheStdenv` to drastically improve rebuild time.
> By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
To build Nix itself in this shell:
@@ -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-clangStdenvPackages
+$ nix develop .#native-clangStdenv
```
> **Note**
@@ -167,24 +167,18 @@ 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.
-Nixpkgs's `configurePhase` 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.
+Here's how to do that:
-Here's how to do that
-
-1. Configure as usual
+1. Instruct Nixpkgs's infra where we want Meson to put its build directory
```bash
- configurePhase
+ mesonBuildDir=build-my-variant-name
```
-2. Rename the build directory
+1. Configure as usual
```bash
- cd .. # since `configurePhase` cd'd inside
- mv build build-linux # or whatever name we want
- cd build-linux
+ configurePhase
```
3. Build as usual
@@ -193,10 +187,6 @@ Here's how to do that
buildPhase
```
-> **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:
@@ -205,19 +195,25 @@ Nix uses a string with the following format to identify the *system type* or *pl
-[-]
```
-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)):
+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)>
```
--[][-]
```
-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)):
+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:
```
--[-]-
+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
```
-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:
+For historic reasons and backward-compatibility, some CPU and OS identifiers are translated as follows:
| `config.guess` | Nix |
|----------------------------|---------------------|
@@ -240,18 +236,18 @@ Nix can be compiled using multiple environments:
To build with one of those environments, you can use
```console
-$ nix build .#nix-ccacheStdenv
+$ nix build .#nix-cli-ccacheStdenv
```
for flake-enabled Nix, or
```console
-$ nix-build --attr nix-ccacheStdenv
+$ nix-build --attr nix-cli-ccacheStdenv
```
for classic Nix.
-You can use any of the other supported environments in place of `nix-ccacheStdenv`.
+You can use any of the other supported environments in place of `nix-cli-ccacheStdenv`.
## Editor integration
@@ -261,7 +257,8 @@ See [supported compilation environments](#compilation-environments) and instruct
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-clangStdenvPackages` shell. You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
+Configure your editor to use the `clangd` from the `.#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).
> **Note**
>
@@ -277,6 +274,8 @@ 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:
```
@@ -291,3 +290,30 @@ 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"
+ ],
+ },
+ },
+ },
+}
+```
diff --git a/doc/manual/source/development/cli-guideline.md b/doc/manual/source/development/cli-guideline.md
index 23df844ec11..052b4aae8e2 100644
--- a/doc/manual/source/development/cli-guideline.md
+++ b/doc/manual/source/development/cli-guideline.md
@@ -170,9 +170,9 @@ sensitive.
```shell
-$ nix init --template=template#pyton
+$ nix init --template=template#python
------------------------------------------------------------------------
- Error! Template `template#pyton` not found.
+ Error! Template `template#python` not found.
------------------------------------------------------------------------
Initializing Nix project at `/path/to/here`.
Select a template for you new project:
diff --git a/doc/manual/source/development/contributing.md b/doc/manual/source/development/contributing.md
index 7de7489dcb7..5c32aeb712a 100644
--- a/doc/manual/source/development/contributing.md
+++ b/doc/manual/source/development/contributing.md
@@ -20,8 +20,9 @@ prs: 1238
Here's one or more paragraphs that describe the change.
- It's markdown
-- Add references to the manual using @docroot@
+- Add references to the manual using [links like this](@_at_docroot@/example.md)
```
+
Significant changes should add the following header, which moves them to the top.
diff --git a/doc/manual/source/development/debugging.md b/doc/manual/source/development/debugging.md
index ce623110b36..98456841af1 100644
--- a/doc/manual/source/development/debugging.md
+++ b/doc/manual/source/development/debugging.md
@@ -2,6 +2,8 @@
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:
@@ -13,6 +15,15 @@ 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.)
+
## Debugging the Nix Binary
Obtain your preferred debugger within the development shell:
diff --git a/doc/manual/source/development/documentation.md b/doc/manual/source/development/documentation.md
index 2e188f23246..30cc8adc44a 100644
--- a/doc/manual/source/development/documentation.md
+++ b/doc/manual/source/development/documentation.md
@@ -19,10 +19,11 @@ nix-build -E '(import ./.).packages.${builtins.currentSystem}.nix.doc'
or
```console
-nix build .#nix^doc
+nix build .#nix-manual
```
-and open `./result-doc/share/doc/nix/manual/index.html`.
+and open `./result/share/doc/nix/manual/index.html`.
+
To build the manual incrementally, [enter the development shell](./building.md) and run:
diff --git a/doc/manual/source/development/testing.md b/doc/manual/source/development/testing.md
index 30aa7d0d51b..c0b13015562 100644
--- a/doc/manual/source/development/testing.md
+++ b/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
-> │ ├── value/context.hh
+> │ ├── include/nix/expr/value/context.hh
> │ ├── value/context.cc
> │ …
> │
@@ -46,8 +46,12 @@ 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
> │ │ …
> │ │
@@ -59,7 +63,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/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}`.
+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`.
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`.
@@ -67,7 +71,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 "tests/"`.
+All headers are in a `tests` subdirectory so they are included with `#include "nix/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:
@@ -87,7 +91,11 @@ A environment variables that Google Test accepts are also worth knowing:
This is used to avoid logging passing tests.
-Putting the two together, one might run
+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
```bash
GTEST_BRIEF=1 GTEST_FILTER='ErrorTraceTest.*' meson test nix-expr-tests -v
@@ -95,6 +103,22 @@ 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 { #characaterisation-testing-unit }
See [functional characterisation testing](#characterisation-testing-functional) for a broader discussion of characterisation testing.
@@ -144,7 +168,7 @@ $ checkPhase
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-addressed derivation outputs.
+For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressing derivation outputs.
That test group can be run like this:
@@ -213,10 +237,10 @@ edit it like so:
bar
```
-Then, running the test with `./mk/debug-test.sh` will drop you into GDB once the script reaches that point:
+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:
```shell-session
-$ ./mk/debug-test.sh tests/functional/${testName}.sh
+$ meson test ${testName} --interactive
...
+ gdb blash blub
GNU gdb (GDB) 12.1
@@ -297,7 +321,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-latest` and `macos-latest`) will try to install Nix with the cached installer and run a trivial Nix command.
+- 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.
### One-time setup
diff --git a/doc/manual/source/glossary.md b/doc/manual/source/glossary.md
index fa357ece3d6..e6a294e7de7 100644
--- a/doc/manual/source/glossary.md
+++ b/doc/manual/source/glossary.md
@@ -1,5 +1,13 @@
# 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
@@ -13,37 +21,62 @@
- [Content-Addressing File System Objects](@docroot@/store/file-system-object/content-address.md)
- [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md)
- - [content-addressed derivation](#gloss-content-addressed-derivation)
+ - [content-addressing derivation](#gloss-content-addressing-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 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`).
+ 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].
[derivation]: #gloss-derivation
- [store derivation]{#gloss-store-derivation}
- A [derivation] represented as a `.drv` file in the [store].
- It has a [store path], like any [store object].
- It is the [instantiated][instantiate] form of a derivation.
-
- Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
+ A [derivation] represented as a [store object].
- See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations.
+ See [Store Derivation](@docroot@/store/derivation/index.md#store-derivation) for details.
[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
- Save an evaluated [derivation] as a [store derivation] in the Nix [store].
+ Translate a [derivation expression] into a [store derivation].
See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation.
@@ -55,9 +88,8 @@
This can be achieved by:
- Fetching a pre-built [store object] from a [substituter]
- - Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation]
+ - [Building](@docroot@/store/building.md) the corresponding [store derivation]
- Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs
-
See [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md) for a detailed description of the algorithm.
@@ -65,7 +97,7 @@
[realise]: #gloss-realise
-- [content-addressed derivation]{#gloss-content-addressed-derivation}
+- [content-addressing derivation]{#gloss-content-addressing-derivation}
A derivation which has the
[`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
@@ -73,7 +105,7 @@
- [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD)
- 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.
+ 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.
- [store]{#gloss-store}
@@ -84,6 +116,12 @@
[store]: #gloss-store
+- [Nix instance]{#gloss-nix-instance}
+
+ 1. An installation of Nix, which includes the presence of a [store], and the Nix package manager which operates on that store.
+ A local Nix installation and a [remote builder](@docroot@/advanced-topics/distributed-builds.md) are two examples of Nix instances.
+ 2. A running Nix process, such as the `nix` command.
+
- [binary cache]{#gloss-binary-cache}
A *binary cache* is a Nix store which uses a different format: its
@@ -130,15 +168,17 @@
- [input-addressed store object]{#gloss-input-addressed-store-object}
A store object produced by building a
- non-[content-addressed](#gloss-content-addressed-derivation),
+ non-[content-addressed](#gloss-content-addressing-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-addressed derivations](#gloss-content-addressed-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
+ This includes derivations, the outputs of [content-addressing derivations](#gloss-content-addressing-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
See [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md) for details.
@@ -188,35 +228,37 @@
>
> The contents of a `.nix` file form a Nix expression.
- Nix expressions specify [derivations][derivation], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
+ Nix expressions specify [derivation expressions][derivation expression], 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 as a high-level description of packages and compositions thereof.
+ > Building and deploying software using Nix entails writing Nix expressions to describe [packages][package] and compositions thereof.
- [reference]{#gloss-reference}
- 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`.
+ An edge from one [store object] to another.
- 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.
+ See [References](@docroot@/store/store-object.md#references) for details.
[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
@@ -226,18 +268,31 @@
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-reference}
+
+ A reversed edge from one [store object] to another.
+
- [output]{#gloss-output}
- A [store object] produced by a [derivation].
+ A [store object] produced by a [store 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 [derivation].
+ The [store path] to the [output] of a [store derivation].
[output path]: #gloss-output-path
@@ -246,14 +301,11 @@
- [deriving path]{#gloss-deriving-path}
- Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
- This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
- There are two forms:
+ Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
- - *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.
+ See [Deriving Path](./store/derivation/index.md#deriving-path) for details.
- - *output*: a pair of a [store path] to a [derivation] and an [output] name.
+ Not to be confused with [derivation path].
- [deriver]{#gloss-deriver}
@@ -301,7 +353,7 @@
See [Nix Archive](store/file-system-object/content-address.html#serial-nix-archive) for details.
-- [`∅`]{#gloss-emtpy-set}
+- [`∅`]{#gloss-empty-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.
@@ -311,18 +363,17 @@
- [package]{#package}
- 1. A software package; a collection of files and other data.
+ A software package; files that belong together for a particular purpose, and metadata.
- 2. A [package attribute set].
+ 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.
-- [package attribute set]{#package-attribute-set}
+ The [Nix language] allows denoting packages in terms of [attribute sets](@docroot@/language/types.md#attribute-set) containing:
+ - attributes that refer to the files of a package, typically in the form of [derivation outputs](#output),
+ - attributes with metadata, such as information about how the package is supposed to be used.
- 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.
+ The exact shape of these attribute sets is up to convention.
- [package attribute set]: #package-attribute-set
+ [package]: #package
- [string interpolation]{#gloss-string-interpolation}
diff --git a/doc/manual/source/installation/index.md b/doc/manual/source/installation/index.md
index 48725c1ba74..3c09f103184 100644
--- a/doc/manual/source/installation/index.md
+++ b/doc/manual/source/installation/index.md
@@ -30,6 +30,8 @@ $ 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.
diff --git a/doc/manual/source/installation/installing-binary.md b/doc/manual/source/installation/installing-binary.md
index 6a1a5ddcaff..21c15637437 100644
--- a/doc/manual/source/installation/installing-binary.md
+++ b/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 configured with various command line arguments and environment variables.
+The installer can be configured with various command line arguments and environment variables.
To show available command line flags:
```console
diff --git a/doc/manual/source/installation/uninstall.md b/doc/manual/source/installation/uninstall.md
index 47689a16ece..8d45da6bba0 100644
--- a/doc/manual/source/installation/uninstall.md
+++ b/doc/manual/source/installation/uninstall.md
@@ -160,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`.
diff --git a/doc/manual/source/introduction.md b/doc/manual/source/introduction.md
index 76489bc1b2c..e70411c11f5 100644
--- a/doc/manual/source/introduction.md
+++ b/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 purely functional programming languages
-such as Haskell — they are built by functions that don’t have
+treats packages like values in a purely functional programming language
+— packages 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
diff --git a/doc/manual/source/language/advanced-attributes.md b/doc/manual/source/language/advanced-attributes.md
index 51b83fc8acc..34c3b636b39 100644
--- a/doc/manual/source/language/advanced-attributes.md
+++ b/doc/manual/source/language/advanced-attributes.md
@@ -2,6 +2,75 @@
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,
@@ -55,34 +124,89 @@ Derivations can declare some infrequently used optional attributes.
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:
+ - [`outputChecks`]{#adv-attr-outputChecks}\
+ When using [structured attributes](#adv-attr-structuredAttrs), the `outputChecks`
+ attribute allows defining checks per-output.
+
+ In addition to
+ [`allowedReferences`](#adv-attr-allowedReferences), [`allowedRequisites`](#adv-attr-allowedRequisites),
+ [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites),
+ the following attributes are available:
+
+ - `maxSize` defines the maximum size of the resulting [store object](@docroot@/store/store-object.md).
+ - `maxClosureSize` defines the maximum size of the output's closure.
+ - `ignoreSelfRefs` controls whether self-references should be considered when
+ checking for allowed references/requisites.
+
+ Example:
```nix
- derivation {
- ...
- exportReferencesGraph = [ "libfoo-graph" libfoo ];
+ __structuredAttrs = true;
+
+ outputChecks.out = {
+ # The closure of 'out' must not be larger than 256 MiB.
+ maxClosureSize = 256 * 1024 * 1024;
+
+ # It must not refer to the C compiler or to the 'dev' output.
+ disallowedRequisites = [ stdenv.cc "dev" ];
+ };
+
+ outputChecks.dev = {
+ # The 'dev' output must not be larger than 128 KiB.
+ maxSize = 128 * 1024;
};
```
- the references graph of `libfoo` is placed in the file
- `libfoo-graph` in the temporary build directory.
+## Other output modifications
- `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).
+ - [`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.
+
+ Example:
+
+ ```nix
+ __structuredAttrs = true;
+ unsafeDiscardReferences.out = true;
+ ```
+
+ This is useful, for example, when generating self-contained filesystem images with
+ their own embedded Nix store: hashes found inside such an image refer
+ to the embedded store and not to the host's Nix store.
+
+## 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
+
+ ```nix
+ requiredSystemFeatures = [ "kvm" ];
+ ```
+
+ 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
@@ -99,8 +223,8 @@ Derivations can declare some infrequently used optional attributes.
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
+ 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.
@@ -119,81 +243,55 @@ Derivations can declare some infrequently used optional attributes.
[`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.
+## Setting the derivation type
- 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.
+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.
- 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,
+- [`__contentAddressed`]
- ```nix
- fetchurl {
- url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
- sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
- }
- ```
+- [`outputHash`]
- 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.,
+- [`outputHashAlgo`]
- ```nix
- fetchurl {
- url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
- sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
- }
- ```
+- [`outputHashMode`]
- 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.
+The three types of derivations are chosen based on the following combinations of these attributes.
+All other combinations are invalid.
- 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.)
+- [Input-addressing derivations](@docroot@/store/derivation/outputs/input-address.md)
- As an example, here is the (simplified) Nix expression for
- `fetchurl`:
+ This is the default for `builtins.derivation`.
+ Nix only currently supports one kind of input-addressing, so no other information is needed.
- ```nix
- { stdenv, curl }: # The curl program is used for downloading.
+ `__contentAddressed = false;` may also be included, but is not needed, and will trigger the experimental feature check.
- { url, sha256 }:
+- [Fixed-output derivations][fixed-output derivation]
- stdenv.mkDerivation {
- name = baseNameOf (toString url);
- builder = ./builder.sh;
- buildInputs = [ curl ];
+ All of [`outputHash`], [`outputHashAlgo`], and [`outputHashMode`].
- # This is a fixed-output derivation; the output must be a regular
- # file with SHA256 hash sha256.
- outputHashMode = "flat";
- outputHashAlgo = "sha256";
- outputHash = sha256;
+
+
+- [(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:
@@ -223,153 +321,56 @@ Derivations can declare some infrequently used optional attributes.
>
> 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.
+ See [content-addressing store objects](@docroot@/store/store-object/content-address.md) for more information about the process this flag controls.
- Setting this attribute also requires setting
- [`outputHashMode`](#adv-attr-outputHashMode)
- and
- [`outputHashAlgo`](#adv-attr-outputHashAlgo)
- like for *fixed-output derivations* (see above).
+ - [`outputHashAlgo`]{#adv-attr-outputHashAlgo}
- 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).
+ This specifies the hash algorithm used to digest the [file system object] data of a content-addressing derivation output.
- - [`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
+ 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).
- ```nix
- passAsFile = ["big"];
- big = "a very long string";
- ```
+ The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
+ It can currently be `"blake3"`, `"sha1"`, `"sha256"`, `"sha512"`, or `null`.
- 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).
+ `outputHashAlgo` can only be `null` when `outputHash` follows the SRI format, because in that case the choice of hash algorithm is determined by `outputHash`.
- - [`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.
+ - [`outputHash`]{#adv-attr-outputHashAlgo}; [`outputHash`]{#adv-attr-outputHashMode}
- - [`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 will specify the output hash of the single output of a [fixed-output derivation].
- This attribute can be ignored by setting [`always-allow-substitutes`](@docroot@/command-ref/conf-file.md#conf-always-allow-substitutes) to `true`.
+ 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**
>
- > 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.
+ > 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.
- [`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]}`.
+ - [`__contentAddressed`]{#adv-attr-__contentAddressed}
> **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.
-
- In addition to
- [`allowedReferences`](#adv-attr-allowedReferences), [`allowedRequisites`](#adv-attr-allowedRequisites),
- [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites),
- the following attributes are available:
-
- - `maxSize` defines the maximum size of the resulting [store object](@docroot@/store/store-object.md).
- - `maxClosureSize` defines the maximum size of the output's closure.
- - `ignoreSelfRefs` controls whether self-references should be considered when
- checking for allowed references/requisites.
-
- Example:
-
- ```nix
- __structuredAttrs = true;
-
- outputChecks.out = {
- # The closure of 'out' must not be larger than 256 MiB.
- maxClosureSize = 256 * 1024 * 1024;
-
- # It must not refer to the C compiler or to the 'dev' output.
- disallowedRequisites = [ stdenv.cc "dev" ];
- };
-
- outputChecks.dev = {
- # The 'dev' output must not be larger than 128 KiB.
- maxSize = 128 * 1024;
- };
- ```
-
- - [`unsafeDiscardReferences`]{#adv-attr-unsafeDiscardReferences}\
-
- When using [structured attributes](#adv-attr-structuredAttrs), the
- attribute `unsafeDiscardReferences` is an attribute set with a boolean value for each output name.
- If set to `true`, it disables scanning the output for runtime dependencies.
-
- Example:
-
- ```nix
- __structuredAttrs = true;
- unsafeDiscardReferences.out = true;
- ```
-
- This is useful, for example, when generating self-contained filesystem images with
- their own embedded Nix store: hashes found inside such an image refer
- to the embedded store and not to the host's Nix store.
-
-- [`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
+ > 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
+ > ```
- ```nix
- requiredSystemFeatures = [ "kvm" ];
- ```
+ This is a boolean with a default of `false`.
+ It determines whether the derivation is floating content-addressing.
- ensures that the derivation can only be built on a machine with the `kvm` feature.
+[`__contentAddressed`]: #adv-attr-__contentAddressed
+[`outputHash`]: #adv-attr-outputHash
+[`outputHashAlgo`]: #adv-attr-outputHashAlgo
+[`outputHashMode`]: #adv-attr-outputHashMode
-[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
+[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-dynamic-derivations]: @docroot@/development/experimental-features.md#xp-feature-dynamic-derivations
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
diff --git a/doc/manual/source/language/derivations.md b/doc/manual/source/language/derivations.md
index 771b2bd9130..43eec680bbc 100644
--- a/doc/manual/source/language/derivations.md
+++ b/doc/manual/source/language/derivations.md
@@ -1,9 +1,10 @@
# Derivations
-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.
+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.
-It takes as input an attribute set, the attributes of which specify the inputs to the process.
+This builtin function 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
@@ -15,7 +16,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.
- 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).
+ See [derivation outputs](@docroot@/store/derivation/index.md#outputs) for what this is affects.
[store path]: @docroot@/store/store-path.md
@@ -28,17 +29,12 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
> }
> ```
>
- > The store derivation's path will be `/nix/store/-hello.drv`.
+ > The derivation's path will be `/nix/store/-hello.drv`.
> The [output](#attr-outputs) paths will be of the form `/nix/store/-hello[-