website·Indexed 32 days ago
https://oxidize-rb.orgLow-level Rust bindings for the Ruby C API used to build safe and high-performance Ruby extensions. The documentation covers memory management with Ruby's GC, type conversions, error mapping between Rust and Ruby, project structure for gems, and the use of rb-sys-test-helpers for integration testing.
rb-sys provides the low-level, unsafe bindings to Ruby's C API, while higher-level libraries like Magnus provide a safe and ergonomic wrapper for developers.When building Ruby extensions with Rust, you can choose between low-level control via rb-sys or high-level convenience via Magnus.
| Aspect | Direct rb-sys | Magnus (High-Level) |
|---|---|---|
| Control | Maximum control over Ruby VM | Abstracts away VM details |
| Safety | Requires unsafe blocks | Mostly safe API |
| Verbosity | Verbose; manual type conversion | Concise; automatic type conversion |
| Error Handling | Manual check of Ruby error state | Idiomatic Result<T, Error> |
| Best For | Performance-critical code, internal APIs | Most general-purpose gems |
For most projects, Magnus is recommended. Use rb-sys only for critical performance requirements or when accessing Ruby internals not covered by wrappers.
ext/ directory houses the Rust crates.my_gem/
├── 📦 Cargo.toml # Workspace configuration
├── 💎 Gemfile # Ruby dependencies
├── 🔨 Rakefile # Build automation
├── 📋 my_gem.gemspec # Gem specification
├── 📝 README.md # Documentation
├── 🔒 Gemfile.lock # Locked dependencies
├── 📂 ext/
│ └── my_gem/
│ ├── 🦀 Cargo.toml # Extension dependencies
│ ├── 🔧 extconf.rb # Build configuration
│ ├── 🏗️ build.rs # Build script (optional)
│ └── 📂 src/
│ ├── 📄 lib.rs # Rust entry point
│ └── 📄 *.rs # Additional modules
├── 📂 lib/
│ ├── 💎 my_gem.rb # Ruby entry point
│ └── 📂 my_gem/
│ ├── 📄 version.rb # Version constant
│ └── 📄 *.rb # Ruby modules
├── 🧪 test/ # Test files
├── 📊 benchmark/ # Performance tests
└── 📚 examples/ # Usage examplesThe oxidize-rb ecosystem provides a layered approach to building Ruby extensions:
When running bundle exec rake compile, the build process follows these four steps:
extconf.rb execution: Ruby's mkmf library executes the extension's extconf.rb script.create_rust_makefile helper from rb-sys generates a Makefile configured for the Rust code.cargo build invocation: The Makefile triggers cargo build to compile the Rust crate into a dynamic shared library.lib directory for Ruby to load.When developing Ruby extensions in Rust using Magnus, follow these critical guidelines:
Result<T, magnus::Error> for any function that can fail. This ensures Rust errors are automatically mapped to Ruby exceptions.String, i64, Vec<T>).RString, RArray, and RHash instead of standard Rust types.panic!. A panic in Rust will crash the entire Ruby process.Result for error handling, significantly reducing the need for unsafe code. It is suitable for most general-purpose Ruby gems.use magnus::{function, prelude::*, Error, Ruby};
fn hello(subject: String) -> String {
format!("Hello from Rust, {subject}!")
}
#[magnus::init]
fn init(ruby: &Ruby) -> Result<(), Error> {
let module = ruby.define_module("StringUtils")?;
module.define_singleton_method("hello", function!(hello, 1))?;
Ok(())
}Depending on your goal, use different tools for interacting with Ruby from Rust:
rb-sys directly for unsafe access to libruby.rb-sys feature) for a safer API.rb-sys with the link-ruby feature to embed the Ruby VM in a Rust binary.gdb or lldb.nil is a special value. When converting a magnus::Value to a Rust type, TryConvert::try_convert(val).ok() will return None if the value is nil or of an incompatible type. To return nil to Ruby, use ruby.qnil().as_value().use magnus::{Value, Ruby, RString, TryConvert, Error};
fn handle_nil(_ruby: &Ruby, val: Value) -> Result<(), Error> {
// Returns None if val is nil or not a string
let maybe_string: Option<RString> = TryConvert::try_convert(val).ok();
Ok(())
}
fn returns_nil(ruby: &Ruby) -> Value {
ruby.qnil().as_value()
}