Skip to content

Commit e6d02fa

Browse files
kripkenkripken
authored
[NFC] Improve wasm-reduce help text (#7293)
1 parent acd3ed3 commit e6d02fa

File tree

2 files changed

+108
-5
lines changed

2 files changed

+108
-5
lines changed

‎src/tools/wasm-reduce.cpp

Lines changed: 55 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1250,9 +1250,61 @@ int main(int argc, const char* argv[]) {
12501250

12511251
const std::string WasmReduceOption = "wasm-reduce options";
12521252

1253-
ToolOptions options("wasm-reduce",
1254-
"Reduce a wasm file to a smaller one that has the same "
1255-
"behavior on a given command");
1253+
ToolOptions options(
1254+
"wasm-reduce",
1255+
R"(Reduce a wasm file to a smaller one with the same behavior on a given command.
1256+
1257+
Typical usage:
1258+
1259+
wasm-reduce orig.wasm '--command=bash a.sh' --test t.wasm --working w.wasm
1260+
1261+
The original file orig.wasm is where we begin. We then repeatedly test a small
1262+
reduction of it by writing that modification to the 'test file' (specified by
1263+
'--test'), and we run the command, in this example 'bash a.sh'. That command
1264+
should use the test file (and not the original file or any other one). Whenever
1265+
the reduction works, we write that new smaller file to the 'working file'
1266+
(specified by '--working'). The reduction 'works' if it correctly preserves the
1267+
behavior of the command on the original input, specifically, that it has the
1268+
same stdout and the result return code. Each time reduction works we continue to
1269+
reduce from that point (and each time it fails, we go back and try something
1270+
else).
1271+
1272+
As mentioned above, the command should run on the test file. That is, the first
1273+
thing that wasm-reduce does on the example above is, effectively,
1274+
1275+
cp orig.wasm t.wasm
1276+
bash a.sh
1277+
1278+
In other words, it copies the original to the test file, and runs the command.
1279+
Whatever the command does, we will preserve as we copy progressively smaller
1280+
files to t.wasm. As we make progress, the smallest file will be written to
1281+
the working file, w.wasm, and when reduction is done you will find the final
1282+
result there.
1283+
1284+
Comparison to creduce:
1285+
1286+
1. creduce requires the command to return 0. wasm-reduce is often used to reduce
1287+
crashes, which have non-zero return codes, so it is natural to allow any
1288+
return code. As mentioned above, we preserve the return code as we reduce.
1289+
2. creduce ignores stdout. wasm-reduce preserves stdout as it reduces, as part
1290+
of the principle of preserving the original behavior of the command (if your
1291+
stdout varies in uninteresting ways, your command can be a script that runs
1292+
the real command and captures stdout to /dev/null, or filters it).
1293+
3. creduce tramples the original input file as it reduces. wasm-reduce never
1294+
modifies the input (to avoid mistakes that cause data loss). Instead,
1295+
when reductions work we write to the 'working file' as mentioned above, and
1296+
the final reduction will be there.
1297+
4. creduce runs the command in a temp directory. That is safer in general, but
1298+
it is not how the original command ran, and in particular forces additional
1299+
work if you have multiple files (which, for wasm-reduce, is common, e.g. if
1300+
the testcase is a combination of JavaScript and wasm). wasm-reduce runs the
1301+
command in the current directory (of course, your command can be a script
1302+
that changes directory to anywhere else).
1303+
1304+
More documentation can be found at
1305+
1306+
https://github.com/WebAssembly/binaryen/wiki/Fuzzing#reducing
1307+
)");
12561308
options
12571309
.add("--command",
12581310
"-cmd",

‎test/lit/help/wasm-reduce.test

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,59 @@
22
;; CHECK: ================================================================================
33
;; CHECK-NEXT: wasm-reduce INFILE
44
;; CHECK-NEXT:
5-
;; CHECK-NEXT: Reduce a wasm file to a smaller one that has the same behavior on a given
6-
;; CHECK-NEXT: command
5+
;; CHECK-NEXT: Reduce a wasm file to a smaller one with the same behavior on a given command.
6+
;; CHECK-NEXT:
7+
;; CHECK-NEXT: Typical usage:
8+
;; CHECK-NEXT:
9+
;; CHECK-NEXT: wasm-reduce orig.wasm '--command=bash a.sh' --test t.wasm --working w.wasm
10+
;; CHECK-NEXT:
11+
;; CHECK-NEXT: The original file orig.wasm is where we begin. We then repeatedly test a small
12+
;; CHECK-NEXT: reduction of it by writing that modification to the 'test file' (specified by
13+
;; CHECK-NEXT: '--test'), and we run the command, in this example 'bash a.sh'. That command
14+
;; CHECK-NEXT: should use the test file (and not the original file or any other one). Whenever
15+
;; CHECK-NEXT: the reduction works, we write that new smaller file to the 'working file'
16+
;; CHECK-NEXT: (specified by '--working'). The reduction 'works' if it correctly preserves the
17+
;; CHECK-NEXT: behavior of the command on the original input, specifically, that it has the
18+
;; CHECK-NEXT: same stdout and the result return code. Each time reduction works we continue to
19+
;; CHECK-NEXT: reduce from that point (and each time it fails, we go back and try something
20+
;; CHECK-NEXT: else).
21+
;; CHECK-NEXT:
22+
;; CHECK-NEXT: As mentioned above, the command should run on the test file. That is, the first
23+
;; CHECK-NEXT: thing that wasm-reduce does on the example above is, effectively,
24+
;; CHECK-NEXT:
25+
;; CHECK-NEXT: cp orig.wasm t.wasm
26+
;; CHECK-NEXT: bash a.sh
27+
;; CHECK-NEXT:
28+
;; CHECK-NEXT: In other words, it copies the original to the test file, and runs the command.
29+
;; CHECK-NEXT: Whatever the command does, we will preserve as we copy progressively smaller
30+
;; CHECK-NEXT: files to t.wasm. As we make progress, the smallest file will be written to
31+
;; CHECK-NEXT: the working file, w.wasm, and when reduction is done you will find the final
32+
;; CHECK-NEXT: result there.
33+
;; CHECK-NEXT:
34+
;; CHECK-NEXT: Comparison to creduce:
35+
;; CHECK-NEXT:
36+
;; CHECK-NEXT: 1. creduce requires the command to return 0. wasm-reduce is often used to reduce
37+
;; CHECK-NEXT: crashes, which have non-zero return codes, so it is natural to allow any
38+
;; CHECK-NEXT: return code. As mentioned above, we preserve the return code as we reduce.
39+
;; CHECK-NEXT: 2. creduce ignores stdout. wasm-reduce preserves stdout as it reduces, as part
40+
;; CHECK-NEXT: of the principle of preserving the original behavior of the command (if your
41+
;; CHECK-NEXT: stdout varies in uninteresting ways, your command can be a script that runs
42+
;; CHECK-NEXT: the real command and captures stdout to /dev/null, or filters it).
43+
;; CHECK-NEXT: 3. creduce tramples the original input file as it reduces. wasm-reduce never
44+
;; CHECK-NEXT: modifies the input (to avoid mistakes that cause data loss). Instead,
45+
;; CHECK-NEXT: when reductions work we write to the 'working file' as mentioned above, and
46+
;; CHECK-NEXT: the final reduction will be there.
47+
;; CHECK-NEXT: 4. creduce runs the command in a temp directory. That is safer in general, but
48+
;; CHECK-NEXT: it is not how the original command ran, and in particular forces additional
49+
;; CHECK-NEXT: work if you have multiple files (which, for wasm-reduce, is common, e.g. if
50+
;; CHECK-NEXT: the testcase is a combination of JavaScript and wasm). wasm-reduce runs the
51+
;; CHECK-NEXT: command in the current directory (of course, your command can be a script
52+
;; CHECK-NEXT: that changes directory to anywhere else).
53+
;; CHECK-NEXT:
54+
;; CHECK-NEXT: More documentation can be found at
55+
;; CHECK-NEXT:
56+
;; CHECK-NEXT: https://github.com/WebAssembly/binaryen/wiki/Fuzzing#reducing
57+
;; CHECK-NEXT:
758
;; CHECK-NEXT: ================================================================================
859
;; CHECK-NEXT:
960
;; CHECK-NEXT:

0 commit comments

Comments
 (0)