WASM-REDUCE(1)

NAME
wasm-reduce - Reduce a wasm file to a smaller one with the same behavior on a given command.

DESCRIPTION
================================================================================ wasm-reduce INFILE

Reduce a wasm file to a smaller one with the same behavior on a given command.

Typical usage:

    wasm-reduce orig.wasm '--command=bash a.sh' --test t.wasm --working w.wasm

The original file orig.wasm is where we begin. We then repeatedly test a small reduction of it by writing that modification to the 'test file' (specified by '--test'), and we run the command, in this example 'bash a.sh'. That command should use the test file (and not the original file or any other one). Whenever the reduction works, we write that new smaller file to the 'working file' (specified by '--working'). The reduction 'works' if it correctly preserves the behavior of the command on the original input, specifically, that it has the same stdout and the result return code. Each time reduction works we continue to reduce from that point (and each time it fails, we go back and try something else).

As mentioned above, the command should run on the test file. That is, the first thing that wasm-reduce does on the example above is, effectively,

    cp orig.wasm t.wasm bash a.sh

In other words, it copies the original to the test file, and runs the command. Whatever the command does, we will preserve as we copy progressively smaller files to t.wasm. As we make progress, the smallest file will be written to the working file, w.wasm, and when reduction is done you will find the final result there.

Comparison to creduce:

1. creduce requires the command to return 0. wasm-reduce is often used to reduce

    crashes, which have non-zero return codes, so it is natural to allow any return code. As mentioned above, we preserve the return code as we reduce.

2. creduce ignores stdout. wasm-reduce preserves stdout as it reduces, as part

    of the principle of preserving the original behavior of the command (if your stdout varies in uninteresting ways, your command can be a script that runs the real command and captures stdout to /dev/null, or filters it).

3. creduce tramples the original input file as it reduces. wasm-reduce never

    modifies the input (to avoid mistakes that cause data loss). Instead, when reductions work we write to the 'working file' as mentioned above, and the final reduction will be there.

4. creduce runs the command in a temp directory. That is safer in general, but

    it is not how the original command ran, and in particular forces additional work if you have multiple files (which, for wasm-reduce, is common, e.g. if the testcase is a combination of JavaScript and wasm). wasm-reduce runs the command in the current directory (of course, your command can be a script that changes directory to anywhere else).

More documentation can be found at

    https://github.com/WebAssembly/binaryen/wiki/Fuzzing#reducing

================================================================================

wasm-reduce options: --------------------

--command,-cmd
    The command to run on the test, that we want to reduce while keeping the command's output identical. We look at the command's return code and stdout here (TODO: stderr), and we reduce while keeping those unchanged.

--test,-t
    Test file (this will be written to test, the given command should read it when we call it)

--working,-w
    Working file (this will contain the current good state while doing temporary computations, and will contain the final best result at the end)

--binaries,-b
    binaryen binaries location (bin/ directory)

--text,-S
    Emit intermediate files as text, instead of binary (also make sure the test and working files have a .wat or .wast suffix)

--denan
    Avoid nans when reducing

--verbose,-v
    Verbose output mode

--debugInfo,-g
    Keep debug info in binaries

--force,-f
    Force the reduction attempt, ignoring problems that imply it is unlikely to succeed

--timeout,-to
    A timeout to apply to each execution of the command, in seconds (default: 2)

--extra-flags,-ef
    Extra commandline flags to pass to wasm-opt while reducing. (default: --enable-all)

--save-all-working,-saw
    Save all intermediate working files, as $WORKING.0, .1, .2 etc

Tool options: -------------

--mvp-features,-mvp
    Disable all non-MVP features

--all-features,-all
    Enable all features

--detect-features
    (deprecated - this flag does nothing)

--quiet,-q
    Emit less verbose output and hide trivial warnings.

--experimental-poppy
    Parse wast files as Poppy IR for testing purposes.

--emit-module-names
    Emit module names, even if not emitting the rest of the names section.

--enable-sign-ext
    Enable sign extension operations

--disable-sign-ext
    Disable sign extension operations

--enable-threads
    Enable atomic operations

--disable-threads
    Disable atomic operations

--enable-mutable-globals
    Enable mutable globals

--disable-mutable-globals
    Disable mutable globals

--enable-nontrapping-float-to-int
    Enable nontrapping float-to-int operations

--disable-nontrapping-float-to-int
    Disable nontrapping float-to-int operations

--enable-simd
    Enable SIMD operations and types

--disable-simd
    Disable SIMD operations and types

--enable-bulk-memory
    Enable bulk memory operations

--disable-bulk-memory
    Disable bulk memory operations

--enable-bulk-memory-opt
    Enable memory.copy and memory.fill

--disable-bulk-memory-opt
    Disable memory.copy and memory.fill

--enable-call-indirect-overlong
    Enable LEB encoding of call-indirect (Ignored for compatibility as it has no effect on Binaryen)

--disable-call-indirect-overlong
    Disable LEB encoding of call-indirect (Ignored for compatibility as it has no effect on Binaryen)

--enable-exception-handling
    Enable exception handling operations

--disable-exception-handling
    Disable exception handling operations

--enable-tail-call
    Enable tail call operations

--disable-tail-call
    Disable tail call operations

--enable-reference-types
    Enable reference types

--disable-reference-types
    Disable reference types

--enable-multivalue
    Enable multivalue functions

--disable-multivalue
    Disable multivalue functions

--enable-gc
    Enable garbage collection

--disable-gc
    Disable garbage collection

--enable-memory64
    Enable memory64

--disable-memory64
    Disable memory64

--enable-relaxed-simd
    Enable relaxed SIMD

--disable-relaxed-simd
    Disable relaxed SIMD

--enable-extended-const
    Enable extended const expressions

--disable-extended-const
    Disable extended const expressions

--enable-strings
    Enable strings

--disable-strings
    Disable strings

--enable-multimemory
    Enable multimemory

--disable-multimemory
    Disable multimemory

--enable-stack-switching
    Enable stack switching

--disable-stack-switching
    Disable stack switching

--enable-shared-everything
    Enable shared-everything threads

--disable-shared-everything
    Disable shared-everything threads

--enable-fp16
    Enable float 16 operations

--disable-fp16
    Disable float 16 operations

--enable-custom-descriptors
    Enable custom descriptors (RTTs) and exact references

--disable-custom-descriptors
    Disable custom descriptors (RTTs) and exact references

--enable-multibyte
    Enable multibyte array loads and stores

--disable-multibyte
    Disable multibyte array loads and stores

--enable-relaxed-atomics
    Enable acquire/release atomic memory operations

--disable-relaxed-atomics
    Disable acquire/release atomic memory operations

--enable-custom-page-sizes
    Enable custom page sizes

--disable-custom-page-sizes
    Disable custom page sizes

--enable-wide-arithmetic
    Enable wide arithmetic

--disable-wide-arithmetic
    Disable wide arithmetic

--enable-compact-imports
    Enable compact import section

--disable-compact-imports
    Disable compact import section

--enable-typed-function-references
    Deprecated compatibility flag

--disable-typed-function-references
    Deprecated compatibility flag

--no-validation,-n
    Disables validation, assumes inputs are correct

--pass-arg,-pa
    An argument passed along to optimization passes being run. Must be in the form KEY@VALUE. If KEY is the name of a pass then it applies to the closest instance of that pass before us. If KEY is not the name of a pass then it is a global option that applies to all pass instances that read it.

--closed-world,-cw
    Assume code outside of the module does not inspect or interact with GC and function references, even if they are passed out. The outside may hold on to them and pass them back in, but not inspect their contents or call them.

--preserve-type-order
    Preserve the order of types from the input (useful for debugging and testing)

--generate-stack-ir
    generate StackIR during writing

--optimize-stack-ir
    optimize StackIR during writing

--print-stack-ir
    print StackIR during writing

General options: ----------------

--version
    Output version information and exit

--help,-h
    Show this help message and exit

--debug,-d
    Print debug information to stderr