Prerequisites and Installation

This chapter provides a streamlined setup guide for building Ruby extensions with Rust.

TL;DR

1. Install Prerequisites

# Install Ruby (3.0+ recommended)
# Using your preferred manager: rbenv, rvm, asdf, etc.

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install rb_sys gem
gem install rb_sys

2. Create a New Gem with Rust Extension

# Generate a new gem with Rust extension support
bundle gem --ext=rust mygem
cd mygem

# Build the extension
bundle install
bundle exec rake compile

# Try it out
bundle exec rake

That's it! You now have a working Ruby gem with Rust extension.

Detailed Installation

If you encounter issues with the quick start above, here are the detailed requirements:

Ruby Requirements

Ruby 3.0+ recommended (2.6+ supported)
Ruby development headers (usually part of official packages)
Bundler (gem install bundler)

Rust Requirements

Rust 1.65.0+ via rustup
Make sure Cargo is in your PATH (typically ~/.cargo/bin)

C Compiler Requirements

macOS: Xcode Command Line Tools (xcode-select --install)
Linux: build-essential (Debian/Ubuntu) or Development Tools (Fedora/RHEL)
Windows: Microsoft Visual Studio C++ Build Tools

libclang (for Ruby/Rust FFI bindings)

Simplest approach: add to your Gemfile

gem "libclang", "~> 14.0"

Verifying Your Setup

The simplest way to verify your setup is to create a test gem:

bundle gem --ext=rust hello_rusty
cd hello_rusty
bundle install
bundle exec rake compile
bundle exec rake test

If everything runs without errors, your environment is correctly set up.

Troubleshooting

If you encounter issues:

Missing libclang: Add the libclang gem to your Gemfile
Missing C compiler: Install appropriate build tools for your platform
Ruby headers not found: Install Ruby development package

For detailed troubleshooting, consult the rb-sys wiki.

Next Steps

Validate your setup with the Quick Start.
Dive into Build Process for deeper compilation insights.
Explore Project Setup patterns.
Learn Testing Extensions to add tests.