readme.md

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.

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.102
x86_64-linux-musl	✅	rbsys/x86_64-linux-musl:0.9.102
aarch64-linux	✅	rbsys/aarch64-linux:0.9.102
aarch64-linux-musl	✅	rbsys/aarch64-linux-musl:0.9.102
arm-linux	✅	rbsys/arm-linux:0.9.102
arm64-darwin	✅	rbsys/arm64-darwin:0.9.102
x64-mingw32	✅	rbsys/x64-mingw32:0.9.102
x64-mingw-ucrt	✅	rbsys/x64-mingw-ucrt:0.9.102
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.