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 therb-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 usesrb-sys
andmagnus
to package the rustwasmtime
library as a Ruby gem. - The
oxi-test
gem is the canonical example of how to userb-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 userb-sys
. -
Docs for the
rb_sys
gem and using it with anextconf.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 integraterb-sys
andmagnus
into an existing gem. - A guide for setting debug breakpoints in VSCode is available.
FAQ
What dependencies do I need to build a Ruby extension in Rust?
rb-sys
will handle most of the dependencies for you, but you will need to have libclang installed on your system.
On MacOS, you can install it with brew install llvm
.
On Linux, you can install it with apt-get install libclang-dev
.
Supported Toolchains
- Ruby: 2.6+ (for full compatibility with Rubygems)
- Rust: 1.65+
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.104 |
x86_64-linux-musl | ✅ | rbsys/x86_64-linux-musl:0.9.104 |
aarch64-linux | ✅ | rbsys/aarch64-linux:0.9.104 |
aarch64-linux-musl | ✅ | rbsys/aarch64-linux-musl:0.9.104 |
arm-linux | ✅ | rbsys/arm-linux:0.9.104 |
arm64-darwin | ✅ | rbsys/arm64-darwin:0.9.104 |
x64-mingw32 | ✅ | rbsys/x64-mingw32:0.9.104 |
x64-mingw-ucrt | ✅ | rbsys/x64-mingw-ucrt:0.9.104 |
mswin | ✅ | not available on Docker |
truffleruby | ✅ | 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.