Trace back CLI parameters

I want to understand:

how cargo run -r --bin powdr_openvm -- ... works and how you can trace back CLI parameters like --input and --autoprecompiles to the source code.

chatGPT said I need to check [bin] definition in Cargo.toml to get what binary will be, but there is no [bin] part in toml file

1. When [[bin]] is not present — what does Cargo do?

If [[bin]] is not explicitly declared, Cargo will use conventions:

• If you have src/main.rs → Cargo builds it as the default binary.
• If you have files in src/bin/*.rs → Cargo builds each of those as a separate named binary.

Then I found

in Cargo.toml, it defines:

[[bin]]
name = "powdr_openvm"
path = "src/main.rs"
bench = false # See https://github.com/bheisler/criterion.rs/issues/458

clap — a popular crate for command-line argument parsing.

1. #[derive(Parser)]

• This macro comes from clap and automatically generates code to parse CLI arguments into this Cli struct.
• It tells clap: “Generate a parser for this struct based on the annotations.”

2. #[command(...)]

• This is a macro attribute to configure metadata for your CLI program.

#[command(name = "powdr-openvm", author, version, about, long_about = None)]

Is equivalent to:

powdr-openvm --version
powdr-openvm --help

It provides the help text and metadata when a user asks for help or version info.

• name: name of the CLI tool (as shown in help/version output)
• author: automatically pulled from Cargo.toml unless overridden
• version: automatically from Cargo.toml unless overridden
• about: a short description of the tool
• long_about: a longer description (can be multi-line); here set to None

The Cli struct

struct Cli {
    #[command(subcommand)]
    command: Option<Commands>,
}

This means:

• The CLI expects a subcommand, like: bashCopyEditpowdr-openvm prove ... powdr-openvm compile ...
• Commands is an enum defined elsewhere in your code, like: rustCopyEditenum Commands { Prove { ... }, Compile { ... }, ... }
• By using #[command(subcommand)], clap knows: “Match whatever subcommand the user types (prove, compile, etc.) to one of the variants in the Commands enum.”

✅ 1. What is a binary in a Cargo project?

In Rust, a binary is an executable program that can be run.

A typical Cargo project can contain:

• One or more binary targets
• Optionally a library (shared across binaries)

When you see:

bashCopyEditcargo run --bin powdr_openvm

You’re telling Cargo:

“Run the binary target named powdr_openvm.”

This binary is defined in your project’s Cargo.toml.

---

🔍 Where is the binary powdr_openvm defined?

In Cargo.toml, you’ll find something like:

[[bin]]
name = "powdr_openvm"
path = "src/bin/powdr_openvm.rs"

That tells Cargo:

• This binary is called powdr_openvm
• Its entry point (i.e. fn main()) is located in src/bin/powdr_openvm.rs

You can also use multiple binaries in one project by placing them under src/bin/.

In a Workspace

In a multi-crate workspace (Cargo.toml at root + sub-crates in folders):

• Each member crate can define its own binaries
• You can run them via:
  • cargo run -p crate_name --bin binary_name

What cargo run does

When you just run:

bashCopyEditcargo run

Cargo tries to guess which binary to run. Here’s the logic:

---

🔹 If there’s only one binary target, it will:

• Build and run it.
• Equivalent to: bashCopyEditcargo run --bin <that-one-binary>

What does cargo build do?

By default, cargo build:

• Compiles your current crate
• Builds:
  • Your library (if it has one: src/lib.rs)
  • Your binary (if it has one: src/main.rs or [[bin]] targets)
• Outputs the result into target/debug/

Summary

Command	What it does
cargo build	Builds everything in debug mode
cargo build --release	Builds in optimized release mode
cargo build --bin name	Builds only the specified binary
cargo run	Builds + runs the binary (auto or specified)