debug-asan-build
Build and test this repo with the CMake preset debug-asan (AddressSanitizer). Use when asked how to configure, build, run, or test with ASAN/debug builds in this project.
When & Why to Use This Skill
This Claude skill streamlines the process of identifying and resolving memory safety issues in C++ projects using CMake and AddressSanitizer (ASAN). It provides a comprehensive workflow for configuring, building, and executing tests with the 'debug-asan' preset, helping developers catch critical bugs like buffer overflows and memory leaks early in the development cycle.
Use Cases
- Case 1: Detecting memory-related vulnerabilities such as use-after-free, heap buffer overflows, and memory leaks during the build and test phase.
- Case 2: Standardizing the build environment across a team by using predefined CMake presets for AddressSanitizer instrumentation.
- Case 3: Running automated regression tests via CTest with memory sanitization enabled to ensure code quality and stability.
- Case 4: Executing complex end-to-end (E2E) test harnesses using Python and 'uv' to validate system behavior under debug conditions.
| name | debug-asan-build |
|---|---|
| description | Build and test this repo with the CMake preset debug-asan (AddressSanitizer). Use when asked how to configure, build, run, or test with ASAN/debug builds in this project. |
Debug ASAN Build
Configure
- Run:
cmake --preset debug-asan
- This preset inherits the default binary dir:
build/and setsENABLE_ASAN=ON.
Build
- Build everything:
cmake --build --preset debug-asan
- Build a specific target:
cmake --build --preset debug-asan --target <target>
- Many app targets live under
debug-asan/. Use the app target name as the build target.
Run
- Preferred binary path pattern:
./build/debug-asan/<target>/<target>_debug
- Example:
./build/debug-asan/cert_ctrl_debug
Test
ctest --test-dir build/debug-asanRun all tests (with failures shown):ctest --test-dir build/debug-asan --output-on-failureList all discovered tests:ctest --test-dir build/debug-asan -NRun a subset by regex:ctest --test-dir build/debug-asan -R <regex> --output-on-failure
Notes:
CTest filters by registered test names (GoogleTest suite/case), not by the test executable name.
For example, the test_websocket_client executable registers tests like WebsocketClientIntegrationTest.*, so this works:
ctest --test-dir build/debug-asan -R WebsocketClientIntegrationTest --output-on-failure- Run a single gtest binary:
Python (Harnesses / E2E)
Some long-running quality checks are implemented as small Python harnesses (e.g. websocket end-to-end drivers under tests/e2e/).
On some minimal Linux images, python3 -m venv or python3 -m pip may not be available by default. Prefer using uv for Python-related tasks.
- Check uv:
uv --version
- Run a one-off script with ephemeral deps (no venv needed):
uv run --with websockets>=12,<14 python tests/e2e/ws_e2e_harness.py --bin ./build/debug-asan/cert_ctrl_debug
If uv is not installed, install it via your standard tooling (for example, your distro package manager or the upstream installer), then rerun the command above.
ASAN Notes
- The preset already sets
ASAN_OPTIONS=allocator_may_return_null=1during configure. - If you need to override runtime ASAN options, export
ASAN_OPTIONSbefore running.