risc0-build

RISC Zero build tool for compiling guest programs

risc0-build

The risc0-build crate provides build-time utilities for compiling RISC-V guest programs for the RISC Zero zkVM.

Installation

[build-dependencies]
risc0-build = "5.0.0"

Overview

This crate is typically used in build.rs files to compile guest code written in Rust for the RISC Zero zkVM. It handles cross-compilation to the RISC-V target and generates metadata about the compiled guest programs.

Feature Flags

docker · feature

Enables building guest programs using Docker for reproducible builds.

guest-list · feature

Generates a list of all compiled guest programs with their metadata.

unstable · feature

Enables unstable/experimental features.

Core Functions

embed_methods

embed_methods · function

Embeds compiled guest methods for use in host code.

pub fn embed_methods() -> Vec<GuestListEntry>

This function reads the [package.metadata.risc0] section from Cargo.toml, builds the specified guest packages, and generates constants for accessing the compiled ELF binaries and image IDs.

Returns: List of compiled guest programs with their metadata.

Example in build.rs:

fn main() {
    risc0_build::embed_methods();
}

embed_methods_with_options

embed_methods_with_options · function

Embeds methods with custom build options per guest package.

pub fn embed_methods_with_options(
    guest_pkg_to_options: HashMap<&str, GuestOptions>
) -> Vec<GuestListEntry>

Parameters:

• guest_pkg_to_options: Map of guest package names to their build options

Example:

use std::collections::HashMap;
use risc0_build::{GuestOptions, embed_methods_with_options};

fn main() {
    let mut opts = HashMap::new();
    opts.insert(
        "my_guest",
        GuestOptions::default()
            .with_features(vec!["custom_feature"]),
    );
    embed_methods_with_options(opts);
}

embed_method_metadata_with_options

embed_method_metadata_with_options · function

Builds methods and embeds minimal metadata (name and path only).

pub fn embed_method_metadata_with_options(
    guest_pkg_to_options: HashMap<&str, GuestOptions>
) -> Vec<MinGuestListEntry>

Use this when you want to load the ELF at runtime rather than embedding it in the binary, reducing compile times for large guest programs.

Types

GuestOptions

GuestOptions · struct

Configuration options for building guest programs.

pub struct GuestOptions {
    pub features: Vec<String>,
    pub use_docker: Option<DockerOptions>,
    // ... other fields
}

Built using GuestOptionsBuilder:

let opts = GuestOptionsBuilder::default()
    .features(vec!["feature1".to_string()])
    .build()
    .unwrap();

DockerOptions · struct

Options for building guests using Docker.

pub struct DockerOptions {
    pub root_dir: Option<PathBuf>,
    // ... other fields
}

Built using DockerOptionsBuilder:

let docker_opts = DockerOptionsBuilder::default()
    .root_dir(Some(PathBuf::from("/workspace")))
    .build()
    .unwrap();

GuestListEntry

GuestListEntry · struct

Metadata for a compiled guest program.

pub struct GuestListEntry {
    pub name: Cow<'static, str>,
    pub elf: Cow<'static, [u8]>,
    pub image_id: Digest,
    pub path: Cow<'static, str>,
}

Fields:

• name: Guest binary name
• elf: Combined user + kernel ELF binary
• image_id: Computed image ID for verification
• path: Path to the ELF file

MinGuestListEntry · struct

Minimal metadata for a compiled guest program.

pub struct MinGuestListEntry {
    pub name: Cow<'static, str>,
    pub path: Cow<'static, str>,
}

Utility Functions

get_package

get_package · function

Returns the Cargo package from a manifest directory.

pub fn get_package(manifest_dir: impl AsRef<Path>) -> Package

get_target_dir

get_target_dir · function

Determines the build target directory from a Cargo manifest.

pub fn get_target_dir(manifest_path: impl AsRef<Path>) -> PathBuf

cargo_command

cargo_command · function

Creates a cargo command configured for building zkVM guests.

#[stability::unstable]
pub fn cargo_command(subcmd: &str, rustc_flags: &[String]) -> Command

Parameters:

• subcmd: Cargo subcommand (e.g., “build”, “test”)
• rustc_flags: Additional rustc flags

Returns: Configured Command ready to execute

Generated Code

After calling embed_methods() in your build.rs, include the generated code:

include!(concat!(env!("OUT_DIR"), "/methods.rs"));

This generates constants like:

pub const METHOD_NAME_ELF: &[u8] = /* ... */;
pub const METHOD_NAME_ID: [u32; 8] = /* ... */;
pub const METHOD_NAME_PATH: &str = /* ... */;

Method names are converted to SCREAMING_SNAKE_CASE (e.g., my-method becomes MY_METHOD_ELF).

Cargo.toml Configuration

Add guest packages to your Cargo.toml:

[package.metadata.risc0]
methods = ["methods/guest"]

Environment Variables

RISC0_BUILD_DEBUG · env

Set to 1 to build guests in debug mode (faster compilation, slower execution).

RISC0_SKIP_BUILD · env

Set to skip building guests (useful for checking without rebuilding).

RISC0_BUILD_LOCKED · env

Set to pass --locked to cargo when building guests.

RISC0_RUST_SRC · env

Path to Rust source for building std from source.

Examples

Basic build.rs

fn main() {
    risc0_build::embed_methods();
}

Custom Features

use std::collections::HashMap;
use risc0_build::{GuestOptions, embed_methods_with_options};

fn main() {
    let mut opts = HashMap::new();
    
    opts.insert(
        "guest_program",
        GuestOptions::default()
            .with_features(vec!["my_feature".to_string()]),
    );
    
    embed_methods_with_options(opts);
}

Using Docker

use std::collections::HashMap;
use risc0_build::{
    DockerOptions, GuestOptions, embed_methods_with_options,
};

fn main() {
    let docker = DockerOptions::default();
    
    let mut opts = HashMap::new();
    opts.insert(
        "guest_program",
        GuestOptions::default()
            .with_use_docker(Some(docker)),
    );
    
    embed_methods_with_options(opts);
}

Links

• docs.rs
• GitHub
• Crate