Stream: git-wasmtime

Topic: wasmtime / issue #14527 Documentation: Clearly document t...

Wasmtime GitHub notifications bot (Oct 04 2026 at 22:40):

mcclure opened issue #14527:

If you look at the wasmtime CLI installation documentation:

https://docs.wasmtime.dev/cli-install.html

It suggests cargo install wasmtime-cli and cargo binstall wasmtime-cli are equivalent to both each other and the tarball releases on your github.

This is false. At minimum, cargo binstall includes the gdbstub feature whereas cargo install does not— as is actually documented much later in the manual.

This can lead to issues which are difficult to debug, because "official" installations on two separate computers can have different behavior depending on the seemingly trivial difference of whether install or binstall was typed to install them.

Expected Results

The cli-install page in the manual should give the cargo install invocation which reproduces the binary-distributed versions.

Test Case / Steps to Reproduce

1. Get a .wasm (here's one)
2. cargo install wasmtime-cli
3. cargo -g 8888 puzzle-start-prebuilt.wasm

Actual Results for test case

Binstalled version gives "Debugger: Debugger listening on 127.0.0.1:8888" , installed version gives "flag -g not recognized, try putting it after a --" error

Versions and Environment

wasmtime 49.0.2
cargo 1.97.1
Debian GNU/Linux 13 (trixie)
AMD64

Extra Info

Some further suggestions:

• In the install docs, you might want to suggest --locked, IE cargo install --features gdbstub --locked wasmtime-cli, when describing the cargo install install, for greater consistency between the install and binstall versions. (Although also a --locked build in my tests does print some strange warnings about deleted versions.)
• This is probably out of scope for a documentation bug, but you should consider wasmtime, when a -g flag is passed when gdbstub is not present, actually printing a message saying "This copy of wasmtime was compiled without the gdbstub feature". As long as an error code is still returned, printing this message would not create compatibility problems.

Wasmtime GitHub notifications bot (Oct 04 2026 at 22:40):

mcclure added the bug label to Issue #14527.

Wasmtime GitHub notifications bot (Oct 04 2026 at 22:41):

mcclure edited issue #14527:

If you look at the wasmtime CLI installation documentation:

https://docs.wasmtime.dev/cli-install.html

It suggests cargo install wasmtime-cli and cargo binstall wasmtime-cli are equivalent to both each other and the tarball releases on your github.

This is false. At minimum, cargo binstall includes the gdbstub feature whereas cargo install does not— as is actually documented much later in the manual. It's possible there are additional differences besides that.

This can lead to issues which are difficult to debug, because "official" installations on two separate computers can have different behavior depending on the seemingly trivial difference of whether install or binstall was typed to install them.

Expected Results

The cli-install page in the manual should give the cargo install invocation which reproduces the binary-distributed versions.

Test Case / Steps to Reproduce

1. Get a .wasm (here's one)
2. cargo install wasmtime-cli
3. cargo -g 8888 puzzle-start-prebuilt.wasm

Actual Results for test case

Binstalled version gives "Debugger: Debugger listening on 127.0.0.1:8888" , installed version gives "flag -g not recognized, try putting it after a --" error

Versions and Environment

wasmtime 49.0.2
cargo 1.97.1
Debian GNU/Linux 13 (trixie)
AMD64

Extra Info

Some further suggestions:

• In the install docs, you might want to suggest --locked, IE cargo install --features gdbstub --locked wasmtime-cli, when describing the cargo install install, for greater consistency between the install and binstall versions. (Although also a --locked build in my tests does print some strange warnings about deleted versions.)
• This is probably out of scope for a documentation bug, but you should consider wasmtime, when a -g flag is passed when gdbstub is not present, actually printing a message saying "This copy of wasmtime was compiled without the gdbstub feature". As long as an error code is still returned, printing this message would not create compatibility problems.

Wasmtime GitHub notifications bot (Oct 04 2026 at 22:44):

mcclure edited issue #14527:

If you look at the wasmtime CLI installation documentation:

https://docs.wasmtime.dev/cli-install.html

It suggests cargo install wasmtime-cli and cargo binstall wasmtime-cli are equivalent to both each other and the tarball releases on your github.

This is false. At minimum, cargo binstall includes the gdbstub feature whereas cargo install does not— as is actually documented much later in the manual. (And it's possible there are additional differences besides that.)

This can lead to issues which are difficult to debug, because "official" installations on two separate computers can have different behavior depending on the seemingly trivial difference of whether install or binstall was typed to install them.

Expected Results

The cli-install page in the manual should give the cargo install invocation which reproduces the binary-distributed versions.

Test Case / Steps to Reproduce

1. Get a .wasm (here's one)
2. cargo install wasmtime-cli
3. cargo -g 8888 puzzle-start-prebuilt.wasm

Actual Results for test case

Binstalled version gives "Debugger: Debugger listening on 127.0.0.1:8888" , installed version gives "flag -g not recognized, try putting it after a --" error

Versions and Environment

wasmtime 49.0.2
cargo 1.97.1
Debian GNU/Linux 13 (trixie)
AMD64

Extra Info

Some further suggestions:

• In the install docs, you might want to suggest --locked, IE cargo install --features gdbstub --locked wasmtime-cli, when describing the cargo install install, for greater consistency between the install and binstall versions. (Although also a --locked build in my tests does print some strange warnings about deleted versions.)
• This is probably out of scope for a documentation bug, but you should consider wasmtime, when a -g flag is passed when gdbstub is not present, actually printing a message saying "This copy of wasmtime was compiled without the gdbstub feature". As long as an error code is still returned, printing this message would not create compatibility problems.

Wasmtime GitHub notifications bot (Oct 04 2026 at 22:46):

alexcrichton added the wasmtime:docs label to Issue #14527.

Wasmtime GitHub notifications bot (Oct 04 2026 at 22:46):

alexcrichton removed the bug label from Issue #14527.

Wasmtime GitHub notifications bot (Oct 05 2026 at 15:03):

cfallin commented on issue #14527:

Sorry about the confusion here!

For anyone digging deeper, the reason that gdbstub is not on by default when building the wasmtime-cli crate directly is that the feature involves taking the build result of one crate (the gdbstub adapter) and including it in another (the wasmtime-cli binary); this is unsupported by Cargo when building from published crates, because (I think) the crates are built separately rather than in-tree (see Alex's comment here). It's a Cargo limitation and something that requires a new Cargo feature ("artifact dependencies") to resolve properly.

Since we build in-tree in CI, we can build release binaries (later consumed by binstall) that have the feature.

I'll add a note to our install docs. Thanks again for filing the issue!

Wasmtime GitHub notifications bot (Oct 05 2026 at 15:46):

alexcrichton closed issue #14527:

If you look at the wasmtime CLI installation documentation:

https://docs.wasmtime.dev/cli-install.html

It suggests cargo install wasmtime-cli and cargo binstall wasmtime-cli are equivalent to both each other and the tarball releases on your github.

This is false. At minimum, cargo binstall includes the gdbstub feature whereas cargo install does not— as is actually documented much later in the manual. (And it's possible there are additional differences besides that.)

This can lead to issues which are difficult to debug, because "official" installations on two separate computers can have different behavior depending on the seemingly trivial difference of whether install or binstall was typed to install them.

Expected Results

The cli-install page in the manual should give the cargo install invocation which reproduces the binary-distributed versions.

Test Case / Steps to Reproduce

1. Get a .wasm (here's one)
2. cargo install wasmtime-cli
3. cargo -g 8888 puzzle-start-prebuilt.wasm

Actual Results for test case

Binstalled version gives "Debugger: Debugger listening on 127.0.0.1:8888" , installed version gives "flag -g not recognized, try putting it after a --" error

Versions and Environment

wasmtime 49.0.2
cargo 1.97.1
Debian GNU/Linux 13 (trixie)
AMD64

Extra Info

Some further suggestions:

• In the install docs, you might want to suggest --locked, IE cargo install --features gdbstub --locked wasmtime-cli, when describing the cargo install install, for greater consistency between the install and binstall versions. (Although also a --locked build in my tests does print some strange warnings about deleted versions.)
• This is probably out of scope for a documentation bug, but you should consider wasmtime, when a -g flag is passed when gdbstub is not present, actually printing a message saying "This copy of wasmtime was compiled without the gdbstub feature". As long as an error code is still returned, printing this message would not create compatibility problems.

Last updated: Oct 11 2026 at 04:10 UTC