Crate pdfium_auto 

pdfium-auto

Auto-download and cache PDFium binaries at runtime, so that users of pdfium-render no longer need to manually download libpdfium and set DYLD_LIBRARY_PATH / LD_LIBRARY_PATH.

How it works

On first call to bind_pdfium or ensure_pdfium_library:

1. Checks ~/.cache/pdf2md/pdfium-{VERSION}/ for the platform library.
2. If absent, downloads the correct .tgz from bblanchon/pdfium-binaries.
3. Extracts lib/libpdfium.dylib (or .so / .dll) to the cache dir.
4. Calls Pdfium::bind_to_library to load the real library.

Subsequent calls skip the network entirely — the library is already cached.

bundled feature — compile-time embedding

For use-cases that require a fully self-contained binary (e.g., CI/CD distribution), the optional bundled feature embeds the pdfium shared library directly into the compiled executable.

Build steps:

# 1. Download and extract the platform archive (example: macOS arm64).
curl -L https://github.com/bblanchon/pdfium-binaries/releases/download/ \
     chromium%2F7690/pdfium-mac-arm64.tgz | tar xz

# 2. Build with the bundled feature, pointing PDFIUM_BUNDLE_LIB at the lib.
PDFIUM_BUNDLE_LIB=./lib/libpdfium.dylib \
  cargo build --release --features pdfium-auto/bundled

At runtime, the embedded bytes are extracted to the cache directory on first use ([ensure_pdfium_bundled] / [bind_bundled]). The resulting binary ships without any external dependency on libpdfium or network access.

Trade-offs:

	Runtime-download (bind_pdfium)	Compile-time-bundled (bind_bundled)
Binary size	~5 MB	~35 MB (+30 MB)
First run	Downloads pdfium (~20 s)	Instant (already embedded)
Net access required at runtime	Once (first run)	Never
Net access required at compile time	No	No
Cross-platform binary	N/A (same arch)	Same constraints

Usage

use pdfium_auto::{bind_pdfium_silent, bind_pdfium_from_path, ensure_pdfium_library};

// Option A: convenient one-shot bind (silent, no progress)
let pdfium = bind_pdfium_silent().expect("PDFium unavailable");

// Option B: download with progress, then bind
let path = ensure_pdfium_library(Some(&|downloaded, total| {
    if let Some(t) = total {
        eprint!("\rDownloading PDFium: {}/{} bytes", downloaded, t);
    }
})).expect("download failed");
let pdfium = bind_pdfium_from_path(&path).expect("bind failed");

Platform support

OS	Arch	Library
macOS	arm64	libpdfium.dylib
macOS	x86_64	libpdfium.dylib
Linux	x86_64	libpdfium.so
Linux	aarch64	libpdfium.so
Windows	x86_64	pdfium.dll
Windows	aarch64	pdfium.dll
Windows	x86	pdfium.dll

Environment variable overrides

• PDFIUM_LIB_PATH — path to an existing pdfium library; skips download.
• PDFIUM_AUTO_CACHE_DIR — override the default cache directory.
• PDFIUM_BUNDLE_LIB — (compile time) path to the dylib to embed when the bundled feature is active.

Enums

PdfiumAutoError

Errors returned by pdfium-auto operations.

Constants

PDFIUM_VERSION

The pdfium-binaries release tag used for downloads.

Functions

bind_pdfium

Binds to PDFium, downloading it first if necessary.

bind_pdfium_from_path

Binds to a PDFium library at an explicit path.

bind_pdfium_silent

Binds to PDFium without any progress output.

cached_pdfium_path

Returns the on-disk path to the PDFium library, or None if not cached.

ensure_pdfium_library

Ensures the PDFium dynamic library is present in the local cache.

is_pdfium_cached

Returns true if the PDFium library is already cached on disk (no network access needed on next call to ensure_pdfium_library).

pdfium_cache_dir

Returns the per-version cache directory for the PDFium library.