How godunko/adawebpack works
Purpose and entry points
AdaWebPack is an Ada-to-WebAssembly toolchain distribution: a GNAT-LLVM WebAssembly target, a tailored Ada runtime, and Ada bindings to browser Web APIs. Build orchestration starts from Makefile and the GNAT project definitions gnat/adawebpack.gpr and gnat/adawebpack_config.gpr. Consumer-facing validation/demo entry points are the browser examples under examples/.
Toolchain integration layer
The repository does not implement a standalone compiler; it adapts external GNAT-LLVM/GCC/bb-runtimes sources to produce a wasm target. Patches alter upstream compiler/interface behavior, while the target makefile is linked into GNAT-LLVM’s build tree:
• patches/gnat-llvm.patch
• patches/llvm_wrapper2.patch
• source/rtl/Makefile.target
The resulting compiler depends on LLVM/Clang plus wasm-ld/LLD with the WebAssembly target enabled.
WebAssembly Ada runtime
A minimal/ported GNAT runtime supplies initialization, exceptions, memory, string/character conversion, stack handling, and target parameters for wasm32. This is the execution boundary between generated Ada code and the Wasm environment. Important restrictions follow from this runtime/toolchain model: no nested subprograms, tasking, or protected objects; exception support is limited.
• source/rtl/wasm32.atp
• source/rtl/s-init.adb
• source/rtl/a-except.adb
JavaScript/Wasm interop substrate
Core Wasm packages model JavaScript objects, constructors, methods, attributes, strings, console output, and controlled abort behavior. Ada bindings use this substrate to invoke browser-provided objects and APIs rather than embedding browser implementations.
• source/wasm.ads
• source/wasm-objects.adb
• source/wasm-strings.adb
Browser API binding layers
Bindings are organized by Web platform domain and build upward from generic DOM types to specialized APIs. The principal flow is Ada application code → typed Ada Web binding → Wasm/JavaScript interop → browser API.
• DOM/BOM: source/dom/web-dom.ads, source/bom/web-window.ads
• HTML elements: source/html/web-html-elements.ads, source/html/web-html-documents.adb
• Event model: source/ui_events/web-ui_events.ads, source/dom/web-dom-events.adb
Network, URL, and graphics integrations
Separate bindings expose browser-managed asynchronous/platform services, maintaining browser APIs as the external-service boundary:
• WebSocket/message events: source/sockets/web-sockets.adb, source/sockets/web-message_events.ads
• XMLHttpRequest: source/xhr/web-xhr-requests.adb
• URL/query parameters: source/url/web-url-url_search_params.adb
• WebGL rendering contexts and resources: source/webgl/web-gl-rendering_contexts.adb, source/webgl/web-gl.ads
Example delivery model
Examples compile Ada application units to Wasm and pair them with static HTML pages loaded by a browser over HTTP. They demonstrate DOM callbacks, Ada-callable behavior, and WebGL; the browser and an HTTP server are required deployment/runtime infrastructure.
• examples/call_ada/main.adb, examples/call_ada/index.html
• examples/toggle_hidden/main.adb, examples/toggle_hidden/index.html
• examples/webgl_basic/main.adb, examples/webgl_basic/index.html
Main entry points: wasm.ads Wasm interop substrate · main.adb Ada example applications · web-dom.ads DOM and BOM · s-init.adb Ported GNAT runtime
Components 19
Toolchain Build
- Build orchestration · Coordinates target and consumer builds.
Makefile - AdaWebPack project
gnat/adawebpack.gpr - GNAT-LLVM patches · Adapts external compiler and interface behavior.
patches/gnat-llvm.patch - Wasm target makefile · Linked into the GNAT-LLVM build tree.
source/rtl/Makefile.target - GNAT-LLVM + LLVM/LLD · Produces WebAssembly-targeted Ada output.
Wasm Runtime & Interop
- Ported GNAT runtime · Initialization, exceptions, memory, stack, and target support.
source/rtl/s-init.adb - Wasm target parameters
source/rtl/wasm32.atp - Wasm interop substrate · Models JavaScript objects, methods, attributes, and console access.
source/wasm.ads - JS objects and strings
source/wasm-objects.adb
Browser Bindings
- DOM and BOM · Generic DOM types and window access.
source/dom/web-dom.ads - HTML bindings
source/html/web-html-elements.ads - UI event bindings
source/ui_events/web-ui_events.ads - Network bindings · WebSocket, message-event, and XMLHttpRequest APIs.
source/sockets/web-sockets.adb - URL bindings
source/url/web-url-url_search_params.adb - WebGL bindings · Rendering contexts and resources.
source/webgl/web-gl-rendering_contexts.adb - Browser Web APIs · Provides DOM, platform services, and WebGL.
Examples & Deployment
- Ada example applications · DOM callbacks, Ada-callable behavior, and WebGL demos.
examples/call_ada/main.adb - Example HTML pages
examples/call_ada/index.html - HTTP server · Serves example pages and Wasm to the browser.
Connections 21
- Build orchestration → AdaWebPack project: uses
- Build orchestration → Wasm target makefile: builds target
- GNAT-LLVM patches → GNAT-LLVM + LLVM/LLD: adapts
- Wasm target makefile → GNAT-LLVM + LLVM/LLD: integrates with
- GNAT-LLVM + LLVM/LLD → Ported GNAT runtime: builds with
- Wasm target parameters → Ported GNAT runtime: configures
- JS objects and strings → Wasm interop substrate: implements
- DOM and BOM → Wasm interop substrate: uses
- HTML bindings → DOM and BOM: specializes
- UI event bindings → DOM and BOM: extends
- Network bindings → Wasm interop substrate: uses
- URL bindings → Wasm interop substrate: uses
- WebGL bindings → Wasm interop substrate: uses
- Wasm interop substrate → Browser Web APIs: invokes
- Ada example applications → AdaWebPack project: compiled by
- Ada example applications → Ported GNAT runtime: runs on
- Ada example applications → DOM and BOM: uses bindings
- Ada example applications → WebGL bindings: uses for graphics
- Example HTML pages → HTTP server: served by
- HTTP server → Browser Web APIs: delivers pages and Wasm
- Browser Web APIs → Ada example applications: loads and executes