Riff supports Rust projects built using Cargo. Riff automatically provides what we call external dependencies to Rust projects. These are dependencies written in non-Rust languages, such as OpenSSL or the Protobuf compiler. So if you're ever tried to run
cargo build on a project and received warnings about missing dependencies, Riff may offer a direct solution to your problem.
Make sure to consult the getting started guide before using Riff in your Rust project.
Using a shell with external dependencies available
Riff uses your Rust dependency graph to automatically infer which external dependencies are required for your project and builds a shell environment with those dependencies available. To enter the Riff-provided shell:
Once in the Riff shell, your Cargo and other commands should work without issue. Here's an example command sequence that shows the Riff shell in action:
git clone https://github.com/tokio-rs/prost cd prost # Enter the Riff shell environment riff shell # ✓ 🦀 rust: cargo, cmake, curl, openssl, pkg-config, rustc, rustfmt, zlib # Check for the presence of openssl which openssl # The path should look like this: # /nix/store/f3xbf94zykbh6drw6wfg9hdrfgwrkck7-openssl-1.1.1q-bin/bin/openssl # This means that Riff is using the Nix-provided openssl # Build the project cargo build # Leave the shell environment exit # Check for openssl again which openssl # This should either point to an openssl executable on your PATH or fail
cargo build on the Prost project fails on many systems due to missing dependencies. In the Riff shell, however, that problem is automatically resolved and
cargo build should succeed.
If you'd like to automatically enter the Riff shell every time you navigate to your Rust project, you may benefit from integrating with direnv.
Running commands with external dependencies available
As an alternative to using the Riff shell, you can use Riff to run arbitrary commands with external dependencies supplied. Here's an example:
riff run cargo build
Note, however, that you need to apply flags behind a
riff cun cargo build -- --release
In cases where you want to limit Riff's access to the Internet, you can run it in offline mode, which disables all network usage except what's required by the
nix develop command (which Riff runs in the background). You can enable offline mode using either the
--offline flag or the
RIFF_OFFLINE environment variable. Here are some examples:
# Via flag riff run --offline # Via environment variable RIFF_OFFLINE=true riff shell
How to declare external dependencies
While Riff does its best to infer external dependencies from your dependency graph, you can explicitly declare external dependencies if necessary by adding a
riff block to the
package.metadata block in your
Cargo.toml. Riff currently supports three types of inputs:
build-inputsare external dependencies that some crates may need to link against.
environment-variablesare environment variables you want to set in your dev shell.
runtime-inputsare libraries you want to add to your
LD_LIBRARY_PATHto ensure that your dev shell works as expected.
Here's an example
Cargo.toml with an explicitly supplied Riff configuration:
[package] name = "riff-example" version = "0.1.0" edition = "2021" [package.metadata.riff] build-inputs = ["openssl"] [package.metadata.riff.environment-variables] DEBUG = "1" # Other Cargo.toml configuration
How to supply target-specific dependencies
[package.metadata.riff.targets.aarch64-apple-darwin] build-inputs = [ "darwin.apple_sdk.frameworks.CoreServices", "darwin.apple_sdk.frameworks.Security" ]
macOS framework dependencies
[package.metadata.riff.targets.x86_64-apple-darwin] build-inputs = [ "darwin.apple_sdk.frameworks.CoreServices", "darwin.apple_sdk.frameworks.Security" ] [package.metadata.riff.targets.aarch64-apple-darwin] build-inputs = [ "darwin.apple_sdk.frameworks.CoreServices", "darwin.apple_sdk.frameworks.Security" ]