{"id":44397253,"url":"https://github.com/clojurewasm/zwasm","last_synced_at":"2026-04-21T13:05:27.878Z","repository":{"id":337811092,"uuid":"1154193071","full_name":"clojurewasm/zwasm","owner":"clojurewasm","description":"A fast, spec-compliant WebAssembly runtime written in Zig","archived":false,"fork":false,"pushed_at":"2026-03-31T06:26:49.000Z","size":4775,"stargazers_count":132,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-31T07:44:23.024Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clojurewasm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"chaploud"}},"created_at":"2026-02-10T05:34:06.000Z","updated_at":"2026-03-31T06:26:52.000Z","dependencies_parsed_at":"2026-02-27T03:02:46.864Z","dependency_job_id":"479e6d7e-8f54-4657-9335-ba1f80e70dee","html_url":"https://github.com/clojurewasm/zwasm","commit_stats":null,"previous_names":["clojurewasm/zwasm"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/clojurewasm/zwasm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojurewasm%2Fzwasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojurewasm%2Fzwasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojurewasm%2Fzwasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojurewasm%2Fzwasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clojurewasm","download_url":"https://codeload.github.com/clojurewasm/zwasm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clojurewasm%2Fzwasm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-02-12T05:23:23.184Z","updated_at":"2026-04-01T23:18:40.420Z","avatar_url":"https://github.com/clojurewasm.png","language":"Zig","funding_links":["https://github.com/sponsors/chaploud"],"categories":["Zig","Tools"],"sub_categories":["Host Runtimes"],"readme":"# zwasm\n\n[![CI](https://github.com/clojurewasm/zwasm/actions/workflows/ci.yml/badge.svg)](https://github.com/clojurewasm/zwasm/actions/workflows/ci.yml)\n[![Spec Tests](https://img.shields.io/badge/spec_tests-62%2C263%2F62%2C263-brightgreen)](https://github.com/clojurewasm/zwasm)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/chaploud?logo=githubsponsors\u0026logoColor=white\u0026color=ea4aaa)](https://github.com/sponsors/chaploud)\n\nA small, fast WebAssembly runtime written in Zig. Library and CLI.\n\nSupported host targets:\n- `aarch64-macos`\n- `x86_64-linux`\n- `aarch64-linux`\n- `x86_64-windows`\n\n## Why zwasm\n\nMost Wasm runtimes are either fast but large (wasmtime ~56MB) or small but slow (wasm3 ~0.3MB, interpreter only). zwasm targets the gap between them: **~1.2MB with ARM64 + x86_64 JIT compilation**, including SIMD.\n\n| Runtime  | Binary  | Memory | JIT                          |\n|----------|--------:|-------:|------------------------------|\n| zwasm    | 1.2MB   | ~3.5MB | ARM64 + x86_64 (incl. SIMD)  |\n| wasmtime | 56MB    | ~12MB  | Cranelift                    |\n| wasm3    | 0.3MB   | ~1MB   | None                         |\n\nzwasm was extracted from [ClojureWasm](https://github.com/clojurewasm/ClojureWasm) (a Zig reimplementation of Clojure) where optimizing a Wasm subsystem inside a language runtime created a \"runtime within runtime\" problem. Separating it produced a cleaner codebase, independent optimization, and a reusable library. ClojureWasm remains the primary consumer.\n\n## Features\n\n- **581+ opcodes**: Full MVP + SIMD (236 + 20 relaxed) + Exception handling + Function references + GC + Threads (79 atomics)\n- **4-tier execution**: bytecode \u003e predecoded IR \u003e register IR \u003e ARM64/x86_64 JIT (NEON/SSE SIMD)\n- **100% spec conformance**: 62,263/62,263 spec tests, 792/792 E2E tests, 50 real-world programs (macOS + Linux + Windows x86_64 CI)\n- **All Wasm 3.0 proposals**: See [Spec Coverage](#wasm-spec-coverage) below\n- **Component Model**: WIT parser, Canonical ABI, component linking, WASI P2 adapter\n- **WAT support**: `zwasm file.wat`, build-time optional (`-Dwat=false`)\n- **WASI Preview 1 + 2**: 46/46 P1 syscalls (100%), P2 via component adapter\n- **Threads**: Shared memory, 79 atomic operations (load/store/RMW/cmpxchg), wait/notify\n- **Security**: Deny-by-default WASI, capability flags, resource limits\n- **Zero dependencies**: Pure Zig, no libc required\n- **Allocator-parameterized**: Caller controls memory allocation\n\n## Wasm Spec Coverage\n\nAll ratified Wasm proposals through 3.0 are implemented.\n\n| Spec     | Proposals                                                                         | Status       |\n|----------|-----------------------------------------------------------------------------------|--------------|\n| Wasm 1.0 | MVP (172 opcodes)                                                                | Complete     |\n| Wasm 2.0 | Sign extension, Non-trapping f-\u003ei, Bulk memory, Reference types, Multi-value, Fixed-width SIMD (236) | All complete |\n| Wasm 3.0 | Memory64, Exception handling, Tail calls, Extended const, Branch hinting, Multi-memory, Relaxed SIMD (20), Function references, GC (31) | All complete |\n| Phase 3  | Wide arithmetic (4), Custom page sizes                                           | Complete     |\n| Phase 4  | Threads (79 atomics)                                                             | Complete     |\n| Layer    | Component Model (WIT, Canon ABI, WASI P2)                                       | Complete     |\n\n18/18 proposals complete. 521 unit tests, 792/792 E2E tests, 50 real-world compatibility tests.\n\n## Performance\n\nBenchmarked on Apple M4 Pro against wasmtime 41.0.1 (Cranelift JIT).\n16 of 29 benchmarks match or beat wasmtime. 25/29 within 1.5x.\nMemory usage 3-4x lower than wasmtime, 8-10x lower than Bun/Node.\n\n| Benchmark       | zwasm  | wasmtime | Bun    | Node   |\n|-----------------|-------:|---------:|-------:|-------:|\n| nqueens(8)      | 2ms    | 5ms      | 14ms   | 23ms   |\n| nbody(1M)       | 22ms   | 22ms     | 32ms   | 36ms   |\n| gcd(12K,67K)    | 2ms    | 5ms      | 14ms   | 23ms   |\n| sieve(1M)       | 5ms    | 7ms      | 17ms   | 29ms   |\n| tak(24,16,8)    | 5ms    | 9ms      | 17ms   | 29ms   |\n| fib(35)         | 46ms   | 51ms     | 36ms   | 52ms   |\n| st_fib2         | 900ms  | 674ms    | 353ms  | 389ms  |\n\nFull results (29 benchmarks): `bench/runtime_comparison.yaml`\n\nSIMD benchmarks (ARM64 NEON / x86_64 SSE JIT):\n\n| Benchmark              | zwasm scalar | zwasm SIMD | wasmtime SIMD | SIMD speedup |\n|------------------------|-------------:|-----------:|--------------:|-------------:|\n| image_blend (128x128)  | 73 ms        | 16 ms      | 12 ms         | **4.7x**     |\n| matrix_mul (16x16)     | 10 ms        | 6 ms       | 8 ms          | **1.6x**     |\n| byte_search (64KB)     | 52 ms        | 43 ms      | 5 ms          | **1.2x**     |\n\nmatrix_mul beats wasmtime. image_blend within 1.3x of wasmtime.\nFull SIMD results: `bench/simd_comparison.yaml`\n\n## Install\n\nmacOS / Linux:\n\n```bash\nzig build -Doptimize=ReleaseSafe\ncp zig-out/bin/zwasm ~/.local/bin/\n\ncurl -fsSL https://raw.githubusercontent.com/clojurewasm/zwasm/main/install.sh | bash\n```\n\nWindows (PowerShell):\n\n```powershell\nzig build -Doptimize=ReleaseSafe\nCopy-Item zig-out\\bin\\zwasm.exe \"$env:LOCALAPPDATA\\Microsoft\\WindowsApps\\zwasm.exe\"\n\nirm https://raw.githubusercontent.com/clojurewasm/zwasm/main/install.ps1 | iex\n```\n\n## Usage\n\n### CLI\n\n```bash\nzwasm module.wasm                         # Run a WASI module (run is optional)\nzwasm module.wasm -- arg1 arg2            # With arguments\nzwasm module.wat                          # Run a WAT text module\nzwasm module.wasm --invoke fib 35         # Call a specific function\nzwasm run module.wasm --allow-all         # Explicit run subcommand also works\nzwasm inspect module.wasm                 # Show exports, imports, memory\nzwasm validate module.wasm                # Validate without running\nzwasm features                            # List supported proposals\nzwasm features --json                     # Machine-readable output\n```\n\n### Library\n\n```zig\nconst zwasm = @import(\"zwasm\");\n\nvar module = try zwasm.WasmModule.load(allocator, wasm_bytes);\ndefer module.deinit();\n\nvar args = [_]u64{35};\nvar results = [_]u64{0};\ntry module.invoke(\"fib\", \u0026args, \u0026results);\n// results[0] == 9227465\n```\n\nSee [docs/usage.md](docs/usage.md) for detailed library and CLI documentation.\n\n### C API\n\nzwasm also exposes a C API for use from any FFI-capable language (C, Python, Rust, Go, etc.):\n\n```bash\nzig build lib    # Build libzwasm (.dll/.lib, .dylib/.a, or .so/.a)\n```\n\n```c\n#include \"zwasm.h\"\n\nzwasm_module_t *mod = zwasm_module_new(wasm_bytes, len);\nuint64_t results[1] = {0};\nzwasm_module_invoke(mod, \"f\", NULL, 0, results, 1);\nzwasm_module_delete(mod);\n```\n\nSee the [C API chapter](https://clojurewasm.github.io/zwasm/en/c-api.html) in the book for the full API reference.\n\n## Examples\n\n### WAT examples (`examples/wat/`)\n\n33 numbered educational WAT files, ordered from simple to advanced:\n\n| # | Category | Examples |\n|---|----------|----------|\n| 01-09 | Basics | `hello_add`, `if_else`, `loop`, `factorial`, `fibonacci`, `select`, `collatz`, `stack_machine`, `counter` |\n| 10-15 | Types | `i64_math`, `float_math`, `bitwise`, `type_convert`, `sign_extend`, `saturating_trunc` |\n| 16-19 | Memory | `memory`, `data_string`, `grow_memory`, `bulk_memory` |\n| 20-24 | Functions | `multi_return`, `multi_value`, `br_table`, `mutual_recursion`, `call_indirect` |\n| 25-26 | Wasm 3.0 | `return_call` (tail calls), `extended_const` |\n| 27-29 | Algorithms | `bubble_sort`, `is_prime`, `simd_add` |\n| 30-33 | WASI | `wasi_hello`, `wasi_echo`, `wasi_args`, `wasi_write_file` |\n\nEach file includes a run command in its header comment:\n\n```bash\nzwasm examples/wat/01_hello_add.wat --invoke add 2 3   # → 5\nzwasm examples/wat/05_fibonacci.wat --invoke fib 10    # → 55\nzwasm examples/wat/30_wasi_hello.wat --allow-all       # → Hi!\n```\n\n### Zig embedding examples (`examples/zig/`)\n\n5 examples showing the library API: `basic`, `memory`, `inspect`, `host_functions`, `wasi`.\n\n### C API examples (`examples/c/`)\n\nC example using `libzwasm`: load a module, invoke an export, read the result.\n\n### Python examples (`examples/python/`)\n\nPython ctypes example: same workflow as C, no compiled bindings needed.\n\n### Rust examples (`examples/rust/`)\n\nRust FFI example: same workflow as C, using `extern \"C\"` bindings.\n\n## Build\n\nRequires Zig 0.15.2.\n\n```bash\nzig build              # Build (Debug)\nzig build test         # Run all tests (521 tests)\nzig build c-test       # Run C API tests\n./zig-out/bin/zwasm run file.wasm\n```\n\nOn Windows use `zig-out\\bin\\zwasm.exe`.\n\n### Feature flags\n\nStrip features at compile time to reduce binary size:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-Djit=false` | Disable JIT compiler | `true` |\n| `-Dcomponent=false` | Disable Component Model | `true` |\n| `-Dwat=false` | Disable WAT parser | `true` |\n| `-Dsimd=false` | Disable SIMD opcodes | `true` |\n| `-Dgc=false` | Disable GC proposal | `true` |\n| `-Dthreads=false` | Disable threads/atomics | `true` |\n\nMinimal build (~940 KB, −24%): `zig build -Doptimize=ReleaseSafe -Djit=false -Dcomponent=false -Dwat=false`\n\n## Architecture\n\n```\n .wat text    .wasm binary    .wasm component\n      |            |                |\n      v            |                v\n WAT Parser        |          Component Decoder\n (optional)        |          (WIT + Canon ABI)\n      |            |                |\n      +------\u003e-----+-----\u003c---------+\n               |\n               v\n         Module (decode + validate)\n               |\n               v\n         Predecoded IR (fixed-width, cache-friendly)\n               |\n               v\n         Register IR (stack elimination, peephole opts)\n               |                          \\\n               v                           v\n         RegIR Interpreter           ARM64/x86_64 JIT\n         (fallback)              (hot functions)\n```\n\nHot functions are detected via call counting and back-edge counting,\nthen compiled to native code. Functions that use unsupported opcodes\nfall back to the register IR interpreter.\n\n## Project Philosophy\n\n**Small and fast.** zwasm prioritizes binary size and runtime performance\ndensity (performance per byte of binary). It targets environments where\nsize and startup time matter: embedded systems, edge computing, CLI tools,\nand as an embeddable library in Zig projects.\n\n**ARM64 + x86_64.** Full JIT support on both architectures including SIMD.\nPrimary optimization target is Apple Silicon; x86_64 Linux and Windows\nare equally supported.\n\n**Spec fidelity over expedience.** Correctness comes before performance.\nThe spec test suite runs on every change.\n\n## Roadmap\n\n- [x] Stages 0-4: Core runtime (extraction, library API, spec conformance, ARM64 JIT)\n- [x] Stage 5: JIT coverage (20/21 benchmarks within 2x of wasmtime)\n- [x] Stages 7-12: Wasm 3.0 (memory64, exception handling, wide arithmetic, custom page sizes, WAT parser)\n- [x] Stage 13: x86_64 JIT backend\n- [x] Stages 14-18: Wasm 3.0 proposals (tail calls, multi-memory, relaxed SIMD, function references, GC)\n- [x] Stage 19: Post-GC improvements (GC spec tests, WASI P1 full coverage, GC collector)\n- [x] Stage 20: `zwasm features` CLI\n- [x] Stage 21: Threads (shared memory, 79 atomic operations)\n- [x] Stage 22: Component Model (WIT, Canon ABI, WASI P2)\n- [x] Stage 23: JIT optimization (smart spill, direct call, FP cache, self-call inline)\n- [x] Stage 25: Lightweight self-call (fib now matches wasmtime)\n- [x] Stages 26-31: JIT peephole, platform verification, spec cleanup, GC benchmarks\n- [x] Stage 32: 100% spec conformance (62,263/62,263 on macOS + Linux)\n- [x] Stage 33: Fuzz testing (differential testing, extended fuzz campaign, 0 crashes)\n- [x] Stage 34: Windows x86_64 native support (build, test, JIT, C API, release artifacts)\n- [x] Stages 35-41: Production hardening (crash safety, CI/CD, docs, API stability, distribution)\n- [x] Stages 42-43: Community preparation, v1.0.0 release\n- [x] Stages 44-47: WAT parser spec parity, SIMD perf analysis, book i18n, WAT roundtrip 100%\n- [x] Reliability: Cross-platform verification (50 real-world programs), JIT correctness (OSR, back-edge, guard pages)\n- [x] Phase 8: Real-world coverage (50 programs), WAT parity 100%, 5 JIT codegen fixes\n- [x] Phase 13: SIMD JIT (ARM64 NEON 253/256 native, x86_64 SSE 244/256 native)\n- [ ] Future: WASI P3/async, contiguous v128 storage\n\n## Known Limitations\n\n### SIMD Performance\n\nSIMD (v128) operations are JIT-compiled to native NEON (ARM64) and SSE (x86_64) instructions.\n253/256 opcodes are native on ARM64, 244/256 on x86_64. Hand-written SIMD microbenchmarks\nshow strong results: matrix_mul beats wasmtime, image_blend within 1.3x.\n\n**Current gap**: Compiler-generated SIMD code (C `-msimd128`) shows larger gaps (13-131x vs\nwasmtime for scalar, wider for SIMD). Root cause is split v128 storage — each 128-bit vector\nis stored as two 64-bit halves, adding overhead on every load/store.\n\n**Planned improvement**: Contiguous v128 register storage (W37) and compiler-pattern\noptimization (W38). See `.dev/checklist.md` for details.\n\n## Versioning\n\nzwasm follows [Semantic Versioning](https://semver.org/). The public API surface is defined in [docs/api-boundary.md](docs/api-boundary.md).\n\n- **Stable** types and functions (WasmModule, WasmFn, etc.) won't break in minor/patch releases\n- **Experimental** types (runtime.\\*, WIT) may change in minor releases\n- **Deprecation**: At least one minor version notice before removal\n\n## Documentation\n\n- [Book (English)](https://clojurewasm.github.io/zwasm/en/) — Getting started, architecture, embedding guide, CLI reference\n- [Book (日本語)](https://clojurewasm.github.io/zwasm/ja/) — 日本語ドキュメント\n- [API Boundary](docs/api-boundary.md) — Stable vs experimental API surface\n- [CHANGELOG](CHANGELOG.md) — Version history\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, development workflow, and CI checks.\n\n## License\n\nMIT\n\n## Support\n\nDeveloped in spare time alongside a day job. If you'd like to support\ncontinued development, sponsorship is welcome via\n[GitHub Sponsors](https://github.com/sponsors/chaploud).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclojurewasm%2Fzwasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclojurewasm%2Fzwasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclojurewasm%2Fzwasm/lists"}