wasmtime / PR #6925 Redesign Wasmtime's CLI · git-wasmtime

Stream: git-wasmtime

Topic: wasmtime / PR #6925 Redesign Wasmtime's CLI

Wasmtime GitHub notifications bot (Aug 29 2023 at 18:00):

alexcrichton requested wasmtime-core-reviewers for a review on PR #6925.

Wasmtime GitHub notifications bot (Aug 29 2023 at 18:04):

alexcrichton opened PR #6925 from alexcrichton:new-cli to bytecodealliance:main:

This commit follows through on discussion from #6741 to redesign the flags that the wasmtime binary accepts on the CLI. Almost all flags have been renamed/moved and will require callers to update. The main motivation here is to cut down on the forest of options in wasmtime -h which are difficult to mentally group together and understand.

The main change implemented here is to move options behind "option groups" which are intended to be abbreviated with a single letter:

-O foo - an optimization or performance-tuning related option

-C foo - a codegen option affecting the compilation process.

-D foo - a debug-related option

-W foo - a wasm-related option, for example changing wasm semantics

-S foo - a WASI-related option, configuring various proposals for example

Each option group can be explored by passing help, for example -O help. This will print all options within the group along with their help message. Additionally -O help-long can be passed to print the full comment for each option if desired.

Option groups can be specified multiple times on the command line, for example -Wrelaxed-simd -Wthreads. They can also be combined together with commas as -Wrelaxed-simd,threads. Configuration works as a "last option wins" so -Ccache,cache=n would end up with a compilation cache disabled.

Boolean options can be specified as -C foo to enable foo, or they can be specified with -Cfoo=$val with any of y, n, yes, no, true, or false. All other options require a =foo value to be passed and the parsing depends on the type.

This commit additionally applies a few small refactorings to the CLI as well. For example the help text no longer prints information about wasm features after printing the option help. This is still available via -Whelp as all wasm features have moved from --wasm-features to -W. Additionally flags are no longer conditionally compiled in, but instead all flags are always supported. A runtime error is returned if support for a flag is not compiled in. Additionally the "experimental" name of WASI proposals has been dropped in favor of just the name of the proposal, for example --wasi nn instead of --wasi-modules experimental-wasi-nn. This is intended to mirror how wasm proposals don't have "experimental" in the name and an opt-in is required regardless.

A full listing of flags and how they have changed is:

old cli flag new cli flag

-O, --optimize removed

--opt-level <LEVEL> -O opt-level=N

--dynamic-memory-guard-size <SIZE> -O dynamic-memory-guard-size=...

--static-memory-forced -O static-memory-forced

--static-memory-guard-size <SIZE> -O static-memory-guard-size=N

--static-memory-maximum-size <MAXIMUM> -O static-memory-maximum-size=N

--dynamic-memory-reserved-for-growth <SIZE> -O dynamic-memory-reserved-for-growth=...

--pooling-allocator -O pooling-allocator

--disable-memory-init-cow -O memory-init-cow=no

--compiler <COMPILER> -C compiler=..

--enable-cranelift-debug-verifier -C cranelift-debug-verifier

--cranelift-enable <SETTING> -C cranelift-NAME

--cranelift-set <NAME=VALUE> -C cranelift-NAME=VALUE

--config <CONFIG_PATH> -C cache-config=..

--disable-cache -C cache=no

--disable-parallel-compilation -C parallel-compilation=no

-g -D debug-info

--disable-address-map -D address-map=no

--disable-logging -D logging=no

--log-to-files -D log-to-files

--coredump-on-trap <PATH> -D coredump=..

--wasm-features all -W all-proposals

--wasm-features -all -W all-proposals=n

--wasm-features bulk-memory -W bulk-memory

--wasm-features multi-memory -W multi-memory

--wasm-features multi-value -W multi-value

--wasm-features reference-types -W reference-types

--wasm-features simd -W simd

--wasm-features tail-call -W tail-call

--wasm-features threads -W threads

--wasm-features memory64 -W memory64

--wasm-features copmonent-model -W component-model

--wasm-features function-references -W function-references

--relaxed-simd-deterministic -W relaxed-simd-deterministic

--enable-cranelift-nan-canonicalization -W nan-canonicalization

--fuel <N> -W fuel=N

--epoch-interruption -W epoch-interruption

--allow-unknown-exports -W unknown-exports-allow

--trap-unknown-imports -W unknown-imports-trap

--default-values-unknown-imports -W unknown-imports-default

--max-instances <MAX_INSTANCES> -W max-instances=N

--max-memories <MAX_MEMORIES> -W max-memories=N

--max-memory-size <BYTES> -W max-memory-size=N

--max-table-elements <MAX_TABLE_ELEMENTS> -W max-table-elements=N

--max-tables <MAX_TABLES> -W max-tables=N

--max-wasm-stack <MAX_WASM_STACK> -W max-wasm-stack=N

--trap-on-grow-failure -W trap-on-grow-failure

--wasm-timeout <TIME> -W timeout=N

--wmemcheck -W wmemcheck

--wasi-modules default removed

--wasi-modules -default removed

--wasi-modules wasi-common -S common

--wasi-modules -wasi-common -S common=n

--wasi-modules experimental-wasi-nn -S nn

--wasi-modules experimental-wasi-threads -S threads

--wasi-modules experimental-wasi-http -S http

--listenfd -S listenfd

--tcplisten <SOCKET ADDRESS> -S tcplisten=...

--wasi-nn-graph <FORMAT::HOST> -S nn-graph=FORMAT::HOST

--preview2 -S preview2

--dir <DIRECTORY> --dir ...

--mapdir <GUEST_DIR::HOST_DIR> --dir a::b

old cli flag	new cli flag
`-O, --optimize`	removed
`--opt-level <LEVEL>`	`-O opt-level=N`
`--dynamic-memory-guard-size <SIZE>`	`-O dynamic-memory-guard-size=...`
`--static-memory-forced`	`-O static-memory-forced`
`--static-memory-guard-size <SIZE>`	`-O static-memory-guard-size=N`
`--static-memory-maximum-size <MAXIMUM>`	`-O static-memory-maximum-size=N`
`--dynamic-memory-reserved-for-growth <SIZE>`	`-O dynamic-memory-reserved-for-growth=...`
`--pooling-allocator`	`-O pooling-allocator`
`--disable-memory-init-cow`	`-O memory-init-cow=no`
`--compiler <COMPILER>`	`-C compiler=..`
`--enable-cranelift-debug-verifier`	`-C cranelift-debug-verifier`
`--cranelift-enable <SETTING>`	`-C cranelift-NAME`
`--cranelift-set <NAME=VALUE>`	`-C cranelift-NAME=VALUE`
`--config <CONFIG_PATH>`	`-C cache-config=..`
`--disable-cache`	`-C cache=no`
`--disable-parallel-compilation`	`-C parallel-compilation=no`
`-g`	`-D debug-info`
`--disable-address-map`	`-D address-map=no`
`--disable-logging`	`-D logging=no`
`--log-to-files`	`-D log-to-files`
`--coredump-on-trap <PATH>`	`-D coredump=..`
`--wasm-features all`	`-W all-proposals`
`--wasm-features -all`	`-W all-proposals=n`
`--wasm-features bulk-memory`	`-W bulk-memory`
`--wasm-features multi-memory`	`-W multi-memory`
`--wasm-features multi-value`	`-W multi-value`
`--wasm-features reference-types`	`-W reference-types`
`--wasm-features simd`	`-W simd`
`--wasm-features tail-call`	`-W tail-call`
`--wasm-features threads`	`-W threads`
`--wasm-features memory64`	`-W memory64`
`--wasm-features copmonent-model`	`-W component-model`
`--wasm-features function-references`	`-W function-references`
`--relaxed-simd-deterministic`	`-W relaxed-simd-deterministic`
`--enable-cranelift-nan-canonicalization`	`-W nan-canonicalization`
`--fuel <N>`	`-W fuel=N`
`--epoch-interruption`	`-W epoch-interruption`
`--allow-unknown-exports`	`-W unknown-exports-allow`
`--trap-unknown-imports`	`-W unknown-imports-trap`
`--default-values-unknown-imports`	`-W unknown-imports-default`
`--max-instances <MAX_INSTANCES>`	`-W max-instances=N`
`--max-memories <MAX_MEMORIES>`	`-W max-memories=N`
`--max-memory-size <BYTES>`	`-W max-memory-size=N`
`--max-table-elements <MAX_TABLE_ELEMENTS>`	`-W max-table-elements=N`
`--max-tables <MAX_TABLES>`	`-W max-tables=N`
`--max-wasm-stack <MAX_WASM_STACK>`	`-W max-wasm-stack=N`
`--trap-on-grow-failure`	`-W trap-on-grow-failure`
`--wasm-timeout <TIME>`	`-W timeout=N`
`--wmemcheck`	`-W wmemcheck`
`--wasi-modules default`	removed
`--wasi-modules -default`	removed
`--wasi-modules wasi-common`	`-S common`
`--wasi-modules -wasi-common`	`-S common=n`
`--wasi-modules experimental-wasi-nn`	`-S nn`
`--wasi-modules experimental-wasi-threads`	`-S threads`
`--wasi-modules experimental-wasi-http`	`-S http`
`--listenfd`	`-S listenfd`
`--tcplisten <SOCKET ADDRESS>`	`-S tcplisten=...`
`--wasi-nn-graph <FORMAT::HOST>`	`-S nn-graph=FORMAT::HOST`
`--preview2`	`-S preview2`
`--dir <DIRECTORY>`	`--dir ...`
`--mapdir <GUEST_DIR::HOST_DIR>`	`--dir a::b`

Wasmtime GitHub notifications bot (Aug 29 2023 at 18:05):

alexcrichton requested wasmtime-default-reviewers for a review on PR #6925.