diff --git a/BUILD.md b/BUILD.md index 8ef5e07ecc..6bde1b70f1 100644 --- a/BUILD.md +++ b/BUILD.md @@ -50,7 +50,9 @@ Once your [development environment](./docs/build/environment.md) is ready, set C That installs our [`global.conf`](./conan/global.conf), our Conan [profiles](./conan/profiles), and the `xrplf` remote that hosts some of our dependencies. It honours `CONAN_HOME` and never deletes an existing Conan home, so it is safe to re-run — it only overwrites the files it manages. -> [!TIP] In the [Nix development shell](./docs/build/nix.md#conan-configuration) this is already done for you: the script runs on entry. + +> [!TIP] +> In the [Nix development shell](./docs/build/nix.md#conan-configuration) this is already done for you: the script runs on entry. You can inspect the resulting profile with `conan profile show`. If it is not suitable for your environment, create a custom profile and pass it to Conan — see [Advanced Conan configuration](./docs/build/advanced_conan.md). @@ -185,7 +187,9 @@ Prerequisites for the coverage report: - `gcov` for GCC or `llvm-cov` for Clang, usually installed with the compiler - `Debug` build type -> [!NOTE] Clang coverage is not available in the [Nix development shell](./docs/build/nix.md#building-xrpld-in-the-nix-shell): its `clang` shells do not ship `llvm-cov`. Use a `gcc` shell instead (`.#gcc`, or `.#gcc-plain` on Linux), which provides a `gcov` matching its compiler. + +> [!NOTE] +> Clang coverage is not available in the [Nix development shell](./docs/build/nix.md#building-xrpld-in-the-nix-shell): its `clang` shells do not ship `llvm-cov`. Use a `gcc` shell instead (`.#gcc`, or `.#gcc-plain` on Linux), which provides a `gcov` matching its compiler. A coverage report is created when the following steps are completed, in order: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5dc1d067ff..a7aba77446 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,7 +180,9 @@ pre-commit run clang-format --all-files You can also format individual files in place by running `clang-format -i ...` from any directory within this project. -> [!NOTE] This uses whatever `clang-format` version is installed locally, which may differ from the pinned version used by `pre-commit` and CI, so the results can vary. + +> [!NOTE] +> This uses whatever `clang-format` version is installed locally, which may differ from the pinned version used by `pre-commit` and CI, so the results can vary. There is a Continuous Integration job that runs clang-format on pull requests. If the code doesn't comply, a patch file that corrects auto-fixable formatting issues is generated. diff --git a/docs/build/advanced_conan.md b/docs/build/advanced_conan.md index 6cafc7d2aa..c28165b83c 100644 --- a/docs/build/advanced_conan.md +++ b/docs/build/advanced_conan.md @@ -54,7 +54,9 @@ cd ../../ In the case we switch to a newer version of a dependency that still requires a patch or add a new dependency, it will be necessary for you to pull in the changes and re-export the updated dependencies with the newer version. However, if we switch to a newer version that no longer requires a patch, no action is required on your part, as the new recipe will be automatically pulled from the official Conan Center. -> [!NOTE] You might need to add `--lockfile=""` to your `conan install` command to avoid automatic use of the existing `conan.lock` file when you run `conan export` manually on your machine + +> [!NOTE] +> You might need to add `--lockfile=""` to your `conan install` command to avoid automatic use of the existing `conan.lock` file when you run `conan export` manually on your machine > > This is not recommended though, as you might end up using different revisions of recipes. diff --git a/docs/build/nix.md b/docs/build/nix.md index 49f355dbb8..2554939b9e 100644 --- a/docs/build/nix.md +++ b/docs/build/nix.md @@ -41,7 +41,9 @@ The first time you run this command, it will take a few minutes to download and - **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 the Nix cache for macOS, so it is built from source the first time you enter the shell, which makes the initial setup slower (this is handled automatically; see [`nix/devshell.nix`](../../nix/devshell.nix)). -> [!TIP] To avoid typing `--experimental-features 'nix-command flakes'` every time, you can permanently enable flakes by creating `~/.config/nix/nix.conf`: + +> [!TIP] +> To avoid typing `--experimental-features 'nix-command flakes'` every time, you can permanently enable flakes by creating `~/.config/nix/nix.conf`: > > ```bash > mkdir -p ~/.config/nix @@ -50,7 +52,9 @@ The first time you run this command, it will take a few minutes to download and > > After this, you can simply use `nix develop` instead. -> [!NOTE] The examples below assume you've enabled flakes in your config. If you haven't, add `--experimental-features 'nix-command flakes'` after each `nix` command. + +> [!NOTE] +> The examples below assume you've enabled flakes in your config. If you haven't, add `--experimental-features 'nix-command flakes'` after each `nix` command. ### Choosing a different compiler @@ -94,7 +98,9 @@ nix develop -c fish nix develop -c "$SHELL" ``` -> [!WARNING] Your shell's interactive startup files (e.g. `config.fish`, `.zshrc`) may prepend other directories — most commonly Homebrew — to `$PATH`, which can shadow the tools provided by the Nix shell. After entering, verify that tools resolve into the Nix store: + +> [!WARNING] +> Your shell's interactive startup files (e.g. `config.fish`, `.zshrc`) may prepend other directories — most commonly Homebrew — to `$PATH`, which can shadow the tools provided by the Nix shell. After entering, verify that tools resolve into the Nix store: > > ```bash > command -v cmake # should print a /nix/store/... path @@ -128,7 +134,9 @@ A Conan package ID records the compiler and its major version, but nothing about That is safe as long as no cached artifact resolves a `/nix/store` path at run time, because store paths change on every update and the old ones disappear with `nix-collect-garbage`. With the `clang` toolchain macOS CI and the dev shell use, they do not: it links against `/usr/lib/libc++` and `/usr/lib/libSystem`, and store paths reach the `.a` files only through debug info, which nothing resolves at link or run time. -> [!WARNING] This does not hold for `nix develop .#gcc` on macOS. There is no system libstdc++, so GCC links its own from the store and every binary keeps a `/nix/store` reference. That shell is fine for tooling, but it is not a build configuration CI covers, and no dependency binaries are published for it. + +> [!WARNING] +> This does not hold for `nix develop .#gcc` on macOS. There is no system libstdc++, so GCC links its own from the store and every binary keeps a `/nix/store` reference. That shell is fine for tooling, but it is not a build configuration CI covers, and no dependency binaries are published for it. This is checked rather than assumed. [`bin/check-nix-store-refs.sh`](../../bin/check-nix-store-refs.sh) takes one file or directory and fails if a binary under it resolves a store path at run time. CI runs it over the build output and the Conan cache, and again in the upload job before anything is published. You can run it yourself: @@ -162,7 +170,9 @@ The repository already ships an `.envrc` at its root that activates the Nix flak 1. [Install direnv](https://direnv.net/docs/installation.html) and [hook it into your shell](https://direnv.net/docs/hook.html) (bash, zsh, fish, …). Installing [nix-direnv](https://github.com/nix-community/nix-direnv) as well is recommended: it caches the shell so that activation is near-instant after the first run. 2. Run `direnv allow` once in the repository root. direnv will then load (and reload) the Nix development shell automatically whenever you enter the directory. -> [!NOTE] direnv only caches the `.direnv` directory (already listed in `.gitignore`); no other repository files are affected. + +> [!NOTE] +> direnv only caches the `.direnv` directory (already listed in `.gitignore`); no other repository files are affected. ## Updating `flake.lock` file diff --git a/docs/build/nix_troubleshooting.md b/docs/build/nix_troubleshooting.md index 59fa44eb6e..6e3404fe95 100644 --- a/docs/build/nix_troubleshooting.md +++ b/docs/build/nix_troubleshooting.md @@ -60,7 +60,9 @@ EOF The scripts guard against double-sourcing via `__ETC_PROFILE_NIX_SOURCED`, so this is safe even if a system-wide hook is later restored. -> [!NOTE] `/etc/zshrc` and `~/.zshrc` are only read by **interactive** zsh. If the snippet is present but `zsh -c '…'`, a script, or an IDE terminal still can't find `nix`, that shell is non-interactive — put the snippet in `~/.zshenv` instead. + +> [!NOTE] +> `/etc/zshrc` and `~/.zshrc` are only read by **interactive** zsh. If the snippet is present but `zsh -c '…'`, a script, or an IDE terminal still can't find `nix`, that shell is non-interactive — put the snippet in `~/.zshenv` instead. ## Git worktrees @@ -75,7 +77,9 @@ error: then your Nix is linked against a libgit2 older than **1.9.4**. Git 2.48+ writes the `extensions.relativeWorktrees` config entry when a worktree is created with relative paths (`git worktree add --relative-paths`, or with `worktree.useRelativePaths=true`), and older libgit2 versions refuse to open a repository that uses it. Nix uses libgit2 to read the flake, so evaluation fails. -> [!IMPORTANT] This entry is written to the **shared** repository config, so once any relative worktree exists, `nix develop` fails in the main checkout too — not just inside the worktree. + +> [!IMPORTANT] +> This entry is written to the **shared** repository config, so once any relative worktree exists, `nix develop` fails in the main checkout too — not just inside the worktree. ### Workarounds @@ -93,7 +97,9 @@ The fix is in [libgit2 1.9.4](https://github.com/libgit2/libgit2/releases/tag/v1 nix-store -qR "$(readlink -f "$(command -v nix)")" | grep libgit2 ``` -> [!WARNING] `nix upgrade-nix` does **not** help yet. It installs the build from the official [`nix-fallback-paths`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/installer/tools/nix-fallback-paths.nix), which is still linked against libgit2 `1.9.2` — there is no new upstream Nix release with the fix. (On some systems that build is even the exact store path you already have, making the upgrade a no-op.) + +> [!WARNING] +> `nix upgrade-nix` does **not** help yet. It installs the build from the official [`nix-fallback-paths`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/installer/tools/nix-fallback-paths.nix), which is still linked against libgit2 `1.9.2` — there is no new upstream Nix release with the fix. (On some systems that build is even the exact store path you already have, making the upgrade a no-op.) nixpkgs has already rebuilt Nix against the fixed libgit2 (e.g. `nix-2.34.7+1`), so the cleanest path is to reinstall Nix using your usual installation method once it picks up that rebuild, then re-run the `grep libgit2` check above to confirm it reports `1.9.4` or newer. diff --git a/docs/build/sanitizers.md b/docs/build/sanitizers.md index efc3f03bb9..873a503a10 100644 --- a/docs/build/sanitizers.md +++ b/docs/build/sanitizers.md @@ -2,7 +2,9 @@ This document explains how to properly configure and run sanitizers (`AddressSanitizer`, `UndefinedBehaviorSanitizer`, `ThreadSanitizer`) with the xrpld project. Corresponding suppression files are located in the `sanitizers/suppressions` directory. -> [!CAUTION] Do not mix Address and Thread sanitizers - they are incompatible. Also, we don't yet support MSVC sanitizers, so this is only for Clang/GCC builds. + +> [!CAUTION] +> Do not mix Address and Thread sanitizers - they are incompatible. Also, we don't yet support MSVC sanitizers, so this is only for Clang/GCC builds. - [Sanitizer Configuration for Xrpld](#sanitizer-configuration-for-xrpld) - [Building with Sanitizers](#building-with-sanitizers) @@ -35,7 +37,9 @@ Follow the same instructions as mentioned in [BUILD.md](../../BUILD.md) but with 2. Set the `SANITIZERS` environment variable before calling `conan install`. Only set it once. Example: `export SANITIZERS=address,undefinedbehavior` 3. Use `--profile:all sanitizers` with Conan to build dependencies with sanitizer instrumentation. - > [!NOTE] Building with sanitizer-instrumented dependencies is slower but produces fewer false positives. + + > [!NOTE] + > Building with sanitizer-instrumented dependencies is slower but produces fewer false positives. 4. Set `ASAN_OPTIONS`, `LSAN_OPTIONS`, `UBSAN_OPTIONS` and `TSAN_OPTIONS` environment variables to configure sanitizer behavior when running executables. [More details below](#running-tests-with-sanitizers). diff --git a/docs/install-legacy.md b/docs/install-legacy.md index 0a3bff4261..0c0e273f79 100644 --- a/docs/install-legacy.md +++ b/docs/install-legacy.md @@ -1,6 +1,8 @@ # Installing xrpld 3.3.0 and earlier -> [!IMPORTANT] These instructions apply to xrpld 3.3.0 and earlier, published to repos.ripple.com. For later releases see [install.md](./install.md). + +> [!IMPORTANT] +> These instructions apply to xrpld 3.3.0 and earlier, published to repos.ripple.com. For later releases see [install.md](./install.md). This document contains instructions for installing xrpld. The APT package manager is common on Debian-based Linux distributions like Ubuntu, while the YUM package manager is common on Red Hat-based Linux distributions like CentOS. Installing from source is an option for all platforms, and the only supported option for installing custom builds. diff --git a/docs/install.md b/docs/install.md index 98ff956259..5f9fcc561c 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,6 +1,8 @@ # Installing xrpld -> [!NOTE] These instructions apply to packages published from 2026-08-19 onwards. For xrpld 3.3.0 and earlier see [install-legacy.md](./install-legacy.md). + +> [!NOTE] +> These instructions apply to packages published from 2026-08-19 onwards. For xrpld 3.3.0 and earlier see [install-legacy.md](./install-legacy.md). `xrpld` is published as DEB and RPM packages for 64-bit x86 Linux. Use APT on Debian-based distributions such as Debian and Ubuntu, and YUM on Red Hat-based distributions such as RHEL, AlmaLinux, and Rocky Linux. To build from source instead, see [BUILD.md](../BUILD.md). @@ -17,7 +19,9 @@ See [Publishing packages](../package/README.md#publishing-packages) for how chan The instructions below use `stable`. To follow another channel, replace `stable` with its name wherever it appears in the repository configuration. -> [!WARNING] Channels other than `stable` may be broken at any time. Do not use them for production servers. + +> [!WARNING] +> Channels other than `stable` may be broken at any time. Do not use them for production servers. ## Install the xrpld package