[SystemZ][z/OS] Add support for an external unwinder

[muiez]

Summary

The aim of this patch is to build and link an external unwinder for libc++abi. The approach is generalized as suggested in https://reviews.llvm.org/D99913#3173529.

[muiez]

Add diff context (-U999)

[muiez]

kickoff CI

[muiez]

kickoff CI

[ldionne]

I think the idea behind this patch is interesting and useful, however I'd like to model what we do for selecting the ABI library from libc++ here. We should have a HandleUnwindLibrary.cmake file that will create interface targets, and we can then link against those from libc++abi directly. Let's avoid introducing even more options like LIBCXXABI_EXTERNAL_UNWIND_SOURCE_DIR and LIBCXXABI_EXTERNAL_UNWIND_LIB_NAME -- instead let's put the logic for how to handle z/OS's unwind library in HandleUnwindLibrary.cmake directly.

libcxx/cmake/caches/zos.cmake

+set(LIBCXXABI_USE_EXTERNAL_UNWINDER ON CACHE BOOL "")
+set(LIBCXXABI_EXTERNAL_UNWIND_SOURCE_DIR "$ENV{LLVM_BASE}/zos-unwind" CACHE PATH "The path to the external unwind source directory.")
+set(LIBCXXABI_EXTERNAL_UNWIND_LIB_NAME "libunwind.x" CACHE PATH "The filename of the built library.")

libcxx/docs/BuildingLibcxx.rst

 
 .. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL
 
   **Default**: ``OFF``
 
   Build and use the LLVM unwinder. Note: This option can only be used when
   libc++abi is the C++ ABI library used.
 
+.. option:: LIBCXXABI_USE_EXTERNAL_UNWINDER:BOOL
+
+  **Default**: ``OFF``
+
+  Build and use an external unwinder. Note: When ON, the path to the unwinder
+  source directory should be provided with ``LIBCXXABI_EXTERNAL_UNWIND_SOURCE_DIR``, and the
+  filename of the built library should be provided with ``LIBCXXABI_EXTERNAL_UNWIND_LIB_NAME``.
+  The external unwinder is built to the library output directory.
 
 libc++ Feature Options
 ----------------------
 
 .. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL
 
   **Default**: ``ON``
 

libcxxabi/CMakeLists.txt

 # Define options.
 option(LIBCXXABI_ENABLE_EXCEPTIONS
   "Provide support for exceptions in the runtime.
   When disabled, libc++abi does not support stack unwinding and other exceptions-related features." ON)
 option(LIBCXXABI_ENABLE_ASSERTIONS "Enable assertions independent of build mode." ON)
 option(LIBCXXABI_ENABLE_PEDANTIC "Compile with pedantic enabled." ON)
 option(LIBCXXABI_ENABLE_WERROR "Fail and stop if a warning is triggered." OFF)
 option(LIBCXXABI_USE_LLVM_UNWINDER "Build and use the LLVM unwinder." OFF)
+option(LIBCXXABI_USE_EXTERNAL_UNWINDER "Build and use an external unwinder." OFF)
 option(LIBCXXABI_ENABLE_STATIC_UNWINDER "Statically link the LLVM unwinder." OFF)
 option(LIBCXXABI_USE_COMPILER_RT "Use compiler-rt instead of libgcc" OFF)
 option(LIBCXXABI_ENABLE_THREADS "Build with threads enabled" ON)
 option(LIBCXXABI_HAS_PTHREAD_API "Ignore auto-detection and force use of pthread API" OFF)
 option(LIBCXXABI_HAS_WIN32_THREAD_API "Ignore auto-detection and force use of win32 thread API" OFF)
 option(LIBCXXABI_HAS_EXTERNAL_THREAD_API
   "Build libc++abi with an externalized threading API.
   This option may only be set to ON when LIBCXXABI_ENABLE_THREADS=ON." OFF)

 
 set(LIBCXXABI_LIBCXX_LIBRARY_PATH "" CACHE PATH "The path to libc++ library.")
 set(LIBCXXABI_LIBRARY_VERSION "1.0" CACHE STRING
 "Version of libc++abi. This will be reflected in the name of the shared \
 library produced. For example, -DLIBCXXABI_LIBRARY_VERSION=x.y will \
 result in the library being named libc++abi.x.y.dylib, along with the \
 usual symlinks pointing to that.")
 
+set(LIBCXXABI_EXTERNAL_UNWIND_SOURCE_DIR "" CACHE PATH "The path to the external unwind source directory.")
+set(LIBCXXABI_EXTERNAL_UNWIND_LIB_NAME "" CACHE PATH "The filename of the built library.")
+
 # Default to building a shared library so that the default options still test
 # the libc++abi that is being built. The problem with testing a static libc++abi
 # is that libc++ will prefer a dynamic libc++abi from the system over a static
 # libc++abi from the output directory.
 option(LIBCXXABI_ENABLE_SHARED "Build libc++abi as a shared library." ON)
 option(LIBCXXABI_ENABLE_STATIC "Build libc++abi as a static library." ON)
 
 cmake_dependent_option(LIBCXXABI_INSTALL_STATIC_LIBRARY

libcxxabi/src/CMakeLists.txt

 if (LLVM_ENABLE_MODULES)
   string(REPLACE "-Wl,-z,defs" "" CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS}")
 endif()
 
 if (NOT TARGET pstl::ParallelSTL)
   message(STATUS "Could not find ParallelSTL, libc++abi will not attempt to use it but the build may fail if the libc++ in use needs it to be available.")
 endif()
 
+if (LIBCXXABI_USE_EXTERNAL_UNWINDER)
+  # The unwinder library is built as an external project.
+  if (LIBCXXABI_USE_LLVM_UNWINDER)
+    message(WARNING "Use either the external unwinder or LLVM unwinder, but not both.")
+  endif()
+
+  include_directories("${LIBCXXABI_EXTERNAL_UNWIND_SOURCE_DIR}")
+
+  set(LIBUNWIND_BUILD_PATH "${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/${LIBCXXABI_EXTERNAL_UNWIND_LIB_NAME}")
+
+  include(ExternalProject)
+  ExternalProject_Add(external-unwind-project
+    SOURCE_DIR ${LIBCXXABI_EXTERNAL_UNWIND_SOURCE_DIR}
+    BUILD_BYPRODUCTS ${LIBUNWIND_BUILD_PATH}
+    CMAKE_ARGS -DOUTPUT_DIR=${CMAKE_LIBRARY_OUTPUT_DIRECTORY}
+    INSTALL_COMMAND ""
+  )
+
+  add_library(external-unwind STATIC IMPORTED)
+  set_property(TARGET external-unwind PROPERTY IMPORTED_LOCATION ${LIBUNWIND_BUILD_PATH})
+  add_dependencies(external-unwind external-unwind-project)
+endif()
+
 # Build the shared library.
 add_library(cxxabi_shared_objects OBJECT EXCLUDE_FROM_ALL ${LIBCXXABI_SOURCES} ${LIBCXXABI_HEADERS})
 if (LIBCXXABI_USE_LLVM_UNWINDER)
   if (LIBCXXABI_STATICALLY_LINK_UNWINDER_IN_SHARED_LIBRARY)
     target_link_libraries(cxxabi_shared_objects PUBLIC unwind_shared_objects) # propagate usage requirements
     target_sources(cxxabi_shared_objects PUBLIC $<TARGET_OBJECTS:unwind_shared_objects>)
   else()
     target_link_libraries(cxxabi_shared_objects PUBLIC unwind_shared)
PROPERTIES
       LINK_FLAGS "${LIBCXXABI_LINK_FLAGS}"
       OUTPUT_NAME "c++abi"
       SOVERSION "1"
       VERSION "${LIBCXXABI_LIBRARY_VERSION}"
   )
   target_link_libraries(cxxabi_shared
     PUBLIC cxxabi_shared_objects
     PRIVATE ${LIBCXXABI_SHARED_LIBRARIES} ${LIBCXXABI_LIBRARIES})
+
+    if (LIBCXXABI_USE_EXTERNAL_UNWINDER)
+      add_dependencies(cxxabi_shared external-unwind)
+      if (ZOS)
+        target_link_libraries(cxxabi_shared PRIVATE
+          "-Wl,${LIBUNWIND_BUILD_PATH}")
+      else()
+        target_link_libraries(cxxabi_shared PRIVATE
+          "${LIBUNWIND_BUILD_PATH}")
+      endif()
+    endif()
+
   if (TARGET pstl::ParallelSTL)
     target_link_libraries(cxxabi_shared PUBLIC pstl::ParallelSTL)
   endif()
 
   list(APPEND LIBCXXABI_BUILD_TARGETS "cxxabi_shared")
   if (LIBCXXABI_INSTALL_SHARED_LIBRARY)
     list(APPEND LIBCXXABI_INSTALL_TARGETS "cxxabi_shared")
   endif()
PRIVATE
       _LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS=)
 endif()
 
 if (LIBCXXABI_ENABLE_STATIC)
   add_library(cxxabi_static STATIC)
   if (LIBCXXABI_USE_LLVM_UNWINDER AND NOT LIBCXXABI_STATICALLY_LINK_UNWINDER_IN_STATIC_LIBRARY)
     target_link_libraries(cxxabi_static PUBLIC unwind_static)
   endif()
+
+  if (LIBCXXABI_USE_EXTERNAL_UNWINDER)
+    add_dependencies(cxxabi_static external-unwind)
+    if (ZOS)
+      target_link_libraries(cxxabi_static PRIVATE
+        "-Wl,${LIBUNWIND_BUILD_PATH}")
+    else()
+      target_link_libraries(cxxabi_static PRIVATE
+        "${LIBUNWIND_BUILD_PATH}")
+    endif()
+  endif()
+
   set_target_properties(cxxabi_static
     PROPERTIES
       LINK_FLAGS "${LIBCXXABI_LINK_FLAGS}"
       OUTPUT_NAME "c++abi"
     )
   target_link_libraries(cxxabi_static
     PUBLIC cxxabi_static_objects
     PRIVATE ${LIBCXXABI_STATIC_LIBRARIES} ${LIBCXXABI_LIBRARIES})