overrides

<!-- GENERATED from docs/api/overrides.md by scripts/build-agent-skill.mjs. Do not edit. -->

Override mechanisms catalog

> crossbind picks sane defaults for every build flag, env var, path, and toolchain. When a default doesn't fit your case, there are **17 documented override points**. This doc lists them in order of preference: **start with the least invasive that solves your problem**.

Why "least invasive first"

Every override point exists for a reason — but each adds a layer of "this build differs from the default in a non-obvious way". Reaching for `extensions[]` to override what `targetSpecs[].specs.binary.emccFlags` could do makes the project harder to maintain and harder for AI agents (or future-you) to reason about.

Order of preference, from least to most invasive:

1. Don't override — restate the constraint as a target filter. 2. `targetSpecs[].specs.*` for declarative per-target tweaks, runtime env vars included. 3. `crossbind.build.js` hooks (package authors only) for source-acquisition / build-step logic. 4. `extensions[]` for cross-cutting plugin behavior. 5. `~/.crossbind.json` for system-wide environment defaults.

The 17 override points

Layer 1 — Target filter (narrow the build matrix)

1. `crossbind.config.js` `target.{platform,arch,runtime,buildType,runtimeEnv}`

Restrict which of the 30 built-in targets actually build. Doesn't *change* defaults — just skips targets you don't need.

target: { platform: 'wasm', runtime: 'st' }   // skip android, ios, all mt builds

When to reach for this **first**: shipping faster (don't build iOS for an internal Node tool), or constraining a per-package build (a wasm-only package has no reason to define ios/android variants).

Layer 2 — Per-target declarative overrides

2. `targetSpecs[].specs.cmake.compileOptions`

Add compiler flags to the sources crossbind compiles with its own CMakeLists (your native sources and the generated bindings) for matching targets. Entries from dependencies are added too. CMake configure flags (`-D…`) for an upstream library belong in its recipe's `getBuildParams` (#11); an array under `specs.cmake` is rejected.

targetSpecs: [{
    platform: 'ios',
    specs: { cmake: { compileOptions: ['-DMYAPP_NO_LOGGING=1'] } },
}]

3. `targetSpecs[].specs.binary.emccFlags`

Append `-s` / `-O` flags to emcc command. Wasm only.

targetSpecs: [{
    platform: 'wasm',
    specs: { binary: { emccFlags: ['-sINITIAL_MEMORY=64MB', '-sJSPI'] } },
}]

4. `targetSpecs[].specs.env`

Env vars for the running module. A value can be a function of `(state, target)` — keep it pure, crossbind calls it wherever it reads the env; see [ADR-0003](../adr/0003-function-typed-env-values.md) — and `_CROSSBIND_DATA_PATH_` in a value becomes the runtime data path. `crossbind.config.js` has no top-level `env`.

targetSpecs: [{
    runtime: 'st',
    specs: {
        env: {
            GDAL_NUM_THREADS: '0',
            DATA_DIR: (state, target) => `${state.config.paths.build}/data`,
            CERT_PATH: '_CROSSBIND_DATA_PATH_/certs/cacert.pem',
        },
    },
}]

5. `targetSpecs[].specs.data`

Bundle data files into the `.data` preload.

targetSpecs: [{
    platform: 'wasm',
    specs: { data: { 'share/myapp': 'myapp/data' } },  // copy share/myapp/* → /<datapath>/myapp/data/
}]

6. `targetSpecs[].specs.ignoreLibName`

Suppress specific `.a` names from the link line. Use when an upstream lib clashes with another transitive dep.

targetSpecs: [{
    platform: 'wasm',
    specs: { ignoreLibName: ['libtiff_legacy'] },
}]

Layer 3 — `crossbind.config.js` global

7. `functions.isEnabled: (target) => boolean`

Override the default "is this target buildable?" check (default: returns true if the target's output binary already exists). Useful for skipping heavy targets in CI subsets.

functions: {
    isEnabled: (target) => target.runtime === 'st' || process.env.CI_FULL === '1',
}

8. `dependencies: [...]`

Each entry is another resolved crossbind config. Affects build order (pnpm topological per ADR-0002), and the dep's `target.runtime: 'mt'` auto-promotes you to `mt`.

9. `paths.cmake`

Point at a custom `CMakeLists.txt` instead of the project default. Rare — crossbind's bundled CMakeLists works for almost every project.

Layer 4 — `crossbind.build.js` hooks (package authors only)

> These are for `ports/*` authors wrapping an upstream library. Consumer apps don't write `crossbind.build.js`.

10. `getURL: (version) => string`

Source acquisition: the CLI downloads the tarball at this URL and extracts it.

11. `getBuildParams: (target, depPaths, ext, buildPath) => string[]`

Returns flags appended to `cmake configure` (or `configureProgram`, default `./configure`, if `buildType: 'configure'`). Receives the current `target`, this target's dependency paths (`depPaths.<libName>.header`, `.lib`), the library extension (`'so'` on Android, `'a'` elsewhere) and the target's build directory.

12. `getExtraLibs: (target) => string[]`

Returns extra libs to add to the link line beyond what `dependencies` already wires up.

13. `env: ((target) => string[]) | string[]`

Build-time env vars (CFLAGS, CXXFLAGS, LDFLAGS as string literals). Different from `targetSpecs[].specs.env` (#4), which is runtime.

env: (target) => [
    'CFLAGS="-fPIC -DSQLITE_ENABLE_FTS5"',
    'LDFLAGS="-Wl,--no-undefined"',
]

14. `replaceList: [{regex, replacement, paths}]` or `sourceReplaceList: (target, depPaths) => Array<...>`

Patch upstream source via regex. Use when the upstream lib has CPU intrinsics, raw pointers, or platform-specific assembly that doesn't compile for your target.

replaceList: [{
    regex: /CPL_CPUID\(1, cpuinfo\);/g,
    replacement: '#ifdef __wasm__\ncpuinfo[0]=0;\n#else\nCPL_CPUID(1, cpuinfo);\n#endif',
    paths: ['port/cpl_cpu_features.cpp'],
}]

Real example: gdal-was