diff --git a/src/bin/wasm-tools/component.rs b/src/bin/wasm-tools/component.rs index 89ba4ca1b7..155a0a5c97 100644 --- a/src/bin/wasm-tools/component.rs +++ b/src/bin/wasm-tools/component.rs @@ -178,6 +178,67 @@ impl NewOpts { /// for you. This is primarily intended for one-off testing or for developers /// working with text format wasm. #[derive(Parser)] +#[clap(after_help = "\ +Examples: + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout. + $ wasm-tools component embed world.wit foo.wasm -t + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and save the resulting binary module to out.wasm. + $ wasm-tools component embed world.wit foo.wasm -o out.wasm + +Supposing feature.wit is as follows: +package a:b; + +@unstable(feature = foo) +interface foo { + @unstable(feature = foo) + type t = u32; +} + # Embed the WIT for feature.wit in the binary core module contained + # in the file foo.wasm, without hiding the unstable \"foo\" feature, + # and print the textual representation of the result to stdout. + $ wasm-tools component embed feature.wit --features foo foo.wasm -t + + # Supposing that the current directory contains several WIT files + # that each define various worlds, embed the world \"adder\" in + # the output and print its textual representation to stdout. + $ wasm-tools component embed . --world adder foo.wasm -t + +Note: without the --world flag in this case, wasm-tools would print an +error message that looks like: +error: There are multiple worlds in `docs:calculator@0.1.0`; one must be explicitly chosen: + docs:calculator/adder@0.1.0 + docs:calculator/calculator@0.1.0 + docs:calculator/subtracter@0.1.0 + + # Generate a template core module with the same imports and exports + # as the WIT world \"calculator\" that appears in a file in the current + # directory, and print a textual representation of the result to stdout. + $ wasm-tools component embed . --world calculator --dummy -t + + # Generate only the custom section; note that this does not require + # a .wasm or .wat file as an argument. + $ wasm-tools component embed --world foo foo.wit --only-custom -o foo.wasm + * using --only-custom + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout, lowering imports using the async ABI and lifting exports + # with the async-with-callback ABI. + $ wasm-tools component embed world.wit foo.wasm --async-callback --dummy-names legacy -t + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout, lowering imports using the async ABI and lifting exports + # with the async-without-callback ABI. + $ wasm-tools component embed world.wit foo.wasm --async-stackful --dummy-names legacy -t + +")] + pub struct EmbedOpts { #[clap(flatten)] resolve: WitResolve, diff --git a/tests/cli/help-component-embed-short.wat b/tests/cli/help-component-embed-short.wat new file mode 100644 index 0000000000..85f88f2095 --- /dev/null +++ b/tests/cli/help-component-embed-short.wat @@ -0,0 +1,2 @@ +;; RUN: component embed -h + diff --git a/tests/cli/help-component-embed-short.wat.stdout b/tests/cli/help-component-embed-short.wat.stdout new file mode 100644 index 0000000000..826192c6dc --- /dev/null +++ b/tests/cli/help-component-embed-short.wat.stdout @@ -0,0 +1,109 @@ +Embeds metadata for a component inside of a core wasm module + +Usage: wasm-tools component embed [OPTIONS] [INPUT] + +Arguments: + Path to WIT files to load + [INPUT] Input file to process + +Options: + --features + Features to enable when parsing the `wit` option + --all-features + Enable all features when parsing the `wit` option + --generate-dwarf + Optionally generate DWARF debugging information from WebAssembly text + files + -g + Shorthand for `--generate-dwarf full` + -o, --output + Where to place output + -v, --verbose... + Use verbose output (-v info, -vv debug, -vvv trace) + --color + Configuration over whether terminal colors are used in output + [default: auto] + --encoding + The expected string encoding format for the component + -w, --world + The world that the component uses + --dummy + Don't read a core wasm module as input, instead generating a "dummy" + module as a placeholder + --dummy-names + Same as `--dummy`, but the style of core wasm names is specified + --async-callback + With `--dummy-names legacy`, this will generate a core module such + that all the imports are lowered using the async ABI and the exports + are lifted using the async-with-callback ABI + --async-stackful + With `--dummy-names legacy`, this will generate a core module such + that all the imports are lowered using the async ABI and the exports + are lifted using the async-without-callback (i.e. stackful) ABI + -t, --wat + Print the output in the WebAssembly text format instead of binary + --only-custom + Print the wasm custom section only + -h, --help + Print help (see more with '--help') + +Examples: + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout. + $ wasm-tools component embed world.wit foo.wasm -t + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and save the resulting binary module to out.wasm. + $ wasm-tools component embed world.wit foo.wasm -o out.wasm + +Supposing feature.wit is as follows: +package a:b; + +@unstable(feature = foo) +interface foo { + @unstable(feature = foo) + type t = u32; +} + # Embed the WIT for feature.wit in the binary core module contained + # in the file foo.wasm, without hiding the unstable "foo" feature, + # and print the textual representation of the result to stdout. + $ wasm-tools component embed feature.wit --features foo foo.wasm -t + + # Supposing that the current directory contains several WIT files + # that each define various worlds, embed the world "adder" in + # the output and print its textual representation to stdout. + $ wasm-tools component embed . --world adder foo.wasm -t + +Note: without the --world flag in this case, wasm-tools would print an +error message that looks like: +error: There are multiple worlds in `docs:calculator@0.1.0`; one must be +explicitly chosen: + docs:calculator/adder@0.1.0 + docs:calculator/calculator@0.1.0 + docs:calculator/subtracter@0.1.0 + + # Generate a template core module with the same imports and exports + # as the WIT world "calculator" that appears in a file in the current + # directory, and print a textual representation of the result to stdout. + $ wasm-tools component embed . --world calculator --dummy -t + + # Generate only the custom section; note that this does not require + # a .wasm or .wat file as an argument. + $ wasm-tools component embed --world foo foo.wit --only-custom -o foo.wasm + * using --only-custom + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout, lowering imports using the async ABI and lifting exports + # with the async-with-callback ABI. + $ wasm-tools component embed world.wit foo.wasm --async-callback + --dummy-names legacy -t + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout, lowering imports using the async ABI and lifting exports + # with the async-without-callback ABI. + $ wasm-tools component embed world.wit foo.wasm --async-stackful + --dummy-names legacy -t diff --git a/tests/cli/help-component-embed.wat b/tests/cli/help-component-embed.wat new file mode 100644 index 0000000000..6db3539f26 --- /dev/null +++ b/tests/cli/help-component-embed.wat @@ -0,0 +1,2 @@ +;; RUN: component embed --help + diff --git a/tests/cli/help-component-embed.wat.stdout b/tests/cli/help-component-embed.wat.stdout new file mode 100644 index 0000000000..47166874d3 --- /dev/null +++ b/tests/cli/help-component-embed.wat.stdout @@ -0,0 +1,203 @@ +Embeds metadata for a component inside of a core wasm module. + +This subcommand is a convenience tool provided for producing core wasm binaries +which will get consumed by `wasm-tools component new`. This will embed metadata +for a component within a core wasm binary as a custom section. + +This metadata describe the imports and exports of a core wasm module with a WIT +package's `world`. The metadata will be used when creating a full component. + +Note that this subcommand may not be required most of the time since most +language tooling will already embed this metadata in the final wasm binary for +you. This is primarily intended for one-off testing or for developers working +with text format wasm. + +Usage: wasm-tools component embed [OPTIONS] [INPUT] + +Arguments: + + Path to WIT files to load. + + This can be a directory containing `*.wit` files, a `*.wit` file + itself, or a `*.wasm` file which is a WIT package encoded as + WebAssembly. + + [INPUT] + Input file to process. + + If not provided or if this is `-` then stdin is read entirely and + processed. Note that for most subcommands this input can either be a + binary `*.wasm` file or a textual format `*.wat` file. + +Options: + --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. + + --generate-dwarf + Optionally generate DWARF debugging information from WebAssembly text + files. + + When the input to this command is a WebAssembly text file, such as + `*.wat`, then this option will instruct the text parser to insert + DWARF debugging information to map binary locations back to the + original source locations in the input `*.wat` file. This option has + no effect if the `INPUT` argument is already a WebAssembly binary or + if the text format uses `(module binary ...)`. + + -g + Shorthand for `--generate-dwarf full` + + -o, --output + Where to place output. + + Required when printing WebAssembly binary output. + + If not provided, then stdout is used. + + -v, --verbose... + Use verbose output (-v info, -vv debug, -vvv trace) + + --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] + + --encoding + The expected string encoding format for the component. + + Supported values are: `utf8` (default), `utf16`, and `compact-utf16`. + This is only applicable to the `wit` argument to describe the string + encoding of the functions in that world. + + -w, --world + The world that the component uses. + + This is the path, within the `WIT` source provided as a positional + argument, to the `world` that the core wasm module works with. If this + option is omitted then the "main package" pointed to by `WIT` must + have a single world and that's what is used to embed. Otherwise this + could be a bare string `foo` to point to the `world foo` within the + main package of WIT. Finally this can be a fully qualified name too + such as `wasi:http/proxy` which can select a world from a WIT + dependency as well. + + --dummy + Don't read a core wasm module as input, instead generating a "dummy" + module as a placeholder. + + This flag will generate a dummy core wasm module on the fly to match + the `WIT` argument provided. This dummy module will have the correct + imports/exports and the right signatures for the component model. This + can be useful to, perhaps, inspect a template module and what it looks + like to work with an interface in the component model. + + This option is equivalent to `--dummy-names standard32` + + --dummy-names + Same as `--dummy`, but the style of core wasm names is specified. + + This flag is the same as `--dummy` where if specified a core wasm + module is not read but is instead generated. The value of the option + here is the name mangling scheme to use for core wasm names generated. + Current options are `legacy|standard32`. + + --async-callback + With `--dummy-names legacy`, this will generate a core module such + that all the imports are lowered using the async ABI and the exports + are lifted using the async-with-callback ABI. + + Note that this does not yet work with `--dummy` or `--dummy-names + standard32` because the standard name mangling scheme does not yet + support async-related features as of this writing. + + --async-stackful + With `--dummy-names legacy`, this will generate a core module such + that all the imports are lowered using the async ABI and the exports + are lifted using the async-without-callback (i.e. stackful) ABI. + + Note that this does not yet work with `--dummy` or `--dummy-names + standard32` because the standard name mangling scheme does not yet + support async-related features as of this writing. + + -t, --wat + Print the output in the WebAssembly text format instead of binary + + --only-custom + Print the wasm custom section only + + -h, --help + Print help (see a summary with '-h') + +Examples: + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout. + $ wasm-tools component embed world.wit foo.wasm -t + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and save the resulting binary module to out.wasm. + $ wasm-tools component embed world.wit foo.wasm -o out.wasm + +Supposing feature.wit is as follows: +package a:b; + +@unstable(feature = foo) +interface foo { + @unstable(feature = foo) + type t = u32; +} + # Embed the WIT for feature.wit in the binary core module contained + # in the file foo.wasm, without hiding the unstable "foo" feature, + # and print the textual representation of the result to stdout. + $ wasm-tools component embed feature.wit --features foo foo.wasm -t + + # Supposing that the current directory contains several WIT files + # that each define various worlds, embed the world "adder" in + # the output and print its textual representation to stdout. + $ wasm-tools component embed . --world adder foo.wasm -t + +Note: without the --world flag in this case, wasm-tools would print an +error message that looks like: +error: There are multiple worlds in `docs:calculator@0.1.0`; one must be +explicitly chosen: + docs:calculator/adder@0.1.0 + docs:calculator/calculator@0.1.0 + docs:calculator/subtracter@0.1.0 + + # Generate a template core module with the same imports and exports + # as the WIT world "calculator" that appears in a file in the current + # directory, and print a textual representation of the result to stdout. + $ wasm-tools component embed . --world calculator --dummy -t + + # Generate only the custom section; note that this does not require + # a .wasm or .wat file as an argument. + $ wasm-tools component embed --world foo foo.wit --only-custom -o foo.wasm + * using --only-custom + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout, lowering imports using the async ABI and lifting exports + # with the async-with-callback ABI. + $ wasm-tools component embed world.wit foo.wasm --async-callback + --dummy-names legacy -t + + # Embed the WIT in world.wit in the binary core module contained in the + # file foo.wasm and print the textual representation of the result + # to stdout, lowering imports using the async ABI and lifting exports + # with the async-without-callback ABI. + $ wasm-tools component embed world.wit foo.wasm --async-stackful + --dummy-names legacy -t