Merge branch 'pratik/otel-phase5-docs-deployment' into pratik/otel-phase6-statsd

docs/build/nix.md

@@ -38,8 +38,10 @@ The first time you run this command, it will take a few minutes to download and
 
 ### Platform notes
 
-- **Linux**: `nix develop` gives you a shell with all the tooling necessary to
-  develop xrpld and with GCC 15.2 (also provided by Nix). There are no caveats.
+- **Linux**: `nix develop` gives you a shell with all the tooling necessary to develop xrpld
+  and with the same GCC/glibc toolchain that Nix builds for CI.
+  See [Choosing a different compiler](#choosing-a-different-compiler)
+  for the custom-vs-plain toolchain trade-off.
 - **macOS**: `nix develop` gives you a full environment too, with Clang (and
   every other tool, including Conan) provided by Nix. To use your system-wide
   Apple Clang instead, enter `nix develop .#apple-clang`. Conan has no binary in
@@ -63,8 +65,16 @@ The first time you run this command, it will take a few minutes to download and
 ### Choosing a different compiler
 
 A compiler can be chosen by providing its name with the `.#` prefix, e.g. `nix develop .#clang`.
-The `.#gcc` and `.#clang` shells provide the same GCC and Clang versions used in CI
-(pinned in [`nix/packages.nix`](../../nix/packages.nix)).
+
+On Linux, `.#gcc` and `.#clang` provide the exact toolchain CI uses:
+the compiler (pinned in [`nix/packages.nix`](../../nix/packages.nix))
+rebuilt against the pinned custom glibc (see [`nix/compilers.nix`](../../nix/compilers.nix)).
+Building that toolchain the first time is slow unless it is fetched from a Nix binary cache.
+If you don't need the custom glibc, the Linux-only `.#gcc-plain` and `.#clang-plain`
+give you the stock nixpkgs compilers of the same versions.
+On macOS there is no custom glibc, so `.#gcc` and `.#clang` are already the plain nixpkgs toolchain,
+and the `-plain` variants do not exist.
+
 Use `nix flake show` to see all the available development shells.
 
 Use `nix develop .#no-compiler` to use the compiler from your system.
@@ -72,14 +82,18 @@ Use `nix develop .#no-compiler` to use the compiler from your system.
 ### Example Usage
 
 ```bash
-# Use GCC (same version as CI)
+# Use GCC — same toolchain as CI (custom glibc on Linux)
 nix develop .#gcc
 
-# Use Clang (same version as CI)
+# Use Clang — same toolchain as CI (custom glibc on Linux)
 nix develop .#clang
 
 # Use default for your platform
 nix develop
+
+# Stock nixpkgs GCC/Clang, Linux only — skips the custom-glibc build, but does not match CI
+nix develop .#gcc-plain
+nix develop .#clang-plain
 ```
 
 ### Using a different shell
@@ -110,6 +124,10 @@ nix develop -c "$SHELL"
 
 Once inside the Nix development shell, follow the standard [build instructions](../../BUILD.md#steps). The Nix shell provides all necessary tools (CMake, Ninja, Conan, etc.).
 
+Coverage builds (`-Dcoverage=ON`) work in the `gcc` shell (and `gcc-plain` on Linux):
+each ships a `gcov` matching its compiler, since Nix's cc-wrapper does not expose one.
+The `clang` shells do not include `llvm-cov`, so use a `gcc` shell for coverage.
+
 ## Automatic Activation with direnv
 
 [direnv](https://direnv.net/) or [nix-direnv](https://github.com/nix-community/nix-direnv) can automatically activate the Nix development shell when you enter the repository directory.
@@ -136,6 +154,14 @@ conan install .. --output-folder . --build '*' --settings build_type=Release
 
 To update `flake.lock` to the latest revision use `nix flake update` command.
 
+## Tooling snapshots
+
+The tool versions in each Nix environment are recorded in
+[`nix/check-tools/`](../../nix/check-tools) and verified by CI. If you change the
+environment (bump the CI image tag, update `flake.lock`, or edit the tool list in
+`bin/check-tools.sh`), CI fails until you regenerate and commit the affected
+snapshot — see [`nix/check-tools/README.md`](../../nix/check-tools/README.md).
+
 ## Troubleshooting
 
 See [Troubleshooting Nix problems](./nix_troubleshooting.md) for common issues,