Named compile-time configurations

Compile-time presets live in build-configs/configurations.json. Each entry is a flat map of OCJS_* environment-variable names to values; the build CLI loads the entry and exports each key before driving emcc and wasm-opt.

All shipped presets ship with the same feature set — native WASM exceptions (OCJS_EXCEPTIONS=1, OCJS_EH_MODE=wasm), EVAL_CTORS=2, and the Closure Compiler on. They differ on optimisation level, threading mode, and the wasm-opt budget.

Shipped presets

For the full OCJS_* matrix that each preset sets — including the flags they share — see BUILD_SYSTEM.md.

Selecting a preset

build-wasm.sh reads the OCJS_CONFIG env var or the --config <name> CLI flag (the CLI flag wins if both are set). When neither is set, the script falls back to single-threaded:

OCJS_CONFIG=debug ./build-wasm.sh link build-configs/my-config.yml

Or via the CLI flag:

./build-wasm.sh --config debug link build-configs/my-config.yml

Adding a custom preset

Append a new entry to build-configs/configurations.json. The shape is a flat OCJS_* env-var map — same keys the shipped presets use:

{
  "single-threaded-no-simd": {
    "OCJS_OPT": "-Os",
    "OCJS_LTO": "0",
    "OCJS_EXCEPTIONS": "1",
    "OCJS_EH_MODE": "wasm",
    "OCJS_SIMD": "0",
    "THREADING": "single-threaded",
    "OCJS_DEFINES": "OCCT_NO_DUMP",
    "OCJS_UNDEFINES": "OCC_CONVERT_SIGNALS",
    "OCJS_WASM_OPT_LEVEL": "-O3",
    "OCJS_CLOSURE": "true",
    "OCJS_EVAL_CTORS": "true",
    "OCJS_EVAL_CTORS_LEVEL": "2",
    "OCJS_CONVERGE": "true",
    "OCJS_BIGINT": "1",
    "OCJS_MALLOC": "mimalloc",
    "BINARYEN_EXTRA_PASSES": ""
  }
}

Custom presets share the same compile-.o cache as shipped ones — the cache is keyed by the compile-flag fingerprint, not by the preset name. Two presets with identical compile-time flags share cache entries automatically.

Cache invalidation

Changing any compile flag invalidates the cached .o files that depended on it. The build manifest records the active fingerprint:

cat build/build-flags.json

The published npm tarball ships dist/opencascade_full.provenance.json and dist/opencascade_full_multi.provenance.json — same preset / flag information for each variant, with the commit SHA the wasm was built from. CI scripts should diff these files across builds to detect surprise cache turnover.

Related

• Two-channel config model — why compile-time and link-time config are separate channels.
• Custom emcc flags — link-time emccFlags rationale.
• Environment variables — every OCJS_* env var.