WASM-TOOLS(1)

📦 version 1.239.0, in ubuntu stonking

🌈 WASM-TOOLS(1) 🌈

User Commands · manual section 1 · the wasm-tools manual

okay so you opened the WASM-TOOLS(1) page from the User Commands manual and bestie, it is long. Buckle in, we're doing the whole thing, no skips. 💖

✨ NAME ✨

wasm-tools smith — a WebAssembly test case generator. That's the whole name, she does exactly what it says on the tin. 💅

🦋 SYNOPSIS 🦋

wasm-tools smith [OPTIONS] [INPUT]

💜 DESCRIPTION 💜

A WebAssembly test case generator. Periodt.

So here's the vibe: you hand wasm-smith an arbitrary input seed, and she generates a valid WebAssembly module for you. That seed gets read as a whole series of predetermined choices, like walking down a decision tree. And the icon behavior: give her the same input seed and she'll always generate the same output WebAssembly module — she is deterministic, fr fr. Bigger input seeds tend to generate bigger WebAssembly modules. And tiny little changes to the input seed tend to produce a tiny little change to the output module too.

Put all those properties together and wasm-smith isn't just for purely random input seeds — she's also perfect with coverage-guided, mutation-based fuzzing engines like libFuzzer and AFL. Obsessed, honestly. 🔥

🎀 Example 🎀

Generate a WebAssembly module from 100 bytes of random data:

$ head -c 100 /dev/urandom | wasm-smith -o test.wasm

🔥 Exit Codes 🔥

  • 0: Success. 🫶
  • 1: An unexpected failure occurred. 😭
  • 2: Failed to generate a WebAssembly module from the input seed. (Happens rarely; try again with a new input.) 💀

🫶 Arguments 🫶

  • [INPUT] — the arbitrary input seed. If you don't supply this argument, stdin is used instead.

👑 OPTIONS 👑

  • -o, --output <OUTPUT> — where to place the output. If you don't provide one, then stdout is used.
  • -t, --wat — output the text format of WebAssembly instead of the binary format.
  • --ensure-termination — make sure execution of generated Wasm modules will always terminate. This inserts a global "fuel" counter that gets decremented at loop headers and in function prologues. When the fuel reaches 0, a trap is raised to terminate execution. You control the default amount of fuel with the --fuel flag.
heads up bestie: when this is combined with --allow-invalid-funcs, this subcommand may return an error, because arbitrary function bodies taken from input bytes cannot be validated to ensure they always terminate. no cap.
  • -f, --fuel <FUEL> — the default amount of fuel used with --ensure-termination. This is roughly the number of loop iterations and function calls that will be executed before a trap is raised to prevent infinite loops.
  • -c, --config <CONFIG> — JSON configuration file with settings to control the wasm output.
  • --available-imports <AVAILABLE_IMPORTS> — the imports that may be used when generating the module. When unspecified, any arbitrary import can be generated. To only allow specific imports, provide a file path of a WebAssembly module which describes the imports allowed. Note that Self::min_imports is ignored when available_imports are enabled. The provided value must be a valid binary encoding of a WebAssembly module. wasm-smith will panic if the module cannot be parsed. 💀
  • --exports <EXPORTS> — if provided, the generated module will have exports with exactly the same names and types as those in the provided WebAssembly module. The implementation (e.g. function bodies, global initializers) of each export in the generated module will be random and unrelated to the implementation in the provided module. Defaults to None, which means arbitrary exports will be generated. To specify which exports the generated modules should have, set this field to a WebAssembly module which describes the desired exports. To generate modules with varying exports that meet some constraints, consider randomly generating the value for this field. The provided value must be a valid binary encoding of a WebAssembly module. wasm-smith will panic if the module cannot be parsed. Module Limits All types, functions, globals, memories, tables, tags, and exports that are needed to provide the required exports will be generated, even if it causes the resulting module to exceed the limits defined in Self::max_type_size, Self::max_types, Self::max_funcs, Self::max_globals, Self::max_memories, Self::max_tables, Self::max_tags, or Self::max_exports. (yes, she will absolutely blow past your limits for this, and that's on purpose ✨)
  • --module-shape <MODULE_SHAPE> — if provided, the generated module will have imports and exports with exactly the same names and types as those in the provided WebAssembly module. Defaults to None, which means arbitrary imports and exports will be generated. Note that Self::available_imports and Self::exports are ignored when module_shape is enabled. The provided value must be a valid binary encoding of a WebAssembly module. wasm-smith will panic if the module cannot be parsed. Module Limits All types, functions, globals, memories, tables, tags, imports, and exports that are needed to provide the required imports and exports will be generated, even if it causes the resulting module to exceed the limits defined in Self::max_type_size, Self::max_types, Self::max_funcs, Self::max_globals, Self::max_memories, Self::max_tables, Self::max_tags, Self::max_imports, or Self::max_exports.
  • --allow-start-export <ALLOW_START_EXPORT> — determines whether a start export may be included. Defaults to true. [possible values: true, false]
  • --allowed-instructions <ALLOWED_INSTRUCTIONS> — the kinds of instructions allowed in the generated wasm programs. Defaults to all. The categories of instructions match the categories used by the WebAssembly specification (https://webassembly.github.io/spec/core/syntax/instructions.html); e.g., numeric, vector, control, memory, etc. Additionally, we include finer-grained categories which exclude floating point instructions, e.g. InstructionKind::NumericInt is a subset of InstructionKind::Numeric consisting of all numeric instructions which don't involve floats. Note that modifying this setting is separate from the proposal flags; that is, if simd_enabled() == true but allowed_instruction() does not include vector instructions, the generated programs will not include these instructions but could contain vector types.
[`InstructionKind::Numeric`]: crate::InstructionKind::Numeric
[`InstructionKind::NumericInt`]: crate::InstructionKind::NumericInt
  • --allow-floats <ALLOW_FLOATS> — determines whether we generate floating point instructions and types. Defaults to true. [possible values: true, false]
  • --bulk-memory-enabled <BULK_MEMORY_ENABLED> — determines whether the bulk memory proposal is enabled for generating instructions. Defaults to true. [possible values: true, false]
  • --canonicalize-nans <CANONICALIZE_NANS> — returns whether NaN values are canonicalized after all f32/f64 operations. Defaults to false. This can be useful when a generated wasm module is executed in multiple runtimes which may produce different NaN values. This ensures that the generated module will always use the same NaN representation for all instructions which have visible side effects, for example writing floats to memory or float-to-int bitcast instructions. [possible values: true, false]
  • --disallow-traps <DISALLOW_TRAPS> — returns whether we should avoid generating code that will possibly trap. For some trapping instructions, this will emit extra instructions to ensure they don't trap, while some instructions will simply be excluded. In cases where we would run into a trap, we instead choose some arbitrary non-trapping behavior. For example, if we detect that a Load instruction would attempt to access out-of-bounds memory, we instead pretend the load succeeded and push 0 onto the stack. One type of trap that we can't currently avoid is StackOverflow. Even when disallow_traps is set to true, wasm-smith will eventually generate a program that infinitely recurses, causing the call stack to be exhausted. Defaults to false. [possible values: true, false]
  • --exceptions-enabled <EXCEPTIONS_ENABLED> — determines whether the exception-handling proposal is enabled for generating instructions. Defaults to true. [possible values: true, false]
  • --export-everything <EXPORT_EVERYTHING> — export all WebAssembly objects in the module. Defaults to false. This overrides Config::min_exports and Config::max_exports. [possible values: true, false]
  • --gc-enabled <GC_ENABLED> — determines whether the GC proposal is enabled when generating a Wasm module. Defaults to true. [possible values: true, false]
  • --custom-page-sizes-enabled <CUSTOM_PAGE_SIZES_ENABLED> — determines whether the custom-page-sizes proposal is enabled when generating a Wasm module. Defaults to false. [possible values: true, false]
  • --generate-custom-sections <GENERATE_CUSTOM_SECTIONS> — returns whether we should generate custom sections or not. Defaults to false. [possible values: true, false]
  • --max-aliases <MAX_ALIASES> — returns the maximal size of the alias section. Defaults to 1000.
  • --max-components <MAX_COMPONENTS> — the maximum number of components to use. Defaults to 10. This includes imported components. Note that this is only relevant for components.
  • --max-data-segments <MAX_DATA_SEGMENTS> — the maximum number of data segments to generate. Defaults to 100.
  • --max-element-segments <MAX_ELEMENT_SEGMENTS> — the maximum number of element segments to generate. Defaults to 100.
  • --max-elements <MAX_ELEMENTS> — the maximum number of elements within a segment to generate. Defaults to 100.
  • --max-exports <MAX_EXPORTS> — the maximum number of exports to generate. Defaults to 100.
  • --max-funcs <MAX_FUNCS> — the maximum number of functions to generate. Defaults to 100. This includes imported functions.
  • --max-globals <MAX_GLOBALS>
  • (tail end of the bullet just above, the globals one) — the maximum number of globals to generate. Defaults to 100. And yes, this includes imported globals 🫶
  • --max-imports <MAX_IMPORTS> — the maximum number of imports to generate. Defaults to 100 ✨
  • --max-instances <MAX_INSTANCES> — the maximum number of instances to use. Defaults to 10.
    • This includes imported instances.
    • Note that this is only relevant for components 🧩
  • --max-instructions <MAX_INSTRUCTIONS> — the maximum number of instructions to generate in a function body. Defaults to 100.
    • Note that some additional ends, elses, and unreachables may be appended to the function body to finish block scopes. it's giving "cleanup crew" 😌
  • --max-memories <MAX_MEMORIES> — the maximum number of memories to use. Defaults to 1.
    • This includes imported memories.
    • Note that more than one memory is in the realm of the multi-memory wasm proposal 🔥
  • --max-memory32-bytes <MAX_MEMORY32_BYTES> — the maximum, in bytes, of any 32-bit memory's initial or maximum size.
    • May not be larger than 2**32.
    • Defaults to 2**32.
  • --max-memory64-bytes <MAX_MEMORY64_BYTES> — the maximum, in bytes, of any 64-bit memory's initial or maximum size.
    • May not be larger than 2**64.
    • Defaults to 2**64.
  • --max-modules <MAX_MODULES> — the maximum number of modules to use. Defaults to 10.
    • This includes imported modules.
    • Note that this is only relevant for components 💅
  • --max-nesting-depth <MAX_NESTING_DEPTH> — returns the maximal nesting depth of modules with the component model proposal. Defaults to 10 🪆
  • --max-table-elements <MAX_TABLE_ELEMENTS> — the maximum, elements, of any table's initial or maximum size. Defaults to 1 million 👑
  • --max-tables <MAX_TABLES> — the maximum number of tables to use. Defaults to 1.
    • This includes imported tables.
    • Note that more than one table is in the realm of the reference types proposal ⭐
  • --max-tags <MAX_TAGS> — the maximum number of tags to generate. Defaults to 100 🏷️
  • --max-type-size <MAX_TYPE_SIZE> — returns the maximal effective size of any type generated by wasm-smith.
    • Note that this number is roughly in units of "how many types would be needed to represent the recursive type". A function with 8 parameters and 2 results would take 11 types (one for the type, 10 for params/results). A module type with 2 imports and 3 exports would take 6 (module + imports + exports) plus the size of each import/export type. This is a somewhat rough measurement that is not intended to be very precise. fr fr, it's vibes-based math bestie 😭
    • Defaults to 1000.
  • --max-types <MAX_TYPES> — the maximum number of types to generate. Defaults to 100 💖
  • --max-values <MAX_VALUES> — the maximum number of values to use. Defaults to 10.
    • This includes imported values.
    • Note that this is irrelevant unless value model support is enabled. 🙈
  • --memory64-enabled <MEMORY64_ENABLED> — returns whether 64-bit memories are allowed. Defaults to true.
    • Note that this is the gate for the memory64 proposal to WebAssembly.
    • possible values: true, false
  • --memory-max-size-required <MEMORY_MAX_SIZE_REQUIRED> — whether every Wasm memory must have a maximum size specified. Defaults to false.
    • possible values: true, false
  • --memory-offset-choices <MEMORY_OFFSET_CHOICES> — control the probability of generating memory offsets that are in bounds vs. potentially out of bounds. chaos dial, we love her 🎛️
    • See the MemoryOffsetChoices struct for details.
  • --min-data-segments <MIN_DATA_SEGMENTS> — the minimum number of data segments to generate. Defaults to 0 🍓
  • --min-element-segments <MIN_ELEMENT_SEGMENTS> — the minimum number of element segments to generate. Defaults to 0 🌸
  • --min-elements <MIN_ELEMENTS> — the minimum number of elements within a segment to generate. Defaults to 0 ✨
  • --min-exports <MIN_EXPORTS> — the minimum number of exports to generate. Defaults to 0 📤
  • --min-funcs <MIN_FUNCS> — the minimum number of functions to generate. Defaults to 0.
    • This includes imported functions.
  • --min-globals <MIN_GLOBALS> — the minimum number of globals to generate. Defaults to 0.
    • This includes imported globals.
  • --min-imports <MIN_IMPORTS> — the minimum number of imports to generate. Defaults to 0.
    • Note that if the sum of the maximum function[^1], table, global and memory counts is less than the minimum number of imports, then it will not be possible to satisfy all constraints (because imports count against the limits for those element kinds). In that case, we strictly follow the max-constraints, and can fail to satisfy this minimum number. so yeah, sometimes you literally cannot have it all 💀
[^1]: the maximum number of functions is also limited by the number of function types arbitrarily chosen; strictly speaking, then, the maximum number of imports that can be created due to max-constraints is sum(min(num_func_types, max_funcs), max_tables, max_globals, max_memories).
  • --min-memories <MIN_MEMORIES> — the minimum number of memories to use. Defaults to 0.
    • This includes imported memories.
  • --min-tables <MIN_TABLES> — the minimum number of tables to use. Defaults to 0.
    • This includes imported tables.
  • --min-tags <MIN_TAGS> — the minimum number of tags to generate. Defaults to 0 🏷️
  • --min-types <MIN_TYPES> — the minimum number of types to generate. Defaults to 0 🌈
  • --min-uleb-size <MIN_ULEB_SIZE> — the minimum size, in bytes, of all leb-encoded integers. Defaults to 1.
    • This is useful for ensuring that all leb-encoded integers are decoded as such rather than as simply one byte. This will forcibly extend leb integers with an over-long encoding in some locations if the size would otherwise be smaller than number returned here. padding, but make it unhinged 💅
  • --multi-value-enabled <MULTI_VALUE_ENABLED> — determines whether the multi-value results are enabled.
    • Defaults to true.
    • possible values: true, false
  • --reference-types-enabled <REFERENCE_TYPES_ENABLED> — determines whether the reference types proposal is enabled for generating instructions.
    • Defaults to true.
    • possible values: true, false
  • --relaxed-simd-enabled <RELAXED_SIMD_ENABLED> — determines whether the Relaxed SIMD proposal is enabled for generating instructions.
    • Defaults to true.
    • possible values: true, false
  • --saturating-float-to-int-enabled <SATURATING_FLOAT_TO_INT_ENABLED> — determines whether the non-trapping float-to-int conversions proposal is enabled.
    • Defaults to true.
    • possible values: true, false
  • --sign-extension-ops-enabled <SIGN_EXTENSION_OPS_ENABLED> — determines whether the sign-extension-ops proposal is enabled.
    • Defaults to true.
    • possible values: true, false
  • --shared-everything-threads-enabled <SHARED_EVERYTHING_THREADS_ENABLED> — determines whether the shared-everything-threads proposal is enabled.
  • --simd-enabled <SIMD_ENABLED> — determines whether the SIMD proposal is enabled for generating instructions.
    • Defaults to true.
    • possible values: true, false
  • --tail-call-enabled <TAIL_CALL_ENABLED> — determines whether the tail calls proposal is enabled for generating instructions.
    • Defaults to true.
    • possible values: true, false
  • --table-max-size-required <TABLE_MAX_SIZE_REQUIRED> — whether every Wasm table must have a maximum size specified. Defaults to false.
    • possible values: true, false
  • --threads-enabled <THREADS_ENABLED> — determines whether the threads proposal is enabled.
  • --allow-invalid-funcs <ALLOW_INVALID_FUNCS> — indicates whether wasm-smith is allowed to generate invalid function bodies.
    • When enabled this option will enable taking raw bytes from the input byte stream and using them as a wasm function body. This means that the output module is not guaranteed to be valid but can help tickle various parts of validation/compilation in some circumstances as well. not valid, on purpose, for science 😭
    • Defaults to false.
    • possible values: true, false
  • --wide-arithmetic-enabled <WIDE_ARITHMETIC_ENABLED> — determines whether the [wide-arithmetic proposal] is enabled.
  • --extended-const-enabled <EXTENDED_CONST_ENABLED> — determines whether the [extended-const proposal] is enabled.
  • -v, --verbose... — use verbose output (-v info, -vv debug, -vvv trace). stack those v's like a queen 👑
  • --color <COLOR> — configuration over whether terminal colors are used in output.
    • Supports one of auto|never|always|always-ansi. The default is to detect what to do based on the terminal environment, for example by using isatty. 🌈
    • default: auto
  • -h, --help — print help (see a summary with -h) 🎀

okay bestie that's the whole vibe 💜 this page is from wasm-tools smith, version 1.239.0+ds, dated August 2026 — go forth and generate some wasm, you absolute icon 🦋✨

📦 where this page comes from