Tracking issue for migrating to the new CLI

[alexcrichton]

Note: if you'd rather not read up on this change and deal with it later then set WASMTIME_NEW_CLI=0 to force usage of the old CLI or WASMTIME_NEW_CLI=1 to force usage of the new CLI. This environment variable will go away in the future and the old CLI will be removed. This won't happen at least until Wasmtime 16 and at this time no exact time to make this change has been determined.

I'm opening this as a tracking issue to assist users in migrating from the old
Wasmtime 13-and-prior CLI to the new Wasmtime 14-and-later CLI. Wasmtime 14.0.x
is going to receive a patch update which restores support for the old CLI to
simultaneously support both the old and the new. The support, however, will
issue warnings that point to this issue. Specifically:

• If a CLI invocation parses different in Wasmtime 13 ("the old") and Wasmtime
  14 ("the new") then a warning is issued. For example:

  wasmtime run foo.wasm --invoke bar
  

  Was parsed in the old parser as invoking the bar function of foo.wasm. In
  the new parser this parses as passing the --invoke flag to the foo.wasm
  CLI program. In this situation a warning will be issued. This example could be
  fixed by changing the order of the arguments:

  wasmtime run --invoke bar foo.wasm
  

  which will no longer emit a warning.

• CLI invocations which fail to parse in the new parser but succeed in the old
  parser will continue to work but emit a warning. For example:

  wasmtime run --disable-cache foo.wasm
  

  no longer works because --disable-cache was renamed to -C cache=n. This
  will continue to work through but emit a warning.

This issue is being filed as I'm going to hardcode in the source code a print
of a warning which points here for users to find and discuss. My hope is to
incorporate feedback here into future iterations of the warning and/or the CLI.

Changes in Wasmtime 14

In Wasmtime 14 the wasmtime executable CLI syntax changed. #6925 has a
summary of the changes as well as a detailed table to renamed flags, but a
summary is restated here as well.

Parsing Changes

The first major change in Wasmtime 14 was a change to how arguments are parsed
to Wasmtime vs the WebAssembly program being run. Previously Wasmtime would
parse arguments anywhere before a -- on the CLI as its own, and everything
else was passed to the wasm program. This is a future compatibility hazard
though because -- is often omitted meaning that in the future it could be
difficult for Wasmtime to add new CLI options as they would shadow any matching
option passed to wasm itself.

Instead, starting in Wasmtime 14, all flags to Wasmtime must happen between the
wasmtime subcommand and the WebAssembly program being run. For example:

wasmtime run [wasmtime-flags] foo.wasm [wasm-flags]

or

wasmtime [wasmtime-flags] foo.wasm [wasm-flags]

Syntax Changes

The second major change in Wasmtime 14 was a change to the syntax of how many
arguments are passed. The Wasmtime CLI had previously organically grown where
options were inconsistently named and surfaced. This ended up with a sprawling
--help page as well differences between option names. Options are now
categorized into five broad categories:

• -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

These single-letter flags additionally have --longer names as well. Nearly
all configuration and tuning options for Wasmtime are now housed behind one of
these flags. Each flag can be explored with wasmtime -O help for example.

Examples of handling warnings

This section is intended to list a suite of old CLI invocations and their
equivalent in the new CLI. Where possible a new command is listed which parses
the same both under the old CLI and the new CLI.

Moving Wasmtime options before the WebAssembly file

[old]$ wasmtime foo.wasm --invoke bar
[new]$ wasmtime --invoke bar foo.wasm
[old]$ wasmtime run foo.wasm --invoke bar
[new]$ wasmtime run --invoke bar foo.wasm

Renaming Wasmtime options

[old]$ wasmtime --disable-cache foo.wasm
[new]$ wasmtime -C cache=n foo.wasm
[old]$ wasmtime run --disable-cache foo.wasm
[new]$ wasmtime run -C cache=n foo.wasm

Passing flags to WebAssembly files

[old]$ wasmtime run foo.wasm -- --flag
[new]$ wasmtime run -- foo.wasm --flag

Note that the new CLI also accepts wasmtime run foo.wasm --flag but the old CLI does not accept this. Additionally this will print a warning while the old CLI is still supported.

Passing -- to a wasm file

[old]$ wasmtime run foo.wasm -- --
[new]$ wasmtime run -- foo.wasm --

Note that the new CLI also accepts wasmtime run foo.wasm -- but the old CLI does not accept this. Additionally this will print a warning while the old CLI is still supported.

[eminence]

Some things to add to the TODO list, when you have a chance:

• Update the usage examples in the output of wasmtime --help
• Update the online docs (for example https://docs.wasmtime.dev/lang-bash.html)

[alexcrichton]

Thanks for the heads up! I posted #7408 to cover those. Apologies for missing the --help, I thought I went through that but I ended up missing it...

[alexcrichton]

The old CLI was removed in #8597 and Wasmtime 22 no longer supports the old CLI