bun.sh/wasm-build-progress.md

Bun WASM Build Compilation Progress

Task: Get the WASM build of Bun to compile successfully, starting with make wasm and eventually getting JavaScript bindings to work end-to-end for extracting test blocks from bun:test files.

Environment:

• Working in /workspace directory containing Bun codebase
• Linux 6.8.0-1024-aws system with /usr/bin/bash shell

✅ COMPLETED ISSUES AND SOLUTIONS

1. Missing Zig Compiler

• Error: "Missing zig. Please make sure zig is in PATH"
• Solution: Downloaded and installed Zig 0.13.0 to /opt/zig with symlink to /usr/local/bin/zig

2. Missing Emscripten

• Error: Required for WASM compilation
• Solution: Downloaded and installed emsdk, activated latest version (4.0.10)

3. Missing mimalloc .a file

• Error: /workspace/vendor/mimalloc directory didn't exist
• Solution: Created vendor directory, cloned specific mimalloc commit (1beadf9651a7bfdec6b5367c380ecc3fe1c40d1a), built mimalloc for WASM using emscripten
• Required: Installing ninja-build for cmake

4. Multiple Zig API Compatibility Issues in build.zig

• Fixed: b.graph.incremental field removal → changed to static value
• Fixed: .path field in union 'Build.LazyPath' → removed .path wrapper
• Fixed: root_module in ObjectOptions/ExecutableOptions → moved to separate assignment
• Fixed: addIncludePath → addIncludeDir
• Fixed: addFail → addSystemCommand
• Fixed: popOrNull() vs pop() for ArrayList
• Fixed: bundle_ubsan_rt field removal → commented out
• Fixed: determined_by_arch_os → determined_by_cpu_arch
• Fixed: unwind_tables enum → boolean

5. Missing LLVM Tools

• Solution: Installed llvm-19, llvm-19-dev, llvm-19-tools, lld-19
• Created: symlink /usr/bin/ld.lld → /usr/bin/ld.lld-19

6. Missing Generated Codegen Files

• Error: "Generated file '/workspace/build/debug/codegen/ZigGeneratedClasses.zig' is missing!"
• Solution: Used cmake to configure build system and ninja to generate required files
• Generated: Successfully created ZigGeneratedClasses.zig and other codegen files in /workspace/build/codegen/

7. Missing bun-wasm Build Target

• Error: "no step named 'bun-wasm'"
• Solution: Added missing bun-wasm target to build.zig that:
  • Creates a WebAssembly object file using src/main_wasm.zig
  • Links with mimalloc WASM object
  • Installs to correct location expected by Makefile

8. Codegen Path Resolution Issue

• Error: Build system looking in /workspace/build/debug/codegen/ vs actual location /workspace/build/codegen/
• Solution: Updated Makefile to pass -Dcodegen_path=build/codegen parameter to all zig build commands

9. Variable Mutability Issues in main_wasm.zig

• Error: Variables declared as var but never mutated
• Solution: Changed var to const for immutable variables in src/main_wasm.zig

🚧 CURRENT STATUS

The build now successfully:

• ✅ Finds and uses correct codegen files
• ✅ Processes all translate-c steps (2459+ dependencies)
• ✅ Reaches the actual Zig compilation phase
• ❌ FAILING: Compilation due to Zig API compatibility issues

🔄 REMAINING WORK

Critical Issue: Zig API Compatibility

The build fails during compilation due to numerous Zig API changes between the version Bun was written for and Zig 0.13.0:

1. @minimum → @min
2. @enumToInt → @intFromEnum
3. @boolToInt → @intFromBool
4. @truncate argument order changed
5. @ptrCast syntax changed
6. @branchHint removed
7. @export syntax changed
8. mem.Alignment → std.mem.Alignment

Two Possible Approaches:

Option A: Downgrade Zig (Recommended)

• Find and install the exact Zig version Bun was built with
• This would avoid the need to fix hundreds of API compatibility issues
• Check Bun's CI/build configuration for the exact version

Option B: Fix All API Compatibility Issues

• Systematically update all Zig API calls throughout the codebase
• This is a very large task affecting many files
• Higher risk of introducing bugs

🎯 NEXT STEPS

1. Determine Original Zig Version: Check Bun's documentation, CI configs, or release notes for the Zig version they use
2. Install Correct Zig Version: Replace Zig 0.13.0 with the version Bun expects
3. Test WASM Build: Run make wasm with the correct Zig version
4. Test JavaScript Bindings: Use node packages/bun-wasm/test/node.mjs <foo.test.ts> to verify end-to-end functionality

📁 FILES MODIFIED

• build.zig: Multiple API compatibility fixes + added bun-wasm target
• src/main_wasm.zig: Fixed variable mutability issues
• Makefile: Added -Dcodegen_path=build/codegen to bun-wasm build commands
• wasm-build-progress.md: This progress tracking document

🎉 ACHIEVEMENTS

We've successfully resolved the major build system configuration issues and created a working build pipeline. The build now processes 2459+ dependencies and reaches the compilation stage. The remaining work is primarily about Zig version compatibility, which is a well-defined and solvable issue.