Skip to main content

Gem Configuration

The rb_sys Ruby gem provides helpers for building Rust-based extensions, integrating with standard tools like rake-compiler.

RbSys::ExtensionTask​

Define how your Rust extension is built within your Rakefile using RbSys::ExtensionTask.

# Rakefile
require "rb_sys/extensiontask"

GEMSPEC = Gem::Specification.load("my_gem.gemspec")

RbSys::ExtensionTask.new("my-crate-name", GEMSPEC) do |ext|
  ext.lib_dir = "lib/my_gem"
  ext.cross_compile = true # Enable cross-compilation with rb-sys-dock.
end

create_rust_makefile​

Generate a Ruby-compatible Makefile for your Rust extension in your extconf.rb.

# ext/my_gem/extconf.rb
require "mkmf"
require "rb_sys/mkmf"

create_rust_makefile("my_gem") do |r|
  r.profile = ENV.fetch("RB_SYS_CARGO_PROFILE", :dev).to_sym # Cargo build profile (:dev or :release).
  r.features = ["a-feature"] # Comma-separated list of Cargo features.
  r.extra_rustflags = ["--cfg=some_config_flag"] # Extra flags for $RUSTFLAGS.
  r.ext_dir = "." # Directory containing Cargo.toml, relative to extconf.rb.
end

Environment Variables​

These environment variables control the rb_sys build process.

Environment VariableDescription
RB_SYS_CARGO_PROFILESet the Cargo profile (e.g., release or dev).
RB_SYS_CARGO_FEATURESComma-separated list of Cargo features to enable.
RB_SYS_FORCE_INSTALL_RUST_TOOLCHAINSet to true to force installation of a Rust toolchain.
RUBY_STATICSet to true to force static linking of libruby.
LIBCLANG_PATHPath to libclang if it can't be found automatically.
RB_SYS_VERBOSE_BUILDSet to true to enable verbose output during the build.

Troubleshooting​

libclang Not Found​

If libclang is not found during bindgen execution, add the libclang gem to your Gemfile.

# Gemfile
gem "libclang", "~> 14.0.6"