Skip to main content

Build

Compiles the guest crate to a RISC-V ELF binary with the ZisK toolchain — the artifact every other cargo-zisk subcommand consumes. Covers compilation options, feature selection, and where the ELF is written.

Compile the guest crate to a RISC-V ELF binary using the ZisK toolchain. The resulting ELF is the artifact every other cargo-zisk subcommand consumes. The output path is target/elf/riscv64ima-zisk-zkvm-elf/<profile>/<name>, where <profile> is release or debug depending on whether --release was passed, and <name> is the name of the guest binary.

cargo-zisk build [OPTIONS]
Always use release mode for proving

Proof size and prover cost are dominated by the number of RISC-V steps your guest executes. A debug build can be 10×–100× larger in step count than the release build of the same program, which translates directly into proof time and memory. Reserve debug builds for source-level debugging and switch back to --release before running execute or prove.

Compilation options​

FlagShortDefaultDescription
--releasefalseBuild with rustc optimizations enabled. Almost always what you want. Debug builds run far more RISC-V steps under proof.
--artifact-dir <PATH>Not working in 1.4.0-alpha (see the warning below). Intended to copy the final ELF into this directory as well.
--bin <BIN>Build only the binary named <BIN>. Pass --bin multiple times to build a subset of targets in a multi-bin crate.
--package <PACKAGE>-pIn a workspace, build only the given package (repeat -p for several). Without this flag every workspace guest builds.

Feature selection​

Cargo features the guest crate exposes. These behave identically to cargo.

FlagShortDefaultDescription
--features <FEATURES>-FNoneActivate the named features on top of the defaults. Accepts a single string with values separated by spaces or commas.
--all-featuresActivate every feature declared by the crate. Useful for CI smoke tests; usually heavier than what you need at runtime.
--no-default-featuresSkip the crate's default feature set entirely. Combine with --features to opt back in to just the ones you need.

Code generation​

Every guest is built with these LLVM target features, on top of the base riscv64ima-zisk-zkvm-elf target:

  • +unaligned-scalar-mem, since ZisK runs unaligned loads and stores as single instructions. It is passed first, so your rustflags can turn it off with -C target-feature=-unaligned-scalar-mem.
  • +zba, which ZisK proves natively.

The Cargo features zba, zbc, zbkc and zbkx (or their <ext>_native variants), and zicond_native for zicond, also enable the matching -C target-feature=+<ext>. --all-features enables all of them.

Rustflags from the program's .cargo/config.toml for the guest target and from the environment (RUSTFLAGS, CARGO_ENCODED_RUSTFLAGS, ...) are honoured. The environment wins over the config file.

Examples​

Release build (the most common invocation):

cargo-zisk build --release

Debug build (skip --release for an unoptimized binary with symbols, useful for diagnostics):

cargo-zisk build

Build a specific binary in a crate that defines multiple [[bin]] targets (repeat --bin for more):

cargo-zisk build --release --bin prover-guest --bin verifier-guest

Outputs​

The compiled ELF is written to the standard target directory by default:

target/elf/riscv64ima-zisk-zkvm-elf/<profile>/<name>
--artifact-dir fails in 1.4.0-alpha

cargo-zisk forwards --artifact-dir to Cargo without -Z unstable-options, so the build stops with the --artifact-dir flag is unstable, pass -Z unstable-options. Copy the ELF from the target path above instead.