macournoyer / rb-sys

Easily build Ruby native extensions in Rust

rb-sys

The primary goal of rb-sys is to make building native Ruby extensions in Rust easier than it would be in C. If it's not easy, it's a bug.

Features

• Battle-tested Rust bindings for the Ruby C API
• Support for Ruby 2.4+
• Supports all major platforms (Linux, macOS, Windows)
• Cross compilation of gems
• Integration with rake-compiler

New to rb-sys?

• Ruby on Rust Book 📖 to describe how to build, test, and deploy a Rusty Ruby Gem
• Contributing Docs 💻 to get started in making your first contributions to rb-sys
• rb-sys gem 💎 to learn more about the rb-sys gem for compiling extensions

Quick links

• Battle-tested Ruby FFI bindings for Rust (via rb-sys crate)
• GitHub action to setup a test environment in CI
• GitHub action to easily cross compile in CI
• Test helpers) for testing Ruby extensions in Rust

Usage

Below are some examples of how to use rb-sys to build native Rust extensions. Use these as a starting point for your building your own gem.

• The wasmtime-rb gem uses rb-sys and magnus to package the rust wasmtime library as a Ruby gem.
• The oxi-test gem is the canonical example of how to use rb-sys. It is a minimal, fully tested with GitHub actions, and cross-compiles native gem binaries. This should be your first stop for learning how to use rb-sys.
• Docs for the rb_sys gem and using it with an extconf.rb file.
• The magnus repo has some solid examples.
• This demo repository that @ianks made for a talk has a gem which has 4 native extensions in the ext directory.
• This PR for the yrb gem shows how to integrate rb-sys and magnus into an existing gem.
• A guide for setting debug breakpoints in VSCode is available.

Supported Toolchains

• Ruby: 2.4+ (for full compatibility with Rubygems)
• Rust: 1.60+

Supported Platforms

We support cross compilation to the following platforms (this information is also available in the ./data directory for automation purposes):

Platform	Supported	Docker Image
x86_64-linux	✅	rbsys/x86_64-linux:0.9.81
x86_64-linux-musl	✅	rbsys/x86_64-linux-musl:0.9.81
aarch64-linux	✅	rbsys/aarch64-linux:0.9.81
arm-linux	✅	rbsys/arm-linux:0.9.81
arm64-darwin	✅	rbsys/arm64-darwin:0.9.81
x64-mingw32	✅	rbsys/x64-mingw32:0.9.81
x64-mingw-ucrt	✅	rbsys/x64-mingw-ucrt:0.9.81
mswin	✅	not available on Docker

Getting Help

We make a concerted effort to help out new users. If you have questions, please join our Slack and post your question in the #general channel. Alternatively, you can open an issue and we'll try to help you out.

Contributing

See the CONTRIBUTING.md file for information about setting up a development environment.

Bug reports and pull requests are welcome on GitHub at https://github.com/oxidize-rb/rb-sys.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.