{"id":13429088,"url":"https://github.com/WebAssembly/binaryen","last_synced_at":"2025-03-16T03:31:11.812Z","repository":{"id":37502720,"uuid":"45208608","full_name":"WebAssembly/binaryen","owner":"WebAssembly","description":"Optimizer and compiler/toolchain library for WebAssembly","archived":false,"fork":false,"pushed_at":"2025-03-14T04:20:03.000Z","size":139827,"stargazers_count":7713,"open_issues_count":455,"forks_count":760,"subscribers_count":173,"default_branch":"main","last_synced_at":"2025-03-14T18:23:17.146Z","etag":null,"topics":["c-plus-plus","compilers","emscripten","hacktoberfest","webassembly"],"latest_commit_sha":null,"homepage":"","language":"WebAssembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebAssembly.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"Contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-29T20:26:28.000Z","updated_at":"2025-03-14T11:45:55.000Z","dependencies_parsed_at":"2023-11-23T01:34:37.671Z","dependency_job_id":"c2c0f9f0-0aa7-43bc-962d-77da271d8a79","html_url":"https://github.com/WebAssembly/binaryen","commit_stats":{"total_commits":7201,"total_committers":180,"mean_commits":40.00555555555555,"dds":0.3905013192612137,"last_synced_commit":"d444abdc9fcee98715813f03e28aa7070879c414"},"previous_names":[],"tags_count":217,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fbinaryen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fbinaryen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fbinaryen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fbinaryen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebAssembly","download_url":"https://codeload.github.com/WebAssembly/binaryen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243822312,"owners_count":20353496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","compilers","emscripten","hacktoberfest","webassembly"],"created_at":"2024-07-31T02:00:24.802Z","updated_at":"2025-03-16T03:31:11.805Z","avatar_url":"https://github.com/WebAssembly.png","language":"WebAssembly","readme":"[![CI](https://github.com/WebAssembly/binaryen/actions/workflows/ci.yml/badge.svg?branch=main\u0026event=push)](https://github.com/WebAssembly/binaryen/actions/workflows/ci.yml?branch=main\u0026event=push)\n\n# Binaryen\n\nBinaryen is a compiler and toolchain infrastructure library for WebAssembly,\nwritten in C++. It aims to make [compiling to WebAssembly] **easy, fast, and\neffective**:\n\n * **Easy**: Binaryen has a simple [C API] in a single header, and can also be\n   [used from JavaScript][JS_API]. It accepts input in [WebAssembly-like\n   form][compile_to_wasm] but also accepts a general [control flow graph] for\n   compilers that prefer that.\n\n * **Fast**: Binaryen's internal IR uses compact data structures and is designed\n   for completely parallel codegen and optimization, using all available CPU\n   cores. Binaryen's IR also compiles down to WebAssembly extremely easily and\n   quickly because it is essentially a subset of WebAssembly.\n\n * **Effective**: Binaryen's optimizer has many passes (see an overview later\n   down) that can improve code size and speed. These optimizations aim to make\n   Binaryen powerful enough to be used as a [compiler backend][backend] by\n   itself. One specific area of focus is on WebAssembly-specific optimizations\n   (that general-purpose compilers might not do), which you can think of as\n   wasm [minification], similar to minification for JavaScript, CSS, etc., all\n   of which are language-specific.\n\nToolchains using Binaryen as a **component** (typically running `wasm-opt`) include:\n\n  * [`Emscripten`](http://emscripten.org) (C/C++)\n  * [`wasm-pack`](https://github.com/rustwasm/wasm-pack) (Rust)\n  * [`J2CL`](https://j2cl.io/) (Java; [`J2Wasm`](https://github.com/google/j2cl/tree/master/samples/wasm))\n  * [`Kotlin`](https://kotl.in/wasmgc) (Kotlin/Wasm)\n  * [`Dart`](https://flutter.dev/wasm) (Flutter)\n  * [`wasm_of_ocaml`](https://github.com/ocaml-wasm/wasm_of_ocaml) (OCaml)\n\nFor more on how some of those work, see the toolchain architecture parts of\nthe [V8 WasmGC porting blogpost](https://v8.dev/blog/wasm-gc-porting).\n\nCompilers using Binaryen as a **library** include:\n\n * [`AssemblyScript`](https://github.com/AssemblyScript/assemblyscript) which compiles a variant of TypeScript to WebAssembly\n * [`wasm2js`](https://github.com/WebAssembly/binaryen/blob/main/src/wasm2js.h) which compiles WebAssembly to JS\n * [`Asterius`](https://github.com/tweag/asterius) which compiles Haskell to WebAssembly\n * [`Grain`](https://github.com/grain-lang/grain) which compiles Grain to WebAssembly\n\nBinaryen also provides a set of **toolchain utilities** that can\n\n * **Parse** and **emit** WebAssembly. In particular this lets you load\n   WebAssembly, optimize it using Binaryen, and re-emit it, thus implementing a\n   wasm-to-wasm optimizer in a single command.\n * **Interpret** WebAssembly as well as run the WebAssembly spec tests.\n * Integrate with **[Emscripten](http://emscripten.org)** in order to provide a\n   complete compiler toolchain from C and C++ to WebAssembly.\n * **Polyfill** WebAssembly by running it in the interpreter compiled to\n   JavaScript, if the browser does not yet have native support (useful for\n   testing).\n\nConsult the [contributing instructions](Contributing.md) if you're interested in\nparticipating.\n\n## Binaryen IR\n\nBinaryen's internal IR is designed to be\n\n * **Flexible and fast** for optimization.\n * **As close as possible to WebAssembly** so it is simple and fast to convert\n   it to and from WebAssembly.\n\nThere are a few differences between Binaryen IR and the WebAssembly language:\n\n * Tree structure\n   * Binaryen IR [is a tree][binaryen_ir], i.e., it has hierarchical structure,\n     for convenience of optimization. This differs from the WebAssembly binary\n     format which is a stack machine.\n   * Consequently Binaryen's text format allows only s-expressions.\n     WebAssembly's official text format is primarily a linear instruction list\n     (with s-expression extensions). Binaryen can't read the linear style, but\n     it can read a wasm text file if it contains only s-expressions.\n   * Binaryen uses Stack IR to optimize \"stacky\" code (that can't be\n     represented in structured form).\n   * When stacky code must be represented in Binaryen IR, such as with\n     multivalue instructions and blocks, it is represented with tuple types that\n     do not exist in the WebAssembly language. In addition to multivalue\n     instructions, locals and globals can also have tuple types in Binaryen IR\n     but not in WebAssembly. Experiments show that better support for\n     multivalue could enable useful but small code size savings of 1-3%, so it\n     has not been worth changing the core IR structure to support it better.\n   * Block input values (currently only supported in `catch` blocks in the\n     exception handling feature) are represented as `pop` subexpressions.\n * Types and unreachable code\n   * WebAssembly limits block/if/loop types to none and the concrete value types\n     (i32, i64, f32, f64). Binaryen IR has an unreachable type, and it allows\n     block/if/loop to take it, allowing [local transforms that don't need to\n     know the global context][unreachable]. As a result, Binaryen's default\n     text output is not necessarily valid wasm text. (To get valid wasm text,\n     you can do `--generate-stack-ir --print-stack-ir`, which prints Stack IR,\n     this is guaranteed to be valid for wasm parsers.)\n   * Binaryen ignores unreachable code when reading WebAssembly binaries. That\n     means that if you read a wasm file with unreachable code, that code will be\n     discarded as if it were optimized out (often this is what you want anyhow,\n     and optimized programs have no unreachable code anyway, but if you write an\n     unoptimized file and then read it, it may look different). The reason for\n     this behavior is that unreachable code in WebAssembly has corner cases that\n     are tricky to handle in Binaryen IR (it can be very unstructured, and\n     Binaryen IR is more structured than WebAssembly as noted earlier). Note\n     that Binaryen does support unreachable code in .wat text files, since as we\n     saw Binaryen only supports s-expressions there, which are structured.\n * Blocks\n   * Binaryen IR has only one node that contains a variable-length list of\n     operands: the block. WebAssembly on the other hand allows lists in loops,\n     if arms, and the top level of a function. Binaryen's IR has a single\n     operand for all non-block nodes; this operand may of course be a block.\n     The motivation for this property is that many passes need special code\n     for iterating on lists, so having a single IR node with a list simplifies\n     them.\n   * As in wasm, blocks and loops may have names. Branch targets in the IR are\n     resolved by name (as opposed to nesting depth). This has 2 consequences:\n     * Blocks without names may not be branch targets.\n     * Names are required to be unique. (Reading .wat files with duplicate names\n       is supported; the names are modified when the IR is constructed).\n   * As an optimization, a block that is the child of a loop (or if arm, or\n     function toplevel) and which has no branches targeting it will not be\n     emitted when generating wasm. Instead its list of operands will be directly\n     used in the containing node. Such a block is sometimes called an \"implicit\n     block\".\n * Reference Types\n   * The wasm text and binary formats require that a function whose address is\n     taken by `ref.func` must be either in the table, or declared via an\n     `(elem declare func $..)`. Binaryen will emit that data when necessary, but\n     it does not represent it in IR. That is, IR can be worked on without needing\n     to think about declaring function references.\n   * Binaryen IR allows non-nullable locals in the form that the wasm spec does,\n     (which was historically nicknamed \"1a\"), in which a `local.get` must be\n     structurally dominated by a `local.set` in order to validate (that ensures\n     we do not read the default value of null). Despite being aligned with the\n     wasm spec, there are some minor details that you may notice:\n     * A nameless `Block` in Binaryen IR does not interfere with validation.\n       Nameless blocks are never emitted into the binary format (we just emit\n       their contents), so we ignore them for purposes of non-nullable locals. As\n       a result, if you read wasm text emitted by Binaryen then you may see what\n       seems to be code that should not validate per the spec (and may not\n       validate in wasm text parsers), but that difference will not exist in the\n       binary format (binaries emitted by Binaryen will always work everywhere,\n       aside for bugs of course).\n     * The Binaryen pass runner will automatically fix up validation after each\n       pass (finding things that do not validate and fixing them up, usually by\n       demoting a local to be nullable). As a result you do not need to worry\n       much about this when writing Binaryen passes. For more details see the\n       `requiresNonNullableLocalFixups()` hook in `pass.h` and the\n       `LocalStructuralDominance` class.\n   * Binaryen IR uses the most refined types possible for references,\n     specifically:\n     * The IR type of a `ref.func` is always a specific function type, and not\n       plain `funcref`. It is also non-nullable.\n     * Non-nullable types are also used for the type that `try_table` sends\n       on branches (if we branch, a null is never sent), that is, it sends\n       (ref exn) and not (ref null exn).\n     In both cases if GC is not enabled then we emit the less-refined type in the\n     binary. When reading a binary, the more refined types will be applied as we\n     build the IR.\n   * `br_if` output types are more refined in Binaryen IR: they have the type of\n     the value, when a value flows in. In the wasm spec the type is that of the\n     branch target, which may be less refined. Using the more refined type here\n     ensures that we optimize in the best way possible, using all the type\n     information, but it does mean that some roundtripping operations may look a\n     little different. In particular, when we emit a `br_if` whose type is more\n     refined in Binaryen IR then we emit a cast right after it, so that the\n     output has the right type in the wasm spec. That may cause a few bytes of\n     extra size in rare cases (we avoid this overhead in the common case where\n     the `br_if` value is unused).\n * Strings\n   * Binaryen allows string views (`stringview_wtf16` etc.) to be cast using\n     `ref.cast`. This simplifies the IR, as it allows `ref.cast` to always be\n     used in all places (and it is lowered to `ref.as_non_null` where possible\n     in the optimizer). The stringref spec does not seem to allow this though,\n     and to fix that the binary writer will replace `ref.cast` that casts a\n     string view to a non-nullable type to `ref.as_non_null`. A `ref.cast` of a\n     string view that is a no-op is skipped entirely.\n\nAs a result, you might notice that round-trip conversions (wasm =\u003e Binaryen IR\n=\u003e wasm) change code a little in some corner cases.\n\n * When optimizing Binaryen uses an additional IR, Stack IR (see\n   `src/wasm-stack.h`). Stack IR allows a bunch of optimizations that are\n   tailored for the stack machine form of WebAssembly's binary format (but Stack\n   IR is less efficient for general optimizations than the main Binaryen IR). If\n   you have a wasm file that has been particularly well-optimized, a simple\n   round-trip conversion (just read and write, without optimization) may cause\n   more noticeable differences, as Binaryen fits it into Binaryen IR's more\n   structured format. If you also optimize during the round-trip conversion then\n   Stack IR opts will be run and the final wasm will be better optimized.\n\nNotes when working with Binaryen IR:\n\n * As mentioned above, Binaryen IR has a tree structure. As a result, each\n   expression should have exactly one parent - you should not \"reuse\" a node by\n   having it appear more than once in the tree. The motivation for this\n   limitation is that when we optimize we modify nodes, so if they appear more\n   than once in the tree, a change in one place can appear in another\n   incorrectly.\n * For similar reasons, nodes should not appear in more than one functions.\n\n### Intrinsics\n\nBinaryen intrinsic functions look like calls to imports, e.g.,\n\n```wat\n(import \"binaryen-intrinsics\" \"foo\" (func $foo))\n```\n\nImplementing them that way allows them to be read and written by other tools,\nand it avoids confusing errors on a binary format error that could happen in\nthose tools if we had a custom binary format extension.\n\nAn intrinsic method may be optimized away by the optimizer. If it is not, it\nmust be **lowered** before shipping the wasm, as otherwise it will look like a\ncall to an import that does not exist (and VMs will show an error on not having\na proper value for that import). That final lowering is *not* done\nautomatically. A user of intrinsics must run the pass for that explicitly,\nbecause the tools do not know when the user intends to finish optimizing, as the\nuser may have a pipeline of multiple optimization steps, or may be doing local\nexperimentation, or fuzzing/reducing, etc. Only the user knows when the final\noptimization happens before the wasm is \"final\" and ready to be shipped. Note\nthat, in general, some additional optimizations may be possible after the final\nlowering, and so a useful pattern is to optimize once normally with intrinsics,\nthen lower them away, then optimize after that, e.g.:\n\n```bash\nwasm-opt input.wasm -o output.wasm -O --intrinsic-lowering -O\n```\n\nEach intrinsic defines its semantics, which includes what the optimizer is\nallowed to do with it and what the final lowering will turn it to. See\n[intrinsics.h](https://github.com/WebAssembly/binaryen/blob/main/src/ir/intrinsics.h)\nfor the detailed definitions. A quick summary appears here:\n\n* `call.without.effects`: Similar to a `call_ref` in that it receives\n  parameters, and a reference to a function to call, and calls that function\n  with those parameters, except that the optimizer can assume the call has no\n  side effects, and may be able to optimize it out (if it does not have a\n  result that is used, generally).\n\n## Tools\n\nThis repository contains code that builds the following tools in `bin/` (see the [building instructions](#building)):\n\n * **`wasm-opt`**: Loads WebAssembly and runs Binaryen IR passes on it.\n * **`wasm-as`**: Assembles WebAssembly in text format (currently S-Expression\n   format) into binary format (going through Binaryen IR).\n * **`wasm-dis`**: Un-assembles WebAssembly in binary format into text format\n   (going through Binaryen IR).\n * **`wasm2js`**: A WebAssembly-to-JS compiler. This is used by Emscripten to\n   generate JavaScript as an alternative to WebAssembly.\n * **`wasm-reduce`**: A testcase reducer for WebAssembly files. Given a wasm file\n   that is interesting for some reason (say, it crashes a specific VM),\n   wasm-reduce can find a smaller wasm file that has the same property, which is\n   often easier to debug. See the\n   [docs](https://github.com/WebAssembly/binaryen/wiki/Fuzzing#reducing)\n   for more details.\n * **`wasm-shell`**: A shell that can load and interpret WebAssembly code. It can\n   also run the spec test suite.\n * **`wasm-emscripten-finalize`**: Takes a wasm binary produced by llvm+lld and\n   performs emscripten-specific passes over it.\n * **`wasm-ctor-eval`**: A tool that can execute functions (or parts of functions)\n   at compile time.\n * **`wasm-merge`**: Merges multiple wasm files into a single file, connecting\n   corresponding imports to exports as it does so. Like a bundler for JS, but\n   for wasm.\n * **`wasm-metadce`**: A tool to remove parts of Wasm files in a flexible way\n   that depends on how the module is used.\n * **`binaryen.js`**: A standalone JavaScript library that exposes Binaryen methods for [creating and optimizing Wasm modules](https://github.com/WebAssembly/binaryen/blob/main/test/binaryen.js/hello-world.js). For builds, see [binaryen.js on npm](https://www.npmjs.com/package/binaryen) (or download it directly from [GitHub](https://raw.githubusercontent.com/AssemblyScript/binaryen.js/master/index.js) or [unpkg](https://unpkg.com/binaryen@latest/index.js)). Minimal requirements: Node.js v15.8 or Chrome v75 or Firefox v78.\n\nAll of the Binaryen tools are deterministic, that is, given the same inputs you should always get the same outputs. (If you see a case that behaves otherwise, please file an issue.)\n\nUsage instructions for each are below.\n\n## Binaryen Optimizations\n\nBinaryen contains\n[a lot of optimization passes](https://github.com/WebAssembly/binaryen/tree/main/src/passes)\nto make WebAssembly smaller and faster. You can run the Binaryen optimizer by\nusing ``wasm-opt``, but also they can be run while using other tools, like\n``wasm2js`` and ``wasm-metadce``.\n\n* The default optimization pipeline is set up by functions like\n  [`addDefaultFunctionOptimizationPasses`](https://github.com/WebAssembly/binaryen/blob/369b8bdd3d9d49e4d9e0edf62e14881c14d9e352/src/passes/pass.cpp#L396).\n* There are various\n  [pass options](https://github.com/WebAssembly/binaryen/blob/369b8bdd3d9d49e4d9e0edf62e14881c14d9e352/src/pass.h#L85)\n  that you can set, to adjust the optimization and shrink levels, whether to\n  ignore unlikely traps, inlining heuristics, fast-math, and so forth. See\n  ``wasm-opt --help`` for how to set them and other details.\n\nSee each optimization pass for details of what it does, but here is a quick\noverview of some of the relevant ones:\n\n* **CoalesceLocals** - Key \"register allocation\" pass. Does a live range\n  analysis and then reuses locals in order to minimize their number, as well as\n  to remove copies between them.\n* **CodeFolding** - Avoids duplicate code by merging it (e.g. if two `if` arms\n  have some shared instructions at their end).\n* **CodePushing** - \"Pushes\" code forward past branch operations, potentially\n  allowing the code to not be run if the branch is taken.\n* **DeadArgumentElimination** - LTO pass to remove arguments to a function if it\n  is always called with the same constants.\n* **DeadCodeElimination**\n* **Directize** - Turn an indirect call into a normal call, when the table index\n  is constant.\n* **DuplicateFunctionElimination** - LTO pass.\n* **Inlining** - LTO pass.\n* **LocalCSE** - Simple local common subexpression elimination.\n* **LoopInvariantCodeMotion**\n* **MemoryPacking** - Key \"optimize data segments\" pass that combines segments,\n  removes unneeded parts, etc.\n* **MergeBlocks** - Merge a `block` to an outer one where possible, reducing\n  their number.\n* **MergeLocals** - When two locals have the same value in part of their\n  overlap, pick in a way to help CoalesceLocals do better later (split off from\n  CoalesceLocals to keep the latter simple).\n* **MinifyImportsAndExports** - Minifies them to \"a\", \"b\", etc.\n* **OptimizeAddedConstants** - Optimize a load/store with an added constant into\n  a constant offset.\n* **OptimizeInstructions** - Key peephole optimization pass with a constantly\n  increasing list of patterns.\n* **PickLoadSigns** - Adjust whether a load is signed or unsigned in order to\n  avoid sign/unsign operations later.\n* **Precompute** - Calculates constant expressions at compile time, using the\n  built-in interpreter (which is guaranteed to be able to handle any constant\n  expression).\n* **ReReloop** - Transforms wasm structured control flow to a CFG and then goes\n  back to structured form using the Relooper algorithm, which may find more\n  optimal shapes.\n* **RedundantSetElimination** - Removes a `local.set` of a value that is already\n  present in a local. (Overlaps with CoalesceLocals; this achieves the specific\n  operation just mentioned without all the other work CoalesceLocals does, and\n  therefore is useful in other places in the optimization pipeline.)\n* **RemoveUnsedBrs** - Key \"minor control flow optimizations\" pass, including\n  jump threading and various transforms that can get rid of a `br` or `br_table`\n  (like turning a `block` with a `br` in the middle into an `if` when possible).\n* **RemoveUnusedModuleElements** - \"Global DCE\", an LTO pass that removes\n  imports, functions, globals, etc., when they are not used.\n* **ReorderFunctions** - Put more-called functions first, potentially allowing\n  the LEB emitted to call them to be smaller (in a very large program).\n* **ReorderLocals** - Put more-used locals first, potentially allowing the LEB\n  emitted to use them to be smaller (in a very large function). After the\n  sorting, it also removes locals not used at all.\n* **SimplifyGlobals** - Optimizes globals in various ways, for example,\n  coalescing them, removing mutability from a global never modified, applying a\n  constant value from an immutable global, etc.\n* **SimplifyLocals** - Key \"`local.get/set/tee`\" optimization pass, doing things\n  like replacing a set and a get with moving the set’s value to the get (and\n  creating a tee) where possible. Also creates `block/if/loop` return values\n  instead of using a local to pass the value.\n* **Vacuum** - Key \"remove silly unneeded code\" pass, doing things like removing\n  an `if` arm that has no contents, a drop of a constant value with no side\n  effects, a `block` with a single child, etc.\n\n\"LTO\" in the above means an optimization is Link Time Optimization-like in that\nit works across multiple functions, but in a sense Binaryen is always \"LTO\" as\nit usually is run on the final linked wasm.\n\nAdvanced optimization techniques in the Binaryen optimizer include\n[SSAification](https://github.com/WebAssembly/binaryen/blob/main/src/passes/SSAify.cpp),\n[Flat IR](https://github.com/WebAssembly/binaryen/blob/main/src/ir/flat.h), and\n[Stack/Poppy IR](https://github.com/WebAssembly/binaryen/blob/main/src/ir/stack-utils.h).\n\nSee the\n[Optimizer Cookbook wiki page](https://github.com/WebAssembly/binaryen/wiki/Optimizer-Cookbook)\nfor more on how to use the optimizer effectively.\n\nBinaryen also contains various passes that do other things than optimizations,\nlike\n[legalization for JavaScript](https://github.com/WebAssembly/binaryen/blob/main/src/passes/LegalizeJSInterface.cpp),\n[Asyncify](https://github.com/WebAssembly/binaryen/blob/main/src/passes/Asyncify.cpp),\netc.\n\n## Building\n\nBinaryen uses git submodules (at time of writing just for gtest), so before you build you will have to initialize the submodules:\n\n```bash\ngit submodule init\ngit submodule update\n```\n\nAfter that you can build with CMake:\n\n```bash\ncmake . \u0026\u0026 make\n```\n\nA C++17 compiler is required. On macOS, you need to install `cmake`, for example, via `brew install cmake`. Note that you can also use `ninja` as your generator: `cmake -G Ninja . \u0026\u0026 ninja`.\n\nTo avoid the gtest dependency, you can pass `-DBUILD_TESTS=OFF` to cmake.\n\nBinaryen.js can be built using Emscripten, which can be installed via [the SDK](http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html).\n\n- Building for Node.js:\n  ```bash\n  emcmake cmake . \u0026\u0026 emmake make binaryen_js\n  ```\n- Building for the browser:\n  ```bash\n  emcmake cmake -DBUILD_FOR_BROWSER=ON . \u0026\u0026 emmake make\n  ```\n\n### Visual C++\n\n1. Using the Microsoft Visual Studio Installer, install the \"Visual C++ tools for CMake\" component.\n\n1. Generate the projects:\n\n   ```bash\n   mkdir build\n   cd build\n   \"%VISUAL_STUDIO_ROOT%\\Common7\\IDE\\CommonExtensions\\Microsoft\\CMake\\CMake\\bin\\cmake.exe\" ..\n   ```\n\n   Substitute VISUAL_STUDIO_ROOT with the path to your Visual Studio\n   installation. In case you are using the Visual Studio Build Tools, the path\n   will be \"C:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\BuildTools\".\n\n1. From the Developer Command Prompt, build the desired projects:\n\n   ```bash\n   msbuild binaryen.vcxproj\n   ```\n\n   CMake generates a project named \"ALL_BUILD.vcxproj\" for conveniently building all the projects.\n\n## Releases\n\nBuilds are distributed by the various toolchains that use Binaryen, like\nEmscripten, `wasm-pack`, etc. There are also official releases on GitHub:\n\nhttps://github.com/WebAssembly/binaryen/releases\n\nCurrently builds of the following platforms are included:\n\n * `Linux-x86_64`\n * `Linux-arm64`\n * `MacOS-x86_64`\n * `MacOS-arm64`\n * `Windows-x86_64`\n * `Node.js` (experimental): A port of `wasm-opt` to JavaScript+WebAssembly.\n   Run `node wasm-opt.js` as a drop-in replacement for a native build of\n   `wasm-opt`, on any platform that Node.js runs on. Requires Node.js 18+ (for\n   Wasm EH and Wasm Threads). (Note that this build may also run in Deno, Bun,\n   or other JavaScript+WebAssembly environments, but is tested only on Node.js.)\n\n## Running\n\n### wasm-opt\n\nRun\n\n```bash\nbin/wasm-opt [.wasm or .wat file] [options] [passes, see --help] [--help]\n```\n\nThe wasm optimizer receives WebAssembly as input, and can run transformation\npasses on it, as well as print it (before and/or after the transformations). For\nexample, try\n\n```bash\nbin/wasm-opt test/lit/passes/name-types.wast -all -S -o -\n```\n\nThat will output one of the test cases in the test suite. To run a\ntransformation pass on it, try\n\n```bash\nbin/wasm-opt test/lit/passes/name-types.wast --name-types -all -S -o -\n```\n\nThe `name-types` pass ensures each type has a name and renames exceptionally long type names. You can see\nthe change the transformation causes by comparing the output of the two commands.\n\nIt's easy to add your own transformation passes to the shell, just add `.cpp`\nfiles into `src/passes`, and rebuild the shell. For example code, take a look at\nthe [`name-types` pass](https://github.com/WebAssembly/binaryen/blob/main/src/passes/NameTypes.cpp).\n\nSome more notes:\n\n * See `bin/wasm-opt --help` for the full list of options and passes.\n * Passing `--debug` will emit some debugging info. Individual debug channels\n   (defined in the source code via `#define DEBUG_TYPE xxx`) can be enabled by\n   passing them as list of comma-separated strings. For example: `bin/wasm-opt\n   --debug=binary`. These debug channels can also be enabled via the\n   `BINARYEN_DEBUG` environment variable.\n\n### wasm2js\n\nRun\n\n```bash\nbin/wasm2js [input.wasm file]\n```\n\nThis will print out JavaScript to the console.\n\nFor example, try\n\n```bash\nbin/wasm2js test/hello_world.wat\n```\n\nThat output contains\n\n```js\n function add(x, y) {\n  x = x | 0;\n  y = y | 0;\n  return x + y | 0 | 0;\n }\n```\n\nas a translation of\n\n```wat\n (func $add (; 0 ;) (type $0) (param $x i32) (param $y i32) (result i32)\n  (i32.add\n   (local.get $x)\n   (local.get $y)\n  )\n )\n```\n\nwasm2js's output is in ES6 module format - basically, it converts a wasm\nmodule into an ES6 module (to run on older browsers and Node.js versions\nyou can use Babel etc. to convert it to ES5). Let's look at a full example\nof calling that hello world wat; first, create the main JS file:\n\n```js\n// main.mjs\nimport { add } from \"./hello_world.mjs\";\nconsole.log('the sum of 1 and 2 is:', add(1, 2));\n```\n\nThe run this (note that you need a new enough Node.js with ES6 module\nsupport):\n\n```bash\n$ bin/wasm2js test/hello_world.wat -o hello_world.mjs\n$ node --experimental-modules main.mjs\nthe sum of 1 and 2 is: 3\n```\n\nThings keep to in mind with wasm2js's output:\n\n * You should run wasm2js with optimizations for release builds, using `-O`\n   or another optimization level. That will optimize along the entire pipeline\n   (wasm and JS). It won't do everything a JS minifer would, though, like\n   minify whitespace, so you should still run a normal JS minifer afterwards.\n * It is not possible to match WebAssembly semantics 100% precisely with fast\n   JavaScript code. For example, every load and store may trap, and to make\n   JavaScript do the same we'd need to add checks everywhere, which would be\n   large and slow. Instead, wasm2js assumes loads and stores do not trap, that\n   int/float conversions do not trap, and so forth. There may also be slight\n   differences in corner cases of conversions, like non-trapping float to int.\n\n### wasm-ctor-eval\n\n`wasm-ctor-eval` executes functions, or parts of them, at compile time.\nAfter doing so it serializes the runtime state into the wasm, which is like\ntaking a \"snapshot\". When the wasm is later loaded and run in a VM, it will\ncontinue execution from that point, without re-doing the work that was already\nexecuted.\n\nFor example, consider this small program:\n\n```wat\n(module\n ;; A global variable that begins at 0.\n (global $global (mut i32) (i32.const 0))\n\n (import \"import\" \"import\" (func $import))\n\n (func \"main\"\n  ;; Set the global to 1.\n  (global.set $global\n   (i32.const 1))\n\n  ;; Call the imported function. This *cannot* be executed at\n  ;; compile time.\n  (call $import)\n\n  ;; We will never get to this point, since we stop at the\n  ;; import.\n  (global.set $global\n   (i32.const 2))\n )\n)\n```\n\nWe can evaluate part of it at compile time like this:\n\n```bash\nwasm-ctor-eval input.wat --ctors=main -S -o -\n```\n\nThis tells it that there is a single function that we want to execute (\"ctor\"\nis short for \"global constructor\", a name that comes from code that is executed\nbefore a program's entry point) and then to print it as text to `stdout`. The\nresult is this:\n\n```bash\ntrying to eval main\n  ...partial evalling successful, but stopping since could not eval: call import: import.import\n  ...stopping\n(module\n (type $none_=\u003e_none (func))\n (import \"import\" \"import\" (func $import))\n (global $global (mut i32) (i32.const 1))\n (export \"main\" (func $0_0))\n (func $0_0\n  (call $import)\n  (global.set $global\n   (i32.const 2)\n  )\n )\n)\n```\n\nThe logging shows us managing to eval part of `main()`, but not all of it, as\nexpected: We can eval the first `global.get`, but then we stop at the call to\nthe imported function (because we don't know what that function will be when the\nwasm is actually run in a VM later). Note how in the output wasm the global's\nvalue has been updated from 0 to 1, and that the first `global.get` has been\nremoved: the wasm is now in a state that, when we run it in a VM, will seamlessly\ncontinue to run from the point at which `wasm-ctor-eval` stopped.\n\nIn this tiny example we just saved a small amount of work. How much work can be\nsaved depends on your program. (It can help to do pure computation up front, and\nleave calls to imports to as late as possible.)\n\nNote that `wasm-ctor-eval`'s name is related to global constructor functions,\nas mentioned earlier, but there is no limitation on what you can execute here.\nAny export from the wasm can be executed, if its contents are suitable. For\nexample, in Emscripten `wasm-ctor-eval` is even run on `main()` when possible.\n\n### wasm-merge\n\n`wasm-merge` combines wasm files together. For example, imagine you have a\nproject that uses wasm files from multiple toolchains. Then it can be helpful to\nmerge them all into a single wasm file before shipping, since in a single wasm\nfile the calls between the modules become just normal calls inside a module,\nwhich allows them to be inlined, dead code eliminated, and so forth, potentially\nimproving speed and size.\n\n`wasm-merge` operates on normal wasm files. It differs from `wasm-ld` in that\nrespect, as `wasm-ld` operates on wasm *object* files. `wasm-merge` can help\nin multi-toolchain situations where at least one of the toolchains does not use\nwasm object files.\n\nFor example, imagine we have these two wasm files:\n\n```wat\n;; a.wasm\n(module\n  (import \"second\" \"bar\" (func $second.bar))\n\n  (export \"main\" (func $func))\n\n  (func $func\n    (call $second.bar)\n  )\n)\n```\n\n```wat\n;; b.wasm\n(module\n  (import \"outside\" \"log\" (func $log (param i32)))\n\n  (export \"bar\" (func $func))\n\n  (func $func\n    (call $log\n      (i32.const 42)\n    )\n  )\n)\n```\n\nThe filenames on your local drive are `a.wasm` and `b.wasm`, but for merging /\nbundling purposes let's say that the first is known as `\"first\"` and the second\nas `\"second\"`. That is, we want the first module's import of `\"second.bar\"` to\ncall the function `$func` in the second module. Here is a wasm-merge command for\nthat:\n\n```bash\nwasm-merge a.wasm first b.wasm second -o output.wasm\n```\n\nWe give it the first wasm file, then its name, and then the second wasm file\nand then its name. The merged output is this:\n\n```wat\n(module\n  (import \"outside\" \"log\" (func $log (param i32)))\n\n  (export \"main\" (func $func))\n  (export \"bar\" (func $func_2))\n\n  (func $func\n    (call $func_2)\n  )\n\n  (func $func_2\n    (call $log\n      (i32.const 42)\n    )\n  )\n)\n```\n\n`wasm-merge` combined the two files into one, merging their functions, imports,\netc., all while fixing up name conflicts and connecting corresponding imports to\nexports. In particular, note how `$func` calls `$func_2`, which is exactly what\nwe wanted: `$func_2` is the function from the second module (renamed to avoid a\nname collision).\n\nNote that the wasm output in this example could benefit from additional\noptimization. First, the call to `$func_2` can now be easily inlined, so we can\nrun `wasm-opt -O3` to do that for us. Also, we may not need all the imports and\nexports, for which we can run\n[wasm-metadce](https://github.com/WebAssembly/binaryen/wiki/Pruning-unneeded-code-in-wasm-files-with-wasm-metadce#example-pruning-exports).\nA good workflow could be to run `wasm-merge`, then `wasm-metadce`, then finish\nwith `wasm-opt`.\n\n`wasm-merge` is kind of like a bundler for wasm files, in the sense of a \"JS\nbundler\" but for wasm. That is, with the wasm files above, imagine that we had\nthis JS code to instantiate and connect them at runtime:\n\n```js\n// Compile the first module.\nvar first = await fetch(\"a.wasm\");\nfirst = new WebAssembly.Module(first);\n\n// Compile the first module.\nvar second = await fetch(\"b.wasm\");\nsecond = new WebAssembly.Module(second);\n\n// Instantiate the second, with a JS import.\nsecond = new WebAssembly.Instance(second, {\n  outside: {\n    log: (value) =\u003e {\n      console.log('value:', value);\n    }\n  }\n});\n\n// Instantiate the first, importing from the second.\nfirst = new WebAssembly.Instance(first, {\n  second: second.exports\n});\n\n// Call the main function.\nfirst.exports.main();\n```\n\nWhat `wasm-merge` does is basically what that JS does: it hooks up imports to\nexports, resolving names using the module names you provided. That is, by\nrunning `wasm-merge` we are moving the work of connecting the modules from\nruntime to compile time. As a result, after running `wasm-merge` we need a lot\nless JS to get the same result:\n\n```js\n// Compile the single module.\nvar merged = await fetch(\"merged.wasm\");\nmerged = new WebAssembly.Module(merged);\n\n// Instantiate it with a JS import.\nmerged = new WebAssembly.Instance(merged, {\n  outside: {\n    log: (value) =\u003e {\n      console.log('value:', value);\n    }\n  }\n});\n\n// Call the main function.\nmerged.exports.main();\n```\n\nWe still need to fetch and compile the merged wasm, and to provide it the JS\nimport, but the work to connect two wasm modules is not needed any more.\n\n#### Handling exports\n\nBy default `wasm-merge` errors if there are overlapping export names. That is,\n`wasm-merge` will automatically handle overlapping function names and so forth,\nbecause those are not externally visible (the code still behaves the same), but\nif we renamed exports then the outside would need to be modified to expect the\nnew export names, and so we error instead on such name conflicts.\n\nIf you do want exports to be renamed, run `wasm-merge` with\n`--rename-export-conflicts`. Later exports will have a suffix appended to them\nto ensure they do not overlap with previous exports. The suffixes are\ndeterministic, so once you see what they are you can call them from the outside.\n\nAnother option is to use `--skip-export-conflicts` which will simply skip later\nexports that have conflicting names. For example, this can be useful in the\ncase where the first module is the only one that interacts with the outside and\nthe later modules just interact with the first module.\n\n#### Features\n\n`wasm-merge` uses the multi-memory and multi-table features. That is, if\nmultiple input modules each have a memory then the output wasm will have several\nmemories, and will depend on the multi-memory feature, which means that older\nwasm VMs might not be able to run the wasm. (As a workaround for such older VMs\nyou can run `wasm-opt --multi-memory-lowering` to lower multiple memories into a\nsingle one.)\n\n## Testing\n\n```bash\n./check.py\n```\n\n(or `python check.py`) will run `wasm-shell`, `wasm-opt`, etc. on the testcases in `test/`, and verify their outputs.\n\nThe `check.py` script supports some options:\n\n```bash\n./check.py [--interpreter=/path/to/interpreter] [TEST1] [TEST2]..\n```\n\n * If an interpreter is provided, we run the output through it, checking for\n   parse errors.\n * If tests are provided, we run exactly those. If none are provided, we run\n   them all. To see what tests are available, run `./check.py --list-suites`.\n * Some tests require `emcc` or `nodejs` in the path. They will not run if the\n   tool cannot be found, and you'll see a warning.\n * We have tests from upstream in `tests/spec`, in git submodules. Running\n   `./check.py` should update those.\n\nNote that we are trying to gradually port the legacy wasm-opt tests to use `lit`\nand `filecheck` as we modify them. For `passes` tests that output wast, this\ncan be done automatically with `scripts/port_passes_tests_to_lit.py` and for\nnon-`passes` tests that output wast, see\nhttps://github.com/WebAssembly/binaryen/pull/4779 for an example of how to do a\nsimple manual port.\n\nFor lit tests the test expectations (the CHECK lines) can often be automatically\nupdated as changes are made to binaryen. See `scripts/update_lit_checks.py`.\n\nNon-lit tests can also be automatically updated in most cases. See\n`scripts/auto_update_tests.py`.\n\n### Setting up dependencies\n\n```bash\n./third_party/setup.py [mozjs|v8|wabt|all]\n```\n\n(or `python third_party/setup.py`) installs required dependencies like the SpiderMonkey JS shell, the V8 JS shell\nand WABT in `third_party/`. Other scripts automatically pick these up when installed.\n\nRun `pip3 install -r requirements-dev.txt` to get the requirements for the `lit`\ntests. Note that you need to have the location `pip` installs to in your `$PATH`\n(on linux, `~/.local/bin`).\n\n### Fuzzing\n\n```bash\n./scripts/fuzz_opt.py [--binaryen-bin=build/bin]\n```\n\n(or `python scripts/fuzz_opt.py`) will run various fuzzing modes on random inputs with random passes until it finds\na possible bug. See [the wiki page](https://github.com/WebAssembly/binaryen/wiki/Fuzzing) for all the details.\n\n## Design Principles\n\n * **Interned strings for names**: It's very convenient to have names on nodes,\n   instead of just numeric indices etc. To avoid most of the performance\n   difference between strings and numeric indices, all strings are interned,\n   which means there is a single copy of each string in memory, string\n   comparisons are just a pointer comparison, etc.\n * **Allocate in arenas**: Based on experience with other\n   optimizing/transformating toolchains, it's not worth the overhead to\n   carefully track memory of individual nodes. Instead, we allocate all elements\n   of a module in an arena, and the entire arena can be freed when the module is\n   no longer needed.\n\n## Debug Info Support\n\n### Source Maps\n\nBinaryen can read and write source maps (see the `-ism` and `-osm` flags to\n`wasm-opt`). It can also read and read source map annotations in the text\nformat, that is,\n\n```wat\n;;@ src.cpp:100:33\n(i32.const 42)\n```\n\nThat 42 constant is annotated as appearing in a file called `src.cpp` at line\n`100` and column `33`. Source maps and text format annotations are\ninterchangeable, that is, they both lead to the same IR representation, so you\ncan start with an annotated wat and have Binaryen write that to a binary + a\nsource map file, or read a binary + source map file and print text which will\ncontain those annotations.\n\nThe IR representation of source map info is simple: in each function we have a\nmap of expressions to their locations. Optimization passes should update the\nmap as relevant. Often this \"just works\" because the optimizer tries to reuse\nnodes when possible, so they keep the same debug info.\n\n#### Shorthand notation\n\nThe text format annotations support a shorthand in which repeated annotations\nare not necessary. For example, children are tagged with the debug info of the\nparent, if they have no annotation of their own:\n\n```wat\n;;@ src.cpp:100:33\n(i32.add\n  (i32.const 41)      ;; This receives an annotation of src.cpp:100:33\n  ;;@ src.cpp:111:44\n  (i32.const 1)\n)\n```\n\nThe first const will have debug info identical to the parent, because it has\nnone specified, and generally such nesting indicates a \"bundle\" of instructions\nthat all implement the same source code.\n\nNote that text printing will not emit such repeated annotations, which can be\nconfusing. To print out all the annotations, set `BINARYEN_PRINT_FULL=1` in the\nenvironment. That will print this for the above `add`:\n\n```wat\n[i32] ;;@ src.cpp:100:33\n(i32.add\n [i32] ;;@ src.cpp:100:33\n (i32.const 41)\n [i32] ;;@ src.cpp:111:44\n (i32.const 1)\n)\n```\n\n(full print mode also adds a `[type]` for each expression, right before the\ndebug location).\n\nThe debug information is also propagated from an expression to its\nnext sibling:\n```wat\n;;@ src.cpp:100:33\n(local.set $x\n (i32.const 0)\n)\n(local.set $y ;; This receives an annotation of src.cpp:100:33\n (i32.const 0)\n)\n```\n\nYou can prevent the propagation of debug info by explicitly mentioning\nthat an expression has not debug info using the annotation `;;@` with\nnothing else:\n```wat\n;;@ src.cpp:100:33\n(local.set $x\n ;;@\n (i32.const 0) ;; This does not receive any annotation\n)\n;;@\n(local.set $y ;; This does not receive any annotation\n (i32.const 7)\n)\n```\nThis stops the propagatation to children and siblings as well. So,\nexpression `(i32.const 7)` does not have any debug info either.\n\nThere is no shorthand in the binary format. That is, roundtripping (writing and\nreading) through a binary + source map should not change which expressions have\ndebug info on them or the contents of that info.\n\n#### Implementation Details\n\nThe [source maps format](https://sourcemaps.info/spec.html) defines a mapping\nusing *segments*, that is, if a segment starts at binary offset 10 then it\napplies to all instructions at that offset and until another segment begins (or\nthe end of the input is reached). Binaryen's IR represents a mapping from\nexpressions to locations, as mentioned, so we need to map to and from the\nsegment-based format when writing and reading source maps.\n\nThat is mostly straightforward, but one thing we need to do is to handle the\nlack of debug info in between things that have it. If we have `A B C` where `B`\nlacks debug info, then just emitting a segment for `A` and `C` would lead `A`'s\nsegment to also cover `B`, since in source maps segments do not have a size -\nrather they end when a new segment begins. To avoid `B` getting smeared in this\nmanner, we emit a source maps entry to `B` of size 1, which just marks the\nbinary offset it has, and without the later 3 fields of the source file, line\nnumber, and column. (This appears to be the intent of the source maps spec, and\nworks in browsers and tools.)\n\n### DWARF\n\nBinaryen also has optional support for DWARF. This primarily just tracks the\nlocations of expressions and rewrites the DWARF's locations accordingly; it does\nnot handle things like re-indexing of locals, and so passes that might break\nDWARF are disabled by default. As a result, this mode is not suitable for a\nfully optimized release build, but it can be useful for local debugging.\n\n## FAQ\n\n* Why the weird name for the project?\n\nBinaryen's name was inspired by *Emscripten*'s: Emscripten's name\n[suggests](https://en.wikipedia.org/wiki/Lisa_the_Iconoclast#Embiggen_and_cromulent)\nit converts something into a **script** - specifically *JavaScript* - and\nBinaryen's suggests it converts something into a **binary** - specifically\n*WebAssembly*. Binaryen began as Emscripten's WebAssembly generation and\noptimization tool, so the name fit as it moved Emscripten from something that\nemitted the text-based format JavaScript (as it did from its early days) to the\nbinary format WebAssembly (which it has done since WebAssembly launched).\n\n\"Binaryen\" is pronounced [in the same manner](https://www.makinggameofthrones.com/production-diary/2011/2/11/official-pronunciation-guide-for-game-of-thrones.html#:~:text=Targaryen%20%2D%20AIR%2Deez-,Tar%2DGAIR%2Dee%2Din,-Alliser%20Thorne%20%2D%20AL)\nas\n\"[Targaryen](https://en.wikipedia.org/wiki/List_of_A_Song_of_Ice_and_Fire_characters#House_Targaryen)\".\n\n* Does it compile under Windows and/or Visual Studio?\n\nYes, it does. Here's a step-by-step [tutorial][win32] on how to compile it\nunder **Windows 10 x64** with with **CMake** and **Visual Studio 2015**.\nHowever, Visual Studio 2017 may now be required. Help would be appreciated on\nWindows and OS X as most of the core devs are on Linux.\n\n[compiling to WebAssembly]: https://github.com/WebAssembly/binaryen/wiki/Compiling-to-WebAssembly-with-Binaryen\n[win32]: https://github.com/brakmic/bazaar/blob/master/webassembly/COMPILING_WIN32.md\n[C API]: https://github.com/WebAssembly/binaryen/wiki/Compiling-to-WebAssembly-with-Binaryen#c-api\n[control flow graph]: https://github.com/WebAssembly/binaryen/wiki/Compiling-to-WebAssembly-with-Binaryen#cfg-api\n[JS_API]: https://github.com/WebAssembly/binaryen/wiki/binaryen.js-API\n[compile_to_wasm]: https://github.com/WebAssembly/binaryen/wiki/Compiling-to-WebAssembly-with-Binaryen#what-do-i-need-to-have-in-order-to-use-binaryen-to-compile-to-webassembly\n[backend]: https://kripken.github.io/talks/binaryen.html#/9\n[minification]: https://kripken.github.io/talks/binaryen.html#/2\n[unreachable]: https://github.com/WebAssembly/binaryen/issues/903\n[binaryen_ir]: https://github.com/WebAssembly/binaryen/issues/663\n","funding_links":[],"categories":["Web","WebAssembly","TypeScript to WASM","Compilers","Misc","Manipulating (optimization, transformation, instrumentation)","Projects","c-plus-plus","Development Tools","Tools","Tool","编译工具","Tooling"],"sub_categories":["Availability \u0026 compatability","Compilers","Polyfilling WebAssembly","Mesh networks","Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebAssembly%2Fbinaryen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWebAssembly%2Fbinaryen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebAssembly%2Fbinaryen/lists"}