Skip to content

Commit 1fc68bb

Browse files
catamorphismcatamorphism
authored
Expand help text for component embed (#2343)
Add example usage section.
1 parent 7018138 commit 1fc68bb

File tree

5 files changed

+377
-0
lines changed

5 files changed

+377
-0
lines changed

‎src/bin/wasm-tools/component.rs‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,67 @@ impl NewOpts {
217217
/// for you. This is primarily intended for one-off testing or for developers
218218
/// working with text format wasm.
219219
#[derive(Parser)]
220+
#[clap(after_help = "\
221+
Examples:
222+
223+
# Embed the WIT in world.wit in the binary core module contained in the
224+
# file foo.wasm and print the textual representation of the result
225+
# to stdout.
226+
$ wasm-tools component embed world.wit foo.wasm -t
227+
228+
# Embed the WIT in world.wit in the binary core module contained in the
229+
# file foo.wasm and save the resulting binary module to out.wasm.
230+
$ wasm-tools component embed world.wit foo.wasm -o out.wasm
231+
232+
Supposing feature.wit is as follows:
233+
package a:b;
234+
235+
@unstable(feature = foo)
236+
interface foo {
237+
@unstable(feature = foo)
238+
type t = u32;
239+
}
240+
# Embed the WIT for feature.wit in the binary core module contained
241+
# in the file foo.wasm, without hiding the unstable \"foo\" feature,
242+
# and print the textual representation of the result to stdout.
243+
$ wasm-tools component embed feature.wit --features foo foo.wasm -t
244+
245+
# Supposing that the current directory contains several WIT files
246+
# that each define various worlds, embed the world \"adder\" in
247+
# the output and print its textual representation to stdout.
248+
$ wasm-tools component embed . --world adder foo.wasm -t
249+
250+
Note: without the --world flag in this case, wasm-tools would print an
251+
error message that looks like:
252+
error: There are multiple worlds in `docs:calculator@0.1.0`; one must be explicitly chosen:
253+
docs:calculator/adder@0.1.0
254+
docs:calculator/calculator@0.1.0
255+
docs:calculator/subtracter@0.1.0
256+
257+
# Generate a template core module with the same imports and exports
258+
# as the WIT world \"calculator\" that appears in a file in the current
259+
# directory, and print a textual representation of the result to stdout.
260+
$ wasm-tools component embed . --world calculator --dummy -t
261+
262+
# Generate only the custom section; note that this does not require
263+
# a .wasm or .wat file as an argument.
264+
$ wasm-tools component embed --world foo foo.wit --only-custom -o foo.wasm
265+
* using --only-custom
266+
267+
# Embed the WIT in world.wit in the binary core module contained in the
268+
# file foo.wasm and print the textual representation of the result
269+
# to stdout, lowering imports using the async ABI and lifting exports
270+
# with the async-with-callback ABI.
271+
$ wasm-tools component embed world.wit foo.wasm --async-callback --dummy-names legacy -t
272+
273+
# Embed the WIT in world.wit in the binary core module contained in the
274+
# file foo.wasm and print the textual representation of the result
275+
# to stdout, lowering imports using the async ABI and lifting exports
276+
# with the async-without-callback ABI.
277+
$ wasm-tools component embed world.wit foo.wasm --async-stackful --dummy-names legacy -t
278+
279+
")]
280+
220281
pub struct EmbedOpts {
221282
#[clap(flatten)]
222283
resolve: WitResolve,

‎tests/cli/help-component-embed-short.wat‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
;; RUN: component embed -h
2+

‎tests/cli/help-component-embed-short.wat.stdout‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
Embeds metadata for a component inside of a core wasm module
2+
3+
Usage: wasm-tools component embed [OPTIONS] <WIT> [INPUT]
4+
5+
Arguments:
6+
<WIT> Path to WIT files to load
7+
[INPUT] Input file to process
8+
9+
Options:
10+
--features <FEATURES>
11+
Features to enable when parsing the `wit` option
12+
--all-features
13+
Enable all features when parsing the `wit` option
14+
--generate-dwarf <lines|full>
15+
Optionally generate DWARF debugging information from WebAssembly text
16+
files
17+
-g
18+
Shorthand for `--generate-dwarf full`
19+
-o, --output <OUTPUT>
20+
Where to place output
21+
-v, --verbose...
22+
Use verbose output (-v info, -vv debug, -vvv trace)
23+
--color <COLOR>
24+
Configuration over whether terminal colors are used in output
25+
[default: auto]
26+
--encoding <ENCODING>
27+
The expected string encoding format for the component
28+
-w, --world <WORLD>
29+
The world that the component uses
30+
--dummy
31+
Don't read a core wasm module as input, instead generating a "dummy"
32+
module as a placeholder
33+
--dummy-names <DUMMY_NAMES>
34+
Same as `--dummy`, but the style of core wasm names is specified
35+
--async-callback
36+
With `--dummy-names legacy`, this will generate a core module such
37+
that all the imports are lowered using the async ABI and the exports
38+
are lifted using the async-with-callback ABI
39+
--async-stackful
40+
With `--dummy-names legacy`, this will generate a core module such
41+
that all the imports are lowered using the async ABI and the exports
42+
are lifted using the async-without-callback (i.e. stackful) ABI
43+
-t, --wat
44+
Print the output in the WebAssembly text format instead of binary
45+
--only-custom
46+
Print the wasm custom section only
47+
-h, --help
48+
Print help (see more with '--help')
49+
50+
Examples:
51+
52+
# Embed the WIT in world.wit in the binary core module contained in the
53+
# file foo.wasm and print the textual representation of the result
54+
# to stdout.
55+
$ wasm-tools component embed world.wit foo.wasm -t
56+
57+
# Embed the WIT in world.wit in the binary core module contained in the
58+
# file foo.wasm and save the resulting binary module to out.wasm.
59+
$ wasm-tools component embed world.wit foo.wasm -o out.wasm
60+
61+
Supposing feature.wit is as follows:
62+
package a:b;
63+
64+
@unstable(feature = foo)
65+
interface foo {
66+
@unstable(feature = foo)
67+
type t = u32;
68+
}
69+
# Embed the WIT for feature.wit in the binary core module contained
70+
# in the file foo.wasm, without hiding the unstable "foo" feature,
71+
# and print the textual representation of the result to stdout.
72+
$ wasm-tools component embed feature.wit --features foo foo.wasm -t
73+
74+
# Supposing that the current directory contains several WIT files
75+
# that each define various worlds, embed the world "adder" in
76+
# the output and print its textual representation to stdout.
77+
$ wasm-tools component embed . --world adder foo.wasm -t
78+
79+
Note: without the --world flag in this case, wasm-tools would print an
80+
error message that looks like:
81+
error: There are multiple worlds in `docs:calculator@0.1.0`; one must be
82+
explicitly chosen:
83+
docs:calculator/adder@0.1.0
84+
docs:calculator/calculator@0.1.0
85+
docs:calculator/subtracter@0.1.0
86+
87+
# Generate a template core module with the same imports and exports
88+
# as the WIT world "calculator" that appears in a file in the current
89+
# directory, and print a textual representation of the result to stdout.
90+
$ wasm-tools component embed . --world calculator --dummy -t
91+
92+
# Generate only the custom section; note that this does not require
93+
# a .wasm or .wat file as an argument.
94+
$ wasm-tools component embed --world foo foo.wit --only-custom -o foo.wasm
95+
* using --only-custom
96+
97+
# Embed the WIT in world.wit in the binary core module contained in the
98+
# file foo.wasm and print the textual representation of the result
99+
# to stdout, lowering imports using the async ABI and lifting exports
100+
# with the async-with-callback ABI.
101+
$ wasm-tools component embed world.wit foo.wasm --async-callback
102+
--dummy-names legacy -t
103+
104+
# Embed the WIT in world.wit in the binary core module contained in the
105+
# file foo.wasm and print the textual representation of the result
106+
# to stdout, lowering imports using the async ABI and lifting exports
107+
# with the async-without-callback ABI.
108+
$ wasm-tools component embed world.wit foo.wasm --async-stackful
109+
--dummy-names legacy -t

‎tests/cli/help-component-embed.wat‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
;; RUN: component embed --help
2+

‎tests/cli/help-component-embed.wat.stdout‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
Embeds metadata for a component inside of a core wasm module.
2+
3+
This subcommand is a convenience tool provided for producing core wasm binaries
4+
which will get consumed by `wasm-tools component new`. This will embed metadata
5+
for a component within a core wasm binary as a custom section.
6+
7+
This metadata describe the imports and exports of a core wasm module with a WIT
8+
package's `world`. The metadata will be used when creating a full component.
9+
10+
Note that this subcommand may not be required most of the time since most
11+
language tooling will already embed this metadata in the final wasm binary for
12+
you. This is primarily intended for one-off testing or for developers working
13+
with text format wasm.
14+
15+
Usage: wasm-tools component embed [OPTIONS] <WIT> [INPUT]
16+
17+
Arguments:
18+
<WIT>
19+
Path to WIT files to load.
20+
21+
This can be a directory containing `*.wit` files, a `*.wit` file
22+
itself, or a `*.wasm` file which is a WIT package encoded as
23+
WebAssembly.
24+
25+
[INPUT]
26+
Input file to process.
27+
28+
If not provided or if this is `-` then stdin is read entirely and
29+
processed. Note that for most subcommands this input can either be a
30+
binary `*.wasm` file or a textual format `*.wat` file.
31+
32+
Options:
33+
--features <FEATURES>
34+
Features to enable when parsing the `wit` option.
35+
36+
This flag enables the `@unstable` feature in WIT documents where the
37+
items are otherwise hidden by default.
38+
39+
--all-features
40+
Enable all features when parsing the `wit` option.
41+
42+
This flag enables all `@unstable` features in WIT documents where the
43+
items are otherwise hidden by default.
44+
45+
--generate-dwarf <lines|full>
46+
Optionally generate DWARF debugging information from WebAssembly text
47+
files.
48+
49+
When the input to this command is a WebAssembly text file, such as
50+
`*.wat`, then this option will instruct the text parser to insert
51+
DWARF debugging information to map binary locations back to the
52+
original source locations in the input `*.wat` file. This option has
53+
no effect if the `INPUT` argument is already a WebAssembly binary or
54+
if the text format uses `(module binary ...)`.
55+
56+
-g
57+
Shorthand for `--generate-dwarf full`
58+
59+
-o, --output <OUTPUT>
60+
Where to place output.
61+
62+
Required when printing WebAssembly binary output.
63+
64+
If not provided, then stdout is used.
65+
66+
-v, --verbose...
67+
Use verbose output (-v info, -vv debug, -vvv trace)
68+
69+
--color <COLOR>
70+
Configuration over whether terminal colors are used in output.
71+
72+
Supports one of `auto|never|always|always-ansi`. The default is to
73+
detect what to do based on the terminal environment, for example by
74+
using `isatty`.
75+
76+
[default: auto]
77+
78+
--encoding <ENCODING>
79+
The expected string encoding format for the component.
80+
81+
Supported values are: `utf8` (default), `utf16`, and `compact-utf16`.
82+
This is only applicable to the `wit` argument to describe the string
83+
encoding of the functions in that world.
84+
85+
-w, --world <WORLD>
86+
The world that the component uses.
87+
88+
This is the path, within the `WIT` source provided as a positional
89+
argument, to the `world` that the core wasm module works with. If this
90+
option is omitted then the "main package" pointed to by `WIT` must
91+
have a single world and that's what is used to embed. Otherwise this
92+
could be a bare string `foo` to point to the `world foo` within the
93+
main package of WIT. Finally this can be a fully qualified name too
94+
such as `wasi:http/proxy` which can select a world from a WIT
95+
dependency as well.
96+
97+
--dummy
98+
Don't read a core wasm module as input, instead generating a "dummy"
99+
module as a placeholder.
100+
101+
This flag will generate a dummy core wasm module on the fly to match
102+
the `WIT` argument provided. This dummy module will have the correct
103+
imports/exports and the right signatures for the component model. This
104+
can be useful to, perhaps, inspect a template module and what it looks
105+
like to work with an interface in the component model.
106+
107+
This option is equivalent to `--dummy-names standard32`
108+
109+
--dummy-names <DUMMY_NAMES>
110+
Same as `--dummy`, but the style of core wasm names is specified.
111+
112+
This flag is the same as `--dummy` where if specified a core wasm
113+
module is not read but is instead generated. The value of the option
114+
here is the name mangling scheme to use for core wasm names generated.
115+
Current options are `legacy|standard32`.
116+
117+
--async-callback
118+
With `--dummy-names legacy`, this will generate a core module such
119+
that all the imports are lowered using the async ABI and the exports
120+
are lifted using the async-with-callback ABI.
121+
122+
Note that this does not yet work with `--dummy` or `--dummy-names
123+
standard32` because the standard name mangling scheme does not yet
124+
support async-related features as of this writing.
125+
126+
--async-stackful
127+
With `--dummy-names legacy`, this will generate a core module such
128+
that all the imports are lowered using the async ABI and the exports
129+
are lifted using the async-without-callback (i.e. stackful) ABI.
130+
131+
Note that this does not yet work with `--dummy` or `--dummy-names
132+
standard32` because the standard name mangling scheme does not yet
133+
support async-related features as of this writing.
134+
135+
-t, --wat
136+
Print the output in the WebAssembly text format instead of binary
137+
138+
--only-custom
139+
Print the wasm custom section only
140+
141+
-h, --help
142+
Print help (see a summary with '-h')
143+
144+
Examples:
145+
146+
# Embed the WIT in world.wit in the binary core module contained in the
147+
# file foo.wasm and print the textual representation of the result
148+
# to stdout.
149+
$ wasm-tools component embed world.wit foo.wasm -t
150+
151+
# Embed the WIT in world.wit in the binary core module contained in the
152+
# file foo.wasm and save the resulting binary module to out.wasm.
153+
$ wasm-tools component embed world.wit foo.wasm -o out.wasm
154+
155+
Supposing feature.wit is as follows:
156+
package a:b;
157+
158+
@unstable(feature = foo)
159+
interface foo {
160+
@unstable(feature = foo)
161+
type t = u32;
162+
}
163+
# Embed the WIT for feature.wit in the binary core module contained
164+
# in the file foo.wasm, without hiding the unstable "foo" feature,
165+
# and print the textual representation of the result to stdout.
166+
$ wasm-tools component embed feature.wit --features foo foo.wasm -t
167+
168+
# Supposing that the current directory contains several WIT files
169+
# that each define various worlds, embed the world "adder" in
170+
# the output and print its textual representation to stdout.
171+
$ wasm-tools component embed . --world adder foo.wasm -t
172+
173+
Note: without the --world flag in this case, wasm-tools would print an
174+
error message that looks like:
175+
error: There are multiple worlds in `docs:calculator@0.1.0`; one must be
176+
explicitly chosen:
177+
docs:calculator/adder@0.1.0
178+
docs:calculator/calculator@0.1.0
179+
docs:calculator/subtracter@0.1.0
180+
181+
# Generate a template core module with the same imports and exports
182+
# as the WIT world "calculator" that appears in a file in the current
183+
# directory, and print a textual representation of the result to stdout.
184+
$ wasm-tools component embed . --world calculator --dummy -t
185+
186+
# Generate only the custom section; note that this does not require
187+
# a .wasm or .wat file as an argument.
188+
$ wasm-tools component embed --world foo foo.wit --only-custom -o foo.wasm
189+
* using --only-custom
190+
191+
# Embed the WIT in world.wit in the binary core module contained in the
192+
# file foo.wasm and print the textual representation of the result
193+
# to stdout, lowering imports using the async ABI and lifting exports
194+
# with the async-with-callback ABI.
195+
$ wasm-tools component embed world.wit foo.wasm --async-callback
196+
--dummy-names legacy -t
197+
198+
# Embed the WIT in world.wit in the binary core module contained in the
199+
# file foo.wasm and print the textual representation of the result
200+
# to stdout, lowering imports using the async ABI and lifting exports
201+
# with the async-without-callback ABI.
202+
$ wasm-tools component embed world.wit foo.wasm --async-stackful
203+
--dummy-names legacy -t

0 commit comments

Comments
 (0)