rpdfium-binary

Companion gem for rpdfium that ships precompiled PDFium binaries for major platforms.

Mirrors pypdfium2's wheel approach: the platform-specific gem includes its native library directly, the generic Ruby-platform gem falls back to a runtime download from bblanchon/pdfium-binaries.

Installation

gem install rpdfium-binary

RubyGems will pick the right gem for your platform automatically. If none of the precompiled gems matches (e.g. FreeBSD, exotic libc), the generic Ruby-platform gem is installed instead, and the binary is downloaded on first use into the user data directory.

require "rpdfium"        # or just rpdfium-binary
puts Rpdfium::Binary.library_path
# => "/.../rpdfium-binary-0.1.7811-x86_64-linux/vendor/lib/libpdfium.so"
puts Rpdfium::Binary.bundled?
# => true     (false on the runtime-download path)

Supported platforms

Ruby platform tag	bblanchon asset
`x86_64-linux`	`pdfium-linux-x64.tgz`
`aarch64-linux`	`pdfium-linux-arm64.tgz`
`x86_64-linux-musl`	`pdfium-linux-musl-x64.tgz`
`aarch64-linux-musl`	`pdfium-linux-musl-arm64.tgz`
`arm64-darwin`	`pdfium-mac-arm64.tgz`
`x86_64-darwin`	`pdfium-mac-x64.tgz`
`x64-mingw-ucrt`	`pdfium-win-x64.tgz`
`x86-mingw32`	`pdfium-win-x86.tgz`
`aarch64-mingw-ucrt`	`pdfium-win-arm64.tgz`

For unsupported platforms, set PDFIUM_LIBRARY_PATH to the path of your own libpdfium.{so,dylib,dll}.

Configuration

Env var	Effect
`PDFIUM_LIBRARY_PATH`	Hard override; rpdfium loads exactly this file.
`RPDFIUM_BINARY_PDFIUM_BUILD`	Override the PDFium build number to fetch (default: bundled gem version).
`RPDFIUM_BINARY_CACHE`	Override the cache directory for runtime-downloaded binaries.
`XDG_DATA_HOME`	Standard XDG override for the cache root.

How it works

The gemspec checks ENV["RPDFIUM_BINARY_PLATFORM"] at build time. The provided Rake tasks build:

the generic gem (platform=ruby) without bundled binary, with the runtime-download fallback;
one platform-specific gem per supported target, each with its own vendor/lib/libpdfium.<ext> packaged inside.

rake fetch:all                 # downloads all tarballs into vendor/
rake package:all               # builds *.gem files for each platform
rake sums                      # prints SHA256 sums for release notes

A maintainer's release flow looks like:

PDFIUM_BUILD=7811 rake fetch:all
rake package:all
rake sums          # paste into the GitHub release page
gem push rpdfium-binary-0.1.7811-x86_64-linux.gem
gem push rpdfium-binary-0.1.7811-arm64-darwin.gem
# ... etc, plus the generic ruby gem
gem push rpdfium-binary-0.1.7811.gem

Memory & threading notes

The shared library is loaded once per process by rpdfium. The binary file itself is just data on disk; loading it is the responsibility of the FFI binding.
Rpdfium::Binary.library_path is memoized; calling it many times is free.
Runtime downloads use Net::HTTP from the standard library — no external runtime dependencies. SHA256 verification is supported when the gem ships with a checksum DB (release-time embedded).

License

This gem's Ruby code is Apache-2.0. PDFium itself is dual-licensed Apache-2.0 / BSD-3-Clause. Bundled binaries from bblanchon/pdfium-binaries are redistributed under their respective upstream licenses, included in the gem under vendor/.