[pull] master from NixOS:master

.github/workflows/check-by-name.yml

@@ -1,5 +1,7 @@
 # Checks pkgs/by-name (see pkgs/by-name/README.md)
 # using the nixpkgs-check-by-name tool (see pkgs/test/nixpkgs-check-by-name)
+#
+# When you make changes to this workflow, also update pkgs/test/nixpkgs-check-by-name/scripts/run-local.sh adequately
 name: Check pkgs/by-name
 
 # The pre-built tool is fetched from a channel,
@@ -21,6 +23,9 @@ jobs:
     # The default of 6 hours is definitely too long
     timeout-minutes: 10
     steps:
+      # This step has to be in this file,
+      # because it's needed to determine which revision of the repository to fetch,
+      # and we can only use other files from the repository once it's fetched.
       - name: Resolving the merge commit
         env:
           GH_TOKEN: ${{ github.token }}
@@ -80,124 +85,20 @@ jobs:
           ref: ${{ env.mergedSha }}
           # Fetches the merge commit and its parents
           fetch-depth: 2
-      - name: Determining PR git hashes
+      - name: Checking out base branch
         run: |
-          # For pull_request_target this is the same as $GITHUB_SHA
-          echo "baseSha=$(git rev-parse HEAD^1)" >> "$GITHUB_ENV"
-
-          echo "headSha=$(git rev-parse HEAD^2)" >> "$GITHUB_ENV"
+          base=$(mktemp -d)
+          git worktree add "$base" "$(git rev-parse HEAD^1)"
+          echo "base=$base" >> "$GITHUB_ENV"
       - uses: cachix/install-nix-action@7ac1ec25491415c381d9b62f0657c7a028df52a7 # v24
-      - name: Determining channel to use for dependencies
-        run: |
-          echo "Determining the preferred channel to use for PR base branch $GITHUB_BASE_REF"
-          if [[ "$GITHUB_BASE_REF" =~ ^(release|staging|staging-next)-([0-9][0-9]\.[0-9][0-9])$ ]]; then
-              # Use the release channel for all PRs to release-XX.YY, staging-XX.YY and staging-next-XX.YY
-              channel=nixos-${BASH_REMATCH[2]}
-              echo "PR is for a release branch, preferred channel is $channel"
-          else
-              # Use the nixos-unstable channel for all other PRs
-              channel=nixos-unstable
-              echo "PR is for a non-release branch, preferred channel is $channel"
-          fi
-          # Check that the channel exists. It doesn't exist for fresh release branches
-          if ! curl -fSs "https://channels.nixos.org/$channel"; then
-            # Fall back to nixos-unstable, makes sense for fresh release branches
-            echo "Preferred channel $channel could not be fetched, falling back to nixos-unstable"
-            channel=nixos-unstable
-          fi
-          echo "channel=$channel" >> "$GITHUB_ENV"
-      - name: Fetching latest version of channel
-        run: |
-          echo "Fetching latest version of channel $channel"
-          # This is probably the easiest way to get Nix to output the path to a downloaded channel!
-          nixpkgs=$(nix-instantiate --find-file nixpkgs -I nixpkgs=channel:"$channel")
-          # This file only exists in channels
-          rev=$(<"$nixpkgs"/.git-revision)
-          echo "Channel $channel is at revision $rev"
-          echo "nixpkgs=$nixpkgs" >> "$GITHUB_ENV"
-          echo "rev=$rev" >> "$GITHUB_ENV"
-      - name: Fetching pre-built nixpkgs-check-by-name from the channel
-        run: |
-          echo "Fetching pre-built nixpkgs-check-by-name from channel $channel at revision $rev"
-          # Passing --max-jobs 0 makes sure that we won't build anything
-          nix-build "$nixpkgs" -A tests.nixpkgs-check-by-name --max-jobs 0
+      - name: Fetching the tool
+        run: pkgs/test/nixpkgs-check-by-name/scripts/fetch-tool.sh "$GITHUB_BASE_REF" result
       - name: Running nixpkgs-check-by-name
         run: |
-          echo "Checking whether the check succeeds on the base branch $GITHUB_BASE_REF"
-          git checkout -q "$baseSha"
-          if baseOutput=$(result/bin/nixpkgs-check-by-name . 2>&1); then
-            baseSuccess=1
-          else
-            baseSuccess=
-          fi
-          printf "%s\n" "$baseOutput"
-
-          echo "Checking whether the check would succeed after merging this pull request"
-          git checkout -q "$mergedSha"
-          if mergedOutput=$(result/bin/nixpkgs-check-by-name . 2>&1); then
-            mergedSuccess=1
-            exitCode=0
+          if result/bin/nixpkgs-check-by-name --base "$base" .; then
+            exit 0
           else
-            mergedSuccess=
-            exitCode=1
+            exitCode=$?
+            echo "To run locally: ./maintainers/scripts/check-by-name.sh $GITHUB_BASE_REF https://github.com/$GITHUB_REPOSITORY.git"
+            exit "$exitCode"
           fi
-          printf "%s\n" "$mergedOutput"
-
-          resultToEmoji() {
-            if [[ -n "$1" ]]; then
-              echo ":heavy_check_mark:"
-            else
-              echo ":x:"
-            fi
-          }
-
-          # Print a markdown summary in GitHub actions
-          {
-            echo "| Nixpkgs version | Check result |"
-            echo "| --- | --- |"
-            echo "| Latest base commit | $(resultToEmoji "$baseSuccess") |"
-            echo "| After merging this PR | $(resultToEmoji "$mergedSuccess") |"
-            echo ""
-
-            if [[ -n "$baseSuccess" ]]; then
-              if [[ -n "$mergedSuccess" ]]; then
-                echo "The check succeeds on both the base branch and after merging this PR"
-              else
-                echo "The check succeeds on the base branch, but would fail after merging this PR:"
-                echo "\`\`\`"
-                echo "$mergedOutput"
-                echo "\`\`\`"
-                echo ""
-              fi
-            else
-              if [[ -n "$mergedSuccess" ]]; then
-                echo "The check fails on the base branch, but this PR fixes it, nicely done!"
-              else
-                echo "The check fails on both the base branch and after merging this PR, unknown if only this PRs changes would satisfy the check, the base branch needs to be fixed first."
-                echo ""
-                echo "Failure on the base branch:"
-                echo "\`\`\`"
-                echo "$baseOutput"
-                echo "\`\`\`"
-                echo ""
-                echo "Failure after merging this PR:"
-                echo "\`\`\`"
-                echo "$mergedOutput"
-                echo "\`\`\`"
-                echo ""
-              fi
-            fi
-
-            echo "### Details"
-            echo "- nixpkgs-check-by-name tool:"
-            echo "  - Channel: $channel"
-            echo "  - Nixpkgs commit: [$rev](https://github.com/${GITHUB_REPOSITORY}/commit/$rev)"
-            echo "  - Store path: \`$(realpath result)\`"
-            echo "- Tested Nixpkgs:"
-            echo "  - Base branch: $GITHUB_BASE_REF"
-            echo "  - Latest base branch commit: [$baseSha](https://github.com/${GITHUB_REPOSITORY}/commit/$baseSha)"
-            echo "  - Latest PR commit: [$headSha](https://github.com/${GITHUB_REPOSITORY}/commit/$headSha)"
-            echo "  - Merge commit: [$mergedSha](https://github.com/${GITHUB_REPOSITORY}/commit/$mergedSha)"
-          } >> "$GITHUB_STEP_SUMMARY"
-
-          exit "$exitCode"

doc/build-helpers/testers.chapter.md

@@ -1,33 +1,41 @@
 # Testers {#chap-testers}
+
 This chapter describes several testing builders which are available in the `testers` namespace.
 
 ## `hasPkgConfigModules` {#tester-hasPkgConfigModules}
 
 <!-- Old anchor name so links still work -->
 []{#tester-hasPkgConfigModule}
 Checks whether a package exposes a given list of `pkg-config` modules.
-If the `moduleNames` argument is omitted, `hasPkgConfigModules` will
-use `meta.pkgConfigModules`.
+If the `moduleNames` argument is omitted, `hasPkgConfigModules` will use `meta.pkgConfigModules`.
+
+:::{.example #ex-haspkgconfigmodules-defaultvalues}
 
-Example:
+# Check that `pkg-config` modules are exposed using default values
 
 ```nix
 passthru.tests.pkg-config = testers.hasPkgConfigModules {
   package = finalAttrs.finalPackage;
-  moduleNames = [ "libfoo" ];
 };
+
+meta.pkgConfigModules = [ "libfoo" ];
 ```
 
-If the package in question has `meta.pkgConfigModules` set, it is even simpler:
+:::
+
+:::{.example #ex-haspkgconfigmodules-explicitmodules}
+
+# Check that `pkg-config` modules are exposed using explicit module names
 
 ```nix
 passthru.tests.pkg-config = testers.hasPkgConfigModules {
   package = finalAttrs.finalPackage;
+  moduleNames = [ "libfoo" ];
 };
-
-meta.pkgConfigModules = [ "libfoo" ];
 ```
 
+:::
+
 ## `testVersion` {#tester-testVersion}
 
 Checks that the output from running a command contains the specified version string in it as a whole word.
@@ -83,7 +91,18 @@ This returns a derivation with an override on the builder, with the following ef
  - Move `$out` to `$out/result`, if it exists (assuming `out` is the default output)
  - Save the build log to `$out/testBuildFailure.log` (same)
 
-Example:
+While `testBuildFailure` is designed to keep changes to the original builder's environment to a minimum, some small changes are inevitable:
+
+ - The file `$TMPDIR/testBuildFailure.log` is present. It should not be deleted.
+ - `stdout` and `stderr` are a pipe instead of a tty. This could be improved.
+ - One or two extra processes are present in the sandbox during the original builder's execution.
+ - The derivation and output hashes are different, but not unusual.
+ - The derivation includes a dependency on `buildPackages.bash` and `expect-failure.sh`, which is built to include a transitive dependency on `buildPackages.coreutils` and possibly more.
+   These are not added to `PATH` or any other environment variable, so they should be hard to observe.
+
+:::{.example #ex-testBuildFailure-showingenvironmentchanges}
+
+# Check that a build fails, and verify the changes made during build
 
 ```nix
 runCommand "example" {
@@ -100,24 +119,15 @@ runCommand "example" {
 '';
 ```
 
-While `testBuildFailure` is designed to keep changes to the original builder's
-environment to a minimum, some small changes are inevitable.
-
- - The file `$TMPDIR/testBuildFailure.log` is present. It should not be deleted.
- - `stdout` and `stderr` are a pipe instead of a tty. This could be improved.
- - One or two extra processes are present in the sandbox during the original
-   builder's execution.
- - The derivation and output hashes are different, but not unusual.
- - The derivation includes a dependency on `buildPackages.bash` and
-   `expect-failure.sh`, which is built to include a transitive dependency on
-   `buildPackages.coreutils` and possibly more. These are not added to `PATH`
-   or any other environment variable, so they should be hard to observe.
+:::
 
 ## `testEqualContents` {#tester-equalContents}
 
 Check that two paths have the same contents.
 
-Example:
+:::{.example #ex-testEqualContents-toyexample}
+
+# Check that two paths have the same contents
 
 ```nix
 testers.testEqualContents {
@@ -137,17 +147,20 @@ testers.testEqualContents {
 }
 ```
 
+:::
+
 ## `testEqualDerivation` {#tester-testEqualDerivation}
 
 Checks that two packages produce the exact same build instructions.
 
-This can be used to make sure that a certain difference of configuration,
-such as the presence of an overlay does not cause a cache miss.
+This can be used to make sure that a certain difference of configuration, such as the presence of an overlay does not cause a cache miss.
 
 When the derivations are equal, the return value is an empty file.
 Otherwise, the build log explains the difference via `nix-diff`.
 
-Example:
+:::{.example #ex-testEqualDerivation-hello}
+
+# Check that two packages produce the same derivation
 
 ```nix
 testers.testEqualDerivation
@@ -156,29 +169,28 @@ testers.testEqualDerivation
   (hello.overrideAttrs(o: { doCheck = true; }))
 ```
 
+:::
+
 ## `invalidateFetcherByDrvHash` {#tester-invalidateFetcherByDrvHash}
 
 Use the derivation hash to invalidate the output via name, for testing.
 
 Type: `(a@{ name, ... } -> Derivation) -> a -> Derivation`
 
-Normally, fixed output derivations can and should be cached by their output
-hash only, but for testing we want to re-fetch everytime the fetcher changes.
+Normally, fixed output derivations can and should be cached by their output hash only, but for testing we want to re-fetch everytime the fetcher changes.
 
-Changes to the fetcher become apparent in the drvPath, which is a hash of
-how to fetch, rather than a fixed store path.
-By inserting this hash into the name, we can make sure to re-run the fetcher
-every time the fetcher changes.
+Changes to the fetcher become apparent in the drvPath, which is a hash of how to fetch, rather than a fixed store path.
+By inserting this hash into the name, we can make sure to re-run the fetcher every time the fetcher changes.
 
-This relies on the assumption that Nix isn't clever enough to reuse its
-database of local store contents to optimize fetching.
+This relies on the assumption that Nix isn't clever enough to reuse its database of local store contents to optimize fetching.
 
-You might notice that the "salted" name derives from the normal invocation,
-not the final derivation. `invalidateFetcherByDrvHash` has to invoke the fetcher
-function twice: once to get a derivation hash, and again to produce the final
-fixed output derivation.
+You might notice that the "salted" name derives from the normal invocation, not the final derivation.
+`invalidateFetcherByDrvHash` has to invoke the fetcher function twice:
+once to get a derivation hash, and again to produce the final fixed output derivation.
 
-Example:
+:::{.example #ex-invalidateFetcherByDrvHash-nix}
+
+# Prevent nix from reusing the output of a fetcher
 
 ```nix
 tests.fetchgit = testers.invalidateFetcherByDrvHash fetchgit {
@@ -189,13 +201,17 @@ tests.fetchgit = testers.invalidateFetcherByDrvHash fetchgit {
 };
 ```
 
+:::
+
 ## `runNixOSTest` {#tester-runNixOSTest}
 
 A helper function that behaves exactly like the NixOS `runTest`, except it also assigns this Nixpkgs package set as the `pkgs` of the test and makes the `nixpkgs.*` options read-only.
 
 If your test is part of the Nixpkgs repository, or if you need a more general entrypoint, see ["Calling a test" in the NixOS manual](https://nixos.org/manual/nixos/stable/index.html#sec-calling-nixos-tests).
 
-Example:
+:::{.example #ex-runNixOSTest-hello}
+
+# Run a NixOS test using `runNixOSTest`
 
 ```nix
 pkgs.testers.runNixOSTest ({ lib, ... }: {
@@ -209,19 +225,17 @@ pkgs.testers.runNixOSTest ({ lib, ... }: {
 })
 ```
 
+:::
+
 ## `nixosTest` {#tester-nixosTest}
 
 Run a NixOS VM network test using this evaluation of Nixpkgs.
 
 NOTE: This function is primarily for external use. NixOS itself uses `make-test-python.nix` directly. Packages defined in Nixpkgs [reuse NixOS tests via `nixosTests`, plural](#ssec-nixos-tests-linking).
 
-It is mostly equivalent to the function `import ./make-test-python.nix` from the
-[NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests),
-except that the current application of Nixpkgs (`pkgs`) will be used, instead of
-letting NixOS invoke Nixpkgs anew.
+It is mostly equivalent to the function `import ./make-test-python.nix` from the [NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), except that the current application of Nixpkgs (`pkgs`) will be used, instead of letting NixOS invoke Nixpkgs anew.
 
-If a test machine needs to set NixOS options under `nixpkgs`, it must set only the
-`nixpkgs.pkgs` option.
+If a test machine needs to set NixOS options under `nixpkgs`, it must set only the `nixpkgs.pkgs` option.
 
 ### Parameter {#tester-nixosTest-parameter}