# webassembly/binaryen architecture

> Architecture diagram of the GitHub repository webassembly/binaryen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/webassembly/binaryen
- Repository: https://github.com/webassembly/binaryen

## Overview

##### Project Type and Purpose
- Binaryen is a C++ compiler‐infrastructure library and toolchain for WebAssembly.
- It provides:
- A core IR (intermediate representation) & optimizer (many passes)
- A set of CLI tools (wasm-opt, wasm-as, wasm-dis, wasm2js, wasm-merge, etc.)
- C API header, JavaScript API (binaryen.js)
- Testing & fuzzing harness (check.py, lit, Python scripts)

##### High‐Level Architectural Layers
- Presentation / Interfaces (CLI & APIs)
– bin/ executables (wasm-opt, wasm-as, wasm-dis, wasm2js, wasm-shell, etc.)
– C API header: src/binaryen-c.h
– JavaScript API: src/js, templates, binaryen.js on npm
- Core Library
– IR definition & data structures (src/ir, src/wasm/*.h)
– Analysis & optimization passes (src/analysis, src/passes)
– Stack IR & flat IR (src/wasm-stack.h, src/ir/flat.h)
– Pass manager & utilities (src/pass.h, src/support, src/compiler-support.h)
- Backends / Code Generators
– WebAssembly emitter (src/wasm/wasm-binary.cpp, wasm-validator.cpp, wasm-io.cpp)
– JS emitter for wasm2js (src/wasm2js.h, src/js/binaryen.js-post.js, templates)
- Frontends / Parsers
– .wat / .wast parser (src/parser/*.cpp)
– CFG API (analysis/cfg.cpp)
- Testing & Tooling
– Tests: test/ (unit, integration, spec tests, lit runner)
– Fuzzing: scripts/fuzz_opt.py, scripts/clusterfuzz
– Build scripts: CMakeLists.txt, scripts/auto_update_tests.py

##### Main Components & Their Relationships
- CLI Tools (bin/wasm-opt, wasm-as, wasm-dis, wasm2js, etc.)
↓ invoke
- Core Library
- Parser → produces AST/IR
- IR (Tree IR + Stack IR)
- Analysis modules (dataflow, CFG, lattices)
- Pass Manager → sequences optimization/transformation passes
- Pass modules (CoalesceLocals, DeadCodeElimination, ReReloop, etc.)
- Code Generators
– Wasm binary writer
– JS emitter (wasm2js)
- C API & JS API wrapper around library
- Support utilities (command-line parsing, file I/O, JSON, threading)
- Third‐Party Submodules
- googletest (unit tests)
- LLVM components (DWARF parsing, LEB128, etc.)
- WABT, SpiderMonkey, V8 for test shells
↓ used by
- Testing & Fuzzing Harness
- check.py / Python scripts → orchestrate CLI tools + interpreters
- lit (LLVM Integrated Tester) suites
- clusterfuzz / fuzz-opt

##### Architectural Patterns & Principles
- Layered architecture: CLI → Library → IR → Codegen
- Modular pass framework: Pass Manager + plug-in style passes
- Arena allocation & interned strings (support/utilities)
- Extensions via submodules (LLVM, WABT, fuzztest)

##### Essential Elements to Capture
- Parser (src/parser)
- IR definitions (src/ir, src/wasm)
- Analysis & Dataflow (src/analysis, src/dataflow)
- Pass Manager & Pass modules (src/pass.h, src/passes)
- Code generators (Wasm binary, wasm2js)
- CLI tools (wasm-opt, wasm-as, wasm-dis, wasm2js, wasm-merge, wasm-shell, wasm-ctor-eval, etc.)
- C API & JS API layers
- Support utilities (src/support)
- Testing & fuzzing harness and third-party submodules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation / Interfaces
    subgraph "Presentation / Interfaces"
        direction TB
        CLI["CLI Tools"]:::frontend
        CAPI["C API (src/binaryen-c.h)"]:::frontend
        JSAPI["JS API (binaryen.js)"]:::frontend
    end

    %% Frontends / Parsers
    subgraph "Frontends / Parsers"
        direction TB
        Parser["Parser"]:::parser
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        IR["IR Definitions & Data Structures"]:::core
        Analysis["Analysis & Dataflow"]:::core
        PassMgr["Pass Manager"]:::core
        Passes["Pass Modules"]:::core
        Support["Support Utilities"]:::core
    end

    %% Backends / Code Generators
    subgraph "Backends / Code Generators"
        direction TB
        WASMGen["Wasm Binary Writer"]:::backend
        JSGen["JS Emitter (wasm2js)"]:::backend
    end

    %% Testing & Fuzzing
    subgraph "Testing & Fuzzing"
        direction TB
        TestHarness["Testing Harness & Fuzzing"]:::test
        ThirdParty["Third-Party Submodules"]:::test
    end

    %% Connections
    CLI -->|"invoke"| Parser
    CLI -->|"invoke"| IR
    CAPI -->|"wraps library"| IR
    JSAPI -->|"wraps library"| IR
    Parser -->|"produces IR"| IR
    IR -->|"used by"| Analysis
    Analysis -->|"coordinate passes"| PassMgr
    PassMgr -->|"runs"| Passes
    Passes -->|"generate binary"| WASMGen
    Passes -->|"generate JS"| JSGen
    Support --> Parser
    Support --> IR
    Support --> Analysis
    Support --> PassMgr
    IR --> ThirdParty
    Analysis --> ThirdParty
    TestHarness -->|"tests"| CLI
    TestHarness -->|"tests"| JSAPI

    %% Legend
    subgraph Legend
        direction LR
        F["CLI / API"]:::frontend
        C["Core Library"]:::core
        P["Parser"]:::parser
        B["Codegen"]:::backend
        T["Testing / Third-Party"]:::test
    end

    %% Click Events
    click CLI "https://github.com/webassembly/binaryen/tree/main/src/tools"
    click CAPI "https://github.com/webassembly/binaryen/blob/main/src/binaryen-c.h"
    click JSAPI "https://github.com/webassembly/binaryen/blob/main/src/js/binaryen.js-post.js"
    click Parser "https://github.com/webassembly/binaryen/tree/main/src/parser"
    click IR "https://github.com/webassembly/binaryen/tree/main/src/ir"
    click Analysis "https://github.com/webassembly/binaryen/tree/main/src/analysis"
    click PassMgr "https://github.com/webassembly/binaryen/blob/main/src/pass.h"
    click WASMGen "https://github.com/webassembly/binaryen/blob/main/src/wasm/wasm-binary.cpp"
    click Support "https://github.com/webassembly/binaryen/tree/main/src/support"
    click TestHarness "https://github.com/webassembly/binaryen/blob/main/check.py"

    %% Styles
    classDef frontend fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    classDef core fill:#bbdefb,stroke:#1565c0,stroke-width:2px
    classDef parser fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px
    classDef backend fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px
    classDef test fill:#eeeeee,stroke:#424242,stroke-width:2px
```
