Rust🦀

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:

riff 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

Running 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.

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 -- invocation:

riff cun cargo build -- --release

Offline mode

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-inputs are external dependencies that some crates may need to link against.
• environment-variables are environment variables you want to set in your dev shell.
• runtime-inputs are libraries you want to add to your LD_LIBRARY_PATH to ensure that your dev shell works as expected.

Both build-inputs and runtime-inputs can be any packages available in Nixpkgs. You may find this particularly useful for build.rs scripts.

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"
]