Cross-Compilation

Publishing native gem binaries is incredibly important for Ruby on Rust gems. No one likes seeing the infamous Compiling native extensions. This could take a while... message when they install a gem. And in Rust, we all know that compiling can take a while...

It's important to make sure that your gem is as fast as possible to install, that's why rb-sys is built from the ground up to support this use-case. rb-sys integrates seamlessly with rake-compiler and rake-compiler-dock. By leveraging the hard-work of others, cross-compilation for Ruby gems is as simple and reliable as it would be for a C extension.

💡 Tip: Join the Slack channel to ask questions and get help from the community!

Using the rb-sys-dock helper

The rb-sys-dock executable allows you to easily enter the Docker container used to cross compile your gem. You can use your tool to build your gem, and then exit the container. The gem will be available in the pkg directory.

$ bundle exec rb-sys-dock -p aarch64-linux --build
$ ls pkg # => my_gem_name-0.1.0-aarch64-linux.gem

GitHub Actions

The oxi-test gem is meant to serve as the canonical example of how to setup cross gem compilation. Here's a walkthrough of the important files to reference:

  1. Setup the Rake::ExtensionTask in the Rakefile
  2. Setup a cross-gem.yml GitHub action to build the gem for multiple platforms.
  3. Download the cross-gem artifacts from the GitHub action and test them out.

In the wild

💡 Tip: Add your gem to this list by opening a PR!

Resources