Fix: Use unique /Catch2 prefix for reproducible builds

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()

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

docs/release-notes.md

@@ -2,6 +2,7 @@
 
 # Release notes
 **Contents**<br>
+[3.13.0](#3130)<br>
 [3.12.0](#3120)<br>
 [3.11.0](#3110)<br>
 [3.10.0](#3100)<br>
@@ -72,6 +73,16 @@
 [Even Older versions](#even-older-versions)<br>
 
 
+## 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 <path>` to their debugger config
+
+
 ## 3.12.0
 
 ### Fixes

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.

extras/lldbinit

@@ -13,4 +13,20 @@
 # line into your ~/.lldbinit file
 #
 
-settings set target.process.thread.step-avoid-regexp Catch
+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.