kreuzberg 4.0.0.pre.rc.7 → 4.0.0.pre.rc.11

data/vendor/kreuzberg/build.rs

@@ -1,3 +1,29 @@
+// Kreuzberg Build Script - PDFium Linking Configuration
+//
+// This build script handles PDFium library downloading and linking for the kreuzberg crate.
+// It supports multiple linking strategies via Cargo features:
+//
+// 1. Default (pdf, bundled-pdfium): Download dynamic library and embed in binary
+//    - Self-contained binary that extracts library at runtime
+//    - Larger binary size but no external .so dependency
+//    - No PDFIUM_*_PATH environment variables needed
+//
+// 2. static-pdfium: Static linking (no runtime dependency)
+//    - REQUIRES: PDFIUM_STATIC_LIB_PATH environment variable pointing to libpdfium.a directory
+//    - Reason: bblanchon/pdfium-binaries only provides dynamic libraries
+//    - Use case: Docker with musl, fully static binaries
+//    - Note: libpdfium.a must be obtained separately (e.g., paulocoutinhox/pdfium-lib)
+//
+// 3. system-pdfium: Use system-installed pdfium
+//    - Detected via pkg-config or KREUZBERG_PDFIUM_SYSTEM_PATH
+//
+// Environment Variables:
+// - PDFIUM_STATIC_LIB_PATH: Path to directory containing libpdfium.a (for static-pdfium)
+// - KREUZBERG_PDFIUM_PREBUILT: Path to prebuilt pdfium directory (skip download)
+// - KREUZBERG_PDFIUM_SYSTEM_PATH: System pdfium library path (for system-pdfium)
+// - PDFIUM_VERSION: Override version for bblanchon/pdfium-binaries
+// - KREUZBERG_PDFIUM_DOWNLOAD_RETRIES: Number of download retries (default: 5)
+
 use std::env;
 use std::fs;
 use std::io;
@@ -6,6 +32,21 @@ use std::process::Command;
 use std::thread;
 use std::time::Duration;
 
+/// PDFium linking strategy
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum PdfiumLinkStrategy {
+    /// Download and link statically (static-pdfium feature)
+    DownloadStatic,
+    /// Download, link dynamically, and embed in binary (bundled-pdfium feature)
+    Bundled,
+    /// Use system-installed pdfium via pkg-config (system-pdfium feature)
+    System,
+}
+
+// ============================================================================
+// MAIN BUILD ORCHESTRATION
+// ============================================================================
+
 fn main() {
     let target = env::var("TARGET").unwrap();
     let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
@@ -18,15 +59,111 @@ fn main() {
         return;
     }
 
-    let (download_url, lib_name) = get_pdfium_url_and_lib(&target);
+    let strategy = determine_link_strategy(&target);
+
+    tracing::debug!("Using PDFium linking strategy: {:?}", strategy);
+
+    match strategy {
+        PdfiumLinkStrategy::DownloadStatic => {
+            let pdfium_dir = download_or_use_prebuilt(&target, &out_dir);
+            link_statically(&pdfium_dir, &target);
+            // Skip copy_lib_to_package - library embedded in binary
+        }
+        PdfiumLinkStrategy::Bundled => {
+            let pdfium_dir = download_or_use_prebuilt(&target, &out_dir);
+            link_bundled(&pdfium_dir, &target, &out_dir);
+            // Skip copy_lib_to_package - each binary extracts its own
+        }
+        PdfiumLinkStrategy::System => {
+            link_system(&target);
+            // No download or copy needed
+        }
+    }
+
+    link_system_frameworks(&target);
+    println!("cargo:rerun-if-changed=build.rs");
+}
+
+// ============================================================================
+// FEATURE & STRATEGY VALIDATION
+// ============================================================================
+
+/// Determine which linking strategy to use based on features and target
+fn determine_link_strategy(target: &str) -> PdfiumLinkStrategy {
+    // WASM handling: check for PDFIUM_WASM_LIB environment variable
+    if target.contains("wasm") {
+        if let Ok(wasm_lib) = env::var("PDFIUM_WASM_LIB") {
+            println!("cargo:rustc-link-search=native={}", wasm_lib);
+            println!("cargo:rustc-link-lib=static=pdfium");
+            return PdfiumLinkStrategy::DownloadStatic;
+        }
+        // For WASM without explicit PDFIUM_WASM_LIB, use bundled strategy
+        // This downloads pdfium-lib which provides WASM-compatible builds
+        println!("cargo:warning=WASM build using bundled PDFium (set PDFIUM_WASM_LIB to link custom WASM PDFium)");
+        return PdfiumLinkStrategy::Bundled;
+    }
+
+    let system_pdfium = cfg!(feature = "system-pdfium");
+    let bundled_pdfium = cfg!(feature = "bundled-pdfium");
+    let static_pdfium = cfg!(feature = "static-pdfium");
+
+    let enabled_count = usize::from(system_pdfium) + usize::from(bundled_pdfium) + usize::from(static_pdfium);
+    if enabled_count > 1 {
+        println!(
+            "cargo:warning=Multiple PDFium linking strategies enabled (static-pdfium={}, bundled-pdfium={}, system-pdfium={}); using bundled-pdfium for this build",
+            static_pdfium, bundled_pdfium, system_pdfium
+        );
+    }
+
+    // Feature-based strategy selection.
+    // Prefer bundled-pdfium when multiple strategies are enabled (e.g. `--all-features`) because it
+    // does not require external PDFIUM_STATIC_LIB_PATH and does not depend on a system install.
+    if bundled_pdfium {
+        return PdfiumLinkStrategy::Bundled;
+    }
+    if system_pdfium {
+        return PdfiumLinkStrategy::System;
+    }
+    if static_pdfium {
+        return PdfiumLinkStrategy::DownloadStatic;
+    }
 
+    // Default: download and link dynamically (bundled-pdfium preferred if pdf not already selected)
+    // When only 'pdf' feature is enabled (no linking strategy), default to bundled-pdfium
+    PdfiumLinkStrategy::Bundled
+}
+
+// ============================================================================
+// DOWNLOAD & PREBUILT ORCHESTRATION
+// ============================================================================
+
+/// Download PDFium or use prebuilt directory
+///
+/// This is the main orchestrator function that:
+/// 1. Checks for `KREUZBERG_PDFIUM_PREBUILT` environment variable
+/// 2. If set and valid, uses prebuilt pdfium directory
+/// 3. If not set, downloads pdfium to out_dir (with caching)
+/// 4. Returns PathBuf to pdfium directory
+///
+/// Reuses all existing helper functions:
+/// - `get_pdfium_url_and_lib()` - determines download URL for target
+/// - `download_and_extract_pdfium()` - downloads with retry logic
+/// - `runtime_library_info()` - platform-specific library names
+/// - `prepare_prebuilt_pdfium()` - handles prebuilt copy
+fn download_or_use_prebuilt(target: &str, out_dir: &Path) -> PathBuf {
+    let (download_url, _lib_name) = get_pdfium_url_and_lib(target);
     let pdfium_dir = out_dir.join("pdfium");
 
+    // Check for prebuilt pdfium directory
     if let Some(prebuilt) = env::var_os("KREUZBERG_PDFIUM_PREBUILT") {
         let prebuilt_path = PathBuf::from(prebuilt);
         if prebuilt_path.exists() {
             prepare_prebuilt_pdfium(&prebuilt_path, &pdfium_dir)
                 .unwrap_or_else(|err| panic!("Failed to copy Pdfium from {}: {}", prebuilt_path.display(), err));
+            if target.contains("windows") {
+                ensure_windows_import_library(&pdfium_dir);
+            }
+            return pdfium_dir;
         } else {
             panic!(
                 "Environment variable KREUZBERG_PDFIUM_PREBUILT points to '{}' but the directory does not exist",
@@ -35,8 +172,10 @@ fn main() {
         }
     }
 
-    let (runtime_lib_name, runtime_subdir) = runtime_library_info(&target);
-    let runtime_lib_path = pdfium_dir.join(runtime_subdir).join(&runtime_lib_name);
+    // Check if library already exists (cache validation) using flexible detection
+    let (runtime_lib_name, runtime_subdir) = runtime_library_info(target);
+    let lib_found = find_pdfium_library(&pdfium_dir, &runtime_lib_name, runtime_subdir).is_ok();
+
     let import_lib_exists = if target.contains("windows") {
         let lib_dir = pdfium_dir.join("lib");
         lib_dir.join("pdfium.lib").exists() || lib_dir.join("pdfium.dll.lib").exists()
@@ -44,60 +183,52 @@ fn main() {
         true
     };
 
-    if !runtime_lib_path.exists() || !import_lib_exists {
+    if !lib_found || !import_lib_exists {
         tracing::debug!("Pdfium library not found, downloading for target: {}", target);
         tracing::debug!("Download URL: {}", download_url);
         download_and_extract_pdfium(&download_url, &pdfium_dir);
     } else {
-        tracing::debug!("Pdfium library already present at {}", runtime_lib_path.display());
+        tracing::debug!("Pdfium library already cached at {}", pdfium_dir.display());
     }
 
+    // Windows-specific: ensure pdfium.lib exists
     if target.contains("windows") {
-        let lib_dir = pdfium_dir.join("lib");
-        let dll_lib = lib_dir.join("pdfium.dll.lib");
-        let expected_lib = lib_dir.join("pdfium.lib");
-
-        if dll_lib.exists() && !expected_lib.exists() {
-            tracing::debug!("Renaming cached {} to {}", dll_lib.display(), expected_lib.display());
-            fs::rename(&dll_lib, &expected_lib).expect("Failed to rename pdfium.dll.lib to pdfium.lib");
-        }
+        ensure_windows_import_library(&pdfium_dir);
     }
 
-    let lib_dir = pdfium_dir.join("lib");
-    println!("cargo:rustc-link-search=native={}", lib_dir.display());
-
-    // WASM requires static linking
-    let link_type = if target.contains("wasm") { "static" } else { "dylib" };
-    println!("cargo:rustc-link-lib={}={}", link_type, lib_name);
-
-    if target.contains("darwin") {
-        println!("cargo:rustc-link-arg=-Wl,-rpath,@loader_path");
-        println!("cargo:rustc-link-arg=-Wl,-rpath,@loader_path/.");
-    } else if target.contains("linux") {
-        println!("cargo:rustc-link-arg=-Wl,-rpath,$ORIGIN");
-        println!("cargo:rustc-link-arg=-Wl,-rpath,$ORIGIN/.");
-    }
+    pdfium_dir
+}
 
-    copy_lib_to_package(&pdfium_dir, &target);
+fn ensure_windows_import_library(pdfium_dir: &Path) {
+    let lib_dir = pdfium_dir.join("lib");
+    let dll_lib = lib_dir.join("pdfium.dll.lib");
+    let expected_lib = lib_dir.join("pdfium.lib");
 
-    if target.contains("darwin") {
-        println!("cargo:rustc-link-lib=framework=CoreFoundation");
-        println!("cargo:rustc-link-lib=framework=CoreGraphics");
-        println!("cargo:rustc-link-lib=framework=CoreText");
-        println!("cargo:rustc-link-lib=framework=AppKit");
-        println!("cargo:rustc-link-lib=dylib=c++");
-    } else if target.contains("linux") {
-        println!("cargo:rustc-link-lib=dylib=stdc++");
-        println!("cargo:rustc-link-lib=dylib=m");
-    } else if target.contains("windows") {
-        println!("cargo:rustc-link-lib=dylib=gdi32");
-        println!("cargo:rustc-link-lib=dylib=user32");
-        println!("cargo:rustc-link-lib=dylib=advapi32");
+    if dll_lib.exists() && !expected_lib.exists() {
+        tracing::debug!(
+            "Ensuring Windows import library at {} (source: {})",
+            expected_lib.display(),
+            dll_lib.display()
+        );
+        fs::copy(&dll_lib, &expected_lib).unwrap_or_else(|err| {
+            panic!(
+                "Failed to copy Windows import library from {} to {}: {}",
+                dll_lib.display(),
+                expected_lib.display(),
+                err
+            )
+        });
     }
-
-    println!("cargo:rerun-if-changed=build.rs");
 }
 
+// ============================================================================
+// DOWNLOAD UTILITIES
+// ============================================================================
+
+/// Fetch the latest release version from a GitHub repository
+///
+/// Uses curl to query the GitHub API and extract the tag_name from the
+/// latest release JSON response. Falls back to "7529" if API call fails.
 fn get_latest_version(repo: &str) -> String {
     let api_url = format!("https://api.github.com/repos/{}/releases/latest", repo);
 
@@ -122,6 +253,12 @@ fn get_latest_version(repo: &str) -> String {
     "7529".to_string()
 }
 
+/// Get the download URL and library name for the target platform
+///
+/// Determines platform/architecture from target triple and constructs
+/// the appropriate GitHub release download URL. Supports:
+/// - WASM: paulocoutinhox/pdfium-lib
+/// - Other platforms: bblanchon/pdfium-binaries
 fn get_pdfium_url_and_lib(target: &str) -> (String, String) {
     if target.contains("wasm") {
         let version = env::var("PDFIUM_WASM_VERSION")
@@ -180,6 +317,15 @@ fn get_pdfium_url_and_lib(target: &str) -> (String, String) {
     (url, "pdfium".to_string())
 }
 
+/// Download and extract PDFium archive with retry logic
+///
+/// Features:
+/// - Exponential backoff retry (configurable via env vars)
+/// - File type validation (gzip check)
+/// - Windows-specific import library handling (pdfium.dll.lib -> pdfium.lib)
+/// - Environment variables:
+///   - KREUZBERG_PDFIUM_DOWNLOAD_RETRIES: number of retries (default: 5)
+///   - KREUZBERG_PDFIUM_DOWNLOAD_BACKOFF_SECS: initial backoff in seconds (default: 2)
 fn download_and_extract_pdfium(url: &str, dest_dir: &Path) {
     fs::create_dir_all(dest_dir).expect("Failed to create pdfium directory");
 
@@ -291,195 +437,407 @@ fn download_and_extract_pdfium(url: &str, dest_dir: &Path) {
     tracing::debug!("Pdfium downloaded and extracted successfully");
 }
 
-fn copy_lib_to_package(pdfium_dir: &Path, target: &str) {
-    let (runtime_lib_name, runtime_subdir) = runtime_library_info(target);
-    let src_lib = pdfium_dir.join(runtime_subdir).join(&runtime_lib_name);
+// ============================================================================
+// PREBUILT HANDLING
+// ============================================================================
 
-    if !src_lib.exists() {
-        tracing::debug!("Source library not found: {}", src_lib.display());
-        return;
-    }
-
-    if target.contains("darwin") {
-        fix_macos_install_name(&src_lib, &runtime_lib_name);
-        codesign_if_needed(target, &src_lib);
+/// Prepare prebuilt PDFium by copying to destination directory
+///
+/// Removes existing destination if present, then recursively copies
+/// all files from prebuilt source to destination.
+fn prepare_prebuilt_pdfium(prebuilt_src: &Path, dest_dir: &Path) -> io::Result<()> {
+    if dest_dir.exists() {
+        fs::remove_dir_all(dest_dir)?;
     }
+    copy_dir_all(prebuilt_src, dest_dir)
+}
 
-    let crate_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
-    let workspace_root = crate_dir.parent().unwrap().parent().unwrap();
-
-    if let Ok(profile) = env::var("PROFILE") {
-        let target_dir = if let Ok(cargo_target) = env::var("TARGET") {
-            workspace_root.join("target").join(cargo_target).join(&profile)
+/// Recursively copy directory tree
+///
+/// Used by `prepare_prebuilt_pdfium()` to copy entire pdfium directory
+/// structure, preserving all files and subdirectories.
+fn copy_dir_all(src: &Path, dst: &Path) -> io::Result<()> {
+    fs::create_dir_all(dst)?;
+    for entry in fs::read_dir(src)? {
+        let entry = entry?;
+        let file_type = entry.file_type()?;
+        let target_path = dst.join(entry.file_name());
+        if file_type.is_dir() {
+            copy_dir_all(&entry.path(), &target_path)?;
         } else {
-            workspace_root.join("target").join(&profile)
-        };
-
-        if target_dir.exists() {
-            copy_lib_if_needed(
-                &src_lib,
-                &target_dir.join(&runtime_lib_name),
-                "CLI target directory",
-                target,
-            );
-        }
-
-        let simple_target_dir = workspace_root.join("target").join(&profile);
-        if simple_target_dir != target_dir {
-            fs::create_dir_all(&simple_target_dir).ok();
-            copy_lib_if_needed(
-                &src_lib,
-                &simple_target_dir.join(&runtime_lib_name),
-                "Java FFI target directory",
-                target,
-            );
+            fs::copy(entry.path(), &target_path)?;
         }
     }
+    Ok(())
+}
 
-    let python_dest_dir = workspace_root.join("packages").join("python").join("kreuzberg");
-    if python_dest_dir.exists() {
-        copy_lib_if_needed(
-            &src_lib,
-            &python_dest_dir.join(&runtime_lib_name),
-            "Python package",
-            target,
-        );
+// ============================================================================
+// PLATFORM UTILITIES
+// ============================================================================
+
+/// Get platform-specific runtime library name and subdirectory
+///
+/// Returns tuple of (library_name, subdirectory) for the target platform:
+/// - WASM: ("libpdfium.a", "release/lib")
+/// - Windows: ("pdfium.dll", "bin")
+/// - macOS: ("libpdfium.dylib", "lib")
+/// - Linux: ("libpdfium.so", "lib")
+fn runtime_library_info(target: &str) -> (String, &'static str) {
+    if target.contains("wasm") {
+        // pdfium-lib `wasm.tgz` extracts into `release/lib/libpdfium.a`
+        ("libpdfium.a".to_string(), "release/lib")
+    } else if target.contains("windows") {
+        ("pdfium.dll".to_string(), "bin")
+    } else if target.contains("darwin") {
+        ("libpdfium.dylib".to_string(), "lib")
     } else {
-        tracing::debug!("Python package directory not found, skipping Python library copy");
+        ("libpdfium.so".to_string(), "lib")
     }
+}
 
-    let node_dest_dir = workspace_root.join("crates").join("kreuzberg-node");
-    if node_dest_dir.exists() {
-        copy_lib_if_needed(
-            &src_lib,
-            &node_dest_dir.join(&runtime_lib_name),
-            "Node.js package",
-            target,
-        );
-    } else {
-        tracing::debug!("Node.js package directory not found, skipping Node library copy");
+/// Find PDFium library in archive with flexible directory detection
+///
+/// Attempts to locate the library at multiple possible locations:
+/// - {subdir}/{lib_name} (standard location)
+/// - {lib_name} (root of archive)
+/// - bin/{lib_name} (alternative location)
+/// - lib/{lib_name} (explicit lib directory)
+///
+/// This handles variations in archive structure across different platform builds,
+/// particularly macOS ARM64 where the archive structure may differ.
+///
+/// Returns the full path to the library if found, or an error with available files.
+fn find_pdfium_library(pdfium_dir: &Path, lib_name: &str, expected_subdir: &str) -> Result<PathBuf, String> {
+    // Candidates in priority order
+    let candidates = [
+        pdfium_dir.join(expected_subdir).join(lib_name), // Standard: lib/libpdfium.dylib
+        pdfium_dir.join(lib_name),                       // Root: libpdfium.dylib
+        pdfium_dir.join("bin").join(lib_name),           // Alternative: bin/libpdfium.dylib
+        pdfium_dir.join("lib").join(lib_name),           // Explicit lib: lib/libpdfium.dylib
+    ];
+
+    // Try each candidate
+    for candidate in &candidates {
+        if candidate.exists() {
+            tracing::debug!("Found PDFium library at: {}", candidate.display());
+            return Ok(candidate.clone());
+        }
     }
 
-    let ruby_dest_dir = workspace_root.join("packages").join("ruby").join("lib");
-    if ruby_dest_dir.exists() {
-        copy_lib_if_needed(&src_lib, &ruby_dest_dir.join(&runtime_lib_name), "Ruby package", target);
-    } else {
-        tracing::debug!("Ruby package directory not found, skipping Ruby library copy");
+    // Library not found - provide detailed error with directory listing
+    let mut error_msg = format!(
+        "PDFium library not found at expected location: {}/{}\n\n",
+        pdfium_dir.display(),
+        expected_subdir
+    );
+    error_msg.push_str("Attempted locations:\n");
+    for candidate in &candidates {
+        error_msg.push_str(&format!("  - {}\n", candidate.display()));
+    }
+
+    // List actual contents of pdfium directory for debugging
+    error_msg.push_str("\nActual archive contents:\n");
+    if let Ok(entries) = fs::read_dir(pdfium_dir) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let file_type = if path.is_dir() { "dir" } else { "file" };
+            error_msg.push_str(&format!("  {} ({})\n", path.display(), file_type));
+
+            // Show contents of subdirectories
+            if path.is_dir()
+                && let Ok(sub_entries) = fs::read_dir(&path)
+            {
+                for sub_entry in sub_entries.flatten() {
+                    let sub_path = sub_entry.path();
+                    let sub_type = if sub_path.is_dir() { "dir" } else { "file" };
+                    error_msg.push_str(&format!("    {} ({})\n", sub_path.display(), sub_type));
+                }
+            }
+        }
     }
+
+    Err(error_msg)
 }
 
-fn copy_lib_if_needed(src: &Path, dest: &Path, package_name: &str, target: &str) {
-    use std::fs;
+// ============================================================================
+// LINKING STRATEGIES
+// ============================================================================
 
-    let should_copy = if dest.exists() {
-        let src_metadata = fs::metadata(src).ok();
-        let dest_metadata = fs::metadata(dest).ok();
-        match (src_metadata, dest_metadata) {
-            (Some(src), Some(dest)) => src.modified().ok() > dest.modified().ok(),
-            _ => true,
-        }
-    } else {
-        true
+/// Link PDFium dynamically (default)
+///
+/// Sets up linker to use PDFium as a dynamic library (.dylib/.so/.dll)
+/// with platform-specific rpath configuration for runtime library discovery.
+/// Supports flexible archive structures by adding multiple possible lib directories.
+fn link_dynamically(pdfium_dir: &Path, target: &str) {
+    let (runtime_lib_name, runtime_subdir) = runtime_library_info(target);
+
+    // Find the actual library location (handles multiple possible archive structures)
+    let lib_path = match find_pdfium_library(pdfium_dir, &runtime_lib_name, runtime_subdir) {
+        Ok(path) => path.parent().unwrap_or(pdfium_dir).to_path_buf(),
+        Err(err) => panic!("{}", err),
     };
 
-    if should_copy {
-        match fs::copy(src, dest) {
-            Ok(_) => {
-                tracing::debug!("Copied {} to {} ({})", src.display(), dest.display(), package_name);
-                codesign_if_needed(target, dest);
-            }
-            Err(e) => tracing::debug!("Failed to copy library to {}: {}", package_name, e),
-        }
+    println!("cargo:rustc-link-search=native={}", lib_path.display());
+    println!("cargo:rustc-link-lib=dylib=pdfium");
+
+    // Also add standard lib directory for compatibility
+    let std_lib_dir = pdfium_dir.join("lib");
+    if std_lib_dir.exists() && std_lib_dir != lib_path {
+        println!("cargo:rustc-link-search=native={}", std_lib_dir.display());
     }
-}
 
-fn codesign_if_needed(target: &str, binary: &Path) {
-    if !target.contains("apple-darwin") || !binary.exists() {
-        return;
+    // Add bin directory for platforms where it might be needed
+    let bin_dir = pdfium_dir.join("bin");
+    if bin_dir.exists() && bin_dir != lib_path {
+        println!("cargo:rustc-link-search=native={}", bin_dir.display());
     }
 
-    let identity = env::var("KREUZBERG_CODESIGN_IDENTITY").unwrap_or_else(|_| "-".to_string());
-    let status = Command::new("codesign")
-        .arg("--force")
-        .arg("--timestamp=none")
-        .arg("--sign")
-        .arg(identity)
-        .arg(binary)
-        .status();
+    // Set rpath for dynamic linking
+    if target.contains("darwin") {
+        println!("cargo:rustc-link-arg=-Wl,-rpath,@loader_path");
+        println!("cargo:rustc-link-arg=-Wl,-rpath,@loader_path/.");
+    } else if target.contains("linux") {
+        println!("cargo:rustc-link-arg=-Wl,-rpath,$ORIGIN");
+        println!("cargo:rustc-link-arg=-Wl,-rpath,$ORIGIN/.");
+    }
+}
 
-    match status {
-        Ok(result) if result.success() => {
-            tracing::debug!("Codesigned {}", binary.display());
+/// Link PDFium statically (static-pdfium feature)
+///
+/// Embeds PDFium into the binary as a static library. Adds system
+/// dependencies required for static linking on Linux.
+/// Supports flexible archive structures by finding library in multiple locations.
+///
+/// Environment Variables:
+/// - `PDFIUM_STATIC_LIB_PATH`: Path to directory containing libpdfium.a (for Docker/musl builds)
+///
+/// Note: bblanchon/pdfium-binaries only provides dynamic libraries.
+/// On macOS, this will fallback to dynamic linking with a warning.
+/// On Linux, you must provide PDFIUM_STATIC_LIB_PATH pointing to a static build.
+fn link_statically(pdfium_dir: &Path, target: &str) {
+    // For static linking, we need libpdfium.a (not .dylib or .so)
+    let static_lib_name = "libpdfium.a";
+    let lib_subdir = if target.contains("wasm") { "release/lib" } else { "lib" };
+
+    // First, check if user provided a static library path via environment variable
+    if let Ok(custom_path) = env::var("PDFIUM_STATIC_LIB_PATH") {
+        let custom_lib_dir = PathBuf::from(&custom_path);
+
+        if !custom_lib_dir.exists() {
+            panic!(
+                "PDFIUM_STATIC_LIB_PATH points to '{}' but the directory does not exist",
+                custom_path
+            );
         }
-        Ok(result) => {
-            tracing::debug!(
-                "codesign exited with status {} while signing {}",
-                result,
-                binary.display()
+
+        let custom_lib = custom_lib_dir.join(static_lib_name);
+        if !custom_lib.exists() {
+            panic!(
+                "PDFIUM_STATIC_LIB_PATH points to '{}' but {} not found.\n\
+                 Expected to find: {}",
+                custom_path,
+                static_lib_name,
+                custom_lib.display()
             );
         }
-        Err(err) => {
-            tracing::debug!("Failed to run codesign for {}: {}", binary.display(), err);
+
+        tracing::debug!("Using custom static PDFium from: {}", custom_lib.display());
+        println!("cargo:rustc-link-search=native={}", custom_lib_dir.display());
+        println!("cargo:rustc-link-lib=static=pdfium");
+
+        // Static linking requires additional system dependencies
+        if target.contains("linux") {
+            println!("cargo:rustc-link-lib=dylib=pthread");
+            println!("cargo:rustc-link-lib=dylib=dl");
+        } else if target.contains("windows") {
+            println!("cargo:rustc-link-lib=dylib=ws2_32");
+            println!("cargo:rustc-link-lib=dylib=userenv");
         }
+
+        return;
     }
-}
 
-fn runtime_library_info(target: &str) -> (String, &'static str) {
-    if target.contains("wasm") {
-        ("libpdfium.a".to_string(), "lib")
-    } else if target.contains("windows") {
-        ("pdfium.dll".to_string(), "bin")
-    } else if target.contains("darwin") {
-        ("libpdfium.dylib".to_string(), "lib")
-    } else {
-        ("libpdfium.so".to_string(), "lib")
+    // Find the actual library location (handles multiple possible archive structures)
+    let lib_path = match find_pdfium_library(pdfium_dir, static_lib_name, lib_subdir) {
+        Ok(path) => path.parent().unwrap_or(pdfium_dir).to_path_buf(),
+        Err(_err) => {
+            // Static library not found - check if we're on macOS and can fallback
+            if target.contains("darwin") {
+                eprintln!("cargo:warning=Static PDFium library (libpdfium.a) not found for macOS.");
+                eprintln!("cargo:warning=bblanchon/pdfium-binaries only provides dynamic libraries.");
+                eprintln!("cargo:warning=Falling back to dynamic linking for local development.");
+                eprintln!("cargo:warning=Production Linux builds require PDFIUM_STATIC_LIB_PATH.");
+
+                // Fallback to dynamic linking on macOS
+                link_dynamically(pdfium_dir, target);
+                return;
+            } else {
+                // On Linux/Windows, provide helpful error with actionable steps
+                panic!(
+                    "Static PDFium library (libpdfium.a) not found.\n\n\
+                     bblanchon/pdfium-binaries only provides dynamic libraries.\n\n\
+                     For static linking (required for Docker with musl), you must:\n\n\
+                     1. Build static PDFium or obtain from a source that provides it\n\
+                        - See: https://github.com/ajrcarey/pdfium-render/issues/53\n\
+                        - Or use: https://github.com/paulocoutinhox/pdfium-lib (provides static builds)\n\n\
+                     2. Set environment variable pointing to the directory containing libpdfium.a:\n\
+                        export PDFIUM_STATIC_LIB_PATH=/path/to/pdfium/lib\n\n\
+                     3. Or use alternative features:\n\
+                        - 'pdf' (dynamic linking, requires .so at runtime)\n\
+                        - 'bundled-pdfium' (embeds dynamic library in binary)\n\
+                        - 'system-pdfium' (use system-installed pdfium)\n\n\
+                     Example Dockerfile pattern:\n\
+                        FROM alpine:latest as pdfium-builder\n\
+                        # Download/build static libpdfium.a\n\
+                        \n\
+                        FROM rust:alpine as builder\n\
+                        ENV PDFIUM_STATIC_LIB_PATH=/pdfium/lib\n\
+                        COPY --from=pdfium-builder /path/to/libpdfium.a /pdfium/lib/"
+                );
+            }
+        }
+    };
+
+    println!("cargo:rustc-link-search=native={}", lib_path.display());
+    println!("cargo:rustc-link-lib=static=pdfium");
+
+    // Also add standard lib directory for compatibility
+    let std_lib_dir = pdfium_dir.join("lib");
+    if std_lib_dir.exists() && std_lib_dir != lib_path {
+        println!("cargo:rustc-link-search=native={}", std_lib_dir.display());
     }
-}
 
-fn prepare_prebuilt_pdfium(prebuilt_src: &Path, dest_dir: &Path) -> io::Result<()> {
-    if dest_dir.exists() {
-        fs::remove_dir_all(dest_dir)?;
+    // Add bin directory for platforms where it might be needed
+    let bin_dir = pdfium_dir.join("bin");
+    if bin_dir.exists() && bin_dir != lib_path {
+        println!("cargo:rustc-link-search=native={}", bin_dir.display());
     }
-    copy_dir_all(prebuilt_src, dest_dir)
-}
 
-fn copy_dir_all(src: &Path, dst: &Path) -> io::Result<()> {
-    fs::create_dir_all(dst)?;
-    for entry in fs::read_dir(src)? {
-        let entry = entry?;
-        let file_type = entry.file_type()?;
-        let target_path = dst.join(entry.file_name());
-        if file_type.is_dir() {
-            copy_dir_all(&entry.path(), &target_path)?;
-        } else {
-            fs::copy(entry.path(), &target_path)?;
-        }
+    // Static linking requires additional system dependencies
+    if target.contains("linux") {
+        println!("cargo:rustc-link-lib=dylib=pthread");
+        println!("cargo:rustc-link-lib=dylib=dl");
+    } else if target.contains("windows") {
+        println!("cargo:rustc-link-lib=dylib=ws2_32");
+        println!("cargo:rustc-link-lib=dylib=userenv");
     }
-    Ok(())
 }
 
-fn fix_macos_install_name(lib_path: &Path, lib_name: &str) {
-    use std::process::Command;
+/// Link PDFium bundled (bundled-pdfium feature)
+///
+/// Links dynamically but copies library to OUT_DIR for embedding in binary.
+/// Each binary extracts and uses its own copy of the PDFium library.
+/// Supports flexible archive structures by finding library in multiple locations.
+///
+/// For WASM targets, links statically using the bundled static library.
+fn link_bundled(pdfium_dir: &Path, target: &str, out_dir: &Path) {
+    // Copy library to OUT_DIR for bundling using flexible detection
+    let (runtime_lib_name, runtime_subdir) = runtime_library_info(target);
+    let src_lib = match find_pdfium_library(pdfium_dir, &runtime_lib_name, runtime_subdir) {
+        Ok(path) => path,
+        Err(err) => panic!("{}", err),
+    };
+    let bundled_lib = out_dir.join(&runtime_lib_name);
 
-    let new_install_name = format!("@rpath/{}", lib_name);
+    fs::copy(&src_lib, &bundled_lib)
+        .unwrap_or_else(|err| panic!("Failed to copy library to OUT_DIR for bundling: {}", err));
 
-    tracing::debug!("Fixing install_name for {} to {}", lib_path.display(), new_install_name);
+    // Emit environment variable with bundled library path
+    let bundled_path = bundled_lib
+        .to_str()
+        .unwrap_or_else(|| panic!("Non-UTF8 path for bundled library: {}", bundled_lib.display()));
+    println!("cargo:rustc-env=KREUZBERG_PDFIUM_BUNDLED_PATH={}", bundled_path);
 
-    let status = Command::new("install_name_tool")
-        .arg("-id")
-        .arg(&new_install_name)
-        .arg(lib_path)
-        .status();
+    // For WASM, link statically using the bundled library
+    if target.contains("wasm") {
+        let lib_dir = bundled_lib
+            .parent()
+            .unwrap_or_else(|| panic!("Invalid bundled library path: {}", bundled_lib.display()));
+        println!("cargo:rustc-link-search=native={}", lib_dir.display());
+        println!("cargo:rustc-link-lib=static=pdfium");
+        tracing::debug!("Bundled PDFium static library linked for WASM at: {}", bundled_path);
+    } else {
+        tracing::debug!("Bundled PDFium library at: {}", bundled_path);
+    }
+}
 
-    match status {
-        Ok(s) if s.success() => {
-            tracing::debug!("Successfully updated install_name");
+/// Link system-installed PDFium (system-pdfium feature)
+///
+/// Attempts to find PDFium via pkg-config first, then falls back to
+/// environment variables (KREUZBERG_PDFIUM_SYSTEM_PATH, KREUZBERG_PDFIUM_SYSTEM_INCLUDE).
+fn link_system(_target: &str) {
+    // Try pkg-config first
+    match pkg_config::Config::new().atleast_version("5.0").probe("pdfium") {
+        Ok(library) => {
+            tracing::debug!("Found system pdfium via pkg-config");
+            for include_path in &library.include_paths {
+                println!("cargo:include={}", include_path.display());
+            }
+            return;
         }
-        Ok(s) => {
-            tracing::debug!("install_name_tool failed with status: {}", s);
+        Err(err) => {
+            tracing::debug!("pkg-config probe failed: {}", err);
         }
-        Err(e) => {
-            tracing::debug!("Failed to run install_name_tool: {}", e);
+    }
+
+    // Fallback to environment variables
+    let lib_path = env::var("KREUZBERG_PDFIUM_SYSTEM_PATH").ok();
+    let include_path = env::var("KREUZBERG_PDFIUM_SYSTEM_INCLUDE").ok();
+
+    if let Some(lib_dir) = lib_path {
+        let lib_dir_path = PathBuf::from(&lib_dir);
+        if !lib_dir_path.exists() {
+            panic!(
+                "KREUZBERG_PDFIUM_SYSTEM_PATH points to '{}' but the directory does not exist",
+                lib_dir
+            );
         }
+
+        println!("cargo:rustc-link-search=native={}", lib_dir);
+        println!("cargo:rustc-link-lib=dylib=pdfium");
+
+        if let Some(inc_dir) = include_path {
+            println!("cargo:include={}", inc_dir);
+        }
+
+        tracing::debug!("Using system pdfium from: {}", lib_dir);
+        return;
+    }
+
+    // No system pdfium found
+    panic!(
+        "system-pdfium feature enabled but pdfium not found.\n\
+         \n\
+         Please install pdfium system-wide or provide:\n\
+         - KREUZBERG_PDFIUM_SYSTEM_PATH: path to directory containing libpdfium\n\
+         - KREUZBERG_PDFIUM_SYSTEM_INCLUDE: path to pdfium headers (optional)\n\
+         \n\
+         Alternatively, use a different linking strategy:\n\
+         - Default (dynamic): cargo build --features pdf\n\
+         - Static linking: cargo build --features pdf,static-pdfium\n\
+         - Bundled: cargo build --features pdf,bundled-pdfium"
+    );
+}
+
+/// Link system frameworks and standard libraries
+///
+/// Adds platform-specific system libraries required for PDFium linking:
+/// - macOS: CoreFoundation, CoreGraphics, CoreText, AppKit, libc++
+/// - Linux: stdc++, libm
+/// - Windows: gdi32, user32, advapi32
+fn link_system_frameworks(target: &str) {
+    if target.contains("darwin") {
+        println!("cargo:rustc-link-lib=framework=CoreFoundation");
+        println!("cargo:rustc-link-lib=framework=CoreGraphics");
+        println!("cargo:rustc-link-lib=framework=CoreText");
+        println!("cargo:rustc-link-lib=framework=AppKit");
+        println!("cargo:rustc-link-lib=dylib=c++");
+    } else if target.contains("linux") {
+        println!("cargo:rustc-link-lib=dylib=stdc++");
+        println!("cargo:rustc-link-lib=dylib=m");
+    } else if target.contains("windows") {
+        println!("cargo:rustc-link-lib=dylib=gdi32");
+        println!("cargo:rustc-link-lib=dylib=user32");
+        println!("cargo:rustc-link-lib=dylib=advapi32");
     }
 }