Skip to content

Compiling a Program

Once you have written a program to be proven by OpenVM, you need to compile it in a way which is compatible with OpenVM. We refer to programs written to be proven by OpenVM as guest programs, with the term coming from its usage in cross-compilation as explained in the specs.

Building Guest Programs for OpenVM

To prove a guest program in OpenVM, we must build it for a RISC-V guest target and then transpile it to a format natively supported by OpenVM. We provide the following CLI command to do this:

cargo openvm build

The presently supported guest target is riscv32im-risc0-zkvm-elf due to its official support by the Rust toolchain. We anticipate upstreaming an OpenVM-specific target to Rust in the future. More details about how cross-compilation works in Rust can be found in the Rust docs.

Build Flags

The following flags are available for the cargo openvm build command. You can run cargo openvm build --help for this list within the command line.

Generally, outputs will always be built to the target directory, which will either be determined by the manifest path or explicitly set using the --target-dir option. By default Cargo sets this to be <workspace_or_package_root>/target/.

OpenVM-specific artifacts will be placed in ${target_dir}/openvm/, but if --output-dir is specified they will be copied to ${output-dir}/ as well.

OpenVM Options

  • --no-transpile

    Description: Skips transpilation into an OpenVM-compatible .vmexe executable when set.

  • --config <CONFIG>

    Description: Path to the OpenVM config .toml file that specifies the VM extensions. By default will search the manifest directory for openvm.toml. If no file is found, OpenVM will use a default configuration. Currently the CLI only supports known extensions listed in the Acceleration Using Pre-Built Extensions section. To use other extensions, use the SDK.

  • --output-dir <OUTPUT_DIR>

    Description: Output directory for OpenVM artifacts to be copied to.

  • --init-file-name <INIT_FILE_NAME>

    Description: Name of the generated initialization file, which will be written into the manifest directory.

    Default: openvm_init.rs

Package Selection

As with cargo build, default package selection depends on the working directory. If the working directory is a subdirectory of a specific package, then only that package will be built. Else, all packages in the workspace will be built by default.

  • --package <PACKAGES>

    Description: Builds only the specified packages. This flag may be specified multiple times or as a comma-separated list.

  • --workspace

    Description: Builds all members of the workspace (alias --all).

  • --exclude <PACKAGES>

    Description: Excludes the specified packages. Must be used in conjunction with --workspace. This flag may be specified multiple times or as a comma-separated list.

Target Selection

By default all package libraries and binaries will be built. To build samples or demos under the examples directory, use either the --example or --examples option.

  • --lib

    Description: Builds the package's library.

  • --bin <BIN>

    Description: Builds the specified binary. This flag may be specified multiple times or as a comma-separated list.

  • --bins

    Description: Builds all binary targets.

  • --example <EXAMPLE>

    Description: Builds the specified example. This flag may be specified multiple times or as a comma-separated list.

  • --examples

    Description: Builds all example targets.

  • --all-targets

    Description: Builds all package targets. Equivalent to specifying --lib --bins --examples.

Feature Selection

The following options enable or disable conditional compilation features defined in your Cargo.toml.

  • -F, --features <FEATURES>

    Description: Space or comma separated list of features to activate. Features of workspace members may be enabled with package-name/feature-name syntax. This flag may also be specified multiple times.

  • --all-features

    Description: Activates all available features of all selected packages.

  • --no-default-features

    Description: Do not activate the default feature of the selected packages.

Compilation Options

  • --profile <NAME>

    Description: Builds with the given profile. Common profiles are dev (faster builds, less optimization) and release (slower builds, more optimization). For more information on profiles, see Cargo's reference page.

    Default: release

Output Options

  • --target-dir <TARGET_DIR>

    Description: Directory for all generated artifacts and intermediate files. Defaults to directory target/ at the root of the workspace.

Display Options

  • -v, --verbose

    Description: Use verbose output.

  • -q, --quiet

    Description: Do not print Cargo log messages.

  • --color <WHEN>

    Description: Controls when colored output is used.

    Default: always

Manifest Options

  • --manifest-path <PATH>

    Description: Path to the guest code Cargo.toml file. By default, build searches for the file in the current or any parent directory. The build command will be executed in that directory.

  • --ignore-rust-version

    Description: Ignores rust-version specification in packages.

  • --locked

    Description: Asserts the same dependencies and versions are used as when the existing Cargo.lock file was originally generated.

  • --offline

    Description: Prevents Cargo from accessing the network for any reason.

  • --frozen

    Description: Equivalent to specifying both --locked and --offline.