Merge pull request #12408 from obsidiansystems/debugging-instructions

More debugging documentation

doc/manual/source/development/building.md

@@ -167,11 +167,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.
+Here's how to do that:
-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
+1. Instruct Nixpkgs's infra where we want Meson to put its build directory
+
+   ```bash
+   mesonBuildDir=build-my-variant-name
+   ```
 
 1. Configure as usual
 
@@ -179,24 +181,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:

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.
@@ -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