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
- Config.
crossbind.config.jsis read and merged withcrossbind.build.js(packages only) and the machine settings in~/.crossbind.json. Dependencies of dependencies come along; if any is multithreaded, the project buildsmt. - Targets. CLI options narrow the target matrix to the
{platform, arch, runtime, runtimeEnv, buildType}combinations this machine can build. - 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.
- Bridges. Each imported header becomes a bridge source that registers its bindings; that is what makes classes and functions appear in JavaScript.
- 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.
- Loader. The JavaScript loader for the runtime environment is written next to the binary.
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
| Target | Runs in | Needs |
|---|---|---|
| wasm, Android | the digest-pinned Docker image | Docker |
| WASI | Docker, or a local wasi-sdk when configured | Docker or wasi-sdk 34+ |
| iOS | the host | macOS, Xcode, CocoaPods |
Rust (export.type: 'cargo') | the host | the cargo toolchain |
Docker sees nothing above the project folder; in a monorepo, set paths.base (Configuration).
Cache and rebuilds
| Path | What it holds | Safe to delete |
|---|---|---|
.crossbind/ | build cache: CMake output, generated bridges, generated types | yes; the next build remakes it |
dist/prebuilt/<target>/ | the static library and headers other packages link against | yes, but dependents must rebuild |
dist/<name>.<env>.{js,wasm,data.txt} | what your app loads | yes |
A build is skipped when its output is newer than the sources. In dev, the bundler plugins rebuild when a .h or .cpp changes.
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.
- Narrow which targets build:
target.{platform, arch, runtime, buildType}. - Per-target flags and data, declaratively:
targetSpecs[].specs.{cmake.compileOptions, binary.emccFlags, env, data, ignoreLibName, binary.wasiFlags}. - Project-wide:
dependencies,functions.isEnabled,paths.cmake. - Package authoring:
crossbind.build.jshooks - source fetch, patches, build parameters, extra libs. - 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.