Skip to content

Commit 8292838

Browse files
catamorphismcatamorphism
authored
Expand --help output for metadata add and metadata show commands (#2327)
Add example usage sections.
1 parent 3d53e00 commit 8292838

9 files changed

+769
-0
lines changed

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

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,144 @@ impl Opts {
3333

3434
/// Read metadata (module name, producers) from a WebAssembly file.
3535
#[derive(clap::Parser)]
36+
#[clap(after_help = "\
37+
Examples:
38+
39+
Suppose foo.wasm has the following textual representation:
40+
41+
(component $my-name
42+
(core module $submodule)
43+
44+
(core module (@name \"another submodule\"))
45+
)
46+
47+
This Wasm file represents a component containing two core modules.
48+
49+
# Show the metadata for foo.wasm in a tabular format.
50+
$ wasm-tools metadata show foo.wasm
51+
52+
╭───────────┬───────────────────┬──────┬───────┬───────────┬─────────╮
53+
│ KIND ┆ NAME ┆ SIZE ┆ SIZE% ┆ LANGUAGES ┆ PARENT │
54+
╞═══════════╪═══════════════════╪══════╪═══════╪═══════════╪═════════╡
55+
│ component ┆ my-name ┆ 136B ┆ 100% ┆ - ┆ <root> │
56+
├╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
57+
│ module ┆ submodule ┆ 27B ┆ 20% ┆ - ┆ my-name │
58+
├╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌┼╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
59+
│ module ┆ another submodule ┆ 35B ┆ 26% ┆ - ┆ my-name │
60+
╰───────────┴───────────────────┴──────┴───────┴───────────┴─────────╯
61+
╭───────┬────────────────────────────╮
62+
│ KIND ┆ VALUE │
63+
╞═══════╪════════════════════════════╡
64+
│ name ┆ my-name │
65+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
66+
│ kind ┆ component │
67+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
68+
│ range ┆ 0x0..0x88 │
69+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
70+
│ child ┆ submodule [module] │
71+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
72+
│ child ┆ another submodule [module] │
73+
╰───────┴────────────────────────────╯
74+
╭───────┬───────────╮
75+
│ KIND ┆ VALUE │
76+
╞═══════╪═══════════╡
77+
│ name ┆ submodule │
78+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
79+
│ kind ┆ module │
80+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
81+
│ range ┆ 0xa..0x25 │
82+
╰───────┴───────────╯
83+
╭───────┬───────────────────╮
84+
│ KIND ┆ VALUE │
85+
╞═══════╪═══════════════════╡
86+
│ name ┆ another submodule │
87+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
88+
│ kind ┆ module │
89+
├╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
90+
│ range ┆ 0x27..0x4a │
91+
╰───────┴───────────────────╯
92+
93+
The first table summarizes the contents of the file: a component and two
94+
core modules.
95+
96+
Next, one table is shown for each component and module. The first table
97+
shows that a component named `my-name` is represented by the bytes in
98+
foo.wasm between the offsets 0x0 and 0x88. The \"child\" rows of the table
99+
show the names of each of its contained modules. The second two tables
100+
show the names, kinds, and ranges of each of the modules in the file.
101+
102+
# Show the metadata for foo.wasm in JSON format.
103+
# The output is not pretty-printed. For clarity, it has been pretty-printed
104+
# here.
105+
$ wasm-tools metadata show foo.wasm --json
106+
{
107+
\"component\": {
108+
\"metadata\": {
109+
\"name\": \"my-name\",
110+
\"producers\": null,
111+
\"authors\": null,
112+
\"description\": null,
113+
\"licenses\": null,
114+
\"source\": null,
115+
\"homepage\": null,
116+
\"revision\": null,
117+
\"version\": null,
118+
\"range\": {
119+
\"start\": 0,
120+
\"end\": 136
121+
},
122+
\"dependencies\": null
123+
},
124+
\"children\": [
125+
{
126+
\"module\": {
127+
\"name\": \"submodule\",
128+
\"producers\": null,
129+
\"authors\": null,
130+
\"description\": null,
131+
\"licenses\": null,
132+
\"source\": null,
133+
\"homepage\": null,
134+
\"revision\": null,
135+
\"version\": null,
136+
\"range\": {
137+
\"start\": 10,
138+
\"end\": 37
139+
},
140+
\"dependencies\": null
141+
}
142+
},
143+
{
144+
\"module\": {
145+
\"name\": \"another submodule\",
146+
\"producers\": null,
147+
\"authors\": null,
148+
\"description\": null,
149+
\"licenses\": null,
150+
\"source\": null,
151+
\"homepage\": null,
152+
\"revision\": null,
153+
\"version\": null,
154+
\"range\": {
155+
\"start\": 39,
156+
\"end\": 74
157+
},
158+
\"dependencies\": null
159+
}
160+
}
161+
]
162+
}
163+
}
164+
165+
The JSON format contains some additional fields. In this example, the values of
166+
those fields are set to `null` because they are not present in the input file.
167+
In the tabular format, these fields were simply omitted.
168+
The offset ranges are also shown in decimal instead of hexadecimal.
169+
170+
Exit status:
171+
0 on success,
172+
nonzero if the input file fails to parse.
173+
")]
36174
pub struct ShowOpts {
37175
#[clap(flatten)]
38176
io: wasm_tools::InputOutput,
@@ -64,6 +202,47 @@ impl ShowOpts {
64202

65203
/// Add metadata (module name, producers) to a WebAssembly file
66204
#[derive(clap::Parser)]
205+
#[clap(after_help = "\
206+
Examples:
207+
208+
Suppose foo.wasm has the following textual representation:
209+
210+
(component $foo
211+
(core module
212+
(func $foo)
213+
)
214+
)
215+
216+
This Wasm file represents a component containing one core module.
217+
218+
# Add a programming language \"foo\" whose version is 1
219+
# to the `producers` section, an \"authors\" string,
220+
# and a homepage URL and print the textual representation
221+
# to stdout
222+
$ wasm-tools metadata add --language foo=1 \\
223+
--authors \"J. Random Hacker\" \\
224+
--homepage \"https://example.com/\" \\
225+
foo.wasm -t
226+
(component $foo
227+
(core module (;0;)
228+
(type (;0;) (func))
229+
(func $foo (;0;) (type 0))
230+
)
231+
(@producers
232+
(language \"foo\" \"1\")
233+
)
234+
(@custom \"authors\" \"J. Random Hacker\")
235+
(@custom \"homepage\" \"https://example.com/\")
236+
)
237+
238+
# Remove the homepage section from the file foo1.wasm
239+
# and write the binary output to foo2.wasm
240+
$ wasm-tools metadata add --clear-homepage foo1.wasm -o foo2.wasm
241+
242+
Exit status:
243+
0 on success,
244+
nonzero if the input file fails to parse.
245+
")]
67246
pub struct AddOpts {
68247
#[clap(flatten)]
69248
generate_dwarf: wasm_tools::GenerateDwarfArg,

‎tests/cli/help-metadata-add-short.wat‎

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

‎tests/cli/help-metadata-add-short.wat.stdout‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
Add metadata (module name, producers) to a WebAssembly file
2+
3+
Usage: wasm-tools metadata add [OPTIONS] [INPUT]
4+
5+
Arguments:
6+
[INPUT] Input file to process
7+
8+
Options:
9+
--generate-dwarf <lines|full>
10+
Optionally generate DWARF debugging information from WebAssembly text
11+
files
12+
-g
13+
Shorthand for `--generate-dwarf full`
14+
-o, --output <OUTPUT>
15+
Where to place output
16+
-v, --verbose...
17+
Use verbose output (-v info, -vv debug, -vvv trace)
18+
--color <COLOR>
19+
Configuration over whether terminal colors are used in output
20+
[default: auto]
21+
--name <NAME>
22+
Add a module or component name to the names section
23+
--clear-name
24+
Remove a module or component name from the names section
25+
--language <NAME=VERSION>
26+
Add a programming language to the producers section
27+
--processed-by <NAME=VERSION>
28+
Add a tool and its version to the producers section
29+
--sdk <NAME=VERSION>
30+
Add an SDK and its version to the producers section
31+
--authors <NAME>
32+
Contact details of the people or organization responsible, encoded as
33+
a freeform string
34+
--clear-authors
35+
Remove authors from the metadata
36+
--description <NAME>
37+
A human-readable description of the binary
38+
--clear-description
39+
Remove description from the metadata
40+
--licenses <NAME>
41+
License(s) under which contained software is distributed as an SPDX
42+
License Expression
43+
--clear-licenses
44+
Remove licenses from the metadata
45+
--source <NAME>
46+
URL to get source code for building the image
47+
--clear-source
48+
Remove source from the metadata
49+
--homepage <NAME>
50+
URL to find more information on the binary
51+
--clear-homepage
52+
Remove homepage from the metadata
53+
--revision <NAME>
54+
Source control revision identifier for the packaged software
55+
--clear-revision
56+
Remove revision from the metadata
57+
--version <NAME>
58+
Version of the packaged software
59+
--clear-version
60+
Remove version from the metadata
61+
-t, --wat
62+
Output the text format of WebAssembly instead of the binary format
63+
-h, --help
64+
Print help (see more with '--help')
65+
66+
Examples:
67+
68+
Suppose foo.wasm has the following textual representation:
69+
70+
(component $foo
71+
(core module
72+
(func $foo)
73+
)
74+
)
75+
76+
This Wasm file represents a component containing one core module.
77+
78+
# Add a programming language "foo" whose version is 1
79+
# to the `producers` section, an "authors" string,
80+
# and a homepage URL and print the textual representation
81+
# to stdout
82+
$ wasm-tools metadata add --language foo=1 /
83+
--authors "J. Random Hacker" /
84+
--homepage "https://example.com/" /
85+
foo.wasm -t
86+
(component $foo
87+
(core module (;0;)
88+
(type (;0;) (func))
89+
(func $foo (;0;) (type 0))
90+
)
91+
(@producers
92+
(language "foo" "1")
93+
)
94+
(@custom "authors" "J. Random Hacker")
95+
(@custom "homepage" "https://example.com/")
96+
)
97+
98+
# Remove the homepage section from the file foo1.wasm
99+
# and write the binary output to foo2.wasm
100+
$ wasm-tools metadata add --clear-homepage foo1.wasm -o foo2.wasm
101+
102+
Exit status:
103+
0 on success,
104+
nonzero if the input file fails to parse.

‎tests/cli/help-metadata-add.wat‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
;; RUN: metadata add --help

0 commit comments

Comments
 (0)