build: add SENTRY_LIBUNWIND_SYSTEM option

.github/workflows/ci.yml

@@ -146,12 +146,14 @@ jobs:
             CC: gcc
             CXX: g++
             SYSTEM_PYTHON: 1
+            CMAKE_DEFINES: -DSENTRY_LIBUNWIND_SYSTEM=ON
           - name: Linux (clang + musl + libunwind)
             os: ubuntu-latest
             container: ghcr.io/getsentry/sentry-native-alpine:3.23
             CC: clang
             CXX: clang++
             SYSTEM_PYTHON: 1
+            CMAKE_DEFINES: -DSENTRY_LIBUNWIND_SYSTEM=ON
           - name: macOS 14 (xcode llvm)
             os: macos-14
             ERROR_ON_WARNINGS: 1
@@ -327,7 +329,7 @@ jobs:
         if: ${{ contains(matrix.container, 'alpine') }}
         run: |
           apk update
-          apk add curl-dev xz-dev
+          apk add curl-dev libunwind-dev xz-dev
       # install manually until available by default (also for future .NET updates)
       - name: Install .NET 10 SDK for ARM64 runners
         if: ${{ runner.os == 'Linux' && runner.arch == 'ARM64' && !matrix.container }}

CMakeLists.txt

@@ -103,6 +103,12 @@ endif()
 
 option(SENTRY_PIC "Build sentry (and dependent) libraries as position independent libraries" ON)
 
+if(LINUX)
+	option(SENTRY_LIBUNWIND_SYSTEM "Use system libunwind library" OFF)
+else()
+	set(SENTRY_LIBUNWIND_SYSTEM OFF)
+endif()
+
 option(SENTRY_TRANSPORT_COMPRESSION "Enable transport gzip compression" OFF)
 
 option(SENTRY_BUILD_TESTS "Build sentry-native tests" "${SENTRY_MAIN_PROJECT}")
@@ -670,14 +676,24 @@ endif()
 
 if(SENTRY_WITH_LIBUNWIND)
 	if(LINUX)
-		# Use vendored libunwind
-		add_subdirectory(vendor/libunwind)
-		target_link_libraries(sentry PRIVATE unwind)
-		if(NOT SENTRY_BUILD_SHARED_LIBS)
-			sentry_install(TARGETS unwind EXPORT sentry
-				LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
-				ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
-			)
+		if(SENTRY_LIBUNWIND_SYSTEM)
+			find_package(PkgConfig REQUIRED)
+			pkg_check_modules(LIBUNWIND REQUIRED IMPORTED_TARGET libunwind)
+			if(SENTRY_BUILD_SHARED_LIBS)
+				target_link_libraries(sentry PRIVATE PkgConfig::LIBUNWIND)
+			else()
+				target_link_libraries(sentry PUBLIC PkgConfig::LIBUNWIND)
+			endif()
+		else()
+			# Use vendored libunwind
+			add_subdirectory(vendor/libunwind)
+			target_link_libraries(sentry PRIVATE unwind)
+			if(NOT SENTRY_BUILD_SHARED_LIBS)
+				sentry_install(TARGETS unwind EXPORT sentry
+					LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+					ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+				)
+			endif()
 		endif()
 	endif()
 endif()
@@ -874,7 +890,11 @@ elseif(SENTRY_BACKEND_NATIVE)
 	endif()
 
 	if(SENTRY_WITH_LIBUNWIND AND LINUX)
-		target_link_libraries(sentry-crash PRIVATE unwind)
+		if(SENTRY_LIBUNWIND_SYSTEM)
+			target_link_libraries(sentry-crash PRIVATE PkgConfig::LIBUNWIND)
+		else()
+			target_link_libraries(sentry-crash PRIVATE unwind)
+		endif()
 	endif()
 
 	# Make sentry library depend on crash daemon so it's always built together

README.md

@@ -259,6 +259,16 @@ using `cmake -D BUILD_SHARED_LIBS=OFF ..`.
 - `SENTRY_BREAKPAD_SYSTEM` (Default: `OFF`):
   This instructs the build system to use system-installed breakpad libraries instead of the in-tree version.
 
+- `SENTRY_LIBUNWIND_SYSTEM` (Default: `OFF`, only for Linux):
+  This instructs the build system to use a system-installed `libunwind` (found via `pkg-config`) instead of the
+  vendored copy in `vendor/libunwind`.
+
+  In contrast to the vendored `libunwind` which is always built as a static archive and either linked into the
+  resulting shared library or colocated with the other static artifacts, with `SENTRY_LIBUNWIND_SYSTEM=ON`, the library
+  type (shared or static) is determined by the host distribution's package. The `SENTRY_BUILD_SHARED_LIBS` option only
+  controls how the dependency is exposed to consuming CMake projects, not the library type of the system `libunwind`
+  itself. Ensure matching build and target environments when using system packages.
+
 - `SENTRY_TRANSPORT_COMPRESSION` (Default: `OFF`):
   Adds Gzip transport compression. Requires `zlib`.
 

sentry-config.cmake.in

@@ -7,6 +7,7 @@ set(SENTRY_BUILD_SHARED_LIBS @SENTRY_BUILD_SHARED_LIBS@)
 set(SENTRY_LINK_PTHREAD @SENTRY_LINK_PTHREAD@)
 set(SENTRY_TRANSPORT_COMPRESSION @SENTRY_TRANSPORT_COMPRESSION@)
 set(SENTRY_BREAKPAD_SYSTEM @SENTRY_BREAKPAD_SYSTEM@)
+set(SENTRY_LIBUNWIND_SYSTEM @SENTRY_LIBUNWIND_SYSTEM@)
 set(CRASHPAD_ZLIB_SYSTEM @CRASHPAD_ZLIB_SYSTEM@)
 
 if(NOT SENTRY_BUILD_SHARED_LIBS)
@@ -17,6 +18,10 @@ if(NOT SENTRY_BUILD_SHARED_LIBS)
 		find_dependency(PkgConfig)
 		pkg_check_modules(BREAKPAD REQUIRED IMPORTED_TARGET breakpad-client)
 	endif()
+	if(SENTRY_LIBUNWIND_SYSTEM)
+		find_dependency(PkgConfig)
+		pkg_check_modules(LIBUNWIND REQUIRED IMPORTED_TARGET libunwind)
+	endif()
 	if(SENTRY_TRANSPORT STREQUAL "curl")
 		find_dependency(CURL)
 	endif()