Installation

Three install paths. Pick the one that matches your workflow.

gem install confium

Pre-compiled platform gems are published for x86_64-linux, aarch64-linux, x86_64-linux-musl, aarch64-linux-musl, x86_64-darwin, arm64-darwin, and x64-mingw-ucrt — each carries one extension per Ruby C-ABI window (3.1, 3.2, and 3.3+), so installation on those platforms needs only:

  • Ruby >= 3.1

Option 2: Bundler

Add to your Gemfile:

gem "confium", "~> 0.3"

Then:

bundle install

Option 3: Build from source

Needed on platforms without pre-compiled gems, or for development on the gem itself. The extension is pure Rust — a single toolchain, no C compiler, no Botan, no OpenSSL, no Boost:

git clone https://github.com/confium/confium-ruby.git
cd confium-ruby
bundle install
bundle exec rake compile
bundle exec rspec

The native extension builds into lib/confium_native/confium_native.bundle (macOS) or .so (Linux).

Pre-compiled gem releases

Platform gems are built on native-architecture runners and published on every release tag by .github/workflows/release-native-gems.yml, which installs and exercises each packaged gem on Ruby 3.1–3.4 before publishing. To build one locally on a matching machine:

bundle exec rake compile
bundle exec rake native_gem:package[arm64-darwin]

Verifying the install

require "confium"
puts Confium::VERSION
puts Confium.core_version

Expected output: the gem version string and the underlying confium-core version string.

Troubleshooting

ERROR: Failed to build gem native extension (source builds): ensure Rust is installed and on your PATH (rustup show). The gem refuses to compile without Rust stable 1.85+. Nothing else is required — the extension has no C dependencies.

LoadError: cannot load such file -- confium_native/confium_native: the native extension didn’t compile. Run bundle exec rake compile for verbose error output.

Next steps