feat boost.stacktrace: C++20 modules support (#230)

- Introduce `boost.stacktrace_dump` module for safe_dump interface
- Introduce `boost.stacktrace_<backend>` module for each unwind/collect implementation method
- Introduce `boost.stacktrace` module exposing best available backend implementation

Also many tests was added for checking all available backend build and also header only library version
Moreover, there are some checks for `Boost::stacktrace_<backend>` and  `Boost::stacktrace_from_exception` compatibility

---------

Co-authored-by: Fedor Osetrov <fdr400@Fedors-MacBook-Pro.local>

Author: fdr400

.github/workflows/ci.yml

@@ -27,10 +27,21 @@ jobs:
           - toolset: gcc-9
             cxxstd: "03,11,14,17,2a"
             os: ubuntu-22.04
-            install: g++-9
+            install: [g++-9]
           - toolset: clang-15
             cxxstd: "03,11,14,17,2a"
             os: ubuntu-22.04
+          - toolset: clang-19
+            compiler: clang++-19
+            cxxstd: "20"
+            os: ubuntu-24.04
+            install: &cxx19
+              - clang-19
+              - llvm-19
+              - libclang-rt-19-dev
+              - libc++-19-dev
+              - libc++abi-19-dev
+              - clang-tools-19
           # TODO: fix and uncomment
           #- toolset: clang
           #  cxxstd: "03,11,14,17,2a"
@@ -45,7 +56,7 @@ jobs:
 
       - name: Install packages
         if: matrix.install
-        run: sudo apt install ${{matrix.install}}
+        run: sudo apt install -y ${{join(matrix.install, ' ')}}
 
       - name: Setup Boost
         run: |
@@ -71,6 +82,35 @@ jobs:
           ./bootstrap.sh
           ./b2 -d0 headers
           ./b2 -j4 variant=debug tools/inspect
+      
+      - name: Build libbacktrace
+        if: ${{matrix.toolset == 'clang-19'}}
+        run: |
+          # libc++ do not have bundled libbacktrace implementation
+          git clone --depth=1 https://github.com/ianlancetaylor/libbacktrace.git
+          cd libbacktrace
+          CC=clang-19 OBJCOPY=/usr/bin/llvm-objcopy NM=/usr/bin/llvm-nm \
+            ./configure --prefix="$HOME/.local" --with-system-libunwind
+          make -j"$(nproc)"
+          make install
+
+      - name: Run modules tests without 'import std;'
+        if: ${{matrix.toolset == 'clang-19'}}
+        run: |
+          pwd
+          cd ../boost-root/libs/$LIBRARY
+          cmake -S test/cmake_subdir_test \
+                -B build_module \
+                -GNinja \
+                -DBOOST_USE_MODULES=1 \
+                -DBUILD_TESTING=1 \
+                -DCMAKE_CXX_STANDARD=20 \
+                -DCMAKE_CXX_COMPILER=${{matrix.compiler}} \
+                -DCMAKE_CXX_FLAGS="-stdlib=libc++ -I$HOME/.local/include" \
+                -DCMAKE_EXE_LINKER_FLAGS="-L$HOME/.local"
+          cmake --build build_module
+          ctest --test-dir build_module -VV
+          rm -rf build_module
 
       - name: Run tests
         run: |
@@ -205,11 +245,14 @@ jobs:
 
       - name: Use library with add_subdirectory
         run: |
-          cd ../boost-root/libs/$LIBRARY/test/cmake_subdir_test
-          mkdir __build__ && cd __build__
-          cmake -DBUILD_SHARED_LIBS=${{matrix.shared}} ..
-          cmake --build .
-          ctest --output-on-failure --no-tests=error
+          cd ../boost-root/libs/$LIBRARY
+          cmake -S test/cmake_subdir_test -B __build__ \
+            -GNinja \
+            -DBUILD_SHARED_LIBS=${{matrix.shared}}
+
+          cmake --build __build__
+          ctest --test-dir __build__ --output-on-failure --no-tests=error
+          rm -rf __build__
 
   posix-cmake-install:
     strategy:

.gitignore

@@ -0,0 +1,3 @@
+build?*
+.cache
+.vscode

CMakeLists.txt

@@ -7,7 +7,18 @@ cmake_minimum_required(VERSION 3.8...4.20)
 
 project(boost_stacktrace VERSION "${BOOST_SUPERPROJECT_VERSION}" LANGUAGES CXX)
 
-function(stacktrace_add_library suffix opt public_libs libs defs)
+function(stacktrace_add_module name)
+  target_sources(${name}
+    PUBLIC
+      FILE_SET CXX_MODULES
+      BASE_DIRS "${CMAKE_CURRENT_LIST_DIR}/modules"
+      FILES "${CMAKE_CURRENT_LIST_DIR}/modules/${name}.cppm"
+  )
+  target_compile_features(${name} PUBLIC cxx_std_20)
+  target_compile_definitions(${name} PUBLIC BOOST_USE_MODULES)
+endfunction()
+
+function(stacktrace_add_library suffix opt public_libs libs defs add_module)
 
   if(NOT opt)
     return()
@@ -38,10 +49,14 @@ function(stacktrace_add_library suffix opt public_libs libs defs)
       ${defs}
   )
 
-  target_sources(boost_stacktrace_${suffix}
-    PRIVATE
-      ${CMAKE_CURRENT_LIST_DIR}/src/${suffix}.cpp
-  )
+  if (add_module)
+    stacktrace_add_module(boost_stacktrace_${suffix})
+  else()
+    target_sources(boost_stacktrace_${suffix}
+      PRIVATE
+        "${CMAKE_CURRENT_LIST_DIR}/src/${suffix}.cpp"
+    )
+  endif()
 
   if(BUILD_SHARED_LIBS)
     target_compile_definitions(boost_stacktrace_${suffix} PUBLIC BOOST_STACKTRACE_DYN_LINK)
@@ -110,24 +125,40 @@ if(BOOST_STACKTRACE_ENABLE_BACKTRACE OR
    BOOST_STACKTRACE_ENABLE_WINDBG_CACHED
   )
   set(_enable_non_noop_backend TRUE)
+else()
+  set(_enable_non_noop_backend FALSE)
 endif()
 
-if(_enable_non_noop_backend)
-  stacktrace_add_library(dump ON "" "" "")
+if(NOT BOOST_USE_MODULES)
+  set(BOOST_USE_MODULES OFF)
 endif()
-stacktrace_add_library(noop ${BOOST_STACKTRACE_ENABLE_NOOP} "" "" "")
-stacktrace_add_library(backtrace ${BOOST_STACKTRACE_ENABLE_BACKTRACE} Boost::stacktrace_dump "backtrace;${CMAKE_DL_LIBS}" "")
-stacktrace_add_library(addr2line ${BOOST_STACKTRACE_ENABLE_ADDR2LINE} Boost::stacktrace_dump "${CMAKE_DL_LIBS}" "")
-stacktrace_add_library(basic ${BOOST_STACKTRACE_ENABLE_BASIC} Boost::stacktrace_dump "${CMAKE_DL_LIBS}" "")
-stacktrace_add_library(windbg ${BOOST_STACKTRACE_ENABLE_WINDBG} Boost::stacktrace_dump "dbgeng;ole32" "_GNU_SOURCE=1")
-stacktrace_add_library(windbg_cached ${BOOST_STACKTRACE_ENABLE_WINDBG_CACHED} Boost::stacktrace_dump "dbgeng;ole32" "_GNU_SOURCE=1")
+
+stacktrace_add_library(dump ${_enable_non_noop_backend} "" "" "" ${BOOST_USE_MODULES})
+stacktrace_add_library(noop ${BOOST_STACKTRACE_ENABLE_NOOP} "" "" "" ${BOOST_USE_MODULES})
+stacktrace_add_library(backtrace ${BOOST_STACKTRACE_ENABLE_BACKTRACE} Boost::stacktrace_dump "backtrace;${CMAKE_DL_LIBS}" "" ${BOOST_USE_MODULES})
+stacktrace_add_library(addr2line ${BOOST_STACKTRACE_ENABLE_ADDR2LINE} Boost::stacktrace_dump "${CMAKE_DL_LIBS}" "" ${BOOST_USE_MODULES})
+stacktrace_add_library(basic ${BOOST_STACKTRACE_ENABLE_BASIC} Boost::stacktrace_dump "${CMAKE_DL_LIBS}" "" ${BOOST_USE_MODULES})
+stacktrace_add_library(windbg ${BOOST_STACKTRACE_ENABLE_WINDBG} Boost::stacktrace_dump "dbgeng;ole32" "_GNU_SOURCE=1" ${BOOST_USE_MODULES})
+stacktrace_add_library(windbg_cached ${BOOST_STACKTRACE_ENABLE_WINDBG_CACHED} Boost::stacktrace_dump "dbgeng;ole32" "_GNU_SOURCE=1" ${BOOST_USE_MODULES})
 
 # boost_stacktrace, default library
 
-add_library(boost_stacktrace INTERFACE)
+if(BOOST_USE_MODULES)
+  add_library(boost_stacktrace)
+  stacktrace_add_module(boost_stacktrace boost_stacktrace)
+  set(__scope PUBLIC)
 
-target_include_directories(boost_stacktrace INTERFACE include)
+  foreach(backend noop backtrace addr2line basic windbg windbg_cached)
+    if (TARGET boost_stacktrace_${backend})
+      target_compile_definitions(boost_stacktrace_${backend} INTERFACE BOOST_STACKTRACE_BACKEND_MODULE=${backend})
+    endif()
+  endforeach()
+else()
+  add_library(boost_stacktrace INTERFACE)
+  set(__scope INTERFACE)
+endif()
 
+target_include_directories(boost_stacktrace ${__scope} "${CMAKE_CURRENT_LIST_DIR}/include")
 add_library(Boost::stacktrace ALIAS boost_stacktrace)
 
 if(BOOST_STACKTRACE_ENABLE_WINDBG)
@@ -147,13 +178,13 @@ else()
 endif()
 
 message(STATUS "Boost.stacktrace default backend: ${__default_stacktrace_backend}")
-target_link_libraries(boost_stacktrace INTERFACE Boost::stacktrace_${__default_stacktrace_backend})
+target_link_libraries(boost_stacktrace ${__scope} Boost::stacktrace_${__default_stacktrace_backend})
 
 # Boost::stacktrace_from_exception is never the default
 if(_enable_non_noop_backend)
-  stacktrace_add_library(from_exception ${BOOST_STACKTRACE_ENABLE_FROM_EXCEPTION} Boost::stacktrace_dump "${CMAKE_DL_LIBS}" "")
-  unset(_enable_non_noop_backend)
+  stacktrace_add_library(from_exception ${BOOST_STACKTRACE_ENABLE_FROM_EXCEPTION} Boost::stacktrace_dump "${CMAKE_DL_LIBS}" "" FALSE)
 endif()
+unset(_enable_non_noop_backend)
 
 if(BUILD_TESTING)
   add_subdirectory(test)

include/boost/stacktrace.hpp

@@ -7,7 +7,10 @@
 #ifndef BOOST_STACKTRACE_HPP
 #define BOOST_STACKTRACE_HPP
 
-#include <boost/config.hpp>
+#include <boost/stacktrace/detail/backend_config.hpp>
+
+#if !defined(BOOST_USE_MODULES) || defined(BOOST_STACKTRACE_INTERFACE_UNIT)
+
 #ifdef BOOST_HAS_PRAGMA_ONCE
 #   pragma once
 #endif
@@ -17,4 +20,6 @@
 #include <boost/stacktrace/safe_dump_to.hpp>
 #include <boost/stacktrace/this_thread.hpp>
 
+#endif // !defined(BOOST_USE_MODULES) || defined(BOOST_STACKTRACE_INTERFACE_UNIT)
+
 #endif // BOOST_STACKTRACE_HPP

include/boost/stacktrace/detail/addr2line_impls.hpp

@@ -12,18 +12,21 @@
 #   pragma once
 #endif
 
-#include <boost/stacktrace/detail/addr_base.hpp>
-#include <boost/stacktrace/detail/to_hex_array.hpp>
-#include <boost/stacktrace/detail/to_dec_array.hpp>
-#include <boost/stacktrace/detail/try_dec_convert.hpp>
+#if !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 #include <boost/core/demangle.hpp>
+
 #include <cstdio>
 #include <cstring>
 
 #include <sys/types.h>
 #include <sys/wait.h>
 #include <signal.h>
+#endif // !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 
+#include <boost/stacktrace/detail/addr_base.hpp>
+#include <boost/stacktrace/detail/to_hex_array.hpp>
+#include <boost/stacktrace/detail/to_dec_array.hpp>
+#include <boost/stacktrace/detail/try_dec_convert.hpp>
 
 namespace boost { namespace stacktrace { namespace detail {
 

include/boost/stacktrace/detail/addr_base.hpp

@@ -12,10 +12,12 @@
 #   pragma once
 #endif
 
+#if !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 #include <fstream>
 #include <sstream>
 #include <cstdint>
 #include <cstdlib>
+#endif // !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 
 namespace boost { namespace stacktrace { namespace detail {
 

include/boost/stacktrace/detail/addr_base_msvc.hpp

@@ -12,6 +12,7 @@
 #   pragma once
 #endif
 
+#if !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 #include <cstdio>
 #include <cstdint>
 #include <memory>
@@ -27,6 +28,7 @@
 #include <psapi.h>
 #undef WIN32_LEAN_AND_MEAN
 #endif
+#endif // !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 
 namespace boost { namespace stacktrace { namespace detail {
   inline std::uintptr_t get_own_proc_addr_base(const void* addr) {

include/boost/stacktrace/detail/backend_config.hpp

@@ -0,0 +1,24 @@
+// Copyright Antony Polukhin, 2025-2026.
+// Copyright Fedor Osetrov, 2025-2026.
+//
+// Distributed under the Boost Software License, Version 1.0. (See
+// accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+#ifndef BOOST_STACKTRACE_DETAIL_BACKEND_CONFIG_HPP
+#define BOOST_STACKTRACE_DETAIL_BACKEND_CONFIG_HPP
+
+#if !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
+# include <boost/config.hpp>
+# ifdef BOOST_HAS_PRAGMA_ONCE
+#  pragma once
+# endif
+#endif
+
+#include "boost/stacktrace/detail/config.hpp"
+
+#if defined(BOOST_USE_MODULES) && !defined(BOOST_STACKTRACE_INTERFACE_UNIT) && !defined(BOOST_STACKTRACE_INTERNAL_BUILD_LIBS)
+    import boost.stacktrace.BOOST_STACKTRACE_BACKEND_MODULE;
+#endif
+
+#endif

include/boost/stacktrace/detail/collect_msvc.ipp

@@ -12,9 +12,11 @@
 #   pragma once
 #endif
 
-#include <boost/stacktrace/safe_dump_to.hpp>
-
+#if !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 #include <boost/winapi/stack_backtrace.hpp>
+#endif // !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
+
+#include <boost/stacktrace/safe_dump_to.hpp>
 
 namespace boost { namespace stacktrace { namespace detail {
 

include/boost/stacktrace/detail/collect_unwind.ipp

@@ -12,8 +12,7 @@
 #   pragma once
 #endif
 
-#include <boost/stacktrace/safe_dump_to.hpp>
-
+#if !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 // On iOS 32-bit ARM architecture _Unwind_Backtrace function doesn't exist, symbol is undefined.
 // Forcing libc backtrace() function usage.
 #include <boost/predef.h>
@@ -28,11 +27,14 @@
 #include <unwind.h>
 #endif
 #include <cstdio>
+#endif // !defined(BOOST_STACKTRACE_INTERFACE_UNIT)
 
 #if !defined(_GNU_SOURCE) && !defined(BOOST_STACKTRACE_GNU_SOURCE_NOT_REQUIRED) && !defined(BOOST_WINDOWS)
 #error "Boost.Stacktrace requires `_Unwind_Backtrace` function. Define `_GNU_SOURCE` macro or `BOOST_STACKTRACE_GNU_SOURCE_NOT_REQUIRED` if _Unwind_Backtrace is available without `_GNU_SOURCE`."
 #endif
 
+#include <boost/stacktrace/safe_dump_to.hpp>
+
 namespace boost { namespace stacktrace { namespace detail {
 
 #if !defined(BOOST_STACKTRACE_USE_LIBC_BACKTRACE_FUNCTION)