⌘K
ENES
GitHub
indexToolchains & Language Targets#webassembly#rust#emscripten#llvm#toolchains

Toolchains and Language Targets

Compiling “to WebAssembly” is not one operation. A frontend chooses source-language semantics, a target chooses environmental assumptions, a linker resolves symbols and lays out memory, optimization passes transform the module, and a binding or packaging layer may generate substantial host code. The resulting .wasm is only one part of the deployable contract.

Introduction and Mental Model

Model the pipeline as a sequence of observable artifacts: source code, compiler intermediate representation, Wasm object files, a linked module, optional Binaryen transformations, binding metadata, JavaScript glue, and final package assets. Each stage can add imports, exports, runtime support, custom sections, memory policies, or compatibility requirements.

Target triples are contracts, not spelling variations. Rust's wasm32-unknown-unknown deliberately assumes little about a host. Emscripten supplies a browser/Node-oriented C and C++ runtime layer. WASI targets expect specified system interfaces from a compatible host. wasm-bindgen and wasm-pack solve binding and packaging problems around a Wasm module; they do not change the core execution model into a universal platform.

This branch builds on compiler and linker fundamentals in the Low-Level Atlas, then concentrates on the Wasm-specific artifacts and host contracts those stages produce.

Why It Matters

AI workloads amplify every hidden toolchain choice. Unused runtime support increases download and compile cost. A convenient string binding may copy tensors. An optimization flag can change floating-point behavior or feature requirements. Debug information can dwarf a small kernel. Without a reproducible pipeline, size and performance comparisons between languages measure different contracts rather than different implementations.

Questions This Branch Answers

  • Which artifacts do Clang, Emscripten, rustc, wasm-bindgen, wasm-pack, wasm-ld, and Binaryen each produce?
  • What host assumptions distinguish wasm32-unknown-unknown, Emscripten, and WASI targets?
  • When is generated JavaScript glue required, optional, or actively hiding the ABI under investigation?
  • Which imports, exports, memories, tables, and custom sections did the toolchain add?
  • How should source maps, DWARF, names, and optimized builds be separated during debugging and measurement?
  • What does “standalone Wasm” mean for a specific module and environment?
  • How can WAT, C, and Rust implementations be compared without changing the algorithm or boundary contract?
  • Which compiler features require runtime detection rather than an assumption of universal engine support?

Scope

  • Handwritten WAT as a transparent baseline.
  • Clang and wasm-ld for direct C/C++ compilation and linking.
  • Emscripten for browser-oriented C/C++ ports and its generated runtime/glue choices.
  • Rust targets, wasm-bindgen, and wasm-pack for browser packages.
  • WASI targets as a distinct host contract, not as a browser synonym.
  • Object files, linking, symbol visibility, imports/exports, custom sections, and standalone-module constraints.
  • Binaryen and compiler optimization levels, including their effect on size and observable behavior.
  • Source maps, DWARF, name sections, disassembly, and reproducible release builds.

Out of Scope

  • A general tutorial for C, C++, Rust, LLVM IR, Cargo, or linker internals.
  • Declaring one language or toolchain globally fastest from a single microbenchmark.
  • Assuming a target tier guarantees browser APIs, threads, SIMD, filesystem access, or test coverage it does not specify.
  • Porting a large native AI framework in this first pass.
  • Treating generated bindings as free in bytes, copies, initialization work, or maintenance.
  • Replacing later runtime, model-format, Component Model, or WASI branches.

Expected Outcomes

After this branch, the reader should be able to:

  • Draw and reproduce the artifact pipeline for a small WAT, C, or Rust module.
  • Select a target based on an explicit host contract instead of the word “Wasm.”
  • Inspect a final module and attribute imports, exports, sections, and glue to their producing stage.
  • Produce debuggable and measured release variants without conflating them.
  • Explain why two source languages can expose the same ABI while shipping different support code.
  • Make a fair, versioned size/API/performance comparison for the Workbench kernel.

Candidate Note Roadmap

  • one-module-many-pipelines — trace equivalent WAT, C, and Rust sources through their intermediate, object, linked, optimized, and packaged artifacts.
  • clang-wasm-ld-linking-and-the-minimal-c-contract — compile freestanding C, inspect objects and relocations, resolve symbols, control imports, exports, memory, entry points, compiler builtins, and standalone-module assumptions.
  • emscripten-runtime-and-generated-glue — identify browser conveniences, settings, loaders, filesystem shims, and bytes introduced outside the core module.
  • rust-targets-are-host-contracts — compare wasm32-unknown-unknown, WASI-family targets, standard-library availability, and target-tier guarantees.
  • wasm-bindgen-and-wasm-pack-boundaries — inspect generated bindings, package targets, ownership conventions, and where conversions or copies occur.
  • binaryen-size-and-speed-passes — compare compiler and wasm-opt transformations with correctness gates and retained build metadata.
  • debugging-optimized-wasm — use names, DWARF, source maps, WAT, and engine tooling without shipping debug weight accidentally.
  • reproducible-wasm-builds — pin versions and flags, normalize measurement inputs, hash outputs, and explain residual nondeterminism.

Future Runnable Artifact

The branch will implement the exact same affine_relu vector kernel three ways: handwritten WAT, freestanding C compiled with Clang, and Rust compiled for wasm32-unknown-unknown. Every variant will export one memory and the same scalar ABI: alloc(byte_length), affine_relu(input_ptr, output_ptr, length, scale, bias), and reset().

A TypeScript harness will feed identical seeded Float32Array inputs, validate outputs against one reference function, and reject a variant whose import/export contract differs. It will preserve compiler and linker commands, version manifests, raw modules, disassembly, section inventories, and any generated JavaScript as separate assets. Optional Emscripten and wasm-bindgen package variants will be measured as complete deployable bundles, not compared using only their .wasm member.

The report will compare raw/gzip/Brotli bytes, required imports, exported surface, initialization time, first-call latency, warmed throughput, and observed copy bytes. It will describe the tested engine and flags rather than generalizing the winner to all programs or devices.

How to Verify and Measure

  • Keep one language-neutral kernel specification, input corpus, ABI manifest, and tolerance policy under version control.
  • Validate and inspect every module; diff section, import, export, memory, table, feature, and custom-section inventories before benchmarking.
  • Run deterministic edge cases and randomized differential tests against the TypeScript reference before accepting size or speed results.
  • Record complete tool versions, target triples, optimization flags, linker flags, environment variables that affect output, and artifact hashes.
  • Measure debug and release builds separately. Report .wasm, generated host code, metadata, and compressed transfer sizes both individually and as a bundle.
  • Separate module fetch/read, compile, instantiate, binding initialization, first call, and steady-state execution.
  • Warm up according to a documented protocol, report distributions rather than one best value, and retain raw samples with CPU, browser/runtime version, power mode, and input size.
  • Repeat on at least two compatible engines before making a portability observation; label a single-engine result as such.

Primary Sources

  • WebAssembly Core Specification — authoritative module, object-level semantics, and binary format against which tool output is interpreted. Release 3.0; checked 2026-07-16.
  • LLVM WebAssembly linker documentation — primary wasm-ld options and linking behavior. Living LLVM documentation; checked 2026-07-16.
  • Clang WebAssembly language extensions — primary feature-selection and WebAssembly-specific compiler interface. Living LLVM documentation; checked 2026-07-16.
  • Emscripten documentation — primary compiler, runtime, porting, debugging, and packaging documentation. Development documentation changes with releases; checked 2026-07-16.
  • Rust wasm32-unknown-unknown target documentation — primary target guarantees, defaults, and limitations. Living stable-channel documentation; target listed as Tier 2 and checked 2026-07-16.
  • wasm-bindgen guide — primary binding-generation and JavaScript interoperation documentation. Active project documentation; checked 2026-07-16.
  • Binaryen — primary source and documentation for wasm-opt and related module tools. Active project; checked 2026-07-16.
  • WASI SDK — primary SDK packaging and target documentation for Clang-based WASI builds. Active project tied to evolving WASI/toolchain releases; checked 2026-07-16.

Connects to: WebAssembly Execution Model · Linear Memory, ABI, and Host Interop · SIMD, Threads, and Workers · WASI, Components, and WASI-NN · Wasm AI Performance, Security, and Craftsmanship