From e24f6b612e9b8c99bfa34e3813a4b77366b07adc Mon Sep 17 00:00:00 2001 From: arryansh5 Date: Sat, 24 Jan 2026 21:19:46 +0530 Subject: [PATCH] Fix: Use unique /Catch2 prefix for reproducible builds --- CMake/CatchMiscFunctions.cmake | 2 +- docs/ci-and-misc.md | 43 ++++++++++++++++++++++++++++++---- docs/release-notes.md | 11 +++++++++ extras/gdbinit | 16 +++++++++++++ extras/lldbinit | 18 +++++++++++++- 5 files changed, 84 insertions(+), 6 deletions(-) diff --git a/CMake/CatchMiscFunctions.cmake b/CMake/CatchMiscFunctions.cmake index d1cf5fc2c8..4be85deb68 100644 --- a/CMake/CatchMiscFunctions.cmake +++ b/CMake/CatchMiscFunctions.cmake @@ -116,6 +116,6 @@ endfunction() function(add_build_reproducibility_settings target) # Make the build reproducible on versions of g++ and clang that supports -ffile-prefix-map if((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR (CMAKE_CXX_COMPILER_ID MATCHES "Clang")) - add_cxx_flag_if_supported_to_targets("-ffile-prefix-map=${CATCH_DIR}/=" "${target}") + add_cxx_flag_if_supported_to_targets("-ffile-prefix-map=${CATCH_DIR}/=/Catch2/" "${target}") endif() endfunction() diff --git a/docs/ci-and-misc.md b/docs/ci-and-misc.md index 879a15fc39..55fdf70847 100644 --- a/docs/ci-and-misc.md +++ b/docs/ci-and-misc.md @@ -100,10 +100,45 @@ can use `pkg-config` to get its include path: `pkg-config --cflags catch2`. ### gdb and lldb scripts -Catch2's `extras` folder also contains two simple debugger scripts, -`gdbinit` for `gdb` and `lldbinit` for `lldb`. If loaded into their -respective debugger, these will tell it to step over Catch2's internals -when stepping through code. +Catch2's `extras` folder contains debugger helper scripts, +`gdbinit` for `gdb` and `lldbinit` for `lldb`. These scripts provide +two features: + +#### Skipping Catch2 internals + +The scripts configure the debugger to skip stepping into Catch2's +internal implementation when debugging your tests. This allows you to +focus on debugging your test code rather than stepping through the +framework internals. + +To use this feature, copy the `skip` command from the appropriate file +to your `~/.gdbinit` or `~/.lldbinit` file. + +#### Path substitution for reproducible builds + +If Catch2 is built with `CATCH_ENABLE_REPRODUCIBLE_BUILD=ON` (the default), +the compiler remaps source file paths in debug symbols to use the prefix +`/Catch2` instead of the full build path. This makes builds reproducible +but requires debuggers to be told where to find the actual source files. + +The helper scripts include commented-out `set substitute-path` (gdb) or +`settings set target.source-map` (lldb) commands that you can uncomment +and customize to point to your Catch2 installation. + +For example, if you built Catch2 in `/home/user/Catch2`, add this to +your `~/.gdbinit`: +```gdb +set substitute-path /Catch2 /home/user/Catch2 +``` + +Or for lldb, add to `~/.lldbinit`: +```lldb +settings set target.source-map /Catch2 /home/user/Catch2 +``` + +If you are also using reproducible builds in your own project, use a +different unique prefix (e.g., `/MyProject`) to avoid conflicts with +Catch2's prefix. ## CMake diff --git a/docs/release-notes.md b/docs/release-notes.md index 35a767748a..02ebc7cadb 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -2,6 +2,7 @@ # Release notes **Contents**
+[3.13.0](#3130)
[3.12.0](#3120)
[3.11.0](#3110)
[3.10.0](#3100)
@@ -72,6 +73,16 @@ [Even Older versions](#even-older-versions)
+## 3.13.0 + +### Improvements +* Improved debugger support for reproducible builds + * Changed `-ffile-prefix-map` to use `/Catch2` prefix instead of empty string + * This avoids conflicts when multiple libraries use reproducible builds + * Updated `gdbinit` and `lldbinit` with path substitution instructions + * Users need to add `set substitute-path /Catch2 ` to their debugger config + + ## 3.12.0 ### Fixes diff --git a/extras/gdbinit b/extras/gdbinit index fb3608aeba..830f67c1bf 100644 --- a/extras/gdbinit +++ b/extras/gdbinit @@ -14,3 +14,19 @@ # skip -rfu Catch + +# +# Path substitution for reproducible builds +# +# If Catch2 was built with CATCH_ENABLE_REPRODUCIBLE_BUILD=ON (the default), +# source paths in debug symbols use the prefix /Catch2 instead of the full +# build path. To allow GDB to find the actual source files, you need to tell +# GDB where your Catch2 sources are located. +# +# Uncomment and adjust the path below to match your Catch2 installation. +# For example, if you built Catch2 in /home/user/Catch2, use: +# +# set substitute-path /Catch2 /home/user/Catch2 +# +# If you are also using reproducible builds in your own project, you should +# use a different unique prefix (e.g., /MyProject) to avoid conflicts. diff --git a/extras/lldbinit b/extras/lldbinit index 4f13634d0b..88c7b05a6a 100644 --- a/extras/lldbinit +++ b/extras/lldbinit @@ -13,4 +13,20 @@ # line into your ~/.lldbinit file # -settings set target.process.thread.step-avoid-regexp Catch \ No newline at end of file +settings set target.process.thread.step-avoid-regexp Catch + +# +# Path substitution for reproducible builds +# +# If Catch2 was built with CATCH_ENABLE_REPRODUCIBLE_BUILD=ON (the default), +# source paths in debug symbols use the prefix /Catch2 instead of the full +# build path. To allow LLDB to find the actual source files, you need to tell +# LLDB where your Catch2 sources are located. +# +# Uncomment and adjust the path below to match your Catch2 installation. +# For example, if you built Catch2 in /home/user/Catch2, use: +# +# settings set target.source-map /Catch2 /home/user/Catch2 +# +# If you are also using reproducible builds in your own project, you should +# use a different unique prefix (e.g., /MyProject) to avoid conflicts. \ No newline at end of file