Tool for working with the WIT text format for components.
This subcommand can be used to inspect and debug the WIT text or binary format
with either WIT packages or binary components. Using this subcommand a WIT
package can be translated to binary, a WIT binary can be translated back to
text, and a WIT document can be extracted from a component binary to inspect its
interfaces.
Usage: wasm-tools component wit [OPTIONS] [INPUT]
Arguments:
[INPUT]
Input file or directory to process.
The file specified can be a `*.wit` file parsed as a single-document
package. It can be a directory to be parsed as a WIT package. It can
be a `*.wat` or `*.wasm` file for either the binary representation of
a WIT package or a component itself to extract the interface from. The
type of input is inferred from the contents of the path specified.
If not provided or if this is `-` then stdin is read entirely and
processed.
Options:
-v, --verbose...
Use verbose output (-v info, -vv debug, -vvv trace)
--color <COLOR>
Configuration over whether terminal colors are used in output.
Supports one of `auto|never|always|always-ansi`. The default is to
detect what to do based on the terminal environment, for example by
using `isatty`.
[default: auto]
-o, --output <OUTPUT>
Where to place output.
Required when printing WebAssembly binary output.
If not provided, then stdout is used.
-w, --wasm
Emit a WebAssembly binary representation instead of the WIT text
format
-t, --wat
Emit a WebAssembly textual representation instead of the WIT text
format
--no-docs
Do not include doc comments when emitting WIT text
--out-dir <OUT_DIR>
Emit the entire WIT resolution graph instead of just the "top level"
package to the output directory specified.
The output directory will contain textual WIT files which represent
all packages known from the input.
--skip-validation
Skips the validation performed when using the `--wasm` and `--wat`
options
-j, --json
Emit the WIT document as JSON instead of text
--importize
Generates WIT to import the component specified to this command.
This flags requires that the input is a binary component, not a
wasm-encoded WIT package. This will then generate a WIT world and
output that. The returned world will have imports corresponding to the
exports of the component which is input.
This is similar to `--importize-world`, but is used with components.
--importize-out-world-name <IMPORTIZE_OUT_WORLD_NAME>
The name of the world to generate when using `--importize` or
`--importize-world`
--importize-world <WORLD>
Generates a WIT world to import a component which corresponds to the
selected world.
This flag is used to indicate that the input is a WIT package and the
world passed here is the name of a WIT `world` within the package. The
output of the command will be the same WIT world but one that's
importing the selected world. This effectively moves the world's
exports to imports.
This is similar to `--importize`, but is used with WIT packages.
--exportize
Generates WIT to export the component specified to this command.
This flag requires that the input is a binary component, not a
wasm-encoded WIT package. This will then generate a WIT world and
output that. The returned world will have exports corresponding to the
imports of the component which is input.
This is similar to `--exportize-world`, but is used with components.
--exportize-out-world-name <EXPORTIZE_OUT_WORLD_NAME>
The name of the world to generate when using `--exportize` or
`--exportize-world`
--exportize-import <IMPORT>
When used with `--exportize` or `--exportize-world`, only move the
specified imports to exports. Can be specified multiple times. If not
provided, all imports are moved
--exportize-world <WORLD>
Generates a WIT world to export a component which corresponds to the
selected world.
This flag is used to indicate that the input is a WIT package and the
world passed here is the name of a WIT `world` within the package. The
output of the command will be the same WIT world but one that's
exporting the selected world. This effectively moves the world's
imports to exports.
This is similar to `--exportize`, but is used with WIT packages.
--merge-world-imports-based-on-semver <WORLD>
Updates the world specified to deduplicate all of its imports based on
semver versions.
This option can be used to read a WIT world from a package and update
it to deduplicate WIT imports based on their version. This happens by
default in the `component new` subcommand for example and this flag
can be used to explore outside of that command what's happening to the
WIT.
--generate-nominal-type-ids <WORLD>
Generates unique type IDs for nominal types in the world provided.
This option can be used to affect the `--json` output of this command,
for example, and it is intended to make the job of bindings generators
easier by ensuring that each `TypeId` corresponds to a single type to
generate in the target language. This will modify the `world`
specified to duplicate exported interfaces, if needed, to ensure that
if they're both imported and exported it generates unique types in the
guest language.
--features <FEATURES>
Features to enable when parsing the `wit` option.
This flag enables the `@unstable` feature in WIT documents where the
items are otherwise hidden by default.
--all-features
Enable all features when parsing the `wit` option.
This flag enables all `@unstable` features in WIT documents where the
items are otherwise hidden by default.
-h, --help
Print help (see a summary with '-h')
Examples:
# Parse the current directory as a WIT package and print the resulting
# package, supposing a directory that contains three WIT files,
# one defining an
# `adder` world; one defining a `subtracter` world; and one defining a
# `calculator` world.
$ wasm-tools component wit .
package docs:calculator@0.1.0;
interface add {
add: func(x: u32, y: u32) -> u32;
}
interface evaluate {
evaluate: func(x: u32, y: u32) -> u32;
}
interface subtract {
subtract: func(x: u32, y: u32) -> u32;
}
world adder {
export add;
}
world calculator {
import add;
import subtract;
export evaluate;
}
world subtracter {
export subtract;
}
# Supposing the same directory contents as above, print the package to
# a file in the `out` subdirectory.
$ wasm-tools component wit . --out-dir out
# Supposing the same directory contents above, print the WIT for a world
# that imports the exports of the `calculator` world.
# In the output, the `calculator` world is replaced with:
# world calculator-importized {
# import evaluate;
# }
$ wasm-tools component wit . --importize-world calculator
# Supposing foo.wasm is a binary component, extract the interface
# from the component and print it to stdout.
$ wasm-tools component wit foo.wasm
# Supposing foo.wasm is a binary component that depends on several
# WASI interfaces, extract the interface from the component and save it
# as WIT, along with WIT files containing all the dependencies, to
# the `out` subdirectory.
$ wasm-tools component wit foo.wasm --out-dir out
Writing: out/deps/io.wit
Writing: out/deps/cli.wit
Writing: out/deps/clocks.wit
Writing: out/deps/filesystem.wit
Writing: out/deps/adder.wit
Writing: out/component.wit
# With the same foo.wasm file, print a textual WAT representation
# of the interface to stdout, skipping validation of the WAT code.
$ wasm-tools component wit foo.wasm -t --skip-validation
# With the same foo.wasm file, print a JSON representation
# of the interface to stdout.
$ wasm-tools component wit foo.wasm --json
# With the same foo.wasm file, print the WIT for a world that
# imports the component's exports to stdout.
$ wasm-tools component wit foo.wasm --importize
Supposing feature.wit is as follows:
package a:b;
@unstable(feature = foo)
interface foo {
@unstable(feature = foo)
type t = u32;
}
# Print the WIT for feature.wit without hiding the unstable
# "foo" feature.
$ wasm-tools component wit feature.wit --features foo
package a:b;
@unstable(feature = foo)
interface foo {
@unstable(feature = foo)
type t = u32;
}
# Print the WIT for feature.wit, hiding the unstable
# "foo" feature.
$ wasm-tools component wit feature.wit
package a:b;