From 49c037493da73292287947bba056284de1068fd2 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 12 Dec 2025 15:23:58 +0000 Subject: [PATCH] updated docs Signed-off-by: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> --- BUILD.md | 49 +++++++++++-------- docs/build/sanitizers.md | 103 +++++++++++++++++++++++++-------------- 2 files changed, 95 insertions(+), 57 deletions(-) diff --git a/BUILD.md b/BUILD.md index 7be6c1d3d7..1987d0ef53 100644 --- a/BUILD.md +++ b/BUILD.md @@ -1,5 +1,5 @@ -| :warning: **WARNING** :warning: -|---| +| :warning: **WARNING** :warning: | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | These instructions assume you have a C++ development environment ready with Git, Python, Conan, CMake, and a C++ compiler. For help setting one up on Linux, macOS, or Windows, [see this guide](./docs/build/environment.md). | > These instructions also assume a basic familiarity with Conan and CMake. @@ -388,19 +388,15 @@ tools.build:cxxflags=['-DBOOST_ASIO_DISABLE_CONCEPTS'] conan install .. --output-folder . --build missing --settings build_type=Debug ``` - If you would like to activate `asan`(`Address`) or `tsan`(`Thread`) or `ubsan`(`UndefinedBehavior`) for the build, - declare an environment variable as follows(with values: `Address`, `Thread`, `UndefinedBehavior`) and use the `sanitizers` - profile in the `conan install` command. + **Sanitizers:** To build dependencies with sanitizer instrumentation, set the + `SANITIZER` environment variable and use the `sanitizers` profile: ``` - SANITIZERS=Address conan install .. --output-folder . --profile:all sanitizers --build missing --settings build_type=Debug - # or if you want asan+ubsan - SANITIZERS=Address,UndefinedBehavior conan install .. --output-folder . --profile:all sanitizers --build missing --settings build_type=Debug + SANITIZER=Address,UndefinedBehavior conan install .. --output-folder . --profile:all sanitizers --build missing --settings build_type=Debug ``` - Note: Do not mix Address and Thread, that's incompatible. - - More details here: [sanitizers](./docs/build/sanitizers.md) + Note: Do not mix Address and Thread sanitizers - they are incompatible. + See [sanitizers documentation](./docs/build/sanitizers.md) for more details. To build Debug, in the next step, be sure to set `-DCMAKE_BUILD_TYPE=Debug` @@ -438,6 +434,15 @@ tools.build:cxxflags=['-DBOOST_ASIO_DISABLE_CONCEPTS'] **Note:** You can pass build options for `xrpld` in this step. + **Sanitizers:** To enable sanitizers (Address, Thread, UndefinedBehavior), + set the `SANITIZER` environment variable when running CMake: + + ``` + SANITIZER=Address,UndefinedBehavior cmake -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Debug -Dxrpld=ON -Dtests=ON .. + ``` + + See [sanitizers documentation](./docs/build/sanitizers.md) for more details. + 4. Build `xrpld`. For a single-configuration generator, it will build whatever configuration @@ -534,16 +539,18 @@ stored inside the build directory, as either of: ## Options -| Option | Default Value | Description | -| ---------- | ------------- | ------------------------------------------------------------------ | -| `assert` | OFF | Enable assertions. | -| `coverage` | OFF | Prepare the coverage report. | -| `san` | N/A | Enable a sanitizer with Clang. Choices are `thread` and `address`. | -| `tests` | OFF | Build tests. | -| `unity` | OFF | Configure a unity build. | -| `xrpld` | OFF | Build the xrpld application, and not just the libxrpl library. | -| `werr` | OFF | Treat compilation warnings as errors | -| `wextra` | OFF | Enable additional compilation warnings | +| Option | Default Value | Description | +| ---------- | ------------- | -------------------------------------------------------------- | +| `assert` | OFF | Enable assertions. | +| `coverage` | OFF | Prepare the coverage report. | +| `tests` | OFF | Build tests. | +| `unity` | OFF | Configure a unity build. | +| `xrpld` | OFF | Build the xrpld application, and not just the libxrpl library. | +| `werr` | OFF | Treat compilation warnings as errors | +| `wextra` | OFF | Enable additional compilation warnings | + +To enable sanitizers, set the `SANITIZER` environment variable when running CMake. +See [sanitizers documentation](./docs/build/sanitizers.md) for details. [Unity builds][5] may be faster for the first build (at the cost of much more memory) since they concatenate sources into fewer diff --git a/docs/build/sanitizers.md b/docs/build/sanitizers.md index 1ce79ed62e..43d48fa648 100644 --- a/docs/build/sanitizers.md +++ b/docs/build/sanitizers.md @@ -5,75 +5,106 @@ Corresponding suppression files are located in the `sanitizers/suppressions` dir - [Sanitizer Configuration for Rippled](#sanitizer-configuration-for-rippled) - [Building with Sanitizers](#building-with-sanitizers) - - [AddressSanitizer (ASan) + UndefinedBehaviorSanitizer (UBSan)](#addresssanitizer-asan--undefinedbehaviorsanitizer-ubsan) - - [ThreadSanitizer (TSan) + UndefinedBehaviorSanitizer (UBSan)](#threadsanitizer-tsan--undefinedbehaviorsanitizer-ubsan) - - [Just UndefinedBehaviorSanitizer (UBSan)](#just-undefinedbehaviorsanitizer-ubsan) -- [Running Tests with Sanitizers](#running-tests-with-sanitizers) - - [AddressSanitizer (ASan)](#addresssanitizer-asan) - - [ThreadSanitizer (TSan)](#threadsanitizer-tsan) - - [LeakSanitizer (LSan)](#leaksanitizer-lsan) -- [Suppression Files](#suppression-files) - - [asan.supp](#asansupp) - - [lsan.supp](#lsansupp) - - [ubsan.supp](#ubsansupp) - - [tsan.supp](#tsansupp) - - [Ignorelist](#sanitizer-ignorelisttxt) -- [Known False Positives](#known-false-positives) -- [References](#references) + - [Summary](#summary) + - [Build steps:](#build-steps) + - [Install dependencies](#install-dependencies) + - [AddressSanitizer (ASan) + UndefinedBehaviorSanitizer (UBSan)](#addresssanitizer-asan--undefinedbehaviorsanitizer-ubsan) + - [ThreadSanitizer (TSan) + UndefinedBehaviorSanitizer (UBSan)](#threadsanitizer-tsan--undefinedbehaviorsanitizer-ubsan) + - [Just AddressSanitizer (ASan)](#just-addresssanitizer-asan) + - [Just UndefinedBehaviorSanitizer (UBSan)](#just-undefinedbehaviorsanitizer-ubsan) + - [Build](#build) + - [Running Tests with Sanitizers](#running-tests-with-sanitizers) + - [AddressSanitizer (ASan)](#addresssanitizer-asan) + - [ThreadSanitizer (TSan) + UndefinedBehaviorSanitizer (UBSan)](#threadsanitizer-tsan--undefinedbehaviorsanitizer-ubsan-1) + - [LeakSanitizer (LSan)](#leaksanitizer-lsan) + - [Suppression Files](#suppression-files) + - [`asan.supp`](#asansupp) + - [`lsan.supp`](#lsansupp) + - [`ubsan.supp`](#ubsansupp) + - [`tsan.supp`](#tsansupp) + - [`sanitizer-ignorelist.txt`](#sanitizer-ignorelisttxt) + - [Troubleshooting](#troubleshooting) + - ["ASan is ignoring requested \_\_asan_handle_no_return" warnings](#asan-is-ignoring-requested-__asan_handle_no_return-warnings) + - [Sanitizer Mismatch Errors](#sanitizer-mismatch-errors) + - [References](#references) ## Building with Sanitizers ### Summary -Follow the same instructions as mentioned in [BUILD.md](../../BUILD.md) but with following changes: +Follow the same instructions as mentioned in [BUILD.md](../../BUILD.md) but with the following changes: -1. Make sure you have clean build directory. -2. Use `--profile sanitizers` to configure build options to include sanitizer flags. [sanitizes](../../conan/profiles/sanitizers) profile contains settings for all sanitizers. -3. Set `ASAN_OPTIONS`, `LSAN_OPTIONS` ,`UBSAN_OPTIONS` and `TSAN_OPTIONS` environment variables to configure sanitizer behavior when running executables. +1. Make sure you have a clean build directory. +2. Set the `SANITIZER` environment variable when running CMake to enable sanitizers. +3. Optionally use `--profile sanitizers` with Conan to build dependencies with sanitizer instrumentation. +4. Set `ASAN_OPTIONS`, `LSAN_OPTIONS`, `UBSAN_OPTIONS` and `TSAN_OPTIONS` environment variables to configure sanitizer behavior when running executables. --- ### Build steps: ```bash - cd /path/to/rippled - rm -rf .build - mkdir .build - cd .build +cd /path/to/rippled +rm -rf .build +mkdir .build +cd .build +``` + +#### Install dependencies + +The `SANITIZER` environment variable is used by both Conan and CMake. + +```bash +# Standard build (without instrumenting dependencies) +SANITIZER=Address,UndefinedBehavior conan install .. --output-folder . --build missing --settings build_type=Debug + +# Or with sanitizer-instrumented dependencies (takes longer but fewer false positives) +SANITIZER=Address,UndefinedBehavior conan install .. --output-folder . --profile:all sanitizers --build missing --settings build_type=Debug ``` #### AddressSanitizer (ASan) + UndefinedBehaviorSanitizer (UBSan) -Build with AddressSanitizer+UndefinedBehavior sanitizers (or you can choose just one of them). +Set the `SANITIZER` environment variable when running CMake: ```bash -SANITIZERS=Address,UndefinedBehavior conan install .. --output-folder . --profile sanitizers --build missing --settings build_type=Release +SANITIZER=Address,UndefinedBehavior cmake .. -G Ninja \ + -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \ + -DCMAKE_BUILD_TYPE=Debug \ + -Dtests=ON -Dxrpld=ON ``` #### ThreadSanitizer (TSan) + UndefinedBehaviorSanitizer (UBSan) ```bash -# Build dependencies with Thread sanitizer -SANITIZERS=Thread,UndefinedBehavior conan install .. --output-folder . --profile sanitizers --build missing --settings build_type=Release +SANITIZER=Thread,UndefinedBehavior cmake .. -G Ninja \ + -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \ + -DCMAKE_BUILD_TYPE=Debug \ + -Dtests=ON -Dxrpld=ON +``` + +#### Just AddressSanitizer (ASan) + +```bash +SANITIZER=Address cmake .. -G Ninja \ + -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \ + -DCMAKE_BUILD_TYPE=Debug \ + -Dtests=ON -Dxrpld=ON ``` #### Just UndefinedBehaviorSanitizer (UBSan) ```bash -# Build dependencies with Thread sanitizer -SANITIZERS=UndefinedBehavior conan install .. --output-folder . --profile sanitizers --build missing --settings build_type=Release +SANITIZER=UndefinedBehavior cmake .. -G Ninja \ + -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \ + -DCMAKE_BUILD_TYPE=Debug \ + -Dtests=ON -Dxrpld=ON ``` -Use `--profile:all sanitizers` if you would like to build all dependencies and libraries (boost etc.) with sanitizers. This might take long time but you won't see some false-positives on sanitizer reports since whole binary will be instrumented. +**Note:** Do not mix Address and Thread sanitizers - they are incompatible. -To build with Thread+UndefinedBehavior Sanitizer, replace `SANITIZERS=Address` with `SANITIZERS=Thread`. - -# Configure CMake +#### Build ```bash -cmake .. -G Ninja -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake -Dunity=ON -Dtests=ON -Dxrpld=ON - -# Build cmake --build . --parallel 4 ```