jolt build

Build guest programs for the Jolt zkVM

The jolt build command compiles Rust code into RISC-V binaries optimized for proving in the Jolt zkVM.

Usage

jolt build [OPTIONS] [-- CARGO_ARGS...]

Build Modes

--std · boolean · default: "false"

Build with Rust standard library support (std mode).

• Uses riscv64imac-zero-linux-musl target
• Includes musl libc and gcc runtime libraries
• Automatically downloads and installs required toolchain
• Larger binary size but full std features

jolt build --std

--no-std · boolean · default: "true"

Build without standard library (no_std mode). This is the default.

• Uses riscv64imac-unknown-none-elf target
• Minimal runtime, smaller binaries
• Requires #![no_std] in guest code

jolt build --no-std

Toolchain Options

--musl-lib-path · path

Path to custom musl libc installation.

If not specified, Jolt will automatically download or build musl. Use this to provide a pre-built musl library.

jolt build --std --musl-lib-path /opt/musl/lib

--gcc-lib-path · path

Path to custom GCC runtime libraries (libgcc).

Used in std mode for exception handling and runtime support. If not specified, Jolt will build it automatically.

jolt build --std --gcc-lib-path /opt/gcc/lib

--fully · boolean · default: "false"

Force full toolchain build from source, even if binaries are available.

Useful for:

• Reproducible builds
• Custom toolchain patches
• Verifying build from source

jolt build --std --fully

Debugging and Backtrace

--backtrace · string · default: "auto"

Controls symbol preservation and frame pointer generation for debugging.

Values:

• auto - Preserve symbols in debug/dev profiles, strip in release
• enable - Always preserve symbols (skips -Cstrip=symbols)
• dwarf - Preserve symbols + enable frame pointers (-Cforce-frame-pointers=yes)
• frame-pointers - Enable frame pointers without DWARF
• disable - Always strip symbols

# Enable backtraces for release builds
jolt build --release --backtrace enable

# Full DWARF debug info
jolt build --backtrace dwarf

The JOLT_BACKTRACE=1 environment variable is often more convenient than --backtrace enable for ad-hoc debugging, as it doesn’t require rebuild flags.

Cargo Integration

CARGO_ARGS · string[]

Additional arguments passed directly to cargo build.

All arguments after -- are forwarded to cargo:

# Release build
jolt build -- --release

# Build specific package
jolt build -- -p my-guest

# Verbose output
jolt build -- --verbose

# Multiple args
jolt build -- --release --target-dir custom-target

Environment Variables

Optimization Level

JOLT_GUEST_OPT · string · default: "3"

Controls optimization level for guest code via -Copt-level.

Valid values:

• 0 - No optimizations
• 1 - Basic optimizations
• 2 - Some optimizations
• 3 - All optimizations (default)
• s - Optimize for size
• z - Optimize for size, more aggressive

JOLT_GUEST_OPT=s jolt build

Backtrace Control

JOLT_BACKTRACE · string

Enables symbol preservation for debugging without modifying build flags.

• 1 - Preserve symbols, enable tracer backtraces
• full - Include register dumps and cycle counts

# Ad-hoc debugging without rebuild
JOLT_BACKTRACE=1 cargo run --release

Unlike --backtrace enable, this triggers a guest rebuild automatically while keeping your existing cargo build flags intact.

Target-Specific CFLAGS

The build system automatically sets:

CFLAGS_riscv64imac_unknown_none_elf="-mcmodel=medany"
CFLAGS_riscv64imac_zero_linux_musl="-mcmodel=medany"

You can extend these by setting the environment variable:

export CFLAGS_riscv64imac_unknown_none_elf="-mcmodel=medany -O3"
jolt build

Rust Flags

Jolt automatically adds these rustflags to guest builds:

• -Cpasses=lower-atomic - Lower atomic operations to library calls
• -Cpanic=abort - Panic = abort (no unwinding)
• -Copt-level=<N> - Optimization level from JOLT_GUEST_OPT
• -Cllvm-args=-enable-machine-outliner=never - Disable broken RISC-V outliner
• --cfg=getrandom_backend="custom" - Use custom entropy source
• -Cstrip=symbols - Strip symbols (unless backtrace enabled)
• -Cforce-frame-pointers=yes - Only with --backtrace dwarf/frame-pointers

Build Process

The build happens in several stages:

1. Workspace detection - Finds the Cargo workspace root
2. Toolchain setup - Downloads/builds musl and gcc libs (std mode only)
3. Target spec generation - Creates custom RISC-V target JSON
4. Linker script - Generates memory layout from embedded template
5. Cargo build - Compiles guest with custom rustflags
6. Post-processing - Strips symbols if configured

Examples

Basic Build

Build with default settings (no_std, opt-level 3):

jolt build

Release Build

Build with cargo release profile:

jolt build -- --release

Std Mode Build

Build with standard library:

jolt build --std -- --release

Debug Build with Backtraces

Build with symbols for debugging:

jolt build --backtrace enable

Or use the environment variable:

JOLT_BACKTRACE=1 jolt build

Optimize for Size

Minimize binary size:

JOLT_GUEST_OPT=z jolt build -- --release

Custom Toolchain

Use pre-built toolchain components:

jolt build --std \
  --musl-lib-path /opt/riscv/musl/lib \
  --gcc-lib-path /opt/riscv/gcc/lib \
  -- --release

Reproducible Build

Build toolchain from source:

jolt build --std --fully -- --release

Output Location

Built binaries are placed in the standard cargo target directory:

No-std mode:

target/riscv64imac-unknown-none-elf/release/guest
target/riscv64imac-unknown-none-elf/debug/guest

Std mode:

target/riscv64imac-zero-linux-musl/release/guest
target/riscv64imac-zero-linux-musl/debug/guest

Troubleshooting

Toolchain Download Failures

If automatic toolchain installation fails:

# Build from source
jolt build --std --fully

# Or provide paths to pre-built components
jolt build --std --musl-lib-path /path/to/musl --gcc-lib-path /path/to/gcc

Optimization Errors

If you encounter “Invalid JOLT_GUEST_OPT value” errors:

# Valid values only: 0, 1, 2, 3, s, z
JOLT_GUEST_OPT=3 jolt build

Linker Errors

For linker errors in std mode:

# Try rebuilding toolchain
jolt build --std --fully

# Check CFLAGS
export CFLAGS_riscv64imac_zero_linux_musl="-mcmodel=medany"
jolt build --std

Performance Considerations

Optimization Level

• Use JOLT_GUEST_OPT=3 (default) for best proving performance
• Use JOLT_GUEST_OPT=z or s only if binary size is critical
• Lower optimization levels (0, 1, 2) increase trace length and proving time

Symbol Stripping

• Stripped binaries are smaller and faster to load
• Only preserve symbols when debugging is needed
• JOLT_BACKTRACE=1 is zero-cost at runtime (only affects build)

Frame Pointers

• --backtrace dwarf adds frame pointer overhead (~500 cycles for std guests)
• Only needed for DWARF unwinding or external tooling
• JOLT_BACKTRACE=1 provides backtraces without this cost

Related Commands

jolt run

Run the built binary on the emulator

jolt new

Create a new Jolt project