DOKK / manpages / debian 13 / binaryen / wasm-metadce.1.en
WASM-METADCE(1) User Commands WASM-METADCE(1)

wasm-metadce - This tool performs dead code elimination (DCE) on a larger space that the wasm

================================================================================ wasm-metadce INFILE

This tool performs dead code elimination (DCE) on a larger space that the wasm module is just a part of. For example, if you have JS and wasm that are connected, this can DCE the combined graph. By doing so, it is able to eliminate wasm module exports, which otherwise regular optimizations cannot.

This tool receives a representation of the reachability graph that the wasm module resides in, which contains abstract nodes and connections showing what they reach. Some of those nodes can represent the wasm module's imports and exports. The tool then completes the graph by adding the internal parts of the module, and does DCE on the entire thing.

This tool will output a wasm module with dead code eliminated, and metadata describing the things in the rest of the graph that can be eliminated as well.

The graph description file should represent the graph in the following JSON-like notation (note, this is not true JSON, things like comments, escaping, single-quotes, etc. are not supported):

[
{
"name": "entity1", "reaches": ["entity2, "entity3"], "root": true
}, {
"name": "entity2", "reaches": ["entity1, "entity4"]
}, {
"name": "entity3", "reaches": ["entity1"], "export": "export1"
}, {
"name": "entity4", "import": ["module", "import1"]
},
]

Each entity has a name and an optional list of the other entities it reaches. It can also be marked as a root, export (with the export string), or import (with the module and import strings). DCE then computes what is reachable from the roots. ================================================================================

wasm-opt options: -----------------

Output file (stdout if not specified)
Consume source map from the specified file
Emit source map to the specified file
Emit specified string as source map URL
Emit text instead of binary for the output file
Emit names section and debug info
Filename of the graph description file
Dump the combined graph file (useful for debugging)

Optimization passes: --------------------

refine and merge abstract (never-created) types
lower unaligned loads and stores to smaller aligned ones
async/await style transform, allowing pausing and resuming
Tries to avoid reinterpret operations via more loads
propagate constant struct field values
propagate constant struct field values, using ref.test
reduce # of locals by coalescing
reduce # of locals by coalescing and learning
fold code, merging duplicates
push code forward, potentially making it not always execute
hoist repeated constants to a local
removes arguments to calls in an lto-like manner
removes arguments to calls in an lto-like manner, and optimizes where we removed
removes unreachable code
forces all loads and stores to have alignment 1
instrument the wasm to convert NaNs into 0 at runtime
optimizes using the DataFlow SSA IR
turns indirect calls into direct ones
discards global effect info
removes duplicate functions
removes duplicate imports
dump DWARF debug info sections from the read binary
emit the target features section in the output
leaves just one function (useful for debugging)
leaves just one function selected by index
flattens out code, removing nesting
emulates function pointer casts, allowing incorrect indirect calls to (sometimes) work
reports function metrics
generate dynCall fuctions used by emscripten ABI
generate global effect info (helps later passes)
generate dynCall functions used by emscripten ABI, but only for functions with i64 in their signature (which cannot be invoked via the wasm table without JavaScript BigInt support).
refine the types of globals
globally optimize struct values
globally optimize GC types
Grand Unified Flow Analysis: optimize the entire program using information about what content can actually appear in each location
GUFA plus add casts for all inferences
GUFA plus local optimizations in functions we modified
optimize heap (GC) stores
replace GC allocations with locals
lower all uses of i64s to use i32s instead
inline __original_main into main
inline functions (you probably want inlining-optimizing)
inline functions and optimizes where we inlined
instrument the build with code to intercept all loads and stores
instrument the build with code to intercept all loads and stores
lower away binaryen intrinsics
wrap imports and exports for JavaScript promise integration
legalizes the import/export boundary and prunes when needed
legalizes i64 types on the import/export boundary
loop invariant code motion
attempt to merge segments to fit within web limits
common subexpression elimination inside basic blocks
apply more specific subtypes to locals where possible
instrument the build with logging of where execution goes
packs memory into separate segments, skipping zeros
lower loads and stores to a 64-bit memory to instead use a 32-bit one
merges blocks to their parents
Merges itable structures into vtables to make types more compact
merges locals when beneficial
merges similar functions when benefical
reports metrics (with an optional title, --metrics[=TITLE])
minifies import names (only those, and not export names), and emits a mapping to the minified ones
minifies both import and export names, and emits a mapping to the minified ones
minifies both import and export names, and emits a mapping to the minified ones, and minifies the modules as well
Split types into minimal recursion groups
apply the assumption that asyncify imports always unwind, and we never rewind
apply the assumption that asyncify never unwinds
creates specialized versions of functions
creates specialized versions of functions (even if unhelpful)
combines multiple memories into a single memory
combines multiple memories into a single memory, trapping if the read or write is larger than the length of the memory's data
(re)name all heap types
name list
mark functions as no-inline (for full inlining only)
mark functions as no-inline
mark functions as no-inline (for partial inlining only)
reduces calls to code that only runs once
optimizes added constants into load/store offsets
optimizes added constants into load/store offsets, propagating them across locals too
eliminate and reuse casts
early optimize of the instruction combinations for js
optimizes instruction combinations
optimizes J2CL specific constructs.
outline instructions
pick load signs based on their uses
Tranform Binaryen IR into Poppy IR
miscellaneous optimizations for Emscripten-generated code
computes compile-time evaluatable expressions
computes compile-time evaluatable expressions and propagates them through locals
print in s-expression format
print call graph
print options for enabled features
print in full s-expression format
print a map of function indexes to names
print in minified s-expression format
propagate debug location from parents or previous siblings to child nodes
propagate global values to other globals (useful for tests)
removes imports and replaces them with nops
removes memory segments
removes operations incompatible with js
removes breaks from locations that are not needed
removes unused module elements
removes names from locations that are never branched to
removes unused module elements that are not functions
remove unused private GC types
sorts functions by access frequency
sorts functions by name (useful for debugging)
sorts globals by access frequency
sorts locals by access frequency
re-optimize control flow using the relooper algorithm
write the module to binary, then read it
remove redundant local.sets
instrument loads and stores to check for invalid behavior
write data segments to a file and strip them from the module
sets specified globals to specified values
remove params from function signature types where possible
apply more specific subtypes to signature types where possible
lower sign-ext operations to wasm mvp and disable the sign extension feature
miscellaneous globals-related optimizations
miscellaneous globals-related optimizations, and optimizes where we replaced global.gets with constants
miscellaneous locals-related optimizations
miscellaneous locals-related optimizations (no nesting at all; preserves flatness)
miscellaneous locals-related optimizations (no structure)
miscellaneous locals-related optimizations (no tees)
miscellaneous locals-related optimizations (no tees or structure)
emit Souper IR in text form
emit Souper IR in text form (single-use nodes only)
spill pointers to the C stack (useful for Boehm-style GC)
ssa-ify variables so that they have a single assignment
ssa-ify variables so that they have a single assignment, ignoring merges
enforce limits on llvm's __stack_pointer global
gathers wasm strings to globals
lowers wasm strings and operations to imports
same as string-lowering, but encodes well-formed strings as magic imports
same as string-lowering-magic-imports, but raise a fatal error if there are invalid strings
deprecated; same as strip-debug
strip debug info (including the names section)
strip dwarf debug info
strip EH instructions
strip the wasm producers section
strip the wasm target features section
stub out unsupported JS operations
(alias for print-function-map)
lower 64-bit tables 32-bit ones
instrument the build with code to intercept specific function calls
translate old Phase 3 EH instructions to new ones with exnref
deprecated; same as translate-to-exnref
replace trapping operations with clamping semantics
replace trapping operations with js semantics
optimize trivial tuples away
mark all leaf types as final
merge types to their supertypes where possible
apply more specific subtypes to type fields where possible
create new nominal types to help other optimizations
mark all types as non-final (open)
removes unnecessary subtyping relationships
removes local.tees, replacing them with sets and gets
removes obviously unneeded code

Optimization options: ---------------------

execute default optimization passes (equivalent to -Os)
execute no optimization passes
execute -O1 optimization passes (quick&useful opts, useful for iteration builds)
execute -O2 optimization passes (most opts, generally gets most perf)
execute -O3 optimization passes (spends potentially a lot of time optimizing)
execute -O4 optimization passes (also flatten the IR, which can take a lot more time and memory, but is useful on more nested / complex / less-optimized input)
execute default optimization passes, focusing on code size
execute default optimization passes, super-focusing on code size
How much to focus on optimizing code
How much to focus on shrinking code size
Emit names section in wasm binary (or full debuginfo in wast)
Max size of functions that are always inlined (default 2, which is safe for use with -Os builds)
Max size of functions that are inlined when lightweight (no loops or function calls) when optimizing aggressively for speed (-O3). Default: 20
inlined when there is only one caller (default -1, which means all such functions are inlined)
Allow inlining functions with loops
Number of ifs allowed in partial inlining (zero means partial inlining is disabled) (default: 0)
Optimize under the helpful assumption that no surprising traps occur (from load, div/mod, etc.)
Optimize under the helpful assumption that no trap is reached at runtime (from load, div/mod, etc.)
Optimize under the helpful assumption that the low 1K of memory is not used by the application
Optimize floats without handling corner cases of NaNs and rounding
Assume that an imported memory will be zero-initialized
Skip a pass (do not run it)

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

Disable all non-MVP features
Enable all features
(deprecated - this flag does nothing)
Emit less verbose output and hide trivial warnings.
Parse wast files as Poppy IR for testing purposes.
Enable sign extension operations
Disable sign extension operations
Enable atomic operations
Disable atomic operations
Enable mutable globals
Disable mutable globals
Enable nontrapping float-to-int operations
Disable nontrapping float-to-int operations
Enable SIMD operations and types
Disable SIMD operations and types
Enable bulk memory operations
Disable bulk memory operations
Enable exception handling operations
Disable exception handling operations
Enable tail call operations
Disable tail call operations
Enable reference types
Disable reference types
Enable multivalue functions
Disable multivalue functions
Enable garbage collection
Disable garbage collection
Enable memory64
Disable memory64
Enable relaxed SIMD
Disable relaxed SIMD
Enable extended const expressions
Disable extended const expressions
Enable strings
Disable strings
Enable multimemory
Disable multimemory
Enable typed continuations
Disable typed continuations
Enable shared-everything threads
Disable shared-everything threads
Enable float 16 operations
Disable float 16 operations
Deprecated compatibility flag
Deprecated compatibility flag
Disables validation, assumes inputs are correct
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.
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 the order of types from the input (useful for debugging and testing)
generate StackIR during writing
optimize StackIR during writing
print StackIR during writing
do not use StackIR (even when it is the default)

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

Output version information and exit
Show this help message and exit
Print debug information to stderr
April 2025 wasm-metadce 120