`v2.0.0-beta`: improve communication of Wasmi CLI configurations and features

[polarathene]

Describe the bug

This is more of a UX/docs issue, but might be worth tackling before the v2 release?

I built the CLI with --no-default-features:

• With the current beta of v2, this cargo option now strips away the actual subcommands. Results in a CLI that can only output help regarding --help/--version and supports nothing else.
• Features wasi and wat had no increase on binary size. They appear dependent on the new subcommand related features to be present?

Those UX concerns could potentially be better by introducing build failures if they serve no practical purpose (effectively misconfigured build).

Expected behavior

As a newbie that isn't that familiar with the Wasmi project (or really using wasm at all), but someone who is interested in customizing builds, it'd be helpful to better communicate when feature opt-out / opt-in choices are not practical.

If wasi and wat features are dependent upon the new command features run/wast, perhaps that should have a build.rs guard to trigger a build failure when run/wast are not present? (here is an example reference from the cudarc crate that does this)

Likewise, there may not be much sense in --no-default-features when building the CLI if not a single subcommand feature is added back? At least I'm not sure of the value building a CLI that only supports --help/--version?

Up to you what makes sense, this is just an issue to provide feedback where I went on a detour from:

• Producing a minimal CLI build that turns out to not do anything with recent v2 changes (understandable).
• Misunderstanding that wasi/wat were enabled when they were dependent upon subcommand features.

Reproduction

1. What Wasmi version was used? v2.0.0-beta.0 (Commit: ce21848)
2. Bug occurs on Wasmi CLI or Wasmi library? CLI
3. Ideally please provide minified Wasm (.wasm) or Wat (.wat) file to reproduce. None

For reference this is how I built the CLI with a minimal footprint and observed impact on size by features (only bothering with the default set):

# Setup environment via Docker:
docker run --rm -it --workdir /wasmi fedora:43

dnf install -yq rustup gcc git
rustup-init -y --profile minimal --default-toolchain stable --target x86_64-unknown-linux-musl && . "$HOME/.cargo/env"
rustup toolchain install nightly --component rust-src

# Optional: `x86_64-unknown-linux-musl` target nightly `-Z build-std` support:
dnf install -yq musl-gcc
rustup target add x86_64-unknown-linux-musl --toolchain nightly

git clone --depth 1 https://github.com/wasmi-labs/wasmi .

# Reference 4.96MB (Rust 1.93.1) or 4.8MB (1.95.0-nightly 2026-02-11):
RUSTFLAGS='-C strip=symbols' cargo build --package wasmi_cli --profile bench

# 2.6MB:
# (NOTE: `--features` value varies as per associated notes that follow)
RUSTFLAGS='-C strip=symbols -C opt-level=z -C relocation-model=static -Z unstable-options -C panic=immediate-abort' \
cargo +nightly build --package wasmi_cli --profile bench \
  -Z build-std=core,std,panic_abort \
  -Z build-std-features=optimize_for_size \
  --target x86_64-unknown-linux-gnu \
  --no-default-features \
  --features run,wasi,wast,wat \
  --quiet

Observed differences:

• --features run produces a 930KB binary.
• --features wast produces a 1.93MB binary (+1MB).
• --features wast,run produces a 1.97MB binary (run effectively only adds 40KB).
• --features wat is additive to size only when run or wast is enabled (+320/350 KB).
• --features wasi is only additive when run is enabled (+300KB).
• All 4 features enabled produces a 2.6MB binary.

Given those observations... The wat feature should probably be dependent upon run/wast features then? And wasi dependent upon the run feature?

[Robbepop]

@polarathene thank you again for your analysis.

This is all correct.

• wast is usually only required for testing/debugging the Wasmi interpreter. I enabled it by default since the same feature is also enabled by default in Wasmtime's CLI application.
• run is what most Wasmi users likely want to have enabled by default as it allows to execute Wasm modules. It is enabled by default but can be disabled when disabling all features via --no-default-features. This may be useful if only the wast command is needed or may be useful later when there are even more commands as is the case in Wasmtime's CLI application which has the same behavior.
• wat allows to read Wasm modules in the .wat format when using the run command. Thus it depends on run as correctly identified by you. It should have no user-facing dependence on the wast feature.
• wasi enables WASI when executing Wasm modules via the run command. It has no dependence on the wast feature.
• simd enables Wasm simd proposal based operators when executing a Wasm module via the run command or testing a Wasm script via wast command.
  • The simd feature is disabled by default since it is very bloaty and most Wasmi users likely won't have a need for it.

[polarathene]

• wast is usually only required for testing/debugging the Wasmi interpreter. I enabled it by default since the same feature is also enabled by default in Wasmtime's CLI application.

That sounds fine I guess?

It does add about 1MB of weight as noted in my previous comments observations at the end. If someone wants a sized optimized binary they'd need to do a custom build to get the savings like I demonstrated anyway.

---

• wat allows to read Wasm modules in the .wat format when using the run command. Thus it depends on run as correctly identified by you. It should have no user-facing dependence on the wast feature.

Ah okay, not sure why the size went up with wast enabled but run disabled then 🤔

In that case perhaps wat and wasi features should add run as a dep to their features?

wasmi/crates/cli/Cargo.toml

Lines 36 to 38 in a6de01f

	wasi = ["wasmi_wasi"]
	wat = ["wasmi/wat"]
	run = []

Possibly also consider prefixing the command specific features with cmd-? It'd make that distinction a bit more clearer and grouped?

default = ["cmd-run", "cmd-wast", "wasi", "wat"]
# ...
wasi = ["cmd-run", "dep:wasmi_wasi"]
wat = ["cmd-run", "dep:wasmi/wat"]
cmd-run = []
cmd-wast = ["dep:wasmi_wast"]

Alternatively I suppose you could also group the command features under a comment like # CLI command support: if you don't like the cmd- prefix.

---

• The simd feature is disabled by default since it is very bloaty and most Wasmi users likely won't have a need for it.

I see that advice is partly covered in the wasmi crate feature docs, apart from the size concern.

Would that be worth pointing out as another reason in those notes or would there be any value in a README.md beside the cli crates Cargo.toml for CLI users curious about the features? (I think just adding context via comments in the Cargo.toml can be sufficient for discovery, or in this case looking up the associated features for the wasmi library crate that is toggled)

[polarathene]

@Robbepop apart from #1824 , did you have any feedback on:

1. The cmd- prefix for features related to adding commands?
2. Better feature dependency for wasi/wat.

I'd understand if 1 doesn't appeal, but 2 seems worthwhile?

[Robbepop]

@Robbepop apart from #1824 , did you have any feedback on:

1. The `cmd-` prefix for features related to adding commands?

2. Better feature dependency for `wasi`/`wat`.

I'd understand if 1 doesn't appeal, but 2 seems worthwhile?

Hi @polarathene sorry I forgot to answer!

I really like the 1. cmp- prefix idea and would certainly go with it. However, Wasmi still wants to provide a best-effort Wasmtime mirror and the Wasmtime CLI application has the same run and wast crate features which behave the same.

I don't think that a dependency for wasi and wat is needed given that in the future more commands might appear that might use those. Furthermore, it may be that wast supports wasi in the future. At least there seems to be a WASI spec testsuite.