WASM-METADCE(1)

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

DESCRIPTION
================================================================================ 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,-o
    Output file

--input-source-map,-ism
    Consume source map from the specified file

--output-source-map,-osm
    Emit source map to the specified file

--output-source-map-url,-osu
    Emit specified string as source map URL

--emit-text,-S
    Emit text instead of binary for the output file

--debuginfo,-g
    Emit names section and debug info

--graph-file,-f
    Filename of the graph description file

--dump,-d
    Dump the combined graph file (useful for debugging)

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

--abstract-type-refining
    refine and merge abstract (never-created) types

--alignment-lowering
    lower unaligned loads and stores to smaller aligned ones

--asyncify
    async/await style transform, allowing pausing and resuming

--avoid-reinterprets
    Tries to avoid reinterpret operations via more loads

--cfp
    propagate constant struct field values

--cfp-reftest
    propagate constant struct field values, using ref.test

--coalesce-locals
    reduce # of locals by coalescing

--coalesce-locals-learning
    reduce # of locals by coalescing and learning

--code-folding
    fold code, merging duplicates

--code-pushing
    push code forward, potentially making it not always execute

--const-hoisting
    hoist repeated constants to a local

--dae
    removes arguments to calls in an lto-like manner

--dae-optimizing
    removes arguments to calls in an lto-like manner, and optimizes where we removed

--dae2
    Experimental reimplementation of DAE

--dce
    removes unreachable code

--dealign
    forces all loads and stores to have alignment 1

--denan
    instrument the wasm to convert NaNs into 0 at runtime

--dfo
    optimizes using the DataFlow SSA IR

--directize
    turns indirect calls into direct ones

--discard-global-effects
    discards global effect info

--duplicate-function-elimination
    removes duplicate functions

--duplicate-import-elimination
    removes duplicate imports

--dwarfdump
    dump DWARF debug info sections from the read binary

--emit-target-features
    emit the target features section in the output

--enclose-world
    modify the wasm (destructively) for closed-world

--extract-function
    leaves just one function (useful for debugging)

--extract-function-index
    leaves just one function selected by index

--flatten
    flattens out code, removing nesting

--fpcast-emu
    emulates function pointer casts, allowing incorrect indirect calls to (sometimes) work

--func-metrics
    reports function metrics

--generate-dyncalls
    generate dynCall functions used by emscripten ABI

--generate-global-effects
    generate global effect info (helps later passes)

--generate-i64-dyncalls
    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).

--global-refining
    refine the types of globals

--gsi
    globally optimize struct values

--gsi-desc-cast
    globally optimize struct values, also emitting ref.cast_desc_eq

--gto
    globally optimize GC types

--gufa
    Grand Unified Flow Analysis: optimize the entire program using information about what content can actually appear in each location

--gufa-cast-all
    GUFA plus add casts for all inferences

--gufa-optimizing
    GUFA plus local optimizations in functions we modified

--heap-store-optimization
    optimize heap (GC) stores

--heap2local
    replace GC allocations with locals

--i64-to-i32-lowering
    lower all uses of i64s to use i32s instead

--inline-main
    inline __original_main into main

--inlining
    inline functions (you probably want inlining-optimizing)

--inlining-optimizing
    inline functions and optimizes where we inlined

--instrument-branch-hints
    instrument branch hints so we can see which guessed right

--instrument-locals
    instrument the build with code to intercept all loads and stores

--instrument-memory
    instrument the build with code to intercept all loads and stores

--intrinsic-lowering
    lower away binaryen intrinsics

--legalize-and-prune-js-interface
    legalizes the import/export boundary and prunes when needed

--legalize-js-interface
    legalizes i64 types on the import/export boundary

--licm
    loop invariant code motion

--limit-segments
    attempt to merge segments to fit within web limits

--llvm-memory-copy-fill-lowering
    Lower memory.copy and memory.fill to wasm mvp and disable the bulk-memory feature.

--llvm-nontrapping-fptoint-lowering
    lower nontrapping float-to-int operations to wasm mvp and disable the nontrapping fptoint feature

--local-cse
    common subexpression elimination inside basic blocks

--local-subtyping
    apply more specific subtypes to locals where possible

--log-execution
    instrument the build with logging of where execution goes

--mark-js-called
    mark js called functions (using configureAll) as doing so

--memory-packing
    packs memory into separate segments, skipping zeros

--memory64-lowering
    lower loads and stores to a 64-bit memory to instead use a 32-bit one

--merge-blocks
    merges blocks to their parents

--merge-j2cl-itables
    Merges itable structures into vtables to make types more compact

--merge-locals
    merges locals when beneficial

--merge-similar-functions
    merges similar functions when benefical

--metrics
    reports metrics (with an optional title, --metrics[=TITLE])

--minify-imports
    minifies import names (only those, and not export names), and emits a mapping to the minified ones

--minify-imports-and-exports
    minifies both import and export names, and emits a mapping to the minified ones

--minify-imports-and-exports-and-modules
    minifies both import and export names, and emits a mapping to the minified ones, and minifies the modules as well

--minimize-rec-groups
    Split types into minimal recursion groups

--monomorphize
    creates specialized versions of functions

--monomorphize-always
    creates specialized versions of functions (even if unhelpful)

--multi-memory-lowering
    combines multiple memories into a single memory

--multi-memory-lowering-with-bounds-checks
    combines multiple memories into a single memory, trapping if the read or write is larger than the length of the memory's data

--name-types
    (re)name all heap types

--nm
    name list

--no-full-inline
    mark functions as no-inline (for full inlining only)

--no-inline
    mark functions as no-inline

--no-partial-inline
    mark functions as no-inline (for partial inlining only)

--once-reduction
    reduces calls to code that only runs once

--optimize-added-constants
    optimizes added constants into load/store offsets

--optimize-added-constants-propagate
    optimizes added constants into load/store offsets, propagating them across locals too

--optimize-casts
    eliminate and reuse casts

--optimize-for-js
    early optimize of the instruction combinations for js

--optimize-instructions
    optimizes instruction combinations

--optimize-j2cl
    optimizes J2CL specific constructs.

--outlining
    outline instructions

--pick-load-signs
    pick load signs based on their uses

--poppify
    Transform Binaryen IR into Poppy IR

--post-emscripten
    miscellaneous optimizations for Emscripten-generated code

--precompute
    computes compile-time evaluatable expressions

--precompute-propagate
    computes compile-time evaluatable expressions and propagates them through locals

--print
    print in s-expression format

--print-boundary
    print boundary in JSON format

--print-call-graph
    print call graph

--print-features
    print options for enabled features

--print-full
    print in full s-expression format

--print-function-map
    print a map of function indexes to names

--print-minified
    print in minified s-expression format

--propagate-debug-locs
    propagate debug location from parents or previous siblings to child nodes

--propagate-globals-globally
    propagate global values to other globals (useful for tests)

--remove-exports
    removes exports using a wildcard

--remove-imports
    removes imports and replaces them with nops

--remove-memory
    removes memory init (legacy name)

--remove-memory-init
    removes memory initialization

--remove-non-js-ops
    removes operations incompatible with js

--remove-relaxed-simd
    replaces relaxed SIMD instructions with unreachable

--remove-unused-brs
    removes breaks from locations that are not needed

--remove-unused-module-elements
    removes unused module elements

--remove-unused-names
    removes names from locations that are never branched to

--remove-unused-nonfunction-module-elements
    removes unused module elements that are not functions

--remove-unused-types
    remove unused private GC types

--reorder-functions
    sorts functions by access frequency

--reorder-functions-by-name
    sorts functions by name (useful for debugging)

--reorder-globals
    sorts globals by access frequency

--reorder-locals
    sorts locals by access frequency

--reorder-types
    sorts private types by access frequency

--rereloop
    re-optimize control flow using the relooper algorithm

--roundtrip
    write the module to binary, then read it

--rse
    remove redundant local.sets

--safe-heap
    instrument loads and stores to check for invalid behavior

--separate-data-segments
    write data segments to a file and strip them from the module

--set-globals
    sets specified globals to specified values

--signature-pruning
    remove params from function signature types where possible

--signature-refining
    apply more specific subtypes to signature types where possible

--signext-lowering
    lower sign-ext operations to wasm mvp and disable the sign extension feature

--simplify-globals
    miscellaneous globals-related optimizations

--simplify-globals-optimizing
    miscellaneous globals-related optimizations, and optimizes where we replaced global.gets with constants

--simplify-locals
    miscellaneous locals-related optimizations

--simplify-locals-nonesting
    miscellaneous locals-related optimizations (no nesting at all; preserves flatness)

--simplify-locals-nostructure
    miscellaneous locals-related optimizations (no structure)

--simplify-locals-notee
    miscellaneous locals-related optimizations (no tees)

--simplify-locals-notee-nostructure
    miscellaneous locals-related optimizations (no tees or structure)

--souperify
    emit Souper IR in text form

--souperify-single-use
    emit Souper IR in text form (single-use nodes only)

--spill-pointers
    spill pointers to the C stack (useful for Boehm-style GC)

--ssa
    ssa-ify variables so that they have a single assignment

--ssa-nomerge
    ssa-ify variables so that they have a single assignment, ignoring merges

--stack-check
    enforce limits on llvm's __stack_pointer global

--string-gathering
    gathers wasm strings to globals

--string-lifting
    lift string imports to wasm strings

--string-lowering
    lowers wasm strings and operations to imports

--string-lowering-magic-imports
    same as string-lowering, but encodes well-formed strings as magic imports

--string-lowering-magic-imports-assert
    same as string-lowering-magic-imports, but raise a fatal error if there are invalid strings

--strip
    deprecated; same as strip-debug

--strip-debug
    strip debug info (including the names section)

--strip-dwarf
    strip dwarf debug info

--strip-eh
    strip EH instructions

--strip-producers
    strip the wasm producers section

--strip-target-features
    strip the wasm target features section

--strip-toolchain-annotations
    strip all toolchain-specific code annotations

--stub-unsupported-js
    stub out unsupported JS operations

--symbolmap
    (alias for print-function-map)

--table64-lowering
    alias for memory64-lowering

--trace-calls
    instrument the build with code to intercept specific function calls

--translate-to-exnref
    translate old Phase 3 EH instructions to new ones with exnref

--translate-to-new-eh
    deprecated; same as translate-to-exnref

--trap-mode-clamp
    replace trapping operations with clamping semantics

--trap-mode-js
    replace trapping operations with js semantics

--tuple-optimization
    optimize trivial tuples away

--type-finalizing
    mark all leaf types as final

--type-merging
    merge types to their supertypes where possible

--type-refining
    apply more specific subtypes to type fields where possible

--type-refining-gufa
    apply more specific subtypes to type fields where possible (using GUFA)

--type-ssa
    create new types to help other optimizations

--type-unfinalizing
    mark all types as non-final (open)

--unsubtyping
    removes unnecessary subtyping relationships

--untee
    removes local.tees, replacing them with sets and gets

--vacuum
    removes obviously unneeded code

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

-O  execute default optimization passes (equivalent to -Os)

-O0 execute no optimization passes

-O1 execute -O1 optimization passes (quick&useful opts, useful for iteration builds)

-O2 execute -O2 optimization passes (most opts, generally gets most perf)

-O3 execute -O3 optimization passes (spends potentially a lot of time optimizing)

-O4 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)

-Os execute default optimization passes, focusing on code size

-Oz execute default optimization passes, super-focusing on code size

--optimize-level,-ol
    How much to focus on optimizing code

--shrink-level,-s
    How much to focus on shrinking code size

--debuginfo,-g
    Emit names section in wasm binary (or full debuginfo in wast)

--always-inline-max-function-size,-aimfs
    Max size of functions that are always inlined (default 2, which is safe for use with -Os builds)

--flexible-inline-max-function-size,-fimfs
    Max size of functions that are inlined when lightweight (no loops or function calls) when optimizing aggressively for speed (-O3). Default: 20

--one-caller-inline-max-function-size,-ocimfs Max size of functions that are
    inlined when there is only one caller (default -1, which means all such functions are inlined)

--inline-max-combined-binary-size,-imcbs
    Max size of combined functions after inlining. Default: 409600

--inline-functions-with-loops,-ifwl
    Allow inlining functions with loops

--partial-inlining-ifs,-pii
    Number of ifs allowed in partial inlining (zero means partial inlining is disabled) (default: 0)

--ignore-implicit-traps,-iit
    Optimize under the helpful assumption that no surprising traps occur (from load, div/mod, etc.)

--traps-never-happen,-tnh
    Optimize under the helpful assumption that no trap is reached at runtime (from load, div/mod, etc.)

--low-memory-unused,-lmu
    Optimize under the helpful assumption that the low 1K of memory is not used by the application

--fast-math,-ffm
    Optimize floats without handling corner cases of NaNs and rounding

--zero-filled-memory,-uim
    Assume that an imported memory will be zero-initialized

--skip-pass,-sp
    Skip a pass (do not run it)

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.

--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-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

--no-stack-ir
    do not use StackIR (even when it is the default)

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

--version
    Output version information and exit

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

--debug,-d
    Print debug information to stderr