tests: add shared library integration test

+ Introduced a new integration test for validating shared library functionality.
+ Added a new workspace member `tests/shared_library` to the `Cargo.toml`.
+ Implemented a shared library test suite to verify `cxx-gen`'s ability to handle DLL scenarios with bidirectional function calls.
+ Created `tests/shared_library/library` with `lib.rs`, `build.rs`, and `Cargo.toml` for the shared library.
+ Added `tests/main.cc` and `tests/test_shared_library.rs` for testing the shared library's interaction with a host executable.
+ Updated `.gitignore` to exclude generated files from the shared library tests.

Author: chrislimpach

.gitignore

@@ -11,3 +11,5 @@
 /expand.rs
 /target/
 /Cargo.lock
+/tests/shared_library/library/target/
+/tests/shared_library/library/Cargo.lock

Cargo.toml

@@ -51,7 +51,7 @@ cxx-build = { version = "=1.0.194", path = "gen/build" }
 cxxbridge-cmd = { version = "=1.0.194", path = "gen/cmd" }
 
 [workspace]
-members = ["demo", "flags", "gen/build", "gen/cmd", "gen/lib", "macro", "tests/ffi"]
+members = ["demo", "flags", "gen/build", "gen/cmd", "gen/lib", "macro", "tests/ffi", "tests/shared_library"]
 
 [package.metadata.docs.rs]
 targets = ["x86_64-unknown-linux-gnu"]

tests/shared_library/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "cxx-test-shared-library"
+version = "0.0.0"
+edition = "2021"
+publish = false
+
+[[test]]
+name = "test_shared_library"
+harness = true
+
+[dev-dependencies]
+cc = "1.0"
+cargo_metadata = "0.19"

tests/shared_library/README.md

@@ -0,0 +1,88 @@
+# Shared Library Test
+
+This test validates cxx-gen's ability to generate code for shared library/DLL scenarios with bidirectional function calls.
+
+## What This Tests
+
+This test specifically validates the cxx_gen functionality for generating:
+
+1. **export_symbols** - List of mangled symbols the shared library exports (Rust functions callable from C++)
+2. **import_symbols** - List of mangled symbols the EXE must export (C++ functions callable from Rust)
+3. **import_thunks** - C++ code compiled into the DLL to dynamically load EXE's exports via GetProcAddress (Windows only)
+
+### Platform-Specific Behavior
+
+**Windows:**
+- Uses `.def` files to control symbol exports/imports
+- Generates thunks that use `GetProcAddress` to dynamically resolve symbols from the executable
+- Thunks are compiled into the DLL
+
+**Linux:**
+- Uses a version script to control symbol visibility in the shared library
+- Uses a dynamic list to export only the required symbols from the executable (more precise than `--export-dynamic`)
+- The shared library resolves imported symbols directly (no thunks needed)
+- Uses `rpath` with `$ORIGIN` for library loading
+
+**macOS:**
+- Uses `-undefined dynamic_lookup` to allow undefined symbols
+- The executable makes symbols available to the shared library at runtime
+
+## Structure
+
+- `library/lib.rs` - Defines the cxx bridge with exported Rust functions and imported C++ functions
+- `library/build.rs` - Uses `cxx_gen::generate_header_and_cc()` to generate .def files and thunks
+- `tests/main.cc` - Test executable that implements C++ functions and calls library functions
+- `tests/exe_functions.{h,cc}` - Implementation of functions exported by the executable
+- `tests/test_shared_library.rs` - Integration test that verifies the generated files and builds/runs test exe
+
+## How It Works
+
+1. **Library Build** (`library/build.rs`):
+   - Parses `lib.rs` using cxx_gen to extract bridge declarations
+   - Generates `library.def` with export_symbols (functions DLL exports) on Windows
+   - Generates `exe.def` with import_symbols (functions EXE must export) on Windows
+   - Generates `thunks.cc` with import_thunks (GetProcAddress-based loaders on Windows)
+   - On Linux, generates a version script to control symbol visibility
+   - On macOS, generates a response file with `-U` flags for each import symbol
+   - Compiles everything into `test_library.dll` (Windows) or `libtest_library.so` (Linux/macOS)
+
+2. **Test Execution** (`tests/test_shared_library.rs`):
+   - Detects the test's target platform and builds the library with the same target
+   - Builds the library with `cargo build --manifest-path library/Cargo.toml --target <target>`
+   - Verifies .def files contain correct mangled symbols (Windows only)
+   - Compiles a test executable linking main.cc + generated lib.cc + shared library
+   - **Windows**: Uses .def files, DLL import library, and MSVC linker
+   - **Linux**: Uses `--export-dynamic` to export symbols from executable, and `rpath` for library loading
+   - **macOS**: Uses `@loader_path` rpath and dynamic symbol lookup
+   - Runs the executable to validate bidirectional calling works
+
+3. **Test Executable** (`tests/main.cc`):
+   - Implements `exe_callback()` and `exe_get_constant()` in `tests/exe_functions.cc`
+   - Calls library's `get_magic_number()`, `multiply_values()`, `library_entry_point()`
+   - All calls go through cxx bridge (not direct mangled names)
+
+## Testing
+
+The tests verify that:
+- The library builds successfully on Windows, Linux, and macOS
+- Exported functions can be called and return correct values
+- Imported functions are called correctly by the library
+- The entry point demonstrates the full round-trip
+- Platform-specific symbol resolution mechanisms work correctly
+
+Run with:
+```bash
+# Test for your current platform
+cargo test
+
+# Test for a specific target
+cargo test --target x86_64-unknown-linux-gnu
+cargo test --target x86_64-pc-windows-msvc
+cargo test --target x86_64-apple-darwin
+```
+
+## Expected Behavior
+
+- `get_magic_number()` calls `exe_get_constant()` (returns 1000) and adds 42, returning 1042
+- `multiply_values(3, 4)` computes 3*4=12, then calls `exe_callback(12)` which doubles it to 24
+- `library_entry_point()` calls both `exe_callback(100)` and `exe_get_constant()`, returning 200 + 1000 = 1200

tests/shared_library/library/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "test-library"
+version = "0.0.0"
+edition = "2021"
+publish = false
+
+# Exclude from parent workspace - this is a standalone test library
+[workspace]
+
+[lib]
+crate-type = ["cdylib"]
+path = "lib.rs"
+
+[dependencies]
+cxx = { path = "../../.." }
+
+[build-dependencies]
+cxx-gen = { path = "../../../gen/lib" }
+cc = "1.0"
+proc-macro2 = "1.0"

tests/shared_library/library/build.rs

@@ -0,0 +1,135 @@
+use std::env;
+use std::fs;
+use std::io::Write;
+use std::path::PathBuf;
+
+fn main() {
+    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
+    let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
+    let profile = env::var("PROFILE").unwrap();
+    let test_artifacts_dir = manifest_dir.join(format!("target/cxxbridge/{}", profile));
+    fs::create_dir_all(&test_artifacts_dir).unwrap();
+
+    // generate the bridge using cxx_gen to get symbols and thunks
+    let lib_source = fs::read_to_string(manifest_dir.join("lib.rs")).unwrap();
+    let lib_tokens: proc_macro2::TokenStream = lib_source.parse().unwrap();
+    let generated = cxx_gen::generate_header_and_cc(lib_tokens, &cxx_gen::Opt::default()).unwrap();
+
+    // write header and implementation
+    fs::write(out_dir.join("lib.h"), &generated.header).unwrap();
+    fs::write(out_dir.join("lib.cc"), &generated.implementation).unwrap();
+
+    // create EXE symbols file in OS-appropriate format
+    // Use TARGET env var to get the target OS, not the host OS
+    let target = env::var("TARGET").unwrap();
+    let target_os = TargetOs::from(target.as_str());
+
+    let exe_symbols_content = cxx_gen::format_import_symbols_for_linker(
+        &generated.import_symbols(),
+        target_os.as_str(),
+    );
+
+    let exe_symbols_path = match target_os {
+        TargetOs::Windows => out_dir.join("exe.def"),
+        TargetOs::Macos => out_dir.join("exe_undefined.txt"),
+        TargetOs::Linux => out_dir.join("exe.dynamic"),
+    };
+    fs::write(&exe_symbols_path, exe_symbols_content).unwrap();
+
+    // compile C++ code needed by the library
+    // On Windows: compile thunks (which call back to the exe via GetProcAddress)
+    // On Unix: no C++ code needed in the library (generate_import_thunks returns empty string)
+    let thunks = generated.generate_import_thunks(target_os.as_str());
+    if !thunks.is_empty() {
+        // write thunks that will be compiled into the DLL
+        let thunks_path = out_dir.join("thunks.cc");
+        fs::write(&thunks_path, &thunks).unwrap();
+
+        let mut build = cc::Build::new();
+        build
+            .cpp(true)
+            .flag("/EHsc")
+            .file(&thunks_path)
+            .include(&out_dir)
+            .include(manifest_dir.parent().unwrap().join("tests"));  // for exe_functions.h
+        build.compile("cxx-test-shared-library");
+    }
+
+    // on Windows, use the .def file for exports
+    if target_os == TargetOs::Windows {
+        // create DLL .def file with export symbols (functions the DLL exports)
+        let dll_def_content = cxx_gen::format_export_symbols_for_linker(
+            &generated.export_symbols(),
+            "windows",
+        );
+        let dll_def_path = out_dir.join("library.def");
+        fs::write(&dll_def_path, dll_def_content).unwrap();
+
+        println!("cargo:rustc-cdylib-link-arg=/DEF:{}", dll_def_path.display());
+
+        // copy for the test to use
+        fs::copy(&dll_def_path, test_artifacts_dir.join("library.def")).unwrap();
+    } else if target_os == TargetOs::Macos {
+        // Per ld(1) man page: "-U symbol_name: Specified that it is ok for symbol_name to
+        // have no definition. With -two_levelnamespace, the resulting symbol will be marked
+        // dynamic_lookup which means dyld will search all loaded images."
+        //
+        // The Rust code in the library calls the cxxbridge wrapper functions (import_symbols),
+        // which are implemented in lib.cc that's compiled into the executable.
+        println!("cargo:rustc-cdylib-link-arg=-Wl,@{}", exe_symbols_path.display());
+    } else {
+        // on Linux, create a version script to export symbols and allow undefined symbols
+        let mut version_script = Vec::new();
+        writeln!(version_script, "{{").unwrap();
+        writeln!(version_script, "  global:").unwrap();
+        for sym in &generated.export_symbols() {
+            writeln!(version_script, "    {};", sym).unwrap();
+        }
+        writeln!(version_script, "  local: *;").unwrap();
+        writeln!(version_script, "}};").unwrap();
+        let version_script_path = out_dir.join("libtest_library.version");
+        fs::write(&version_script_path, version_script).unwrap();
+
+        println!("cargo:rustc-cdylib-link-arg=-Wl,--version-script={}", version_script_path.display());
+        println!("cargo:rustc-cdylib-link-arg=-Wl,--allow-shlib-undefined");
+    }
+
+    // expose paths for the test to use
+    println!("cargo:rustc-env=EXE_SYMBOLS_PATH={}", exe_symbols_path.display());
+
+    // copy generated files to a predictable location for the test to find
+    fs::copy(&exe_symbols_path, test_artifacts_dir.join(exe_symbols_path.file_name().unwrap())).unwrap();
+    fs::copy(out_dir.join("lib.h"), test_artifacts_dir.join("lib.h")).unwrap();
+    fs::copy(out_dir.join("lib.cc"), test_artifacts_dir.join("lib.cc")).unwrap();
+
+    println!("cargo:rerun-if-changed=lib.rs");
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TargetOs {
+    Windows,
+    Macos,
+    Linux,
+}
+
+impl From<&str> for TargetOs {
+    fn from(target: &str) -> Self {
+        if target.contains("windows") {
+            TargetOs::Windows
+        } else if target.contains("darwin") || target.contains("ios") {
+            TargetOs::Macos
+        } else {
+            TargetOs::Linux
+        }
+    }
+}
+
+impl TargetOs {
+    fn as_str(self) -> &'static str {
+        match self {
+            TargetOs::Windows => "windows",
+            TargetOs::Macos => "macos",
+            TargetOs::Linux => "linux",
+        }
+    }
+}

tests/shared_library/library/lib.rs

@@ -0,0 +1,34 @@
+#[cxx::bridge]
+pub mod ffi {
+    extern "Rust" {
+        // functions exported by the cdylib, imported by test exe
+        fn get_magic_number() -> i32;
+        fn multiply_values(a: i32, b: i32) -> i32;
+        fn library_entry_point() -> i32;
+    }
+
+    unsafe extern "C++" {
+        include!("exe_functions.h");
+
+        // functions exported by test exe, imported by cdylib
+        fn exe_callback(value: i32) -> i32;
+        fn exe_get_constant() -> i32;
+    }
+}
+
+pub fn get_magic_number() -> i32 {
+    // call back to the exe to get a constant, then add our magic
+    let exe_value = ffi::exe_get_constant();
+    exe_value + 42
+}
+
+pub fn multiply_values(a: i32, b: i32) -> i32 {
+    // use exe callback to process the result
+    let product = a * b;
+    ffi::exe_callback(product)
+}
+
+pub fn library_entry_point() -> i32 {
+    // test that we can call exe functions from the library
+    ffi::exe_callback(100) + ffi::exe_get_constant()
+}

tests/shared_library/tests/exe_functions.cc

@@ -0,0 +1,11 @@
+#include "exe_functions.h"
+
+// Implementation of exe callback functions
+int exe_callback(int value) {
+    // doubles the value
+    return value * 2;
+}
+
+int exe_get_constant() {
+    return 1000;
+}

tests/shared_library/tests/exe_functions.h

@@ -0,0 +1,5 @@
+#pragma once
+
+// Functions exported by the executable that the library can call back to
+int exe_callback(int value);
+int exe_get_constant();

tests/shared_library/tests/main.cc

@@ -0,0 +1,31 @@
+#include <iostream>
+#include <cstdint>
+#include "lib.h"
+
+int main() {
+    std::cout << "Testing shared library interaction..." << std::endl;
+
+    std::int32_t magic = get_magic_number();
+    std::cout << "magic number: " << magic << std::endl;
+    if (magic != 1042) {
+        std::cerr << "ERROR: expected 1042, got " << magic << std::endl;
+        return 1;
+    }
+
+    std::int32_t product = multiply_values(3, 4);
+    std::cout << "multiply result: " << product << std::endl;
+    if (product != 24) {
+        std::cerr << "ERROR: expected 24, got " << product << std::endl;
+        return 1;
+    }
+
+    std::int32_t entry_result = library_entry_point();
+    std::cout << "entry point result: " << entry_result << std::endl;
+    if (entry_result != 1200) {
+        std::cerr << "ERROR: expected 1200, got " << entry_result << std::endl;
+        return 1;
+    }
+
+    std::cout << "All tests passed!" << std::endl;
+    return 0;
+}