Skip to main content

Getting Started

This guide will walk you through creating a new Ruby gem with a Rust extension using rb-sys.

Prerequisites​

Before you begin, you'll need to have the following installed:

Create Your Gem​

The easiest way to get started is by using the built-in bundle gem command with the --ext=rust option. This will generate a complete gem skeleton with a Rust extension ready for you to start building.

# Create a new gem with a Rust extension
bundle gem --ext=rust my_gem
cd my_gem

This will create a new directory called my_gem with the following structure:

my_gem/
├── Gemfile              # Ruby dependencies
├── my_gem.gemspec       # Gem metadata
├── Rakefile             # Build tasks
├── ext/my_gem/          # Rust extension
│   ├── Cargo.toml       # Rust dependencies
│   ├── extconf.rb       # Build configuration
│   └── src/
│       └── lib.rs       # Rust code
└── lib/
    └── my_gem.rb        # Ruby wrapper

Build and Compile​

To compile the Rust extension, you can use the provided Rake task:

# Install dependencies and compile the extension
bundle install
bundle exec rake compile

This will:

  1. Install any Ruby dependencies from the Gemfile.
  2. Run the extconf.rb script, which creates a Makefile for building the Rust extension.
  3. Compile the Rust code in ext/my_gem/src/lib.rs into a shared library.
  4. Copy the compiled library into the lib/my_gem/ directory, so it can be loaded by Ruby.

Next Steps​

Now that you have a working gem with a Rust extension, you're ready to start building!