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 theCARGO
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'sextensions
list. - In
Rakefile
, addrequire '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 toCargo.toml
. These settings override the arguments passed to theTasks
class. Due to the conflict, it is infeasible forcargo_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, andcargo
is not found. Defaults tofalse
.git_tag_format
- whengithub_releases
is enabled, a regular expression (expressed as aString
) 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 tovN.N.N
, whereN
is any n-digit number. In this case, the group is around the entire expression.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.
FAQ
Why is it named Thermite?
According to Wikipedia:
- The chemical formula for ruby includes Al2O3, or aluminum oxide.
- Rust is iron oxide, or Fe2O3.
- A common thermite reaction uses iron oxide and aluminum to produce iron and aluminum oxide: Fe2O3 + 2Al → 2Fe + Al2O3
Release Notes
Contributing
Legal
This gem is licensed under the MIT license.