WASM-SPLIT(1)

📦
version 131 · 3 versions
, in ubuntu stonking

🎀 NAME 🎀

wasm-split — Split a module into a primary module and a secondary module, or instrument a 💅

✨ DESCRIPTION ✨

================================================================================
wasm-split INFILES
================================================================================

okay so bestie, here's the tea ☕: wasm-split can split a module into a primary module and a secondary module, or instrument a module to gather a profile that can inform future splitting, or manage such profiles. Options that are only accepted in particular modes are marked with the accepted "[<modes>]" in their descriptions. periodt. 🫶

💖 wasm-split options 💖

  • --split — Split an input module into two output modules. The default mode. 👑
  • --multi-split — Split an input module into an arbitrary number of output modules. she can do multiples, no cap 💅
  • --instrument — Instrument an input module to allow it to generate a profile that can be used to guide splitting. 📊
  • --merge-profiles — Merge multiple profiles for the same module into a single profile. glow-up but for profile data 🧚
  • --print-profile — [print-profile] Print profile contents in a human-readable format. make it make sense, bestie 📝
  • --profile — [split] The profile to use to guide splitting. 🗺️
  • --keep-funcs — [split] Comma-separated list of functions to keep in the primary module. The rest will be split out. Can be used alongside --profile and --split-funcs. You can also pass a file with one function per line by passing @filename. 🌸
  • --split-funcs — [split] Comma-separated list of functions to split out to the secondary module. The rest will be kept. Can be used alongside --profile and --keep-funcs. This takes precedence over other split options. You can also pass a file with one function per line by passing @filename. she's the boss of split options, fr fr 🔥
  • --manifest — [multi-split] File describing the functions to be split into each module. Each section separated by a blank line begins with the base name of an output module, which is followed by a list of functions to place in that module, one per line. 📜
  • --out-prefix — [multi-split] Prefix prepended to module names in the manifest file to create output file names. prepend era 🌈
  • --primary-output,-o1 — [split] Output file for the primary module. 💖
  • --secondary-output,-o2 — [split] Output file for the secondary module. 💜
  • --symbolmap — [split, multi-split] Write a symbol map file for each of the output modules. 🗂️
  • --no-placeholders — [split, multi-split] Do not import placeholder functions. Calls to secondary functions will fail before the secondary module has been instantiated. so dramatic, but also literally true 😭
  • --placeholdermap — [split, multi-split] Write a file mapping placeholder indices to the function names. 🧾
  • --import-namespace — [split, multi-split, instrument] When provided as an option for module splitting, the namespace from which to import objects from the primary module into the secondary module. In instrument mode, refers to the namespace from which to import the secondary memory, if any. 🌐
  • --placeholder-namespace-prefix — [split, multi-split] The prefix for the namespaces from which to import placeholder functions into the primary module. The namespaces will be concatenations of the prefix and the module name. 🧩
  • --placeholder-namespace — [split, multi-split] The same as --placeholder-namespace-prefix. twins 👯
  • --export-prefix — [split, multi-split] An identifying prefix to prepend to new export names created by module splitting. 🏷️
  • --profile-export — [instrument] The export name of the function the embedder calls to write the profile into memory. Defaults to __write_profile. 💾
  • --in-memory — [instrument] Store profile information in memory (starting at address 0 and taking one byte per function) rather than globals (the default) so that it can be shared between multiple threads. Users are responsible for ensuring that the module does not use the initial memory region for anything else. you better not touch that memory, bestie 🙈
  • --in-secondary-memory — [instrument] Store profile information in a separate memory, rather than in module main memory or globals (the default). With this option, users do not need to reserve the initial memory region for profile data and the data can be shared between multiple threads. 🌊
  • --secondary-memory-name — [instrument] The name of the secondary memory created to store profile information. 📛
  • --initial-table — [split, instrument] A hack to ensure the split and instrumented modules have the same table size when using Emscripten's SPLIT_MODULE mode with dynamic linking. TODO: Figure out a more elegant solution for that use case and remove this. it's giving temporary, your honor 💀
  • --emit-text,-S — [split, multi-split, instrument] Emit text instead of binary for the output file or files. 📄
  • --debuginfo,-g — [split, multi-split, instrument] Emit names section in wasm binary (or full debuginfo in wast). 🔍
  • --strip-debug — [split, multi-split, instrument] Strip debug info (including the names section). ✂️
  • --traps-never-happen,-tnh — [split, multi-split] Split under the helpful assumption that no trap is reached at runtime (from load, div/mod, etc.). optimistic queen 🌈
  • --output,-o — [instrument, merge-profiles, multi-split] Output file. 📁
  • --verbose,-v — Verbose output mode. Prints the functions that will be kept and split out when splitting a module. spill the tea about every function ☕

🛠️ Tool options 🛠️

  • --mvp-features,-mvp — Disable all non-MVP features. 🚫
  • --all-features,-all — Enable all features. all of them?? iconic 🌟
  • --detect-features — (deprecated - this flag does nothing). not me showing up to do absolutely 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. old news, bestie 💀
  • --disable-typed-function-references — Deprecated compatibility flag. 💀
  • --no-validation,-n — Disables validation, assumes inputs are correct. living dangerously, no cap 😳
  • --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 — okay so this one tells wasm-split to assume that whatever code lives outside the module is not out here spying on or messing with GC references and function references, even if those get passed out. 💅 The outside world can hold onto them and hand them back to you later, but bestie it is not allowed to inspect their contents and it is not allowed to call them. That's the whole vibe.
  • --preserve-type-order — keeps the order of types from the input exactly as-is, no reshuffling, nothing moved. useful for debugging and testing bestie, iykyk 🧚
  • --generate-stack-ir — generates StackIR during writing ✨
  • --optimize-stack-ir — optimizes StackIR during writing 🔥
  • --print-stack-ir — prints StackIR during writing 👑

🌈 General options 🌈

like the lil home base of flags, fr fr 🫶

  • --version — outputs version information and then dips out, exit stage left. that's it, that's the whole thing.
  • --help, -h — shows this help message (yes, this one, the very thing you're reading rn 💖) and exits.
  • --debug, -d — prints debug information to stderr. not stdout, bestie — stderr. important distinction, no cap.
seriously tho — when a flag says it exits, it exits. it won't stick around and do the rest of your command. main character behaviour only. 💀

and that's a wrap on this page 🎀 it came to you from wasm-split 131, dated August 2026 — so if you're reading this from the future, hiii, hope the flags still slay 💜🦋

📦 where this page comes from