Repository files navigation

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

• Provides wrappers forcargo commands.
• Handles non-standardcargo installations via theCARGO environment variable.
• Opt-in to allow users to install pre-compiled Rust extensions hosted on GitHub releases.
• Opt-in to allow users to install pre-compiled Rust extensions hosted on a third party server.
• Provides a wrapper for initializing a Rust extension via Fiddle.

1. Add the following to your gemspec file:

spec.extensions <<'ext/Rakefile'spec.add_runtime_dependency'thermite','~> 0'

2. Createext/Rakefile with the following code, assuming that the Cargo project root is the sameas the Ruby project root:

require'thermite/tasks'project_dir=File.dirname(File.dirname(__FILE__))Thermite::Tasks.new(cargo_project_path:project_dir,ruby_project_path:project_dir)taskdefault:%w(thermite:build)

3. InRakefile, integrate Thermite into your build-test workflow:

require'thermite/tasks'Thermite::Tasks.newdesc'Run Rust & Ruby testsuites'tasktest:['thermite:build','thermite:test']do# …end

Runrake -T thermite to view all of the available tasks in thethermite namespace.

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

• passing arguments toThermite::Tasks.new
• adding apackage.metadata.thermite section toCargo.toml. These settings override thearguments passed to theTasks class. Due to the conflict, it is infeasible forcargo_project_path orcargo_workspace_member to be set in this way. Example section:

[package.metadata.thermite]github_releases =true

Possible options:

• binary_uri_format - if set, the interpolation-formatted string used to construct the downloadURI for the pre-built native extension. If the environment variableTHERMITE_BINARY_URI_FORMATis set, it takes precedence over this option. Either method of setting this option overrides thegithub_releases option.Example:https://example.com/download/%{version}/%{filename}. Replacement variables:
  • filename - The value ofConfig.tarball_filename
  • version - the crate version fromCargo.toml
• cargo_project_path - the path to the top-level Cargo project. Defaults to the current workingdirectory.
• cargo_workspace_member - if set, the relative path to the Cargo workspace member. Usually usedwhen it is part of a repository containing multiple crates.
• github_releases - whether to look for Rust binaries via GitHub releases when installingthe gem, andcargo is not found. Defaults tofalse.
• github_release_type - whengithub_releases istrue, the mode to use to download the Rustbinary from GitHub releases.'cargo' (the default) uses the version inCargo.toml, along withthegit_tag_format option (described below) to determine the download URI.'latest' takes thelatest release matching thegit_tag_regex option (described below) to determine the downloadURI.
• git_tag_format - whengithub_release_type is'cargo' (the default), theformat string used to determine the tag usedin the GitHub download URI. Defaults tov%s, where%s is the version inCargo.toml.
• git_tag_regex - whengithub_releases is enabled andgithub_release_type is'latest', aregular expression (expressed as aString) that determines which tagged releases to look forprecompiled Rust tarballs. One group must be specified that indicates the version number to beused in the tarball filename. Defaults to thesemantic versioning 2.0.0format. In this case, the group is around the entireexpression.
• optional_rust_extension - prints a warning to STDERR instead of raising an exception, if Cargois unavailable andgithub_releases is either disabled or unavailable. Useful for projects whereeither fallback code exists, or a native extension is desirable but not required. Defaultstofalse.
• ruby_project_path - the top-level directory of the Ruby gem's project. Defaults to thecurrent working directory.
• ruby_extension_dir - the directory relative toruby_project_path where the extension islocated. Defaults tolib.

Using the cliché Rust+Ruby example, therusty_blankrepository contains an example of using Thermite withruruto provide aString.blank? speedup extension. While the example uses ruru, this gem should beusable with any method of integrating Rust and Ruby that you choose.

By default Thermite will do a release build of your Rust code. To do a debug build instead,set theCARGO_PROFILE environment variable todebug.

For example, you can runCARGO_PROFILE=debug rake thermite:build.

Debug statements can be written to a file specified by theTHERMITE_DEBUG_FILENAME environmentvariable.

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₃

This gem is licensed under the MIT license.