From 982c52493b9f75b3001274b6ec317e7d08676a16 Mon Sep 17 00:00:00 2001 From: Tamas Almos Vami Date: Fri, 14 Nov 2025 15:04:37 -0800 Subject: [PATCH] Add Debugging chapter and detail our just helping tools --- src/SUMMARY.md | 1 + src/developing/Debugging.md | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 src/developing/Debugging.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e399d5b4..ade4b89a 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -47,6 +47,7 @@ - [Unit Testing](developing/Unit-Testing-in-ldmx-sw.md) - [Logging](developing/Logging.md) - [Creating a new Event Bus Object](developing/Creating-a-new-Event-Bus-Object.md) +- [Debugging](developing/Debugging.md) - [Creating your own production image](developing/custom-production-image.md) - [What the F.A.Q.?](developing/faq.md) - [Why this workflow?](developing/whyyyy.md) diff --git a/src/developing/Debugging.md b/src/developing/Debugging.md new file mode 100644 index 00000000..175e06de --- /dev/null +++ b/src/developing/Debugging.md @@ -0,0 +1,23 @@ +# Debugging + +CMAKE provides several useful flags for debugging and code analysis. We've included many of these in `just` recipes for convenience. + +## Commands to use: + +### Static Analysis + - **`configure-clang-tidy`** - Enables clang-tidy static analysis during compilation to catch potential bugs and style issues before runtime. The CMAKE flag is `-DENABLE_CLANG_TIDY=ON`. This will slow down compilation but provides valuable feedback on code quality. + +### Optimization + - **`configure-clang-lto`** - Switches to the clang/clang++ compiler and enables LTO (Link Time Optimization), which can improve performance by optimizing across compilation units during linking. The flags are `-DENABLE_LTO=ON -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang`. Note: LTO significantly increases link time but may catch additional optimization-related issues. + +### Runtime Sanitizers + - **`configure-asan-ubsan`** - Enables both ASAN (AddressSanitizer) and UBSAN (UndefinedBehaviorSanitizer) to detect memory errors (buffer overflows, use-after-free, etc.) and undefined behavior at runtime. The flags are `-DENABLE_SANITIZER_UNDEFINED_BEHAVIOR=ON -DENABLE_SANITIZER_ADDRESS=ON`. + - **Important:** These sanitizers only detect issues when the problematic code is actually executed. + - If issues are detected, the program will abort and print detailed diagnostic information. + +### Interactive Debugging + - **`configure-gdb`** - Compiles with debug symbols preserved and optimizations disabled, enabling effective debugging with GDB (GNU Debugger). The flag is `-DCMAKE_BUILD_TYPE=Debug`. This allows you to: + - Set breakpoints and step through code line-by-line + - Inspect variable values during execution + - View readable stack traces + - Note: Debug builds are significantly slower than release builds due to disabled optimizations. \ No newline at end of file