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]
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
| Flag | Short | Default | Description |
|---|---|---|---|
--release | false | Build 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> | -p | In 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.
| Flag | Short | Default | Description |
|---|---|---|---|
--features <FEATURES> | -F | None | Activate the named features on top of the defaults. Accepts a single string with values separated by spaces or commas. |
--all-features | Activate every feature declared by the crate. Useful for CI smoke tests; usually heavier than what you need at runtime. | ||
--no-default-features | Skip 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-alphacargo-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.