Crate risc0_build

Build RISC Zero zkVM guest code and provide handles to the host side.

In order for the host to execute guest code in the RISC Zero zkVM, the host must be provided a compiled RISC-V ELF file and the corresponding ImageID. This crate contains the functions needed to take zkVM guest code, build a corresponding ELF file and ImageID, and make the ImageID and a path to the ELF file available for the host to use.

Using risc0-build to Build Guest Methods

Using this crate can be a bit delicate, so we encourage you to follow along in our RISC Zero Rust Starter repository. In that repository, risc0-build is used in the methods directory.

Guest methods are embedded for the host to use by calling embed_methods (or embed_methods_with_options) in a build script. An example build.rs file would look like:

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

This requires including risc0-build as a build dependency. You will also need add a [package.metadata.risc0] section to your cargo file. In this section, put a methods field with a list of relative paths containing the guest code. For example, if your guest code is in the guest directory, then Cargo.toml might include:

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

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

This builds a file methods.rs in your cargo output directory which you must then include for the host to use. For example, you might make a file src/lib.rs containing:

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

This process will generate an image ID (*_ID) and the contents of an ELF file (*_ELF). The names will be derived from the name of the ELF binary, which will be converted to ALL_CAPS to comply with Rust naming conventions. Thus, if a method binary is named multiply, the image ID will be named methods::MULTIPLY_ID and the contents of the ELF file will be named methods::MULTIPLY_ELF. These are included at the beginning of the host-side code:

use methods::{MULTIPLY_ELF, MULTIPLY_ID};

Structs

• DockerOptions
  Options for configuring a docker build environment.
• GuestListEntry
  Represents an item in the generated list of compiled guest binaries
• GuestOptions
  Options defining how to embed a guest package in crate::embed_methods_with_options.
• MinGuestListEntry
  Represents an item in the generated list of compiled guest binaries

Enums

• BuildStatus
  Indicates weather the build was successful or skipped.

Constants

• RUST_RZUP_INDICATOR
  This const represents a filename that is used in the use to indicate to in order to indicate to the client and the risc0-build crate that the new rust implementation of rzup is in use. The rust implementation of rzup will place a file with this name under $RISC0_HOME.
• TARGET_DIR
  The target directory for the ELF binaries.

Functions

• build_rust_runtime
  Builds a static library providing a rust runtime.
• build_rust_runtime_with_features
  Builds a static library providing a rust runtime, with additional features given as arguments.
• cargo_command
  Creates a std::process::Command to execute the given cargo command in an environment suitable for targeting the zkvm guest.
• docker_build
  Build the package in the manifest path using a docker environment.
• embed_method_metadata_with_options
  Build methods for RISC-V and embed minimal metadata - the elf name and path. To embed the full elf, use embed_methods_with_options.
• embed_methods
  Embeds methods built for RISC-V for use by host-side dependencies.
• embed_methods_with_options
  Embeds methods built for RISC-V for use by host-side dependencies. Specify custom options for a guest package by defining its GuestOptions. See embed_methods.
• get_package
  Returns the given cargo Package from the metadata in the Cargo.toml manifest within the provided manifest_dir.
• get_target_dir
  Determines and returns the build target directory from the Cargo manifest at the given manifest_path.
• risc0_data
  Get the path used by cargo-risczero that stores downloaded toolchains