From a6f6d5c0a6e022687cf8439f667d91b60ac7b3ca Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Mon, 14 Sep 2026 20:37:36 +0200
Subject: [PATCH 01/14] Add shared CMake libraries and use them in C++ CI

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 .github/workflows/ci.yml                      |  5 +-
 lang/cpp/CMakeLists.txt                       | 52 ++++++++++++-------
 lang/cpp/README.md                            | 15 ++++--
 lang/cpp/examples/CMakeLists.txt              |  7 ++-
 lang/cpp/tests/CMakeLists.txt                 |  6 ++-
 vortex-ffi/CMakeLists.txt                     | 10 +++-
 vortex-ffi/README.md                          |  9 ++--
 vortex-ffi/cmake/Configure.cmake              | 31 ++++++++++-
 vortex-ffi/cmake/SystemDependencies.cmake     |  4 +-
 vortex-ffi/cmake/exports.map                  |  7 +++
 vortex-ffi/cmake/shared.c                     |  5 ++
 .../tests/fixtures/native/header_consumer.c   |  1 +
 .../tests/fixtures/native/vortex-ffi/build.rs |  5 +-
 .../tests/fixtures/native/vortex-ffi/lib.rs   |  7 +++
 .../cmake/tests/test_compiler_commands.py     | 29 ++++++++++-
 vortex-ffi/cmake/tests/test_configure.py      |  2 +-
 vortex-ffi/examples/CMakeLists.txt            |  6 ++-
 vortex-ffi/test/CMakeLists.txt                |  6 ++-
 18 files changed, 168 insertions(+), 39 deletions(-)
 create mode 100644 vortex-ffi/cmake/exports.map
 create mode 100644 vortex-ffi/cmake/shared.c

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 42d18337af3..7e7e5488812 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -673,9 +673,12 @@ jobs:
         run: |
           cmake -S lang/cpp -B build \
             -DCMAKE_BUILD_TYPE=Debug \
-            -DVORTEX_DEBUG_INFO=0 \
+            -DBUILD_SHARED_LIBS=ON \
+            -DVORTEX_DEBUG_INFO=2 \
             -DCMAKE_C_COMPILER=clang \
             -DCMAKE_CXX_COMPILER=clang++ \
+            -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=mold \
+            -DCMAKE_SHARED_LINKER_FLAGS=-fuse-ld=mold \
             -DVORTEX_SANITIZER=asan \
             -DVORTEX_SANITIZE_RUST_STD=ON \
             -DVORTEX_BUILD_TESTS=ON \
diff --git a/lang/cpp/CMakeLists.txt b/lang/cpp/CMakeLists.txt
index 4d969b375bd..62bbe1cfd70 100644
--- a/lang/cpp/CMakeLists.txt
+++ b/lang/cpp/CMakeLists.txt
@@ -1,8 +1,8 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright the Vortex contributors
 
-# Entry point for the static Vortex C++ wrapper. It consumes the Rust FFI
-# archive from vortex-ffi and exports Vortex::cpp_static. It supports standalone
+# Entry point for the Vortex C++ wrapper. It consumes the Rust FFI library
+# from vortex-ffi and exports static and shared targets. It supports standalone
 # configuration and add_subdirectory() from the repository root or a parent.
 
 # CMake 3.25 is required for block() and FetchContent SYSTEM.
@@ -33,6 +33,7 @@ if(_vortex_top_level AND NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Debug)
 endif()
 
+option(BUILD_SHARED_LIBS "Build and use shared libraries" OFF)
 option(VORTEX_BUILD_TESTS "Build Vortex tests" OFF)
 option(VORTEX_BUILD_EXAMPLES "Build Vortex examples" OFF)
 option(VORTEX_WARNINGS_AS_ERRORS
@@ -50,27 +51,35 @@ endif()
 # The C++ wrapper over the C FFI. Public headers live under include/.
 file(GLOB _vortex_cpp_sources CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp")
 
-# Consumers inherit the FFI archive, its headers, and its system libraries
-# through this target. Hidden visibility keeps wrapper symbols out of a parent
-# shared library's exports.
+# Preserve the static API and its hidden symbols for embedding in other DSOs.
 add_library(vortex_cxx STATIC ${_vortex_cpp_sources})
-set_target_properties(vortex_cxx PROPERTIES
-    POSITION_INDEPENDENT_CODE ON
-    CXX_VISIBILITY_PRESET hidden
-    VISIBILITY_INLINES_HIDDEN ON)
-target_compile_features(vortex_cxx PUBLIC cxx_std_20)
-target_include_directories(vortex_cxx PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
+set_target_properties(vortex_cxx PROPERTIES CXX_VISIBILITY_PRESET hidden)
 target_link_libraries(vortex_cxx PUBLIC Vortex::ffi_static)
-
-# Warning policy is private to Vortex-owned sources so embedding this target
-# never injects warning flags into consumers.
-target_compile_options(vortex_cxx PRIVATE -Wall -Wextra -Wpedantic)
-if(VORTEX_WARNINGS_AS_ERRORS)
-    target_compile_options(vortex_cxx PRIVATE -Werror)
+add_library(Vortex::cpp_static ALIAS vortex_cxx)
+set(_vortex_cpp_targets vortex_cxx)
+if(BUILD_SHARED_LIBS)
+    set_target_properties(vortex_cxx PROPERTIES EXCLUDE_FROM_ALL TRUE)
+    add_library(vortex_cxx_shared SHARED ${_vortex_cpp_sources})
+    set_target_properties(vortex_cxx_shared PROPERTIES
+        OUTPUT_NAME vortex_cxx
+        CXX_VISIBILITY_PRESET default)
+    target_link_libraries(vortex_cxx_shared PUBLIC Vortex::ffi_shared)
+    add_library(Vortex::cpp_shared ALIAS vortex_cxx_shared)
+    list(APPEND _vortex_cpp_targets vortex_cxx_shared)
 endif()
 
-# The only supported consumer-facing name for the C++ API.
-add_library(Vortex::cpp_static ALIAS vortex_cxx)
+foreach(_target IN LISTS _vortex_cpp_targets)
+    set_target_properties(${_target} PROPERTIES
+        POSITION_INDEPENDENT_CODE ON
+        VISIBILITY_INLINES_HIDDEN ON)
+    target_compile_features(${_target} PUBLIC cxx_std_20)
+    target_include_directories(${_target} PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
+    # Warning policy must not propagate into consumers.
+    target_compile_options(${_target} PRIVATE -Wall -Wextra -Wpedantic)
+    if(VORTEX_WARNINGS_AS_ERRORS)
+        target_compile_options(${_target} PRIVATE -Werror)
+    endif()
+endforeach()
 
 # Test and example dependencies are fetched at configure time and never installed.
 if(VORTEX_BUILD_TESTS OR VORTEX_BUILD_EXAMPLES)
@@ -83,7 +92,12 @@ if(VORTEX_BUILD_TESTS OR VORTEX_BUILD_EXAMPLES)
         SYSTEM
         GIT_REPOSITORY https://github.com/apache/arrow-nanoarrow
         GIT_TAG apache-arrow-nanoarrow-0.8.0)
+    FetchContent_GetProperties(Nanoarrow POPULATED _vortex_nanoarrow_populated)
     FetchContent_MakeAvailable(Nanoarrow)
+    if(NOT _vortex_nanoarrow_populated)
+        # Build only the shared variant used below, without altering a parent's dependency.
+        set_property(DIRECTORY "${nanoarrow_SOURCE_DIR}" PROPERTY EXCLUDE_FROM_ALL TRUE)
+    endif()
     # Suppress Nanoarrow warnings.
     target_compile_options(nanoarrow_static PRIVATE -w)
     target_compile_options(nanoarrow_shared PRIVATE -w)
diff --git a/lang/cpp/README.md b/lang/cpp/README.md
index 950f11fe001..b251ab9eba3 100644
--- a/lang/cpp/README.md
+++ b/lang/cpp/README.md
@@ -17,20 +17,26 @@ cmake --build build/cpp --parallel
 CMake runs Cargo for you. Configuration and builds download uncached dependencies.
 
 **Native builds only:** GNU/Linux x86_64 and aarch64, plus macOS arm64 for standalone development.
-Cross-compilation, universal binaries, Windows, musl, and shared Vortex targets are unsupported.
+Cross-compilation, universal binaries, Windows, and musl are unsupported.
 
 ## Embed in a CMake project
 
 Vendor or fetch a pinned, complete checkout:
 
 ```cmake
+set(BUILD_SHARED_LIBS ON)
 add_subdirectory(path/to/vortex vortex)
-target_link_libraries(my_cpp_target PRIVATE Vortex::cpp_static)
-target_link_libraries(my_c_target PRIVATE Vortex::ffi_static)
+target_link_libraries(my_cpp_target PRIVATE Vortex::cpp_shared)
+target_link_libraries(my_c_target PRIVATE Vortex::ffi_shared)
 ```
 
 Vortex leaves parent build settings unchanged. Its archives are position-independent.
 
+`BUILD_SHARED_LIBS=ON` also selects shared Catch2 libraries when building tests.
+For static linkage, use `Vortex::ffi_static` and `Vortex::cpp_static`; these targets remain
+available in either mode. CMake supplies build-tree runtime paths; deployment requires
+configuring runtime search paths for the application and its shared libraries.
+
 ## Build options
 
 Pass `-D<OPTION>=<VALUE>` or set options before `add_subdirectory`. Both bindings share these
@@ -38,6 +44,7 @@ options. Defaults below are for standalone builds.
 
 | Option                      | Default  | Purpose                                                     |
 | --------------------------- | -------- | ----------------------------------------------------------- |
+| `BUILD_SHARED_LIBS`         | `OFF`    | Select shared Vortex libraries and test dependencies.       |
 | `VORTEX_BUILD_TESTS`        | `OFF`    | C API and C++23 wrapper tests.                              |
 | `VORTEX_BUILD_EXAMPLES`     | `OFF`    | C/C++ examples.                                             |
 | `VORTEX_WARNINGS_AS_ERRORS` | `ON`     | Warnings as errors for Vortex targets only.                 |
@@ -172,7 +179,7 @@ This does not retarget the prebuilt nvCOMP SDK.
 
 - Kernel sources are generated in the checkout. Compiled kernels live in Cargo's build directory
   and are embedded in the archive as fat binaries.
-- CMake does not stage shared libraries. `libvortex_cub.so` must remain at its Cargo build path
+- CMake does not stage CUDA dependency libraries. `libvortex_cub.so` must remain at its Cargo build path
   or beside the executable. `libnvcomp.so` is loaded from its original Cargo build path.
 - CUDA operations require a compatible NVIDIA driver and an accessible GPU.
 
diff --git a/lang/cpp/examples/CMakeLists.txt b/lang/cpp/examples/CMakeLists.txt
index a89908f1078..abcf62a9ec4 100644
--- a/lang/cpp/examples/CMakeLists.txt
+++ b/lang/cpp/examples/CMakeLists.txt
@@ -12,5 +12,10 @@ foreach(_name reader writer dtype scan scan_to_arrow)
         RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
     # Drop the inherited per-config override so the local output directory takes effect.
     set_property(TARGET cpp_${_name} PROPERTY RUNTIME_OUTPUT_DIRECTORY_${_config_upper})
-    target_link_libraries(cpp_${_name} PRIVATE Vortex::cpp_static nanoarrow_shared)
+    if(BUILD_SHARED_LIBS)
+        target_link_libraries(cpp_${_name} PRIVATE Vortex::cpp_shared)
+    else()
+        target_link_libraries(cpp_${_name} PRIVATE Vortex::cpp_static)
+    endif()
 endforeach()
+target_link_libraries(cpp_scan_to_arrow PRIVATE nanoarrow_shared)
diff --git a/lang/cpp/tests/CMakeLists.txt b/lang/cpp/tests/CMakeLists.txt
index 02d8327e4df..7581e0697ef 100644
--- a/lang/cpp/tests/CMakeLists.txt
+++ b/lang/cpp/tests/CMakeLists.txt
@@ -14,8 +14,12 @@ add_executable(vortex_cxx_test ${TEST_FILES})
 # Required by the std::float16_t coverage.
 target_compile_features(vortex_cxx_test PRIVATE cxx_std_23)
 target_include_directories(vortex_cxx_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+if(BUILD_SHARED_LIBS)
+    target_link_libraries(vortex_cxx_test PRIVATE Vortex::cpp_shared)
+else()
+    target_link_libraries(vortex_cxx_test PRIVATE Vortex::cpp_static)
+endif()
 target_link_libraries(vortex_cxx_test PRIVATE
-    Vortex::cpp_static
     Catch2::Catch2WithMain
     magic_enum::magic_enum
     nanoarrow_shared)
diff --git a/vortex-ffi/CMakeLists.txt b/vortex-ffi/CMakeLists.txt
index 8e2db94db14..7e1f00168f1 100644
--- a/vortex-ffi/CMakeLists.txt
+++ b/vortex-ffi/CMakeLists.txt
@@ -33,6 +33,7 @@ if(_vortex_top_level AND NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Debug)
 endif()
 
+option(BUILD_SHARED_LIBS "Build and use shared libraries" OFF)
 option(VORTEX_BUILD_TESTS "Build Vortex tests" OFF)
 option(VORTEX_BUILD_EXAMPLES "Build Vortex examples" OFF)
 option(VORTEX_ENABLE_CUDA "Build the CUDA-enabled Vortex FFI" OFF)
@@ -53,8 +54,10 @@ option(VORTEX_WARNINGS_AS_ERRORS
 # Define the Cargo build and the imported vortex_ffi_static archive.
 include(cmake/Configure.cmake)
 
-# The only supported consumer-facing name for the C API.
 add_library(Vortex::ffi_static ALIAS vortex_ffi_static)
+if(BUILD_SHARED_LIBS)
+    add_library(Vortex::ffi_shared ALIAS vortex_ffi_shared)
+endif()
 
 # Test and example dependencies are fetched at configure time and never installed.
 if(VORTEX_BUILD_TESTS OR VORTEX_BUILD_EXAMPLES)
@@ -67,7 +70,12 @@ if(VORTEX_BUILD_TESTS OR VORTEX_BUILD_EXAMPLES)
         SYSTEM
         GIT_REPOSITORY https://github.com/apache/arrow-nanoarrow
         GIT_TAG apache-arrow-nanoarrow-0.8.0)
+    FetchContent_GetProperties(Nanoarrow POPULATED _vortex_nanoarrow_populated)
     FetchContent_MakeAvailable(Nanoarrow)
+    if(NOT _vortex_nanoarrow_populated)
+        # Build only the shared variant used below, without altering a parent's dependency.
+        set_property(DIRECTORY "${nanoarrow_SOURCE_DIR}" PROPERTY EXCLUDE_FROM_ALL TRUE)
+    endif()
     # Suppress Nanoarrow warnings.
     target_compile_options(nanoarrow_static PRIVATE -w)
     target_compile_options(nanoarrow_shared PRIVATE -w)
diff --git a/vortex-ffi/README.md b/vortex-ffi/README.md
index ac180656359..b040ccf9652 100644
--- a/vortex-ffi/README.md
+++ b/vortex-ffi/README.md
@@ -5,13 +5,14 @@
 Add a complete Vortex checkout. CMake builds the Rust archive for you:
 
 ```cmake
+set(BUILD_SHARED_LIBS ON)
 add_subdirectory(path/to/vortex vortex)
-target_link_libraries(my_target PRIVATE Vortex::ffi_static)
+target_link_libraries(my_target PRIVATE Vortex::ffi_shared)
 ```
 
-The target supplies the archive, headers, and native libraries. You can also add `vortex-ffi`
-directly. See the [CMake build guide](../lang/cpp/README.md) for shared requirements, options,
-and deployment limits.
+The target supplies the library and headers. For static linkage, use `Vortex::ffi_static`.
+You can also add `vortex-ffi` directly. See the [CMake build guide](../lang/cpp/README.md)
+for requirements, options, and deployment limits.
 
 ### Examples and tests
 
diff --git a/vortex-ffi/cmake/Configure.cmake b/vortex-ffi/cmake/Configure.cmake
index 7ae8ad06405..20d1d00bf67 100644
--- a/vortex-ffi/cmake/Configure.cmake
+++ b/vortex-ffi/cmake/Configure.cmake
@@ -373,9 +373,36 @@ block(SCOPE_FOR VARIABLES)
         INTERFACE_INCLUDE_DIRECTORIES "${_ffi_include_dir}")
     add_dependencies(vortex_ffi_static vortex_ffi_cargo_build)
     _vortex_attach_system_dependencies(vortex_ffi_static "${VORTEX_RUST_TARGET}")
+    set(_ffi_targets vortex_ffi_static)
+    if(BUILD_SHARED_LIBS)
+        # Link Rust once, and keep its internal symbols out of the shared C ABI.
+        add_library(vortex_ffi_shared SHARED "${CMAKE_CURRENT_LIST_DIR}/shared.c")
+        if(NOT PROJECT_IS_TOP_LEVEL)
+            set_target_properties(vortex_ffi_shared PROPERTIES EXCLUDE_FROM_ALL TRUE)
+        endif()
+        target_link_libraries(vortex_ffi_shared PRIVATE
+            "$<LINK_LIBRARY:WHOLE_ARCHIVE,vortex_ffi_static>")
+        target_include_directories(vortex_ffi_shared INTERFACE "${_ffi_include_dir}")
+        set_target_properties(vortex_ffi_shared PROPERTIES
+            OUTPUT_NAME vortex_ffi
+            LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/vortex-artifacts")
+        set_property(TARGET vortex_ffi_shared PROPERTY LIBRARY_OUTPUT_DIRECTORY_${_configuration})
+        if(APPLE)
+            target_link_options(vortex_ffi_shared PRIVATE
+                "LINKER:-exported_symbol,_vx_*" "LINKER:-dead_strip")
+        else()
+            set(_exports "${CMAKE_CURRENT_LIST_DIR}/exports.map")
+            target_link_options(vortex_ffi_shared PRIVATE
+                "LINKER:--version-script=${_exports}" "LINKER:--gc-sections")
+            set_property(TARGET vortex_ffi_shared APPEND PROPERTY LINK_DEPENDS "${_exports}")
+        endif()
+        list(APPEND _ffi_targets vortex_ffi_shared)
+    endif()
     if(_sanitizer_compile_flag)
-        target_compile_options(vortex_ffi_static INTERFACE "${_sanitizer_compile_flag}")
-        target_link_options(vortex_ffi_static INTERFACE "${_sanitizer_compile_flag}")
+        foreach(_target IN LISTS _ffi_targets)
+            target_compile_options(${_target} INTERFACE "${_sanitizer_compile_flag}")
+            target_link_options(${_target} INTERFACE "${_sanitizer_compile_flag}")
+        endforeach()
     endif()
 
     message(STATUS "Vortex Rust target: ${VORTEX_RUST_TARGET}")
diff --git a/vortex-ffi/cmake/SystemDependencies.cmake b/vortex-ffi/cmake/SystemDependencies.cmake
index 28168639e71..ede189daf05 100644
--- a/vortex-ffi/cmake/SystemDependencies.cmake
+++ b/vortex-ffi/cmake/SystemDependencies.cmake
@@ -21,7 +21,9 @@ function(_vortex_attach_system_dependencies target rust_target)
         # The archive needs no C++ runtime, so C and C++ consumers alike only
         # need libSystem from their driver plus these extra libraries.
         find_library(_vortex_core_foundation CoreFoundation REQUIRED NO_CACHE)
-        target_link_libraries("${target}" INTERFACE iconv "${_vortex_core_foundation}")
+        find_library(_vortex_security Security REQUIRED NO_CACHE)
+        target_link_libraries("${target}" INTERFACE
+            iconv "${_vortex_core_foundation}" "${_vortex_security}")
     else()
         message(FATAL_ERROR
             "Vortex has no validated native static-link manifest for Rust target "
diff --git a/vortex-ffi/cmake/exports.map b/vortex-ffi/cmake/exports.map
new file mode 100644
index 00000000000..65752b4fe23
--- /dev/null
+++ b/vortex-ffi/cmake/exports.map
@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* SPDX-FileCopyrightText: Copyright the Vortex contributors */
+
+{
+    global: vx_*;
+    local: *;
+};
diff --git a/vortex-ffi/cmake/shared.c b/vortex-ffi/cmake/shared.c
new file mode 100644
index 00000000000..5b6b6284fdf
--- /dev/null
+++ b/vortex-ffi/cmake/shared.c
@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+// The implementation is supplied by the whole-archive Rust dependency.
+#include "vortex.h"
diff --git a/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c b/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
index f1642e2e42a..7f3af7716c5 100644
--- a/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
+++ b/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
@@ -6,4 +6,5 @@
 
 int main(void) {
     printf("%d\n", VORTEX_HEADER_VERSION);
+    return vx_fixture_value() <= 10;
 }
diff --git a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs
index 791eff47e66..8aa92c45a06 100644
--- a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs
+++ b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs
@@ -10,7 +10,10 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     fs::create_dir_all("cinclude")?;
     fs::write(
         "cinclude/vortex.h",
-        format!("#define VORTEX_HEADER_VERSION {}\n", version.trim()),
+        format!(
+            "#define VORTEX_HEADER_VERSION {}\nint vx_fixture_value(void);\n",
+            version.trim()
+        ),
     )?;
     println!("cargo:rerun-if-changed=header-version");
     Ok(())
diff --git a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs
index 576a14aeccf..4d50790a5be 100644
--- a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs
+++ b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs
@@ -2,3 +2,10 @@
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
 pub use native_helper::value;
+
+/// Exercise both native dependencies through the C ABI.
+// SAFETY: This fixture is the only definition of `vx_fixture_value`.
+#[unsafe(no_mangle)]
+pub extern "C" fn vx_fixture_value() -> i32 {
+    value()
+}
diff --git a/vortex-ffi/cmake/tests/test_compiler_commands.py b/vortex-ffi/cmake/tests/test_compiler_commands.py
index 0d2a67c5da0..a247f64e846 100644
--- a/vortex-ffi/cmake/tests/test_compiler_commands.py
+++ b/vortex-ffi/cmake/tests/test_compiler_commands.py
@@ -8,6 +8,7 @@
 import shlex
 import shutil
 import subprocess
+import sys
 import tomllib
 import unittest
 from pathlib import Path
@@ -60,10 +61,11 @@ def configure(
         generator="Ninja",
         build_name=None,
         debug_info=None,
+        build_shared=False,
     ) -> None:
         self.build_dir = self.work / (build_name or f"{generator} build directory's")
         self.target_dir = self.build_dir / "ffi/cargo-target"
-        options = []
+        options = ["-DBUILD_SHARED_LIBS=ON"] if build_shared else []
         if debug_info is not None:
             options.append(f"-DVORTEX_DEBUG_INFO={debug_info}")
         include = self.source / "native-helper/include directory's"
@@ -147,6 +149,31 @@ def test_header_lifecycle(self) -> None:
                 self.assertEqual(self.command(consumer).stdout.strip(), "2")
                 self.assertEqual(staged.read_bytes(), source_header.read_bytes())
 
+    def test_shared_ffi_consumer(self) -> None:
+        cmake_lists = self.source / "CMakeLists.txt"
+        self.write(cmake_lists, cmake_lists.read_text().replace("Vortex::ffi_static", "Vortex::ffi_shared"))
+        self.configure(build_shared=True, build_name="shared build directory")
+        self.build("header_consumer")
+        consumer = self.build_dir / "header_consumer"
+        artifacts = self.build_dir / "ffi/vortex-artifacts"
+        library = artifacts / ("libvortex_ffi.dylib" if sys.platform == "darwin" else "libvortex_ffi.so")
+        self.assertEqual(self.command(consumer).stdout.strip(), "1")
+
+        link = self.command("ninja", "-C", self.build_dir, "-t", "commands", "header_consumer").stdout.splitlines()[-1]
+        self.assertIn(library.name, link)
+        self.assertNotIn("libvortex_ffi.a", link, "The consumer must not relink the Rust static archive")
+        nm_flags = ("-gU",) if sys.platform == "darwin" else ("-D", "--defined-only")
+        exports = self.command("nm", *nm_flags, library).stdout
+        self.assertEqual(
+            {line.split()[-1].removeprefix("_") for line in exports.splitlines() if line.strip()},
+            {"vx_fixture_value"},
+            exports,
+        )
+
+        outputs = snapshot(consumer, library, artifacts / "libvortex_ffi.a", artifacts / "include/vortex.h")
+        self.build("header_consumer")
+        self.assertEqual(snapshot(*outputs), outputs, "An unchanged shared build must remain fresh")
+
     def test_host_target_instrumentation_and_cache_boundary(self) -> None:
         log = self.work / "cache calls.jsonl"
         # Record the cache boundary, not cache behavior; every call still runs the real compiler.
diff --git a/vortex-ffi/cmake/tests/test_configure.py b/vortex-ffi/cmake/tests/test_configure.py
index d7f4c6bf272..fe31fc73180 100644
--- a/vortex-ffi/cmake/tests/test_configure.py
+++ b/vortex-ffi/cmake/tests/test_configure.py
@@ -118,7 +118,7 @@ def test_unused_embedded_ffi_keeps_cargo_lazy(self) -> None:
             add_subdirectory("{self.repo}/vortex-ffi" ffi)
             """,
         ).parent
-        self.configure("lazy", source=source)
+        self.configure("lazy", "-DBUILD_SHARED_LIBS=ON", source=source)
         build = self.work / "lazy"
         self.cmake_build(build)
         self.assertFalse(list(build.rglob("libvortex_ffi.a")))
diff --git a/vortex-ffi/examples/CMakeLists.txt b/vortex-ffi/examples/CMakeLists.txt
index be0fdf18cf2..b1f6043a910 100644
--- a/vortex-ffi/examples/CMakeLists.txt
+++ b/vortex-ffi/examples/CMakeLists.txt
@@ -17,6 +17,10 @@ foreach(_name scan scan_to_arrow dtype write_sample)
     if(VORTEX_WARNINGS_AS_ERRORS)
         target_compile_options(ffi_${_name} PRIVATE -Werror)
     endif()
-    target_link_libraries(ffi_${_name} PRIVATE Vortex::ffi_static)
+    if(BUILD_SHARED_LIBS)
+        target_link_libraries(ffi_${_name} PRIVATE Vortex::ffi_shared)
+    else()
+        target_link_libraries(ffi_${_name} PRIVATE Vortex::ffi_static)
+    endif()
 endforeach()
 target_link_libraries(ffi_scan_to_arrow PRIVATE nanoarrow_shared)
diff --git a/vortex-ffi/test/CMakeLists.txt b/vortex-ffi/test/CMakeLists.txt
index c124a007c81..07daeed9dd0 100644
--- a/vortex-ffi/test/CMakeLists.txt
+++ b/vortex-ffi/test/CMakeLists.txt
@@ -24,8 +24,12 @@ target_compile_options(vortex_ffi_test PRIVATE -Wall -Wextra -Wpedantic)
 if(VORTEX_WARNINGS_AS_ERRORS)
     target_compile_options(vortex_ffi_test PRIVATE -Werror)
 endif()
+if(BUILD_SHARED_LIBS)
+    target_link_libraries(vortex_ffi_test PRIVATE Vortex::ffi_shared)
+else()
+    target_link_libraries(vortex_ffi_test PRIVATE Vortex::ffi_static)
+endif()
 target_link_libraries(vortex_ffi_test PRIVATE
-    Vortex::ffi_static
     Catch2::Catch2WithMain
     nanoarrow_shared)
 

From fb030715efb3d56907b18e4a8d57d8752ef46dda Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Mon, 14 Sep 2026 21:51:36 +0200
Subject: [PATCH 02/14] Simplify shared CMake target selection and test setup

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 .github/workflows/ci.yml                         |  2 --
 lang/cpp/CMakeLists.txt                          |  7 ++-----
 lang/cpp/README.md                               |  3 +--
 lang/cpp/examples/CMakeLists.txt                 |  6 +-----
 lang/cpp/tests/CMakeLists.txt                    |  6 +-----
 vortex-ffi/CMakeLists.txt                        |  7 ++-----
 vortex-ffi/cmake/tests/test_compiler_commands.py | 12 +++++++-----
 vortex-ffi/examples/CMakeLists.txt               |  6 +-----
 vortex-ffi/test/CMakeLists.txt                   |  6 +-----
 9 files changed, 16 insertions(+), 39 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7e7e5488812..bb9687ec0ee 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -677,8 +677,6 @@ jobs:
             -DVORTEX_DEBUG_INFO=2 \
             -DCMAKE_C_COMPILER=clang \
             -DCMAKE_CXX_COMPILER=clang++ \
-            -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=mold \
-            -DCMAKE_SHARED_LINKER_FLAGS=-fuse-ld=mold \
             -DVORTEX_SANITIZER=asan \
             -DVORTEX_SANITIZE_RUST_STD=ON \
             -DVORTEX_BUILD_TESTS=ON \
diff --git a/lang/cpp/CMakeLists.txt b/lang/cpp/CMakeLists.txt
index 62bbe1cfd70..ba292e46e11 100644
--- a/lang/cpp/CMakeLists.txt
+++ b/lang/cpp/CMakeLists.txt
@@ -56,6 +56,7 @@ add_library(vortex_cxx STATIC ${_vortex_cpp_sources})
 set_target_properties(vortex_cxx PROPERTIES CXX_VISIBILITY_PRESET hidden)
 target_link_libraries(vortex_cxx PUBLIC Vortex::ffi_static)
 add_library(Vortex::cpp_static ALIAS vortex_cxx)
+set(_vortex_cpp_target Vortex::cpp_static)
 set(_vortex_cpp_targets vortex_cxx)
 if(BUILD_SHARED_LIBS)
     set_target_properties(vortex_cxx PROPERTIES EXCLUDE_FROM_ALL TRUE)
@@ -65,6 +66,7 @@ if(BUILD_SHARED_LIBS)
         CXX_VISIBILITY_PRESET default)
     target_link_libraries(vortex_cxx_shared PUBLIC Vortex::ffi_shared)
     add_library(Vortex::cpp_shared ALIAS vortex_cxx_shared)
+    set(_vortex_cpp_target Vortex::cpp_shared)
     list(APPEND _vortex_cpp_targets vortex_cxx_shared)
 endif()
 
@@ -92,12 +94,7 @@ if(VORTEX_BUILD_TESTS OR VORTEX_BUILD_EXAMPLES)
         SYSTEM
         GIT_REPOSITORY https://github.com/apache/arrow-nanoarrow
         GIT_TAG apache-arrow-nanoarrow-0.8.0)
-    FetchContent_GetProperties(Nanoarrow POPULATED _vortex_nanoarrow_populated)
     FetchContent_MakeAvailable(Nanoarrow)
-    if(NOT _vortex_nanoarrow_populated)
-        # Build only the shared variant used below, without altering a parent's dependency.
-        set_property(DIRECTORY "${nanoarrow_SOURCE_DIR}" PROPERTY EXCLUDE_FROM_ALL TRUE)
-    endif()
     # Suppress Nanoarrow warnings.
     target_compile_options(nanoarrow_static PRIVATE -w)
     target_compile_options(nanoarrow_shared PRIVATE -w)
diff --git a/lang/cpp/README.md b/lang/cpp/README.md
index b251ab9eba3..b7d90809e51 100644
--- a/lang/cpp/README.md
+++ b/lang/cpp/README.md
@@ -32,7 +32,6 @@ target_link_libraries(my_c_target PRIVATE Vortex::ffi_shared)
 
 Vortex leaves parent build settings unchanged. Its archives are position-independent.
 
-`BUILD_SHARED_LIBS=ON` also selects shared Catch2 libraries when building tests.
 For static linkage, use `Vortex::ffi_static` and `Vortex::cpp_static`; these targets remain
 available in either mode. CMake supplies build-tree runtime paths; deployment requires
 configuring runtime search paths for the application and its shared libraries.
@@ -44,7 +43,7 @@ options. Defaults below are for standalone builds.
 
 | Option                      | Default  | Purpose                                                     |
 | --------------------------- | -------- | ----------------------------------------------------------- |
-| `BUILD_SHARED_LIBS`         | `OFF`    | Select shared Vortex libraries and test dependencies.       |
+| `BUILD_SHARED_LIBS`         | `OFF`    | Build shared Vortex libraries and Catch2.                   |
 | `VORTEX_BUILD_TESTS`        | `OFF`    | C API and C++23 wrapper tests.                              |
 | `VORTEX_BUILD_EXAMPLES`     | `OFF`    | C/C++ examples.                                             |
 | `VORTEX_WARNINGS_AS_ERRORS` | `ON`     | Warnings as errors for Vortex targets only.                 |
diff --git a/lang/cpp/examples/CMakeLists.txt b/lang/cpp/examples/CMakeLists.txt
index abcf62a9ec4..f5edc544957 100644
--- a/lang/cpp/examples/CMakeLists.txt
+++ b/lang/cpp/examples/CMakeLists.txt
@@ -12,10 +12,6 @@ foreach(_name reader writer dtype scan scan_to_arrow)
         RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
     # Drop the inherited per-config override so the local output directory takes effect.
     set_property(TARGET cpp_${_name} PROPERTY RUNTIME_OUTPUT_DIRECTORY_${_config_upper})
-    if(BUILD_SHARED_LIBS)
-        target_link_libraries(cpp_${_name} PRIVATE Vortex::cpp_shared)
-    else()
-        target_link_libraries(cpp_${_name} PRIVATE Vortex::cpp_static)
-    endif()
+    target_link_libraries(cpp_${_name} PRIVATE ${_vortex_cpp_target})
 endforeach()
 target_link_libraries(cpp_scan_to_arrow PRIVATE nanoarrow_shared)
diff --git a/lang/cpp/tests/CMakeLists.txt b/lang/cpp/tests/CMakeLists.txt
index 7581e0697ef..d9e96f12c1b 100644
--- a/lang/cpp/tests/CMakeLists.txt
+++ b/lang/cpp/tests/CMakeLists.txt
@@ -14,12 +14,8 @@ add_executable(vortex_cxx_test ${TEST_FILES})
 # Required by the std::float16_t coverage.
 target_compile_features(vortex_cxx_test PRIVATE cxx_std_23)
 target_include_directories(vortex_cxx_test PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
-if(BUILD_SHARED_LIBS)
-    target_link_libraries(vortex_cxx_test PRIVATE Vortex::cpp_shared)
-else()
-    target_link_libraries(vortex_cxx_test PRIVATE Vortex::cpp_static)
-endif()
 target_link_libraries(vortex_cxx_test PRIVATE
+    ${_vortex_cpp_target}
     Catch2::Catch2WithMain
     magic_enum::magic_enum
     nanoarrow_shared)
diff --git a/vortex-ffi/CMakeLists.txt b/vortex-ffi/CMakeLists.txt
index 7e1f00168f1..588f21c1132 100644
--- a/vortex-ffi/CMakeLists.txt
+++ b/vortex-ffi/CMakeLists.txt
@@ -55,8 +55,10 @@ option(VORTEX_WARNINGS_AS_ERRORS
 include(cmake/Configure.cmake)
 
 add_library(Vortex::ffi_static ALIAS vortex_ffi_static)
+set(_vortex_ffi_target Vortex::ffi_static)
 if(BUILD_SHARED_LIBS)
     add_library(Vortex::ffi_shared ALIAS vortex_ffi_shared)
+    set(_vortex_ffi_target Vortex::ffi_shared)
 endif()
 
 # Test and example dependencies are fetched at configure time and never installed.
@@ -70,12 +72,7 @@ if(VORTEX_BUILD_TESTS OR VORTEX_BUILD_EXAMPLES)
         SYSTEM
         GIT_REPOSITORY https://github.com/apache/arrow-nanoarrow
         GIT_TAG apache-arrow-nanoarrow-0.8.0)
-    FetchContent_GetProperties(Nanoarrow POPULATED _vortex_nanoarrow_populated)
     FetchContent_MakeAvailable(Nanoarrow)
-    if(NOT _vortex_nanoarrow_populated)
-        # Build only the shared variant used below, without altering a parent's dependency.
-        set_property(DIRECTORY "${nanoarrow_SOURCE_DIR}" PROPERTY EXCLUDE_FROM_ALL TRUE)
-    endif()
     # Suppress Nanoarrow warnings.
     target_compile_options(nanoarrow_static PRIVATE -w)
     target_compile_options(nanoarrow_shared PRIVATE -w)
diff --git a/vortex-ffi/cmake/tests/test_compiler_commands.py b/vortex-ffi/cmake/tests/test_compiler_commands.py
index a247f64e846..1ae6a39f9c4 100644
--- a/vortex-ffi/cmake/tests/test_compiler_commands.py
+++ b/vortex-ffi/cmake/tests/test_compiler_commands.py
@@ -61,11 +61,10 @@ def configure(
         generator="Ninja",
         build_name=None,
         debug_info=None,
-        build_shared=False,
     ) -> None:
         self.build_dir = self.work / (build_name or f"{generator} build directory's")
         self.target_dir = self.build_dir / "ffi/cargo-target"
-        options = ["-DBUILD_SHARED_LIBS=ON"] if build_shared else []
+        options = []
         if debug_info is not None:
             options.append(f"-DVORTEX_DEBUG_INFO={debug_info}")
         include = self.source / "native-helper/include directory's"
@@ -151,13 +150,16 @@ def test_header_lifecycle(self) -> None:
 
     def test_shared_ffi_consumer(self) -> None:
         cmake_lists = self.source / "CMakeLists.txt"
-        self.write(cmake_lists, cmake_lists.read_text().replace("Vortex::ffi_static", "Vortex::ffi_shared"))
-        self.configure(build_shared=True, build_name="shared build directory")
+        self.write(
+            cmake_lists,
+            "set(BUILD_SHARED_LIBS ON)\n" + cmake_lists.read_text().replace("Vortex::ffi_static", "Vortex::ffi_shared"),
+        )
+        self.configure(build_name="shared build directory")
         self.build("header_consumer")
         consumer = self.build_dir / "header_consumer"
         artifacts = self.build_dir / "ffi/vortex-artifacts"
         library = artifacts / ("libvortex_ffi.dylib" if sys.platform == "darwin" else "libvortex_ffi.so")
-        self.assertEqual(self.command(consumer).stdout.strip(), "1")
+        self.command(consumer)
 
         link = self.command("ninja", "-C", self.build_dir, "-t", "commands", "header_consumer").stdout.splitlines()[-1]
         self.assertIn(library.name, link)
diff --git a/vortex-ffi/examples/CMakeLists.txt b/vortex-ffi/examples/CMakeLists.txt
index b1f6043a910..14c69ae479b 100644
--- a/vortex-ffi/examples/CMakeLists.txt
+++ b/vortex-ffi/examples/CMakeLists.txt
@@ -17,10 +17,6 @@ foreach(_name scan scan_to_arrow dtype write_sample)
     if(VORTEX_WARNINGS_AS_ERRORS)
         target_compile_options(ffi_${_name} PRIVATE -Werror)
     endif()
-    if(BUILD_SHARED_LIBS)
-        target_link_libraries(ffi_${_name} PRIVATE Vortex::ffi_shared)
-    else()
-        target_link_libraries(ffi_${_name} PRIVATE Vortex::ffi_static)
-    endif()
+    target_link_libraries(ffi_${_name} PRIVATE ${_vortex_ffi_target})
 endforeach()
 target_link_libraries(ffi_scan_to_arrow PRIVATE nanoarrow_shared)
diff --git a/vortex-ffi/test/CMakeLists.txt b/vortex-ffi/test/CMakeLists.txt
index 07daeed9dd0..cfe0a967880 100644
--- a/vortex-ffi/test/CMakeLists.txt
+++ b/vortex-ffi/test/CMakeLists.txt
@@ -24,12 +24,8 @@ target_compile_options(vortex_ffi_test PRIVATE -Wall -Wextra -Wpedantic)
 if(VORTEX_WARNINGS_AS_ERRORS)
     target_compile_options(vortex_ffi_test PRIVATE -Werror)
 endif()
-if(BUILD_SHARED_LIBS)
-    target_link_libraries(vortex_ffi_test PRIVATE Vortex::ffi_shared)
-else()
-    target_link_libraries(vortex_ffi_test PRIVATE Vortex::ffi_static)
-endif()
 target_link_libraries(vortex_ffi_test PRIVATE
+    ${_vortex_ffi_target}
     Catch2::Catch2WithMain
     nanoarrow_shared)
 

From d83c9d002525e2aebc725fd5602f2007d96eaa5a Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 08:30:15 +0200
Subject: [PATCH 03/14] fix(cmake): expose static and shared targets
 independently

Let BUILD_SHARED_LIBS select default builds and test/example linkage without controlling target availability.

Generate the Linux export policy in the build tree, document linker settings, reject unsupported export platforms, and honor CMake output directories.

Assert exact fixture results and cover explicit shared linkage with BUILD_SHARED_LIBS off. Remove the redundant CI debug-info flag while retaining full symbols through the default level of 2 for sanitizer diagnostics.


Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 .github/workflows/ci.yml                      |  1 -
 CMakeLists.txt                                |  2 +
 lang/cpp/CMakeLists.txt                       | 33 ++++++-----
 lang/cpp/README.md                            | 11 ++--
 vortex-ffi/CMakeLists.txt                     | 16 +++---
 vortex-ffi/README.md                          |  6 +-
 vortex-ffi/cmake/Configure.cmake              | 55 ++++++++++---------
 vortex-ffi/cmake/exports.map                  |  7 ---
 .../tests/fixtures/native/header_consumer.c   |  4 +-
 .../cmake/tests/test_compiler_commands.py     | 15 ++---
 vortex-ffi/cmake/tests/test_configure.py      |  5 ++
 11 files changed, 80 insertions(+), 75 deletions(-)
 delete mode 100644 vortex-ffi/cmake/exports.map

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bb9687ec0ee..e8a7e67c9a1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -674,7 +674,6 @@ jobs:
           cmake -S lang/cpp -B build \
             -DCMAKE_BUILD_TYPE=Debug \
             -DBUILD_SHARED_LIBS=ON \
-            -DVORTEX_DEBUG_INFO=2 \
             -DCMAKE_C_COMPILER=clang \
             -DCMAKE_CXX_COMPILER=clang++ \
             -DVORTEX_SANITIZER=asan \
diff --git a/CMakeLists.txt b/CMakeLists.txt
index dd146ef57c8..883a29a2e3c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -8,6 +8,8 @@
 #   target_link_libraries(my_c_target PRIVATE Vortex::ffi_static)
 #   target_link_libraries(my_cpp_target PRIVATE Vortex::cpp_static)
 #
+# Use Vortex::ffi_shared and Vortex::cpp_shared for shared linkage.
+#
 # See lang/cpp/README.md for build options and embedding requirements,
 # and vortex-ffi/README.md for C API development.
 
diff --git a/lang/cpp/CMakeLists.txt b/lang/cpp/CMakeLists.txt
index ba292e46e11..d338095c85a 100644
--- a/lang/cpp/CMakeLists.txt
+++ b/lang/cpp/CMakeLists.txt
@@ -33,7 +33,7 @@ if(_vortex_top_level AND NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Debug)
 endif()
 
-option(BUILD_SHARED_LIBS "Build and use shared libraries" OFF)
+option(BUILD_SHARED_LIBS "Use shared libraries for Vortex builds, tests, and examples" OFF)
 option(VORTEX_BUILD_TESTS "Build Vortex tests" OFF)
 option(VORTEX_BUILD_EXAMPLES "Build Vortex examples" OFF)
 option(VORTEX_WARNINGS_AS_ERRORS
@@ -53,27 +53,30 @@ file(GLOB _vortex_cpp_sources CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src
 
 # Preserve the static API and its hidden symbols for embedding in other DSOs.
 add_library(vortex_cxx STATIC ${_vortex_cpp_sources})
-set_target_properties(vortex_cxx PROPERTIES CXX_VISIBILITY_PRESET hidden)
+set_target_properties(vortex_cxx PROPERTIES
+    POSITION_INDEPENDENT_CODE ON
+    CXX_VISIBILITY_PRESET hidden)
 target_link_libraries(vortex_cxx PUBLIC Vortex::ffi_static)
 add_library(Vortex::cpp_static ALIAS vortex_cxx)
-set(_vortex_cpp_target Vortex::cpp_static)
-set(_vortex_cpp_targets vortex_cxx)
+
+add_library(vortex_cxx_shared SHARED ${_vortex_cpp_sources})
+# Override an inherited hidden preset so the shared C++ API remains exported.
+set_target_properties(vortex_cxx_shared PROPERTIES
+    OUTPUT_NAME vortex_cxx
+    CXX_VISIBILITY_PRESET default)
+target_link_libraries(vortex_cxx_shared PUBLIC Vortex::ffi_shared)
+add_library(Vortex::cpp_shared ALIAS vortex_cxx_shared)
+
 if(BUILD_SHARED_LIBS)
     set_target_properties(vortex_cxx PROPERTIES EXCLUDE_FROM_ALL TRUE)
-    add_library(vortex_cxx_shared SHARED ${_vortex_cpp_sources})
-    set_target_properties(vortex_cxx_shared PROPERTIES
-        OUTPUT_NAME vortex_cxx
-        CXX_VISIBILITY_PRESET default)
-    target_link_libraries(vortex_cxx_shared PUBLIC Vortex::ffi_shared)
-    add_library(Vortex::cpp_shared ALIAS vortex_cxx_shared)
     set(_vortex_cpp_target Vortex::cpp_shared)
-    list(APPEND _vortex_cpp_targets vortex_cxx_shared)
+else()
+    set_target_properties(vortex_cxx_shared PROPERTIES EXCLUDE_FROM_ALL TRUE)
+    set(_vortex_cpp_target Vortex::cpp_static)
 endif()
 
-foreach(_target IN LISTS _vortex_cpp_targets)
-    set_target_properties(${_target} PROPERTIES
-        POSITION_INDEPENDENT_CODE ON
-        VISIBILITY_INLINES_HIDDEN ON)
+foreach(_target IN ITEMS vortex_cxx vortex_cxx_shared)
+    set_target_properties(${_target} PROPERTIES VISIBILITY_INLINES_HIDDEN ON)
     target_compile_features(${_target} PUBLIC cxx_std_20)
     target_include_directories(${_target} PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
     # Warning policy must not propagate into consumers.
diff --git a/lang/cpp/README.md b/lang/cpp/README.md
index b7d90809e51..751626d0794 100644
--- a/lang/cpp/README.md
+++ b/lang/cpp/README.md
@@ -24,7 +24,6 @@ Cross-compilation, universal binaries, Windows, and musl are unsupported.
 Vendor or fetch a pinned, complete checkout:
 
 ```cmake
-set(BUILD_SHARED_LIBS ON)
 add_subdirectory(path/to/vortex vortex)
 target_link_libraries(my_cpp_target PRIVATE Vortex::cpp_shared)
 target_link_libraries(my_c_target PRIVATE Vortex::ffi_shared)
@@ -32,9 +31,10 @@ target_link_libraries(my_c_target PRIVATE Vortex::ffi_shared)
 
 Vortex leaves parent build settings unchanged. Its archives are position-independent.
 
-For static linkage, use `Vortex::ffi_static` and `Vortex::cpp_static`; these targets remain
-available in either mode. CMake supplies build-tree runtime paths; deployment requires
-configuring runtime search paths for the application and its shared libraries.
+For static linkage, use `Vortex::ffi_static` and `Vortex::cpp_static`. Both flavours are always
+available; `BUILD_SHARED_LIBS` selects the default build and linkage for Vortex's tests and
+examples. CMake supplies build-tree runtime paths; deployment requires configuring runtime
+search paths for the application and its shared libraries.
 
 ## Build options
 
@@ -43,7 +43,7 @@ options. Defaults below are for standalone builds.
 
 | Option                      | Default  | Purpose                                                     |
 | --------------------------- | -------- | ----------------------------------------------------------- |
-| `BUILD_SHARED_LIBS`         | `OFF`    | Build shared Vortex libraries and Catch2.                   |
+| `BUILD_SHARED_LIBS`         | `OFF`    | Build shared Vortex libraries.                              |
 | `VORTEX_BUILD_TESTS`        | `OFF`    | C API and C++23 wrapper tests.                              |
 | `VORTEX_BUILD_EXAMPLES`     | `OFF`    | C/C++ examples.                                             |
 | `VORTEX_WARNINGS_AS_ERRORS` | `ON`     | Warnings as errors for Vortex targets only.                 |
@@ -54,6 +54,7 @@ options. Defaults below are for standalone builds.
 | `VORTEX_DEBUG_INFO`         | `2`      | C/C++ and Rust debug info: `0` none, `1` limited, `2` full. |
 | `VORTEX_ENABLE_CUDA`        | `OFF`    | Linux-only [CUDA build](#cuda).                             |
 
+As a standard CMake option, `BUILD_SHARED_LIBS` also affects dependencies such as Catch2.
 Embedded builds default `VORTEX_WARNINGS_AS_ERRORS` to `OFF`. Parents must call
 `enable_testing()` to register tests.
 
diff --git a/vortex-ffi/CMakeLists.txt b/vortex-ffi/CMakeLists.txt
index 588f21c1132..ecd4aa90887 100644
--- a/vortex-ffi/CMakeLists.txt
+++ b/vortex-ffi/CMakeLists.txt
@@ -1,9 +1,9 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright the Vortex contributors
 
-# Entry point for the Rust FFI archive. It builds vortex-ffi with Cargo and
-# exports Vortex::ffi_static for C consumers; lang/cpp layers the C++ wrapper on
-# top. It supports standalone configuration and add_subdirectory() from a parent.
+# Entry point for the Rust FFI libraries. It exports Vortex::ffi_static and
+# Vortex::ffi_shared for C consumers; lang/cpp layers the C++ wrapper on top.
+# It supports standalone configuration and add_subdirectory() from a parent.
 
 # CMake 3.25 is required for block() and FetchContent SYSTEM.
 cmake_minimum_required(VERSION 3.25)
@@ -33,14 +33,14 @@ if(_vortex_top_level AND NOT CMAKE_BUILD_TYPE)
     set(CMAKE_BUILD_TYPE Debug)
 endif()
 
-option(BUILD_SHARED_LIBS "Build and use shared libraries" OFF)
+option(BUILD_SHARED_LIBS "Use shared libraries for Vortex builds, tests, and examples" OFF)
 option(VORTEX_BUILD_TESTS "Build Vortex tests" OFF)
 option(VORTEX_BUILD_EXAMPLES "Build Vortex examples" OFF)
 option(VORTEX_ENABLE_CUDA "Build the CUDA-enabled Vortex FFI" OFF)
 set(VORTEX_CARGO_PROFILE "" CACHE STRING "Override the Cargo profile selected from CMAKE_BUILD_TYPE")
 
-# Sanitizers instrument the Rust archive, its C dependencies, and every target
-# that links Vortex::ffi_static; Configure.cmake enforces the toolchain constraints.
+# Sanitizers instrument the Rust archive, its C dependencies, and consumers of
+# either FFI target; Configure.cmake enforces the toolchain constraints.
 set(VORTEX_SANITIZER "" CACHE STRING
     "Comma-separated sanitizers for Vortex and its consumers: asan, lsan, ubsan, tsan")
 option(VORTEX_SANITIZE_RUST_STD
@@ -51,13 +51,13 @@ option(VORTEX_WARNINGS_AS_ERRORS
     "Treat warnings in Vortex-owned sources as errors"
     "${_vortex_top_level}")
 
-# Define the Cargo build and the imported vortex_ffi_static archive.
+# Define the Cargo build and both FFI library targets.
 include(cmake/Configure.cmake)
 
 add_library(Vortex::ffi_static ALIAS vortex_ffi_static)
+add_library(Vortex::ffi_shared ALIAS vortex_ffi_shared)
 set(_vortex_ffi_target Vortex::ffi_static)
 if(BUILD_SHARED_LIBS)
-    add_library(Vortex::ffi_shared ALIAS vortex_ffi_shared)
     set(_vortex_ffi_target Vortex::ffi_shared)
 endif()
 
diff --git a/vortex-ffi/README.md b/vortex-ffi/README.md
index b040ccf9652..aede05497b8 100644
--- a/vortex-ffi/README.md
+++ b/vortex-ffi/README.md
@@ -5,14 +5,14 @@
 Add a complete Vortex checkout. CMake builds the Rust archive for you:
 
 ```cmake
-set(BUILD_SHARED_LIBS ON)
 add_subdirectory(path/to/vortex vortex)
 target_link_libraries(my_target PRIVATE Vortex::ffi_shared)
 ```
 
 The target supplies the library and headers. For static linkage, use `Vortex::ffi_static`.
-You can also add `vortex-ffi` directly. See the [CMake build guide](../lang/cpp/README.md)
-for requirements, options, and deployment limits.
+Both targets are available regardless of `BUILD_SHARED_LIBS`. You can also add `vortex-ffi`
+directly. See the [CMake build guide](../lang/cpp/README.md) for requirements, options, and
+deployment limits.
 
 ### Examples and tests
 
diff --git a/vortex-ffi/cmake/Configure.cmake b/vortex-ffi/cmake/Configure.cmake
index 20d1d00bf67..1571b504563 100644
--- a/vortex-ffi/cmake/Configure.cmake
+++ b/vortex-ffi/cmake/Configure.cmake
@@ -373,33 +373,38 @@ block(SCOPE_FOR VARIABLES)
         INTERFACE_INCLUDE_DIRECTORIES "${_ffi_include_dir}")
     add_dependencies(vortex_ffi_static vortex_ffi_cargo_build)
     _vortex_attach_system_dependencies(vortex_ffi_static "${VORTEX_RUST_TARGET}")
-    set(_ffi_targets vortex_ffi_static)
-    if(BUILD_SHARED_LIBS)
-        # Link Rust once, and keep its internal symbols out of the shared C ABI.
-        add_library(vortex_ffi_shared SHARED "${CMAKE_CURRENT_LIST_DIR}/shared.c")
-        if(NOT PROJECT_IS_TOP_LEVEL)
-            set_target_properties(vortex_ffi_shared PROPERTIES EXCLUDE_FROM_ALL TRUE)
-        endif()
-        target_link_libraries(vortex_ffi_shared PRIVATE
-            "$<LINK_LIBRARY:WHOLE_ARCHIVE,vortex_ffi_static>")
-        target_include_directories(vortex_ffi_shared INTERFACE "${_ffi_include_dir}")
-        set_target_properties(vortex_ffi_shared PROPERTIES
-            OUTPUT_NAME vortex_ffi
-            LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/vortex-artifacts")
-        set_property(TARGET vortex_ffi_shared PROPERTY LIBRARY_OUTPUT_DIRECTORY_${_configuration})
-        if(APPLE)
-            target_link_options(vortex_ffi_shared PRIVATE
-                "LINKER:-exported_symbol,_vx_*" "LINKER:-dead_strip")
-        else()
-            set(_exports "${CMAKE_CURRENT_LIST_DIR}/exports.map")
-            target_link_options(vortex_ffi_shared PRIVATE
-                "LINKER:--version-script=${_exports}" "LINKER:--gc-sections")
-            set_property(TARGET vortex_ffi_shared APPEND PROPERTY LINK_DEPENDS "${_exports}")
-        endif()
-        list(APPEND _ffi_targets vortex_ffi_shared)
+    # Link Rust once, and keep its internal symbols out of the shared C ABI.
+    add_library(vortex_ffi_shared SHARED "${CMAKE_CURRENT_LIST_DIR}/shared.c")
+    if(NOT BUILD_SHARED_LIBS OR NOT PROJECT_IS_TOP_LEVEL)
+        set_target_properties(vortex_ffi_shared PROPERTIES EXCLUDE_FROM_ALL TRUE)
+    endif()
+    target_link_libraries(vortex_ffi_shared PRIVATE
+        "$<LINK_LIBRARY:WHOLE_ARCHIVE,vortex_ffi_static>")
+    target_include_directories(vortex_ffi_shared INTERFACE "${_ffi_include_dir}")
+    set_target_properties(vortex_ffi_shared PROPERTIES OUTPUT_NAME vortex_ffi)
+    if(APPLE)
+        target_link_options(vortex_ffi_shared PRIVATE
+            # Export only the C ABI; Mach-O prefixes C symbols with an underscore.
+            "LINKER:-exported_symbol,_vx_*"
+            # Discard unreachable code and data pulled in by whole-archive linking.
+            "LINKER:-dead_strip")
+    elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+        # Keep the generated linker script in the build tree.
+        set(_exports "${CMAKE_CURRENT_BINARY_DIR}/vortex-ffi-exports.map")
+        # Export vx_*; localize all other symbols. GENERATE preserves unchanged timestamps.
+        file(GENERATE OUTPUT "${_exports}" CONTENT "{ global: vx_*; local: *; };\n")
+        target_link_options(vortex_ffi_shared PRIVATE
+            # Apply the export allowlist to the Rust archive and its dependencies.
+            "LINKER:--version-script=${_exports}"
+            # Discard sections unreachable from exported symbols and other linker roots.
+            "LINKER:--gc-sections")
+        # Relink if the generated export policy changes.
+        set_property(TARGET vortex_ffi_shared APPEND PROPERTY LINK_DEPENDS "${_exports}")
+    else()
+        message(FATAL_ERROR "Vortex shared-library exports are not configured for ${CMAKE_SYSTEM_NAME}")
     endif()
     if(_sanitizer_compile_flag)
-        foreach(_target IN LISTS _ffi_targets)
+        foreach(_target IN ITEMS vortex_ffi_static vortex_ffi_shared)
             target_compile_options(${_target} INTERFACE "${_sanitizer_compile_flag}")
             target_link_options(${_target} INTERFACE "${_sanitizer_compile_flag}")
         endforeach()
diff --git a/vortex-ffi/cmake/exports.map b/vortex-ffi/cmake/exports.map
deleted file mode 100644
index 65752b4fe23..00000000000
--- a/vortex-ffi/cmake/exports.map
+++ /dev/null
@@ -1,7 +0,0 @@
-/* SPDX-License-Identifier: Apache-2.0 */
-/* SPDX-FileCopyrightText: Copyright the Vortex contributors */
-
-{
-    global: vx_*;
-    local: *;
-};
diff --git a/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c b/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
index 7f3af7716c5..609918b4ae0 100644
--- a/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
+++ b/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
@@ -5,6 +5,6 @@
 #include <vortex.h>
 
 int main(void) {
-    printf("%d\n", VORTEX_HEADER_VERSION);
-    return vx_fixture_value() <= 10;
+    printf("%d %d\n", VORTEX_HEADER_VERSION, vx_fixture_value());
+    return 0;
 }
diff --git a/vortex-ffi/cmake/tests/test_compiler_commands.py b/vortex-ffi/cmake/tests/test_compiler_commands.py
index 1ae6a39f9c4..f8aa1c046ad 100644
--- a/vortex-ffi/cmake/tests/test_compiler_commands.py
+++ b/vortex-ffi/cmake/tests/test_compiler_commands.py
@@ -130,11 +130,11 @@ def test_header_lifecycle(self) -> None:
                 staged = self.build_dir / "ffi/vortex-artifacts/include/vortex.h"
                 archive = self.build_dir / "ffi/vortex-artifacts/libvortex_ffi.a"
                 self.build("header_consumer")
-                self.assertEqual(self.command(consumer).stdout.strip(), "1")
+                self.assertEqual(self.command(consumer).stdout.strip(), "1 46")
                 archive_state = snapshot(archive)
                 self.write(version, "2\n")
                 self.build("header_consumer")
-                self.assertEqual(self.command(consumer).stdout.strip(), "2", "Must update on the first build")
+                self.assertEqual(self.command(consumer).stdout.strip(), "2 46", "Must update on the first build")
                 self.assertEqual(snapshot(archive), archive_state, "Header-only change must leave archive identical")
                 self.assertEqual(staged.read_bytes(), source_header.read_bytes())
                 outputs = snapshot(archive, staged, source_header, consumer, *self.build_dir.rglob("*.o"))
@@ -145,21 +145,18 @@ def test_header_lifecycle(self) -> None:
                     self.assertFalse(path.exists(), path)
                 self.assertEqual(snapshot(source_header), {source_header: outputs[source_header]})
                 self.build("header_consumer")
-                self.assertEqual(self.command(consumer).stdout.strip(), "2")
+                self.assertEqual(self.command(consumer).stdout.strip(), "2 46")
                 self.assertEqual(staged.read_bytes(), source_header.read_bytes())
 
     def test_shared_ffi_consumer(self) -> None:
         cmake_lists = self.source / "CMakeLists.txt"
-        self.write(
-            cmake_lists,
-            "set(BUILD_SHARED_LIBS ON)\n" + cmake_lists.read_text().replace("Vortex::ffi_static", "Vortex::ffi_shared"),
-        )
+        self.write(cmake_lists, cmake_lists.read_text().replace("Vortex::ffi_static", "Vortex::ffi_shared"))
         self.configure(build_name="shared build directory")
         self.build("header_consumer")
         consumer = self.build_dir / "header_consumer"
         artifacts = self.build_dir / "ffi/vortex-artifacts"
-        library = artifacts / ("libvortex_ffi.dylib" if sys.platform == "darwin" else "libvortex_ffi.so")
-        self.command(consumer)
+        library = self.build_dir / "ffi" / ("libvortex_ffi.dylib" if sys.platform == "darwin" else "libvortex_ffi.so")
+        self.assertEqual(self.command(consumer).stdout.strip(), "1 46")
 
         link = self.command("ninja", "-C", self.build_dir, "-t", "commands", "header_consumer").stdout.splitlines()[-1]
         self.assertIn(library.name, link)
diff --git a/vortex-ffi/cmake/tests/test_configure.py b/vortex-ffi/cmake/tests/test_configure.py
index fe31fc73180..26ba9bee52d 100644
--- a/vortex-ffi/cmake/tests/test_configure.py
+++ b/vortex-ffi/cmake/tests/test_configure.py
@@ -94,6 +94,11 @@ def test_embedded_root_preserves_parent_variables(self) -> None:
             set(CMAKE_BUILD_TYPE "")
             set(_vortex_top_level ON)
             add_subdirectory("{self.repo}" vortex EXCLUDE_FROM_ALL)
+            foreach(target IN ITEMS Vortex::ffi_static Vortex::ffi_shared Vortex::cpp_static Vortex::cpp_shared)
+                if(NOT TARGET ${{target}})
+                    message(FATAL_ERROR "Missing target: ${{target}}")
+                endif()
+            endforeach()
             if(NOT CMAKE_BUILD_TYPE STREQUAL "" OR NOT _vortex_top_level STREQUAL "ON")
                 message(FATAL_ERROR "Vortex changed parent variables")
             endif()

From 699a94f538f49d12045d8b57c66d43ded59c382a Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 09:47:54 +0200
Subject: [PATCH 04/14] fix

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/README.md                                | 5 +----
 vortex-ffi/cmake/tests/test_compiler_commands.py  | 6 ++++--
 vortex-ffi/cmake/tests/test_cuda_architectures.py | 2 +-
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/lang/cpp/README.md b/lang/cpp/README.md
index 751626d0794..14c93312ae9 100644
--- a/lang/cpp/README.md
+++ b/lang/cpp/README.md
@@ -31,10 +31,7 @@ target_link_libraries(my_c_target PRIVATE Vortex::ffi_shared)
 
 Vortex leaves parent build settings unchanged. Its archives are position-independent.
 
-For static linkage, use `Vortex::ffi_static` and `Vortex::cpp_static`. Both flavours are always
-available; `BUILD_SHARED_LIBS` selects the default build and linkage for Vortex's tests and
-examples. CMake supplies build-tree runtime paths; deployment requires configuring runtime
-search paths for the application and its shared libraries.
+For static linkage, use `Vortex::ffi_static` and `Vortex::cpp_static`.
 
 ## Build options
 
diff --git a/vortex-ffi/cmake/tests/test_compiler_commands.py b/vortex-ffi/cmake/tests/test_compiler_commands.py
index f8aa1c046ad..2d45182158f 100644
--- a/vortex-ffi/cmake/tests/test_compiler_commands.py
+++ b/vortex-ffi/cmake/tests/test_compiler_commands.py
@@ -170,8 +170,10 @@ def test_shared_ffi_consumer(self) -> None:
         )
 
         outputs = snapshot(consumer, library, artifacts / "libvortex_ffi.a", artifacts / "include/vortex.h")
-        self.build("header_consumer")
-        self.assertEqual(snapshot(*outputs), outputs, "An unchanged shared build must remain fresh")
+        rebuild = self.cmake_build(self.build_dir, "--target", "header_consumer", "--", "-d", "explain")
+        self.assertEqual(
+            snapshot(*outputs), outputs, f"An unchanged shared build must remain fresh\n{rebuild.stdout}{rebuild.stderr}"
+        )
 
     def test_host_target_instrumentation_and_cache_boundary(self) -> None:
         log = self.work / "cache calls.jsonl"
diff --git a/vortex-ffi/cmake/tests/test_cuda_architectures.py b/vortex-ffi/cmake/tests/test_cuda_architectures.py
index 15ed2ad7ac1..e063fb1bd98 100644
--- a/vortex-ffi/cmake/tests/test_cuda_architectures.py
+++ b/vortex-ffi/cmake/tests/test_cuda_architectures.py
@@ -72,7 +72,7 @@ def test_configure_forwards_flags_and_cpu_ignores_policy(self) -> None:
             "source/CMakeLists.txt",
             f"""\
             cmake_minimum_required(VERSION 3.25)
-            project(CudaArchitectureFixture LANGUAGES NONE)
+            project(CudaArchitectureFixture LANGUAGES C)
             set(CMAKE_SYSTEM_NAME Linux)
             set(APPLE FALSE)
             set(CMAKE_BUILD_TYPE Debug)

From 08b0479b3f245202a9205e503742e3eca4cd739f Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 10:03:47 +0200
Subject: [PATCH 05/14] fix(cmake): avoid redundant shared-library relinks

Defer disabling linker depfiles until the FFI directory finishes configuring, preserving child settings and explicit archive and export-script dependencies. This avoids GNU ld's unescaped paths forcing relinks in build directories containing spaces.

Format the shared-build freshness assertion for Ruff.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 vortex-ffi/cmake/Configure.cmake                 | 4 ++++
 vortex-ffi/cmake/tests/test_compiler_commands.py | 4 +++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/vortex-ffi/cmake/Configure.cmake b/vortex-ffi/cmake/Configure.cmake
index 1571b504563..5a700d4c692 100644
--- a/vortex-ffi/cmake/Configure.cmake
+++ b/vortex-ffi/cmake/Configure.cmake
@@ -400,6 +400,10 @@ block(SCOPE_FOR VARIABLES)
             "LINKER:--gc-sections")
         # Relink if the generated export policy changes.
         set_property(TARGET vortex_ffi_shared APPEND PROPERTY LINK_DEPENDS "${_exports}")
+
+        # GNU ld depfiles break on spaces; CMake already tracks the archive and script.
+        # Defer disabling linker depfiles so child directories keep their settings.
+        cmake_language(DEFER CALL set CMAKE_LINK_DEPENDS_USE_LINKER FALSE)
     else()
         message(FATAL_ERROR "Vortex shared-library exports are not configured for ${CMAKE_SYSTEM_NAME}")
     endif()
diff --git a/vortex-ffi/cmake/tests/test_compiler_commands.py b/vortex-ffi/cmake/tests/test_compiler_commands.py
index 2d45182158f..84e173a312a 100644
--- a/vortex-ffi/cmake/tests/test_compiler_commands.py
+++ b/vortex-ffi/cmake/tests/test_compiler_commands.py
@@ -172,7 +172,9 @@ def test_shared_ffi_consumer(self) -> None:
         outputs = snapshot(consumer, library, artifacts / "libvortex_ffi.a", artifacts / "include/vortex.h")
         rebuild = self.cmake_build(self.build_dir, "--target", "header_consumer", "--", "-d", "explain")
         self.assertEqual(
-            snapshot(*outputs), outputs, f"An unchanged shared build must remain fresh\n{rebuild.stdout}{rebuild.stderr}"
+            snapshot(*outputs),
+            outputs,
+            f"An unchanged shared build must remain fresh\n{rebuild.stdout}{rebuild.stderr}",
         )
 
     def test_host_target_instrumentation_and_cache_boundary(self) -> None:

From 86039c1f70e79372f8d6a3924765ca4e70f00dd9 Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 10:10:24 +0200
Subject: [PATCH 06/14] refactor(cmake): name the static C++ target explicitly

Rename vortex_cxx to vortex_cxx_static and update coverage and test references. Keep the public alias and archive filename unchanged, and document the PIC and visibility settings.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/CMakeLists.txt                  | 18 +++++++++++-------
 lang/cpp/gcov-report.sh                  |  2 +-
 vortex-ffi/cmake/tests/test_configure.py |  2 +-
 3 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/lang/cpp/CMakeLists.txt b/lang/cpp/CMakeLists.txt
index d338095c85a..163ad7db8c6 100644
--- a/lang/cpp/CMakeLists.txt
+++ b/lang/cpp/CMakeLists.txt
@@ -51,14 +51,17 @@ endif()
 # The C++ wrapper over the C FFI. Public headers live under include/.
 file(GLOB _vortex_cpp_sources CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp")
 
-# Preserve the static API and its hidden symbols for embedding in other DSOs.
-add_library(vortex_cxx STATIC ${_vortex_cpp_sources})
-set_target_properties(vortex_cxx PROPERTIES
+add_library(vortex_cxx_static STATIC ${_vortex_cpp_sources})
+set_target_properties(vortex_cxx_static PROPERTIES
+    OUTPUT_NAME vortex_cxx
+    # Allow embedding the static archive in a shared library.
     POSITION_INDEPENDENT_CODE ON
+    # Keep embedded wrapper symbols out of the parent library's exports.
     CXX_VISIBILITY_PRESET hidden)
-target_link_libraries(vortex_cxx PUBLIC Vortex::ffi_static)
-add_library(Vortex::cpp_static ALIAS vortex_cxx)
+target_link_libraries(vortex_cxx_static PUBLIC Vortex::ffi_static)
+add_library(Vortex::cpp_static ALIAS vortex_cxx_static)
 
+# CMake enables PIC automatically for SHARED targets.
 add_library(vortex_cxx_shared SHARED ${_vortex_cpp_sources})
 # Override an inherited hidden preset so the shared C++ API remains exported.
 set_target_properties(vortex_cxx_shared PROPERTIES
@@ -68,14 +71,15 @@ target_link_libraries(vortex_cxx_shared PUBLIC Vortex::ffi_shared)
 add_library(Vortex::cpp_shared ALIAS vortex_cxx_shared)
 
 if(BUILD_SHARED_LIBS)
-    set_target_properties(vortex_cxx PROPERTIES EXCLUDE_FROM_ALL TRUE)
+    set_target_properties(vortex_cxx_static PROPERTIES EXCLUDE_FROM_ALL TRUE)
     set(_vortex_cpp_target Vortex::cpp_shared)
 else()
     set_target_properties(vortex_cxx_shared PROPERTIES EXCLUDE_FROM_ALL TRUE)
     set(_vortex_cpp_target Vortex::cpp_static)
 endif()
 
-foreach(_target IN ITEMS vortex_cxx vortex_cxx_shared)
+foreach(_target IN ITEMS vortex_cxx_static vortex_cxx_shared)
+    # Keep inline implementation symbols out of shared-library exports.
     set_target_properties(${_target} PROPERTIES VISIBILITY_INLINES_HIDDEN ON)
     target_compile_features(${_target} PUBLIC cxx_std_20)
     target_include_directories(${_target} PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
diff --git a/lang/cpp/gcov-report.sh b/lang/cpp/gcov-report.sh
index dfd432f9a03..9233d40815a 100755
--- a/lang/cpp/gcov-report.sh
+++ b/lang/cpp/gcov-report.sh
@@ -19,7 +19,7 @@ cmake --build build \
 ctest --test-dir build --output-on-failure
 
 # lcov matches exclude globs against full source paths.
-geninfo build/CMakeFiles/vortex_cxx.dir/ \
+geninfo build/CMakeFiles/vortex_cxx_static.dir/ \
     build/tests/CMakeFiles/vortex_cxx_test.dir/ \
     --rc geninfo_unexecuted_blocks=1 \
     --exclude '/usr/*' --exclude '*/_deps/*' --exclude '*/tests/*' \
diff --git a/vortex-ffi/cmake/tests/test_configure.py b/vortex-ffi/cmake/tests/test_configure.py
index 26ba9bee52d..dbb4378593c 100644
--- a/vortex-ffi/cmake/tests/test_configure.py
+++ b/vortex-ffi/cmake/tests/test_configure.py
@@ -29,7 +29,7 @@ def setUp(self) -> None:
                 file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/defaults.txt"
                     "${CMAKE_BUILD_TYPE}\n${VORTEX_WARNINGS_AS_ERRORS}\n")
                 if(PROJECT_NAME STREQUAL "VortexCXX")
-                    get_target_property(options vortex_cxx COMPILE_OPTIONS)
+                    get_target_property(options vortex_cxx_static COMPILE_OPTIONS)
                     file(APPEND "${CMAKE_CURRENT_BINARY_DIR}/defaults.txt" "${options}\n")
                 endif()
             endfunction()

From 0cc5b3b78fdeafb69f523954f1d3f3dda3200a78 Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 10:49:55 +0200
Subject: [PATCH 07/14] docs(cmake): clarify inline visibility for both library
 types

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/CMakeLists.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lang/cpp/CMakeLists.txt b/lang/cpp/CMakeLists.txt
index 163ad7db8c6..a4acdfcdb05 100644
--- a/lang/cpp/CMakeLists.txt
+++ b/lang/cpp/CMakeLists.txt
@@ -79,7 +79,7 @@ else()
 endif()
 
 foreach(_target IN ITEMS vortex_cxx_static vortex_cxx_shared)
-    # Keep inline implementation symbols out of shared-library exports.
+    # Hide inline symbols in the shared library and when embedding the static archive.
     set_target_properties(${_target} PROPERTIES VISIBILITY_INLINES_HIDDEN ON)
     target_compile_features(${_target} PUBLIC cxx_std_20)
     target_include_directories(${_target} PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")

From 8c9d70d0c3b2346d57698378e6f030446f6d1fc0 Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 09:21:48 +0000
Subject: [PATCH 08/14] fix(cmake): bypass compiler caching for C++ coverage

Cached GCC objects embed the original gcda output path, so sccache hits after the static target rename leave the coverage directory empty. Clear inherited and cached C++ compiler launchers in the coverage script while preserving caching for other builds.

Add isolated CMake regression tests for environment and cache launcher settings, exercising real compilation, CTest, and coverage data generation.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/gcov-report.sh                 |   7 +-
 vortex-ffi/cmake/tests/test_coverage.py | 105 ++++++++++++++++++++++++
 2 files changed, 110 insertions(+), 2 deletions(-)
 create mode 100644 vortex-ffi/cmake/tests/test_coverage.py

diff --git a/lang/cpp/gcov-report.sh b/lang/cpp/gcov-report.sh
index 9233d40815a..e59ae43c7aa 100755
--- a/lang/cpp/gcov-report.sh
+++ b/lang/cpp/gcov-report.sh
@@ -9,9 +9,12 @@
 set -eu
 cd "$(dirname "$0")"
 
-cmake -S . -B build \
+# Cached GCC objects retain their original .gcda paths when target names change.
+# Clear both inherited and cached launchers so coverage stays in this build tree.
+CMAKE_CXX_COMPILER_LAUNCHER= cmake -S . -B build \
     -DVORTEX_BUILD_TESTS=ON \
-    -DCMAKE_CXX_FLAGS=--coverage
+    -DCMAKE_CXX_FLAGS=--coverage \
+    -DCMAKE_CXX_COMPILER_LAUNCHER=
 
 # getconf works on Linux and macOS; nproc is not installed on stock macOS.
 cmake --build build \
diff --git a/vortex-ffi/cmake/tests/test_coverage.py b/vortex-ffi/cmake/tests/test_coverage.py
new file mode 100644
index 00000000000..2a6b6f0fcca
--- /dev/null
+++ b/vortex-ffi/cmake/tests/test_coverage.py
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+"""Exercise the production coverage script without Rust, fetched dependencies, or lcov."""
+
+import json
+import os
+import shutil
+import unittest
+from pathlib import Path
+
+from support import CMakeTest
+
+
+class CoverageTests(CMakeTest):
+    def setUp(self) -> None:
+        super().setUp()
+        for name in list(self.env):
+            if name.startswith(("CMAKE_", "GCOV_")) or name == "CXXFLAGS":
+                self.env.pop(name)
+        self.env.update(CMAKE_GENERATOR="Ninja", CMAKE_BUILD_PARALLEL_LEVEL="2")
+        self.source = self.write(
+            "cpp/CMakeLists.txt",
+            """\
+            # SPDX-License-Identifier: Apache-2.0
+            # SPDX-FileCopyrightText: Copyright the Vortex contributors
+            cmake_minimum_required(VERSION 3.25)
+            project(CoverageFixture LANGUAGES CXX)
+            option(VORTEX_BUILD_TESTS "Build tests" OFF)
+            add_library(vortex_cxx_static STATIC src/value.cpp)
+            if(VORTEX_BUILD_TESTS)
+                enable_testing()
+                add_subdirectory(tests)
+            endif()
+            """,
+        ).parent
+        self.write(
+            self.source / "src/value.cpp",
+            """\
+            // SPDX-License-Identifier: Apache-2.0
+            // SPDX-FileCopyrightText: Copyright the Vortex contributors
+            int value() { return 42; }
+            """,
+        )
+        self.write(
+            self.source / "tests/CMakeLists.txt",
+            """\
+            # SPDX-License-Identifier: Apache-2.0
+            # SPDX-FileCopyrightText: Copyright the Vortex contributors
+            add_executable(vortex_cxx_test main.cpp)
+            target_link_libraries(vortex_cxx_test PRIVATE vortex_cxx_static)
+            add_test(NAME coverage COMMAND vortex_cxx_test)
+            """,
+        )
+        self.write(
+            self.source / "tests/main.cpp",
+            """\
+            // SPDX-License-Identifier: Apache-2.0
+            // SPDX-FileCopyrightText: Copyright the Vortex contributors
+            int value();
+            int main() { return value() == 42 ? 0 : 1; }
+            """,
+        )
+        shutil.copyfile(self.repo / "lang/cpp/gcov-report.sh", self.source / "gcov-report.sh")
+        self.launcher = self.executable(
+            "reject-launcher", 'raise SystemExit("coverage compiler launcher must not run")\n'
+        )
+        self.executable(
+            "bin/geninfo",
+            """\
+            # SPDX-License-Identifier: Apache-2.0
+            # SPDX-FileCopyrightText: Copyright the Vortex contributors
+            import json
+            import sys
+            from pathlib import Path
+            Path("geninfo-args.json").write_text(json.dumps(sys.argv[1:]))
+            """,
+        )
+        self.env["PATH"] = str(self.work / "bin") + os.pathsep + self.env["PATH"]
+
+    def run_report(self) -> None:
+        self.command("sh", self.source / "gcov-report.sh")
+        args = json.loads((self.source / "geninfo-args.json").read_text())
+        directories = [
+            Path("build/CMakeFiles/vortex_cxx_static.dir"),
+            Path("build/tests/CMakeFiles/vortex_cxx_test.dir"),
+        ]
+        self.assertEqual([Path(arg) for arg in args[:2]], directories)
+        for directory in directories:
+            self.assertTrue(list((self.source / directory).rglob("*.gcda")), f"No coverage data in {directory}")
+
+    def test_inherited_launcher_is_disabled(self) -> None:
+        self.env["CMAKE_CXX_COMPILER_LAUNCHER"] = self.launcher
+        self.run_report()
+
+    def test_cached_launcher_is_disabled(self) -> None:
+        build = self.source / "build"
+        # Detect the real compiler before installing the rejecting launcher in the cache.
+        self.cmake_configure(self.source, build)
+        self.cmake_configure(self.source, build, f"-DCMAKE_CXX_COMPILER_LAUNCHER={self.launcher}")
+        self.run_report()
+
+
+if __name__ == "__main__":
+    unittest.main()

From c7d7ed403cba58a1874139d50b9641c5ae32bbea Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 09:31:44 +0000
Subject: [PATCH 09/14] ci: use shared libraries for FFI tests and examples

Enable shared linkage for the C API test build and both FFI sanitizer jobs, matching the existing C++ API job. This avoids linking the Rust archive separately into each test and example executable.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 .github/workflows/ci.yml                | 1 +
 .github/workflows/rust-instrumented.yml | 1 +
 2 files changed, 2 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e8a7e67c9a1..9914fb62d28 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -879,6 +879,7 @@ jobs:
           RUSTUP_TOOLCHAIN: ${{ env.NIGHTLY_TOOLCHAIN }}
         run: |
           cmake -S vortex-ffi -B vortex-ffi/build \
+            -DBUILD_SHARED_LIBS=ON \
             -DVORTEX_CARGO_PROFILE=ci \
             -DVORTEX_BUILD_TESTS=ON
           cmake --build vortex-ffi/build --parallel "$(nproc)"
diff --git a/.github/workflows/rust-instrumented.yml b/.github/workflows/rust-instrumented.yml
index e64753fd3b6..80cdb9be282 100644
--- a/.github/workflows/rust-instrumented.yml
+++ b/.github/workflows/rust-instrumented.yml
@@ -262,6 +262,7 @@ jobs:
         run: |
           cmake -S . -B build \
             -DCMAKE_BUILD_TYPE=Debug \
+            -DBUILD_SHARED_LIBS=ON \
             -DCMAKE_C_COMPILER=clang \
             -DCMAKE_CXX_COMPILER=clang++ \
             -DVORTEX_SANITIZER=${{ matrix.sanitizer }} \

From 1613979792e215584395daab62686c213f06c3c9 Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 09:31:44 +0000
Subject: [PATCH 10/14] ci: collect C++ coverage from shared libraries

Build shared libraries in the coverage script and collect data from vortex_cxx_shared.dir. Update the regression fixture to honor BUILD_SHARED_LIBS and require coverage in the shared target directory.

Clarify how the empty environment assignment and CMake cache option disable compiler launchers for coverage builds.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/gcov-report.sh                 |  6 ++++--
 vortex-ffi/cmake/tests/test_coverage.py | 12 +++++++++---
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/lang/cpp/gcov-report.sh b/lang/cpp/gcov-report.sh
index e59ae43c7aa..65618bce066 100755
--- a/lang/cpp/gcov-report.sh
+++ b/lang/cpp/gcov-report.sh
@@ -10,8 +10,10 @@ set -eu
 cd "$(dirname "$0")"
 
 # Cached GCC objects retain their original .gcda paths when target names change.
-# Clear both inherited and cached launchers so coverage stays in this build tree.
+# CMAKE_CXX_COMPILER_LAUNCHER= clears the inherited launcher during configuration;
+# -DCMAKE_CXX_COMPILER_LAUNCHER= also clears its value in CMakeCache.txt.
 CMAKE_CXX_COMPILER_LAUNCHER= cmake -S . -B build \
+    -DBUILD_SHARED_LIBS=ON \
     -DVORTEX_BUILD_TESTS=ON \
     -DCMAKE_CXX_FLAGS=--coverage \
     -DCMAKE_CXX_COMPILER_LAUNCHER=
@@ -22,7 +24,7 @@ cmake --build build \
 ctest --test-dir build --output-on-failure
 
 # lcov matches exclude globs against full source paths.
-geninfo build/CMakeFiles/vortex_cxx_static.dir/ \
+geninfo build/CMakeFiles/vortex_cxx_shared.dir/ \
     build/tests/CMakeFiles/vortex_cxx_test.dir/ \
     --rc geninfo_unexecuted_blocks=1 \
     --exclude '/usr/*' --exclude '*/_deps/*' --exclude '*/tests/*' \
diff --git a/vortex-ffi/cmake/tests/test_coverage.py b/vortex-ffi/cmake/tests/test_coverage.py
index 2a6b6f0fcca..2bf924ab9f2 100644
--- a/vortex-ffi/cmake/tests/test_coverage.py
+++ b/vortex-ffi/cmake/tests/test_coverage.py
@@ -26,8 +26,14 @@ def setUp(self) -> None:
             # SPDX-FileCopyrightText: Copyright the Vortex contributors
             cmake_minimum_required(VERSION 3.25)
             project(CoverageFixture LANGUAGES CXX)
+            option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
             option(VORTEX_BUILD_TESTS "Build tests" OFF)
-            add_library(vortex_cxx_static STATIC src/value.cpp)
+            if(BUILD_SHARED_LIBS)
+                set(coverage_target vortex_cxx_shared)
+            else()
+                set(coverage_target vortex_cxx_static)
+            endif()
+            add_library(${coverage_target} src/value.cpp)
             if(VORTEX_BUILD_TESTS)
                 enable_testing()
                 add_subdirectory(tests)
@@ -48,7 +54,7 @@ def setUp(self) -> None:
             # SPDX-License-Identifier: Apache-2.0
             # SPDX-FileCopyrightText: Copyright the Vortex contributors
             add_executable(vortex_cxx_test main.cpp)
-            target_link_libraries(vortex_cxx_test PRIVATE vortex_cxx_static)
+            target_link_libraries(vortex_cxx_test PRIVATE ${coverage_target})
             add_test(NAME coverage COMMAND vortex_cxx_test)
             """,
         )
@@ -82,7 +88,7 @@ def run_report(self) -> None:
         self.command("sh", self.source / "gcov-report.sh")
         args = json.loads((self.source / "geninfo-args.json").read_text())
         directories = [
-            Path("build/CMakeFiles/vortex_cxx_static.dir"),
+            Path("build/CMakeFiles/vortex_cxx_shared.dir"),
             Path("build/tests/CMakeFiles/vortex_cxx_test.dir"),
         ]
         self.assertEqual([Path(arg) for arg in args[:2]], directories)

From 8e73ea24d44a1f8302edb2ea7f8e775a89c67fab Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 09:35:44 +0000
Subject: [PATCH 11/14] chore(cmake): remove branch-added integration tests

Remove the coverage and shared-FFI integration tests and their supporting fixture changes. Preserve compatibility updates to existing tests and shorten the coverage launcher comment.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/gcov-report.sh                       |   4 +-
 .../tests/fixtures/native/header_consumer.c   |   3 +-
 .../tests/fixtures/native/vortex-ffi/build.rs |   5 +-
 .../tests/fixtures/native/vortex-ffi/lib.rs   |   7 --
 .../cmake/tests/test_compiler_commands.py     |  36 +-----
 vortex-ffi/cmake/tests/test_configure.py      |   7 +-
 vortex-ffi/cmake/tests/test_coverage.py       | 111 ------------------
 7 files changed, 7 insertions(+), 166 deletions(-)
 delete mode 100644 vortex-ffi/cmake/tests/test_coverage.py

diff --git a/lang/cpp/gcov-report.sh b/lang/cpp/gcov-report.sh
index 65618bce066..fda7a917b90 100755
--- a/lang/cpp/gcov-report.sh
+++ b/lang/cpp/gcov-report.sh
@@ -9,9 +9,7 @@
 set -eu
 cd "$(dirname "$0")"
 
-# Cached GCC objects retain their original .gcda paths when target names change.
-# CMAKE_CXX_COMPILER_LAUNCHER= clears the inherited launcher during configuration;
-# -DCMAKE_CXX_COMPILER_LAUNCHER= also clears its value in CMakeCache.txt.
+# Clear environment and cached launchers: cached GCC objects embed stale .gcda paths.
 CMAKE_CXX_COMPILER_LAUNCHER= cmake -S . -B build \
     -DBUILD_SHARED_LIBS=ON \
     -DVORTEX_BUILD_TESTS=ON \
diff --git a/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c b/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
index 609918b4ae0..f1642e2e42a 100644
--- a/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
+++ b/vortex-ffi/cmake/tests/fixtures/native/header_consumer.c
@@ -5,6 +5,5 @@
 #include <vortex.h>
 
 int main(void) {
-    printf("%d %d\n", VORTEX_HEADER_VERSION, vx_fixture_value());
-    return 0;
+    printf("%d\n", VORTEX_HEADER_VERSION);
 }
diff --git a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs
index 8aa92c45a06..791eff47e66 100644
--- a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs
+++ b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/build.rs
@@ -10,10 +10,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     fs::create_dir_all("cinclude")?;
     fs::write(
         "cinclude/vortex.h",
-        format!(
-            "#define VORTEX_HEADER_VERSION {}\nint vx_fixture_value(void);\n",
-            version.trim()
-        ),
+        format!("#define VORTEX_HEADER_VERSION {}\n", version.trim()),
     )?;
     println!("cargo:rerun-if-changed=header-version");
     Ok(())
diff --git a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs
index 4d50790a5be..576a14aeccf 100644
--- a/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs
+++ b/vortex-ffi/cmake/tests/fixtures/native/vortex-ffi/lib.rs
@@ -2,10 +2,3 @@
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
 pub use native_helper::value;
-
-/// Exercise both native dependencies through the C ABI.
-// SAFETY: This fixture is the only definition of `vx_fixture_value`.
-#[unsafe(no_mangle)]
-pub extern "C" fn vx_fixture_value() -> i32 {
-    value()
-}
diff --git a/vortex-ffi/cmake/tests/test_compiler_commands.py b/vortex-ffi/cmake/tests/test_compiler_commands.py
index 84e173a312a..0d2a67c5da0 100644
--- a/vortex-ffi/cmake/tests/test_compiler_commands.py
+++ b/vortex-ffi/cmake/tests/test_compiler_commands.py
@@ -8,7 +8,6 @@
 import shlex
 import shutil
 import subprocess
-import sys
 import tomllib
 import unittest
 from pathlib import Path
@@ -130,11 +129,11 @@ def test_header_lifecycle(self) -> None:
                 staged = self.build_dir / "ffi/vortex-artifacts/include/vortex.h"
                 archive = self.build_dir / "ffi/vortex-artifacts/libvortex_ffi.a"
                 self.build("header_consumer")
-                self.assertEqual(self.command(consumer).stdout.strip(), "1 46")
+                self.assertEqual(self.command(consumer).stdout.strip(), "1")
                 archive_state = snapshot(archive)
                 self.write(version, "2\n")
                 self.build("header_consumer")
-                self.assertEqual(self.command(consumer).stdout.strip(), "2 46", "Must update on the first build")
+                self.assertEqual(self.command(consumer).stdout.strip(), "2", "Must update on the first build")
                 self.assertEqual(snapshot(archive), archive_state, "Header-only change must leave archive identical")
                 self.assertEqual(staged.read_bytes(), source_header.read_bytes())
                 outputs = snapshot(archive, staged, source_header, consumer, *self.build_dir.rglob("*.o"))
@@ -145,38 +144,9 @@ def test_header_lifecycle(self) -> None:
                     self.assertFalse(path.exists(), path)
                 self.assertEqual(snapshot(source_header), {source_header: outputs[source_header]})
                 self.build("header_consumer")
-                self.assertEqual(self.command(consumer).stdout.strip(), "2 46")
+                self.assertEqual(self.command(consumer).stdout.strip(), "2")
                 self.assertEqual(staged.read_bytes(), source_header.read_bytes())
 
-    def test_shared_ffi_consumer(self) -> None:
-        cmake_lists = self.source / "CMakeLists.txt"
-        self.write(cmake_lists, cmake_lists.read_text().replace("Vortex::ffi_static", "Vortex::ffi_shared"))
-        self.configure(build_name="shared build directory")
-        self.build("header_consumer")
-        consumer = self.build_dir / "header_consumer"
-        artifacts = self.build_dir / "ffi/vortex-artifacts"
-        library = self.build_dir / "ffi" / ("libvortex_ffi.dylib" if sys.platform == "darwin" else "libvortex_ffi.so")
-        self.assertEqual(self.command(consumer).stdout.strip(), "1 46")
-
-        link = self.command("ninja", "-C", self.build_dir, "-t", "commands", "header_consumer").stdout.splitlines()[-1]
-        self.assertIn(library.name, link)
-        self.assertNotIn("libvortex_ffi.a", link, "The consumer must not relink the Rust static archive")
-        nm_flags = ("-gU",) if sys.platform == "darwin" else ("-D", "--defined-only")
-        exports = self.command("nm", *nm_flags, library).stdout
-        self.assertEqual(
-            {line.split()[-1].removeprefix("_") for line in exports.splitlines() if line.strip()},
-            {"vx_fixture_value"},
-            exports,
-        )
-
-        outputs = snapshot(consumer, library, artifacts / "libvortex_ffi.a", artifacts / "include/vortex.h")
-        rebuild = self.cmake_build(self.build_dir, "--target", "header_consumer", "--", "-d", "explain")
-        self.assertEqual(
-            snapshot(*outputs),
-            outputs,
-            f"An unchanged shared build must remain fresh\n{rebuild.stdout}{rebuild.stderr}",
-        )
-
     def test_host_target_instrumentation_and_cache_boundary(self) -> None:
         log = self.work / "cache calls.jsonl"
         # Record the cache boundary, not cache behavior; every call still runs the real compiler.
diff --git a/vortex-ffi/cmake/tests/test_configure.py b/vortex-ffi/cmake/tests/test_configure.py
index dbb4378593c..f99080a0283 100644
--- a/vortex-ffi/cmake/tests/test_configure.py
+++ b/vortex-ffi/cmake/tests/test_configure.py
@@ -94,11 +94,6 @@ def test_embedded_root_preserves_parent_variables(self) -> None:
             set(CMAKE_BUILD_TYPE "")
             set(_vortex_top_level ON)
             add_subdirectory("{self.repo}" vortex EXCLUDE_FROM_ALL)
-            foreach(target IN ITEMS Vortex::ffi_static Vortex::ffi_shared Vortex::cpp_static Vortex::cpp_shared)
-                if(NOT TARGET ${{target}})
-                    message(FATAL_ERROR "Missing target: ${{target}}")
-                endif()
-            endforeach()
             if(NOT CMAKE_BUILD_TYPE STREQUAL "" OR NOT _vortex_top_level STREQUAL "ON")
                 message(FATAL_ERROR "Vortex changed parent variables")
             endif()
@@ -123,7 +118,7 @@ def test_unused_embedded_ffi_keeps_cargo_lazy(self) -> None:
             add_subdirectory("{self.repo}/vortex-ffi" ffi)
             """,
         ).parent
-        self.configure("lazy", "-DBUILD_SHARED_LIBS=ON", source=source)
+        self.configure("lazy", source=source)
         build = self.work / "lazy"
         self.cmake_build(build)
         self.assertFalse(list(build.rglob("libvortex_ffi.a")))
diff --git a/vortex-ffi/cmake/tests/test_coverage.py b/vortex-ffi/cmake/tests/test_coverage.py
deleted file mode 100644
index 2bf924ab9f2..00000000000
--- a/vortex-ffi/cmake/tests/test_coverage.py
+++ /dev/null
@@ -1,111 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright the Vortex contributors
-
-"""Exercise the production coverage script without Rust, fetched dependencies, or lcov."""
-
-import json
-import os
-import shutil
-import unittest
-from pathlib import Path
-
-from support import CMakeTest
-
-
-class CoverageTests(CMakeTest):
-    def setUp(self) -> None:
-        super().setUp()
-        for name in list(self.env):
-            if name.startswith(("CMAKE_", "GCOV_")) or name == "CXXFLAGS":
-                self.env.pop(name)
-        self.env.update(CMAKE_GENERATOR="Ninja", CMAKE_BUILD_PARALLEL_LEVEL="2")
-        self.source = self.write(
-            "cpp/CMakeLists.txt",
-            """\
-            # SPDX-License-Identifier: Apache-2.0
-            # SPDX-FileCopyrightText: Copyright the Vortex contributors
-            cmake_minimum_required(VERSION 3.25)
-            project(CoverageFixture LANGUAGES CXX)
-            option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
-            option(VORTEX_BUILD_TESTS "Build tests" OFF)
-            if(BUILD_SHARED_LIBS)
-                set(coverage_target vortex_cxx_shared)
-            else()
-                set(coverage_target vortex_cxx_static)
-            endif()
-            add_library(${coverage_target} src/value.cpp)
-            if(VORTEX_BUILD_TESTS)
-                enable_testing()
-                add_subdirectory(tests)
-            endif()
-            """,
-        ).parent
-        self.write(
-            self.source / "src/value.cpp",
-            """\
-            // SPDX-License-Identifier: Apache-2.0
-            // SPDX-FileCopyrightText: Copyright the Vortex contributors
-            int value() { return 42; }
-            """,
-        )
-        self.write(
-            self.source / "tests/CMakeLists.txt",
-            """\
-            # SPDX-License-Identifier: Apache-2.0
-            # SPDX-FileCopyrightText: Copyright the Vortex contributors
-            add_executable(vortex_cxx_test main.cpp)
-            target_link_libraries(vortex_cxx_test PRIVATE ${coverage_target})
-            add_test(NAME coverage COMMAND vortex_cxx_test)
-            """,
-        )
-        self.write(
-            self.source / "tests/main.cpp",
-            """\
-            // SPDX-License-Identifier: Apache-2.0
-            // SPDX-FileCopyrightText: Copyright the Vortex contributors
-            int value();
-            int main() { return value() == 42 ? 0 : 1; }
-            """,
-        )
-        shutil.copyfile(self.repo / "lang/cpp/gcov-report.sh", self.source / "gcov-report.sh")
-        self.launcher = self.executable(
-            "reject-launcher", 'raise SystemExit("coverage compiler launcher must not run")\n'
-        )
-        self.executable(
-            "bin/geninfo",
-            """\
-            # SPDX-License-Identifier: Apache-2.0
-            # SPDX-FileCopyrightText: Copyright the Vortex contributors
-            import json
-            import sys
-            from pathlib import Path
-            Path("geninfo-args.json").write_text(json.dumps(sys.argv[1:]))
-            """,
-        )
-        self.env["PATH"] = str(self.work / "bin") + os.pathsep + self.env["PATH"]
-
-    def run_report(self) -> None:
-        self.command("sh", self.source / "gcov-report.sh")
-        args = json.loads((self.source / "geninfo-args.json").read_text())
-        directories = [
-            Path("build/CMakeFiles/vortex_cxx_shared.dir"),
-            Path("build/tests/CMakeFiles/vortex_cxx_test.dir"),
-        ]
-        self.assertEqual([Path(arg) for arg in args[:2]], directories)
-        for directory in directories:
-            self.assertTrue(list((self.source / directory).rglob("*.gcda")), f"No coverage data in {directory}")
-
-    def test_inherited_launcher_is_disabled(self) -> None:
-        self.env["CMAKE_CXX_COMPILER_LAUNCHER"] = self.launcher
-        self.run_report()
-
-    def test_cached_launcher_is_disabled(self) -> None:
-        build = self.source / "build"
-        # Detect the real compiler before installing the rejecting launcher in the cache.
-        self.cmake_configure(self.source, build)
-        self.cmake_configure(self.source, build, f"-DCMAKE_CXX_COMPILER_LAUNCHER={self.launcher}")
-        self.run_report()
-
-
-if __name__ == "__main__":
-    unittest.main()

From cbe1f8933e404d08a06d9c5bb422be8177d66f58 Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 09:46:44 +0000
Subject: [PATCH 12/14] refactor(cmake): simplify coverage compiler launcher
 override

Keep the CMake cache option that disables caching for coverage targets and remove the environment override used only for compiler probes. Explain the stale gcda path issue next to the flag.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/gcov-report.sh | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/lang/cpp/gcov-report.sh b/lang/cpp/gcov-report.sh
index fda7a917b90..3d4844967fb 100755
--- a/lang/cpp/gcov-report.sh
+++ b/lang/cpp/gcov-report.sh
@@ -9,12 +9,11 @@
 set -eu
 cd "$(dirname "$0")"
 
-# Clear environment and cached launchers: cached GCC objects embed stale .gcda paths.
-CMAKE_CXX_COMPILER_LAUNCHER= cmake -S . -B build \
+cmake -S . -B build \
     -DBUILD_SHARED_LIBS=ON \
     -DVORTEX_BUILD_TESTS=ON \
     -DCMAKE_CXX_FLAGS=--coverage \
-    -DCMAKE_CXX_COMPILER_LAUNCHER=
+    -DCMAKE_CXX_COMPILER_LAUNCHER=  # Disable caching: reused GCC objects can write .gcda files to an old target directory.
 
 # getconf works on Linux and macOS; nproc is not installed on stock macOS.
 cmake --build build \

From b2bffefd1095892075e639f2d8c1c0689beacf83 Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 10:01:00 +0000
Subject: [PATCH 13/14] fix(cmake): preserve compiler caching for C++ coverage

Namespace sccache entries by the CMake target's build directory and name so renamed targets cannot reuse GCC objects with stale gcda paths. Preserve the inherited launcher and any existing custom cache key while retaining warm-cache hits.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/gcov-report.sh | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/lang/cpp/gcov-report.sh b/lang/cpp/gcov-report.sh
index 3d4844967fb..ca2870f1381 100755
--- a/lang/cpp/gcov-report.sh
+++ b/lang/cpp/gcov-report.sh
@@ -9,11 +9,15 @@
 set -eu
 cd "$(dirname "$0")"
 
+coverage_key='$<TARGET_PROPERTY:BINARY_DIR>/$<TARGET_PROPERTY:NAME>'
+coverage_launcher="cmake;-E;env;SCCACHE_C_CUSTOM_CACHE_BUSTER=${SCCACHE_C_CUSTOM_CACHE_BUSTER:-}:$coverage_key"
+coverage_launcher="$coverage_launcher${CMAKE_CXX_COMPILER_LAUNCHER:+;$CMAKE_CXX_COMPILER_LAUNCHER}"
+
 cmake -S . -B build \
     -DBUILD_SHARED_LIBS=ON \
     -DVORTEX_BUILD_TESTS=ON \
     -DCMAKE_CXX_FLAGS=--coverage \
-    -DCMAKE_CXX_COMPILER_LAUNCHER=  # Disable caching: reused GCC objects can write .gcda files to an old target directory.
+    -DCMAKE_CXX_COMPILER_LAUNCHER="$coverage_launcher"  # Keep .gcda paths correct by separating sccache entries per target.
 
 # getconf works on Linux and macOS; nproc is not installed on stock macOS.
 cmake --build build \

From cd1c57ba11469fe00c2dd2af13f83a4c465516f8 Mon Sep 17 00:00:00 2001
From: Alexander Droste <alexander.droste@protonmail.com>
Date: Tue, 15 Sep 2026 10:23:37 +0000
Subject: [PATCH 14/14] fix(cmake): link gcov into shared coverage libraries

Pass --coverage through CMAKE_SHARED_LINKER_FLAGS so the C-linked FFI shared library resolves its gcov runtime internally. Document the runtime-linking and target-specific compiler cache settings.

Signed-off-by: Alexander Droste <alexander.droste@protonmail.com>
---
 lang/cpp/gcov-report.sh | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/lang/cpp/gcov-report.sh b/lang/cpp/gcov-report.sh
index ca2870f1381..b32ba5423ac 100755
--- a/lang/cpp/gcov-report.sh
+++ b/lang/cpp/gcov-report.sh
@@ -13,11 +13,14 @@ coverage_key='$<TARGET_PROPERTY:BINARY_DIR>/$<TARGET_PROPERTY:NAME>'
 coverage_launcher="cmake;-E;env;SCCACHE_C_CUSTOM_CACHE_BUSTER=${SCCACHE_C_CUSTOM_CACHE_BUSTER:-}:$coverage_key"
 coverage_launcher="$coverage_launcher${CMAKE_CXX_COMPILER_LAUNCHER:+;$CMAKE_CXX_COMPILER_LAUNCHER}"
 
+# CMAKE_SHARED_LINKER_FLAGS links gcov into C-linked shared libraries.
+# CMAKE_CXX_COMPILER_LAUNCHER keeps cached .gcda paths target-specific.
 cmake -S . -B build \
     -DBUILD_SHARED_LIBS=ON \
     -DVORTEX_BUILD_TESTS=ON \
     -DCMAKE_CXX_FLAGS=--coverage \
-    -DCMAKE_CXX_COMPILER_LAUNCHER="$coverage_launcher"  # Keep .gcda paths correct by separating sccache entries per target.
+    -DCMAKE_SHARED_LINKER_FLAGS=--coverage \
+    -DCMAKE_CXX_COMPILER_LAUNCHER="$coverage_launcher"
 
 # getconf works on Linux and macOS; nproc is not installed on stock macOS.
 cmake --build build \