Skip to content

Commit 3250de5

Browse files
catamorphismcatamorphism
authored
Expand help text for component wit (#2342)
Add example usage section.
1 parent 4c2b177 commit 3250de5

File tree

5 files changed

+472
-0
lines changed

5 files changed

+472
-0
lines changed

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

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -488,6 +488,108 @@ impl LinkOpts {
488488
/// back to text, and a WIT document can be extracted from a component binary to
489489
/// inspect its interfaces.
490490
#[derive(Parser)]
491+
#[clap(after_help = "\
492+
Examples:
493+
494+
# Parse the current directory as a WIT package and print the resulting
495+
# package, supposing a directory that contains three WIT files,
496+
# one defining an
497+
# `adder` world; one defining a `subtracter` world; and one defining a
498+
# `calculator` world.
499+
$ wasm-tools component wit .
500+
package docs:[email protected];
501+
502+
interface add {
503+
add: func(x: u32, y: u32) -> u32;
504+
}
505+
506+
interface evaluate {
507+
evaluate: func(x: u32, y: u32) -> u32;
508+
}
509+
510+
interface subtract {
511+
subtract: func(x: u32, y: u32) -> u32;
512+
}
513+
514+
world adder {
515+
export add;
516+
}
517+
world calculator {
518+
import add;
519+
import subtract;
520+
521+
export evaluate;
522+
}
523+
world subtracter {
524+
export subtract;
525+
}
526+
527+
# Supposing the same directory contents as above, print the package to
528+
# a file in the `out` subdirectory.
529+
$ wasm-tools component wit . --out-dir out
530+
531+
# Supposing the same directory contents above, print the WIT for a world
532+
# that imports the exports of the `calculator` world.
533+
# In the output, the `calculator` world is replaced with:
534+
# world calculator-importized {
535+
# import evaluate;
536+
# }
537+
$ wasm-tools component wit . --importize-world calculator
538+
539+
# Supposing foo.wasm is a binary component, extract the interface
540+
# from the component and print it to stdout.
541+
$ wasm-tools component wit foo.wasm
542+
543+
# Supposing foo.wasm is a binary component that depends on several
544+
# WASI interfaces, extract the interface from the component and save it
545+
# as WIT, along with WIT files containing all the dependencies, to
546+
# the `out` subdirectory.
547+
$ wasm-tools component wit foo.wasm --out-dir out
548+
Writing: out/deps/io.wit
549+
Writing: out/deps/cli.wit
550+
Writing: out/deps/clocks.wit
551+
Writing: out/deps/filesystem.wit
552+
Writing: out/deps/adder.wit
553+
Writing: out/component.wit
554+
555+
# With the same foo.wasm file, print a textual WAT representation
556+
# of the interface to stdout, skipping validation of the WAT code.
557+
$ wasm-tools component wit foo.wasm -t --skip-validation
558+
559+
# With the same foo.wasm file, print a JSON representation
560+
# of the interface to stdout.
561+
$ wasm-tools component wit foo.wasm --json
562+
563+
# With the same foo.wasm file, print the WIT for a world that
564+
# imports the component's exports to stdout.
565+
$ wasm-tools component wit foo.wasm --importize
566+
567+
Supposing feature.wit is as follows:
568+
package a:b;
569+
570+
@unstable(feature = foo)
571+
interface foo {
572+
@unstable(feature = foo)
573+
type t = u32;
574+
}
575+
576+
# Print the WIT for feature.wit without hiding the unstable
577+
# \"foo\" feature.
578+
$ wasm-tools component wit feature.wit --features foo
579+
package a:b;
580+
581+
@unstable(feature = foo)
582+
interface foo {
583+
@unstable(feature = foo)
584+
type t = u32;
585+
}
586+
587+
# Print the WIT for feature.wit, hiding the unstable
588+
# \"foo\" feature.
589+
$ wasm-tools component wit feature.wit
590+
package a:b;
591+
592+
")]
491593
pub struct WitOpts {
492594
#[clap(flatten)]
493595
general: wasm_tools::GeneralOpts,

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

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

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

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
Tool for working with the WIT text format for components
2+
3+
Usage: wasm-tools component wit [OPTIONS] [INPUT]
4+
5+
Arguments:
6+
[INPUT] Input file or directory to process
7+
8+
Options:
9+
-v, --verbose...
10+
Use verbose output (-v info, -vv debug, -vvv trace)
11+
--color <COLOR>
12+
Configuration over whether terminal colors are used in output
13+
[default: auto]
14+
-o, --output <OUTPUT>
15+
Where to place output
16+
-w, --wasm
17+
Emit a WebAssembly binary representation instead of the WIT text
18+
format
19+
-t, --wat
20+
Emit a WebAssembly textual representation instead of the WIT text
21+
format
22+
--no-docs
23+
Do not include doc comments when emitting WIT text
24+
--out-dir <OUT_DIR>
25+
Emit the entire WIT resolution graph instead of just the "top level"
26+
package to the output directory specified
27+
--skip-validation
28+
Skips the validation performed when using the `--wasm` and `--wat`
29+
options
30+
-j, --json
31+
Emit the WIT document as JSON instead of text
32+
--importize
33+
Generates WIT to import the component specified to this command
34+
--importize-out-world-name <IMPORTIZE_OUT_WORLD_NAME>
35+
The name of the world to generate when using `--importize` or
36+
`importize-world`
37+
--importize-world <WORLD>
38+
Generates a WIT world to import a component which corresponds to the
39+
selected world
40+
--merge-world-imports-based-on-semver <WORLD>
41+
Updates the world specified to deduplicate all of its imports based on
42+
semver versions
43+
--features <FEATURES>
44+
Features to enable when parsing the `wit` option
45+
--all-features
46+
Enable all features when parsing the `wit` option
47+
-h, --help
48+
Print help (see more with '--help')
49+
50+
Examples:
51+
52+
# Parse the current directory as a WIT package and print the resulting
53+
# package, supposing a directory that contains three WIT files,
54+
# one defining an
55+
# `adder` world; one defining a `subtracter` world; and one defining a
56+
# `calculator` world.
57+
$ wasm-tools component wit .
58+
package docs:[email protected];
59+
60+
interface add {
61+
add: func(x: u32, y: u32) -> u32;
62+
}
63+
64+
interface evaluate {
65+
evaluate: func(x: u32, y: u32) -> u32;
66+
}
67+
68+
interface subtract {
69+
subtract: func(x: u32, y: u32) -> u32;
70+
}
71+
72+
world adder {
73+
export add;
74+
}
75+
world calculator {
76+
import add;
77+
import subtract;
78+
79+
export evaluate;
80+
}
81+
world subtracter {
82+
export subtract;
83+
}
84+
85+
# Supposing the same directory contents as above, print the package to
86+
# a file in the `out` subdirectory.
87+
$ wasm-tools component wit . --out-dir out
88+
89+
# Supposing the same directory contents above, print the WIT for a world
90+
# that imports the exports of the `calculator` world.
91+
# In the output, the `calculator` world is replaced with:
92+
# world calculator-importized {
93+
# import evaluate;
94+
# }
95+
$ wasm-tools component wit . --importize-world calculator
96+
97+
# Supposing foo.wasm is a binary component, extract the interface
98+
# from the component and print it to stdout.
99+
$ wasm-tools component wit foo.wasm
100+
101+
# Supposing foo.wasm is a binary component that depends on several
102+
# WASI interfaces, extract the interface from the component and save it
103+
# as WIT, along with WIT files containing all the dependencies, to
104+
# the `out` subdirectory.
105+
$ wasm-tools component wit foo.wasm --out-dir out
106+
Writing: out/deps/io.wit
107+
Writing: out/deps/cli.wit
108+
Writing: out/deps/clocks.wit
109+
Writing: out/deps/filesystem.wit
110+
Writing: out/deps/adder.wit
111+
Writing: out/component.wit
112+
113+
# With the same foo.wasm file, print a textual WAT representation
114+
# of the interface to stdout, skipping validation of the WAT code.
115+
$ wasm-tools component wit foo.wasm -t --skip-validation
116+
117+
# With the same foo.wasm file, print a JSON representation
118+
# of the interface to stdout.
119+
$ wasm-tools component wit foo.wasm --json
120+
121+
# With the same foo.wasm file, print the WIT for a world that
122+
# imports the component's exports to stdout.
123+
$ wasm-tools component wit foo.wasm --importize
124+
125+
Supposing feature.wit is as follows:
126+
package a:b;
127+
128+
@unstable(feature = foo)
129+
interface foo {
130+
@unstable(feature = foo)
131+
type t = u32;
132+
}
133+
134+
# Print the WIT for feature.wit without hiding the unstable
135+
# "foo" feature.
136+
$ wasm-tools component wit feature.wit --features foo
137+
package a:b;
138+
139+
@unstable(feature = foo)
140+
interface foo {
141+
@unstable(feature = foo)
142+
type t = u32;
143+
}
144+
145+
# Print the WIT for feature.wit, hiding the unstable
146+
# "foo" feature.
147+
$ wasm-tools component wit feature.wit
148+
package a:b;

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

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

0 commit comments

Comments
 (0)