Tagging release 2.27.1

-----BEGIN PGP SIGNATURE-----
 
 iQFHBAABCAAxFiEEtUHVUwEnDgvPFcpdgXC0cm1xmN4FAmfheacTHGVkb2xzdHJh
 QGdtYWlsLmNvbQAKCRCBcLRybXGY3kt2B/4tQvs6iDXA12d409ClHbVQjr1d0FLP
 rv8RxZ7Z4+Jaw8r2ra/I+gpr9juI5ULyEJWqfES72hTvbYPjH1Grsrrjak1tx57E
 +STs21oEPojE8LXsFH1oZamGPPIIpyQdxCvTgZs1N6cqUfCRQ3Jx97X6E6SIGJDR
 VqBM4ruSXCY57yT36HqwYydTkxzZHiNP5wwABGfSb7u9pYW5x3r8W7+fQ3udTnCw
 kCRhA5vnfxIQSlxu4j7dJqSCGzOIPnhYB19bXDV4aPhl4sn3pkBCdMZxPBlCWSwx
 it0ngMITf+TeiMpVl2TtvMBOHtlGrbhusbyKcsqzFYULGyGOC9ngTAY3
 =/JzB
 -----END PGP SIGNATURE-----

Merge tag '2.27.1' into detsys-main

Tagging release 2.27.1

doc/manual/source/development/building.md

@@ -11,7 +11,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**
@@ -93,11 +93,13 @@ 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. Instruct Nixpkgs's infra where we want Meson to put its build directory
+
+   ```bash
+   mesonBuildDir=build-my-variant-name
+   ```
 
 1. Configure as usual
 
@@ -105,24 +107,12 @@ Here's how to do that
    configurePhase
    ```
 
-2. Rename the build directory
-
-   ```bash
-   cd .. # since `configurePhase` cd'd inside
-   mv build build-linux # or whatever name we want
-   cd build-linux
-   ```
-
 3. Build as usual
 
    ```bash
    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:
@@ -179,7 +169,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**
 >
@@ -195,6 +186,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:
 
 ```
@@ -209,3 +202,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"
+        ],
+      },
+    },
+  },
+}
+```

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:

doc/manual/source/development/testing.md

@@ -87,7 +87,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 +99,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 +164,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 +233,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