build-state

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

`state` and `target` shapes — what build hooks receive

> When you write a `crossbind.build.js` hook (`getBuildParams(target, depPaths, ext, buildPath)`, `sourceReplaceList(target, depPaths)`, etc.), or an `extensions[]` plugin, you receive a `state` object and a `target` object. This doc enumerates every key on both. Source: `core/crossbind/src/state/index.js`.

`state` — top-level keys

state = {
    targets:               Target[],            // 32 built-in build targets (see § Target inventory)
    config:                ResolvedConfig,      // merged crossbind.config.js + crossbind.build.js + system
    cache:                 BuildCache,          // persisted to .crossbind/cache.json
    system:                SystemConfig,        // ~/.crossbind.json + defaults from systemKeys
}

`state.config` (the resolved configuration)

The output of `loadConfig()` in `src/state/loadConfig.js`. Every key:

state.config = {
    general: { name: string },                  // package name; OPFS namespace = /opfs/<name>/

    dependencies: ResolvedConfig[],             // immediate crossbind deps (each is its own resolved config)
    allDependencies: ResolvedConfig[],          // flattened transitive deps, deduped by paths.project

    paths: {
        config:              string,            // import.meta.url of crossbind.config.js
        project:             string,            // absolute project root
        base:                string,            // = project unless overridden
        cache:               string,            // .crossbind (build cache root)
        build:               string,            // .crossbind/build (staging dir for sources)
        output:              string,            // dist artifacts dir
        native:              string[],          // C++ source roots (ARRAY)
        module:              string[],          // SWIG .i source roots
        header:              string[],          // C++ header roots
        bridge:              string[],          // bridge code roots = [...native, build]
        cmake:               string,            // resolved CMakeLists.txt path
        cmakeDir:            string,            // dirname of cmake
        cli:                 string,            // path to crossbind CLI install
        cliCMakeListsTxt:    string,            // bundled fallback CMakeLists.txt
        systemConfig:        string,            // = ~/.crossbind.json
    },

    ext: {
        header: string[],                       // ['h','hpp','hxx','hh']
        source: string[],                       // ['c','cpp','cxx','cc']
        module: string[],                       // ['i'] — SWIG interface extensions
    },

    export: {
        type:        'cmake' | 'source',        // distribution shape
        header:      string,                    // include dir name in dist
        libPath:     string,                    // .a output dir
        libName:     string[],                  // .a basenames (one per item; e.g. ['ssl','crypto'])
        binHeaders:  string[],                  // headers to ship as raw binary blobs
    },

    target: {                                   // FILTER (restrict which targets are built)
        platform?:    'wasm' | 'android' | 'ios',
        arch?:        string,                    // 'wasm32' | 'wasm64' | 'arm64-v8a' | …
        runtime?:     'st' | 'mt',
        buildType?:   'release' | 'debug',
        runtimeEnv?:  'browser' | 'node' | 'edge',
    },

    targetSpecs: TargetSpec[],                  // per-target overrides (see § targetSpecs)

    build: {                                    // merged from crossbind.build.js (package authors only)
        withBuildConfig:      boolean,           // true if a crossbind.build.js was loaded
        buildType?:           'cmake' | 'configure',
        configureProgram?:    string,             // configure entrypoint; default './configure'
        setState?:            (state)         => void,
        beforeRun?:           (cmakeDir)      => Array<{program, parameters}>,
        getBuildParams?:      (target, depPaths, ext, buildPath) => string[],
        getExtraLibs?:        (target)        => string[],
        sourceReplaceList?:   (target, depPaths) => Array<{regex, replacement, paths}>,
        patches?:             Array<{file: URL | string, advisories?: string[]}>, // upstream fixes, applied with git apply; file is a URL or an absolute path
        env?:                 ((target) => string[]) | string[],
        copyToSource?:        Record<string, string[]>,
        copyToDist?:          Record<string, string[]>,
    },

    extensions: Extension[],                    // plugin hooks (see § Extensions)

    functions: {
        isEnabled: (target) => boolean,         // default: checks ${cmakeDir}/{target.path} or .xcframework exists
    },

    package: object | null,                     // parsed package.json of paths.project

    allDependencyPaths: {                       // per-target dependency lookup
        [target.path]: {
            cmake: { ... },
            [libName]: { root, header, libPath, lib, bin },
        },
    },

    dependencyParameters: ...,                  // CMake -D injection from calculateDependencyParameters()
}

`state.cache`

Persisted to `.crossbind/cache.json` between builds:

state.cache = {
    hashes:     Record<string, string>,         // file hash → seen?
    interfaces: Record<string, string>,         // SWIG .i hash cache
    bridges:    Record<string, string>,         // bridge code cache
}

`isSourceNewer` checks mtime against this cache to decide whether to rebuild a target.

Alongside `cache.json`, the build writes fingerprint files next to its artifacts and treats a mismatch as a cache miss even when the artifact exists:

• `…/prebuilt/<target>/crossbind-nativeglob.fingerprint` — the Br