crossbind-build

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

`crossbind.build.js` — Package-author Build Hooks

> **Port authors only.** Apps and libraries consuming `@crossbind/port-*` do not write this file. Each platform variant owns one at `ports/<name>/<platform>/crossbind.build.js`; the shared recipe lives at `ports/<name>/base/build.mjs`, and variants import or extend it.

`crossbind.build.js` describes how to fetch and build the upstream C++ library that this package wraps. The CLI auto-merges its exports into `config.build` of the sibling `crossbind.config.js` at build time.

Shape

export default {
  // ─────────────────────────────────────────────────────────────
  // Source acquisition
  // ─────────────────────────────────────────────────────────────
  getURL: (version) => 'https://example.com/upstream-${version}.tar.gz',
    // Simplest path: return a tarball URL. The CLI fetches + extracts
    // into state.config.paths.build automatically.
    // `version` is the nativeVersion field from package.json.

  getMirrors: (version) => ['https://mirror.example.com/upstream-${version}.tar.gz'],
    // Optional: other https URLs that serve the same tarball. When getURL's
    // download fails, or its bytes miss the sha256, the CLI tries these in
    // order. getURL stays the source that license/SBOM rows name.

  sha256: '1051c33d…',
    // Checksum of the tarball getURL returns. Verified on download, and the
    // single source for license/SBOM rows and the -bin provenance block
    // (contract K4) — required for packages that publish binaries.

  // ─────────────────────────────────────────────────────────────
  // Build system selector
  // ─────────────────────────────────────────────────────────────
  buildType: 'cmake',
    // 'cmake'     — default; the CLI runs cmake configure + build.
    // 'configure' — runs `./configure && make` for autotools projects.
    //               See ports/openssl-* for the canonical example.

  configureProgram: './configure',
    // 'configure' only: explicit configure entrypoint. Defaults to
    // './configure'; OpenSSL uses the case-sensitive './Configure'.

  makePhases: ['all', 'install'],
    // 'configure' only: split the make step into explicit phases when a
    // single `make` is not enough (openssl needs `make all` + `make install`).

  // ─────────────────────────────────────────────────────────────
  // Published tool surface + vendored copies (contract-governed)
  // ─────────────────────────────────────────────────────────────
  bin: { /* tools map */ },
    // -bin packages only: the single-source tool map. The engine derives the
    // npm command shims, .npmignore, crossbind-bin.json and the multicall
    // multitool from it, and stamps crossbind.provenance + the compound license
    // field into package.json. Full schema and rules ("Bin & License
    // Contract"): ports/README.md.

  bundled: { wasi: [{ name: 'libpng', version: '1.6.43', license: 'libpng-2.0', files: ['frmts/png/libpng/LICENSE'] }] },
    // Third-party copies the upstream compiles INTO the artifact, per
    // platform (e.g. GDAL's internal codecs). `crossbind licenses` turns these
    // into notice/SBOM rows with texts pulled from the source tree. The build
    // copies those texts to dist/licenses/<name>/, where a package installed
    // from npm still has them.

  // ─────────────────────────────────────────────────────────────
  // Configure-step parameters
  // ─────────────────────────────────────────────────────────────
  getBuildParams: (target) => [
    '-DBUILD_SHARED_LIBS=OFF',
    '-DBUILD_TESTING=OFF',
  ],
    // Extra cmake -D flags (or autotools args). Called as
    // getBuildParams(target, depPaths, ext, buildPath):
    //   target    — current build target ({ platform, arch, runtime, … })
    //   depPaths  — this target's dependency paths (depPaths.<libName>.header / .lib)
    //   ext       — 'so' on android, 'a' elsewhere
    //   buildPath — this target's build directory
    //
    // Use `target` to branch on per-arch needs:
    //   target.platform === 'wasm' | 'android' | 'ios'
    //   target.runtime  === 'st' | 'mt'

  // ─────────────────────────────────────────────────────────────
  // Build-time env vars (CFLAGS / CXXFLAGS / LDFLAGS as string literals)
  // ─────────────────────────────────────────────────────────────
  env: (target) => [
    'CFLAGS="-fPIC -DSQLITE_ENABLE_FTS5"',
    'LDFLAGS="-Wl,--no-undefined"',
  ],
    // Function form receives target; can also be a plain string array.
    // DIFFERENT from crossbind.config.js `targetSpecs[].specs.env`, which is RUNTIME env.

  // ─────────────────────────────────────────────────────────────
  // Extra link libraries
  // ─────────────────────────────────────────────────────────────
  getExtraLibs: (target) => ['-lpthread', '-lm'],
    // Returns extra libs appended to the link line beyond what
    // `dependencies` already wires up. Rarely needed; most upstream
    // libs declare their own link deps.

  // ─────────────────────────────────────────────────────────────
  // Upstream source patching (regex)
  // ─────────────────────────────────────────────────────────────
  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'],
    },
  ],
    // Patch the extracted upstream source before configure. Each entry:
    //   regex       — matched against file contents
    //   replacement — substitution
    //   paths       — file globs (relative to state.config.paths.build)
    //
    // Real users: gdal-wasm (CPU intrinsic gating), curl-wasm
    // (Emscripten Fetch API swap), sqlite3-android (Makefile fixups).
    //
    // Function form (sourceReplaceList) gets state + depPaths if you
    // need them to compute the regex/replacement:
    //   sourceReplaceList: (target,