pcbjam/wasm

WASM Compatibility Layer

This directory contains WASM-specific implementations that allow KiCad to run in a web browser while keeping our KiCad fork as close to upstream as possible.

Principle

Instead of patching KiCad source files, we:

1. Provide alternative implementations for platform-specific code (kiplatform)
2. Stub out libraries/features that can't work in the browser (libgit2, curl, nng, scripting, 3D viewer, ...)
3. Expose KiCad to JavaScript via Embind bindings
4. Override host package detection during cross-compilation (cmake find-modules)

The KiCad-side hooks for this are small if(EMSCRIPTEN) branches in KiCad's own CMakeLists that pull sources from this directory — see "How it's wired" below.

Directory Structure

wasm/
├── README.md               # This file
├── kiplatform/             # Platform abstraction implementations (compiled into KiCad)
│   ├── app.cpp             # App lifecycle (paths, startup)
│   ├── drivers.cpp         # GPU detection (returns "WebGL")
│   ├── environment.cpp     # Environment variables
│   ├── io.cpp              # File I/O (WASM virtual filesystem)
│   ├── policy.cpp          # Security policy (always permissive)
│   ├── secrets.cpp         # Credential storage
│   ├── sysinfo.cpp         # System information
│   ├── printing.cpp        # Print support (browser print())
│   └── ui.cpp              # UI helpers
├── bindings/               # Embind bindings exposing each app to JavaScript
│   ├── pcbnew_embind.cpp
│   ├── eeschema_embind.cpp
│   ├── pl_editor_embind.cpp
│   └── calculator_embind.cpp
├── stubs/                  # Stub implementations + header shims for unavailable deps
│   ├── *.c / *.cpp         # libgit2, curl, nng, scripting, 3D viewer, frame stubs, ...
│   ├── char_traits_uint16_workaround.h
│   └── GL/ nng/ ngspice/   # Header stubs found via include paths
└── cmake/                  # CMake find-module overrides for cross-compilation
    └── Find*.cmake / Use*.cmake

How it's wired

kiplatform — compiled into KiCad

The kiplatform/*.cpp files are added directly to KiCad's kiplatform library by an if(EMSCRIPTEN) branch in kicad/libs/kiplatform/CMakeLists.txt, which references them as ${PROJECT_SOURCE_DIR}/../wasm/kiplatform/*.cpp. There is no separate libkiplatform_wasm.a.

stubs — compiled by the build script and KiCad CMakeLists

scripts/kicad/build-kicad-target.sh compiles the C stubs (libgit2_stub.c, curl_stub.c, nng_stub.c) and force-includes char_traits_uint16_workaround.h. App-specific *_frame_stub.cpp / *_scripting_stub.cpp are picked up per app, and the remaining *_stub.cpp files are pulled in by if(EMSCRIPTEN) branches in the KiCad fork's own CMakeLists. Header stubs under GL/, nng/, ngspice/ are resolved via include paths.

bindings — per app

build-kicad-target.sh compiles wasm/bindings/<app>_embind.cpp for the app being built (apps without an embind file get an empty placeholder object).

cmake — module path

build-kicad-target.sh passes -DCMAKE_MODULE_PATH="${PROJECT_ROOT}/wasm/cmake" so the WASM find-module stubs override host package detection.

Coroutine/fiber support is not in this directory — it comes from the KiCad fork's kicad/thirdparty/libcontext/libcontext.cpp (LIBCONTEXT_PLATFORM_wasm32). The GLU tesselator comes from kicad/libs/kimath/glu_tess/glu_tess_impl.cpp.

Adding New Implementations

1. Create the implementation file in the appropriate directory (kiplatform/, stubs/, bindings/).
2. Wire it in: a stub C file goes in build-kicad-target.sh; a kiplatform/app source goes in the relevant if(EMSCRIPTEN) branch of the KiCad-side CMakeLists.
3. Ensure the header interface matches KiCad's expected interface.
4. Test with a minimal build before full integration.