crossbind
GitHub

How it works

You never call the compiler yourself, so it helps to know what a crossbind build does, from crossbind build to the files your bundler picks up.

The pipeline

  1. Config. crossbind.config.js is read and merged with crossbind.build.js (packages only) and the machine settings in ~/.crossbind.json. Dependencies of dependencies come along; if any is multithreaded, the project builds mt.
  2. Targets. CLI options narrow the target matrix to the {platform, arch, runtime, runtimeEnv, buildType} combinations this machine can build.
  3. Library. Per target, your C++ compiles to a static library with CMake or configure: in Docker for wasm, Android and WASI, through Xcode for iOS.
  4. Bridges. Each imported header becomes a bridge source that registers its bindings; that is what makes classes and functions appear in JavaScript.
  5. Link. The archives link into the wasm module or the WASI command, a Rust crate's archive is staged, and the iOS slices become an xcframework.
  6. Loader. The JavaScript loader for the runtime environment is written next to the binary.
dist/ (after a wasm build)
dist/
├── myapp-wasm-wasm32-st-release.browser.js # loader
├── myapp-wasm-wasm32-st-release.browser.wasm # module
└── prebuilt/
└── wasm-wasm32-st-release/
├── include/ # headers for dependent packages
└── lib/libmyapp.a

Targets are the unit of work

Everything after the config is per target, and the target is in every file name: myapp-wasm-wasm32-st-release.browser.js is platform, arch, runtime, build type and runtime environment. So st and mt builds cannot be confused, and mixing them in one bundle fails loudly.

The JavaScript runtime layer

The loader is one core with a small adapter per environment: how files are found (URLs in the browser, the filesystem in Node.js and on the edge), OPFS and file mounting in the browser, and the bridge to a worker. So initNative() behaves the same everywhere.

Where the toolchain lives

TargetRuns inNeeds
wasm, Androidthe digest-pinned Docker imageDocker
WASIDocker, or a local wasi-sdk when configuredDocker or wasi-sdk 34+
iOSthe hostmacOS, Xcode, CocoaPods
Rust (export.type: 'cargo')the hostthe cargo toolchain

Docker sees nothing above the project folder; in a monorepo, set paths.base (Configuration).

Cache and rebuilds

PathWhat it holdsSafe to delete
.crossbind/build cache: CMake output, generated bridges, generated typesyes; the next build remakes it
dist/prebuilt/<target>/the static library and headers other packages link againstyes, but dependents must rebuild
dist/<name>.<env>.{js,wasm,data.txt}what your app loadsyes

A build is skipped when its output is newer than the sources. In dev, the bundler plugins rebuild when a .h or .cpp changes.

When a change is not picked up
Restart the dev server first. A stale artifact almost always means the source is older than the output, or paths.native does not point where you think it does.

The override hierarchy

To change what the build does, use the highest layer that works: the higher the layer, the less of the build you own.

  1. Narrow which targets build: target.{platform, arch, runtime, buildType}.
  2. Per-target flags and data, declaratively: targetSpecs[].specs.{cmake.compileOptions, binary.emccFlags, env, data, ignoreLibName, binary.wasiFlags}.
  3. Project-wide: dependencies, functions.isEnabled, paths.cmake.
  4. Package authoring: crossbind.build.js hooks - source fetch, patches, build parameters, extra libs.
  5. Machine-wide: ~/.crossbind.json (runner, Xcode team, local wasi-sdk).

Layers one to three are in Configuration, the fourth in Publishing packages. Every layer in full: overrides.md.

Type to search every guide page and section.
↑↓ navigate↵ openesc close