Thermite

Thermite is a Rake-based helper for building and distributing Rust-based Ruby extensions.

Features

Provides wrappers for cargo commands.
Handles non-standard cargo installations via the CARGO environment variable.
Opt-in to allow users to install pre-compiled Rust extensions hosted on GitHub releases.

Usage

Add thermite as a runtime dependency in your gem.
In your gemspec, add Rakefile to the specification's extensions list.
In Rakefile, add require 'thermite/tasks' and then add the tasks to the file by running:

Thermite::Tasks.new

Run rake -T to view all of the available tasks in the thermite namespace.

Configuration

Task configuration for your project can be set in two ways:

passing arguments to Thermite::Tasks.new
adding a package.metadata.thermite section to Cargo.toml. These settings override the arguments passed to the Tasks class. Due to the conflict, it is infeasible for cargo_project_path to be set in this way. Example section:

[package.metadata.thermite]

github_releases = true

Possible options:

cargo_project_path - the path to the Cargo project. Defaults to the current working directory.
github_releases - whether to look for Rust binaries via GitHub releases when installing the gem, and cargo is not found. Defaults to false.
github_release_type - when github_releases is true, the mode to use to download the Rust binary from GitHub releases. 'cargo' (the default) uses the version in Cargo.toml, along with the git_tag_format option (described below) to determine the download URI. 'latest' takes the latest release matching the git_tag_regex option (described below) to determine the download URI.
git_tag_format - when github_release_type is 'cargo' (the default), the format string used to determine the tag used in the GitHub download URI. Defaults to v%s, where %s is the version in Cargo.toml.
git_tag_regex - when github_releases is enabled and github_release_type is 'latest', a regular expression (expressed as a String) that determines which tagged releases to look for precompiled Rust tarballs. One group must be specified that indicates the version number to be used in the tarball filename. Defaults to vN.N.N, where N is any n-digit number. In this case, the group is around the entire expression.
optional_rust_extension - prints a warning to STDERR instead of raising an exception, if Cargo is unavailable and github_releases is either disabled or unavailable. Useful for projects where either fallback code exists, or a native extension is desirable but not required. Defaults to false.
ruby_project_path - the top-level directory of the Ruby gem's project. Defaults to the current working directory.

Example

Using the cliché Rust+Ruby example, the rusty_blank repository contains an example of using Thermite with ruru to provide a String.blank? speedup extension. While the example uses ruru, this gem should be usable with any method of integrating Rust and Ruby that you choose.

Troubleshooting

Debug statements can be written to a file specified by the THERMITE_DEBUG_FILENAME environment variable.

FAQ

Why is it named Thermite?

According to Wikipedia:

The chemical formula for ruby includes Al₂O₃, or aluminum oxide.
Rust is iron oxide, or Fe₂O₃.
A common thermite reaction uses iron oxide and aluminum to produce iron and aluminum oxide: Fe₂O₃ + 2Al → 2Fe + Al₂O₃

Release Notes

Contributing

Legal

This gem is licensed under the MIT license.

d-unseductable / thermite