crossbind 2.0.0-beta.62 → 2.0.0-beta.63

package/src/state/attachConanDependencies.js

@@ -0,0 +1,56 @@
+import { getFilledConfig, flattenDependencies } from './loadConfig.js';
+import calculateDependencyParameters from './calculateDependencyParameters.js';
+import { conanStageDir, conanPackageDir } from '../utils/conanImport.js';
+import { conanDependenciesKey } from '../utils/conanDependencies.js';
+import { readConanManifest, conanTargetName } from '../utils/conanStage.js';
+import { TARGETS, targetPathOf } from '../utils/targets.js';
+
+// What a recipe declares for its consumers, per staged target since it declares other things on another
+// platform: the defines your code compiles with, and the system libraries and frameworks a Node.js addon
+// or a native executable links. A framework goes as one linker argument: CMake collapses a repeated
+// -framework. A debug build takes the release packages, so the build type is left out, and a target's
+// specs stay one object, as getData takes them.
+function targetSpecsOf(name, targets) {
+    return Object.entries(targets).flatMap(([targetPath, packages]) => {
+        const target = TARGETS.find((t) => targetPathOf(t) === targetPath);
+        const pkg = packages.find((entry) => entry.name === name);
+        if (!target || !pkg) return [];
+        const compileOptions = pkg.defines.map((define) => `-D${define}`);
+        const addonFlags = [...pkg.frameworks.map((framework) => `-Wl,-framework,${framework}`), ...pkg.systemLibs.map((lib) => `-l${lib}`)];
+        const specs = {
+            ...(compileOptions.length > 0 ? { cmake: { compileOptions } } : {}),
+            ...(addonFlags.length > 0 ? { binary: { addonFlags } } : {}),
+        };
+        if (Object.keys(specs).length === 0) return [];
+        return [{
+            platform: target.platform, arch: target.arch, runtime: target.runtime, specs,
+        }];
+    });
+}
+
+// Every library a recipe names on some target (libpng is png16 on Windows): a target links the archives
+// staged for it, so a name it lacks drops out there.
+const libsOf = (name, targets) => [...new Set(Object.values(targets).flat().filter((entry) => entry.name === name).flatMap((entry) => entry.libs))];
+
+export function conanDependencyConfigs(manifest, stageDir) {
+    return manifest.packages.map((pkg) => ({
+        general: { name: conanTargetName(pkg.name), conan: pkg },
+        export: { type: 'cmake', libName: libsOf(pkg.name, manifest.targets) },
+        paths: { project: conanPackageDir(stageDir, pkg.name), output: `${conanPackageDir(stageDir, pkg.name)}/dist` },
+        targetSpecs: targetSpecsOf(pkg.name, manifest.targets),
+    }));
+}
+
+// The staged Conan packages join the config as dependencies, so header resolution, the link, the
+// cmake graph and the license rows see them like any port. Only packages staged for the current
+// conanDependencies join; reading the manifest runs nothing, so state can do it while it loads.
+export default function attachConanDependencies(config) {
+    const isDeclared = Object.keys(config.conanDependencies ?? {}).length > 0;
+    if (!isDeclared && !config.dependencies?.some((d) => d.general.conan)) return;
+    const stageDir = conanStageDir(config.paths.cache);
+    const manifest = isDeclared ? readConanManifest(stageDir, conanDependenciesKey(config.conanDependencies)) : null;
+    const conan = manifest ? conanDependencyConfigs(manifest, stageDir).map((d) => getFilledConfig(d, { isDepend: true })) : [];
+    config.dependencies = [...config.dependencies.filter((d) => !d.general.conan), ...conan];
+    config.allDependencies = flattenDependencies(config.dependencies);
+    config.dependencyParameters = calculateDependencyParameters(config);
+}

package/src/state/index.js

@@ -1,8 +1,11 @@
+import fs from 'node:fs';
 import loadJson from '../utils/loadJson.js';
 import writeJson from '../utils/writeJson.js';
-import { TARGETS, targetPathOf, nodeAddonNamesOf } from '../utils/targets.js';
+import { TARGETS, targetPathOf, nodeAddonNamesOf, nativeCommandNamesOf } from '../utils/targets.js';
 import { findCargoModuleImportsIn, writeCargoMarker } from '../utils/cargoImport.js';
-import loadConfig from './loadConfig.js';
+import { exportWasiSdkPath } from '../utils/wasiToolchain.js';
+import loadConfig, { assertBinarySelection } from './loadConfig.js';
+import refreshConanDependencies from './refreshConanDependencies.js';
 
 const cacheDir = `${process.cwd()}/.crossbind`;
 
@@ -21,12 +24,9 @@ await initProcessState();
 async function initProcessState() {
     state.cache = loadCacheState();
     state.config = await loadConfig();
-    // Recipes read the wasi-sdk location from the environment (lazily, in
-    // getBuildParams); mirror the system-config value there so both sources
-    // behave the same.
-    if (state.config.system.WASI_SDK_PATH && !process.env.CROSSBIND_WASI_SDK_PATH) {
-        process.env.CROSSBIND_WASI_SDK_PATH = state.config.system.WASI_SDK_PATH;
-    }
+    assertBinarySelection(state.config);
+    refreshConanDependencies(state.config);
+    exportWasiSdkPath(state.config.system);
     // Same idea for the docker image overrides: pullDockerImage.js resolves them from the
     // environment alone, so it stays free of a state import (and of the cycle that would create).
     Object.entries({
@@ -58,6 +58,9 @@ async function initProcessState() {
         if (target.runtimeEnv === 'node' && target.platform !== 'wasm') {
             Object.assign(target, nodeAddonNamesOf(target, state.config.general.name));
         }
+        if (target.runtimeEnv === 'native') {
+            Object.assign(target, nativeCommandNamesOf(target, state.config.general.name));
+        }
     });
 
     setAllDependecyPaths();
@@ -89,7 +92,12 @@ export function setAllDependecyPaths() {
         state.config.allDependencyPaths[target.path] = { cmake: {} };
         state.config.allDependencies.forEach((d) => {
             state.config.allDependencyPaths[target.path].cmake[d.general.name] = `${d.paths.output}/prebuilt`;
-            d.export.libName.forEach((name) => {
+            // A Conan recipe can name a library on another platform only (libpng is png16 on Windows).
+            const libNames = d.general.conan
+                ? d.export.libName.filter((name) => [target.path, target.releasePath]
+                    .some((targetPath) => fs.existsSync(`${d.paths.output}/prebuilt/${targetPath}/lib/lib${name}.a`)))
+                : d.export.libName;
+            libNames.forEach((name) => {
                 state.config.allDependencyPaths[target.path][name] = {
                     root: `${d.paths.output}/prebuilt/${target.path}`,
                 };

package/src/state/loadConfig.js

@@ -12,8 +12,23 @@ import fixPackageName from '../utils/fixPackageName.js';
 import getCMakeListsFilePath from '../utils/getCMakeListsFilePath.js';
 import calculateDependencyParameters from './calculateDependencyParameters.js';
 import logger from '../utils/logger.js';
+import { RUNTIME_ENVS } from '../utils/targets.js';
+import { normalizeConanDependencies } from '../utils/conanDependencies.js';
+import isSourceCmakePackage from '../utils/isSourceCmakePackage.js';
 // import getCmakeParameters from './getCmakeParameters.js';
 
+// For the project being built only: dependency builds load published configs that may still set
+// export.bundle.
+export function assertBinarySelection(config) {
+    if ('bundle' in config.export) {
+        throw new Error('crossbind: export.bundle was removed. A build makes binaries only for the runtime environments it is asked for: -e on the command line, target.runtimeEnv in crossbind.config.js, or a bundler plugin. Remove export.bundle.');
+    }
+    const { runtimeEnv } = config.target;
+    if (runtimeEnv !== undefined && runtimeEnv !== null && !RUNTIME_ENVS.includes(runtimeEnv)) {
+        throw new Error(`crossbind: target.runtimeEnv must be one of ${RUNTIME_ENVS.join(', ')} (got ${JSON.stringify(runtimeEnv)}).`);
+    }
+}
+
 export default async function loadConfig(configDir = process.cwd(), configName = 'crossbind.config') {
     const config = await loadJs(configDir, configName) || {};
     if (config.excludedDependencies?.length) {
@@ -80,6 +95,15 @@ export default async function loadConfig(configDir = process.cwd(), configName =
     return output;
 }
 
+// Direct and transitive dependencies, one entry per package directory.
+export function flattenDependencies(dependencies) {
+    const output = {};
+    [...dependencies, ...dependencies.map((d) => d.allDependencies).flat()].forEach((d) => {
+        output[d.paths.project] = d;
+    });
+    return Object.values(output);
+}
+
 export function getFilledConfig(config, options = { isDepend: false }) {
     const exclude = options.exclude || [];
     const { seen, replaces } = options;
@@ -101,6 +125,7 @@ export function getFilledConfig(config, options = { isDepend: false }) {
         general: config.general || {},
         dependencies,
         cargoDependencies: config.cargoDependencies || {},
+        conanDependencies: normalizeConanDependencies(config.conanDependencies),
         // 'sync' types the direct surface; 'promise' wraps every generated method return
         // for useWorker-style runtimes (constructors stay sync-typed: await new X()).
         dts: config.dts || 'sync',
@@ -176,15 +201,8 @@ export function getFilledConfig(config, options = { isDepend: false }) {
     newConfig.export.libPath = getPath(newConfig.export.libPath || 'lib');
     newConfig.export.libName = newConfig.export.libName || [newConfig.general.name];
     newConfig.export.binHeaders = newConfig.export.binHeaders || [];
-    newConfig.export.bundle = newConfig.export.bundle ?? true;
 
-    newConfig.allDependencies = (() => {
-        const output = {};
-        [...newConfig.dependencies, ...newConfig.dependencies.map((d) => d.allDependencies).flat()].forEach((d) => {
-            output[d.paths.project] = d;
-        });
-        return Object.values(output);
-    })();
+    newConfig.allDependencies = flattenDependencies(newConfig.dependencies);
 
     newConfig.extensions?.forEach(e => {
         e?.loadConfig?.after(newConfig);
@@ -194,22 +212,13 @@ export function getFilledConfig(config, options = { isDepend: false }) {
         newConfig.target.runtime = 'mt';
     }
 
-    newConfig.functions.isEnabled = newConfig.functions.isEnabled || ((target) => {
-        // Source-cmake packages ship no prebuilt at all: their own CMakeLists (at the
-        // package root, not a generated dist/prebuilt one) is compiled into the consuming
-        // build via add_subdirectory, so they serve every target.
-        const isSourceCmakePackage = newConfig.export?.type === 'cmake'
-            && newConfig.paths.cmake !== newConfig.paths.cliCMakeListsTxt
-            && !newConfig.paths.cmakeDir.endsWith('/prebuilt')
-            && fs.existsSync(newConfig.paths.cmake);
-
-        return (
-            isSourceCmakePackage
-            || fs.existsSync(`${newConfig.paths.cmakeDir}/${target.path}`)
-            || fs.existsSync(`${newConfig.paths.cmakeDir}/${target.releasePath}`)
-            || (target.platform === 'ios' && fs.existsSync(`${newConfig.paths.cmakeDir}/../../${newConfig.general.name}-${target.runtime}.xcframework`))
-        );
-    });
+    // A package that ships its sources serves every target.
+    newConfig.functions.isEnabled = newConfig.functions.isEnabled || ((target) => (
+        isSourceCmakePackage(newConfig)
+        || fs.existsSync(`${newConfig.paths.cmakeDir}/${target.path}`)
+        || fs.existsSync(`${newConfig.paths.cmakeDir}/${target.releasePath}`)
+        || (target.platform === 'ios' && fs.existsSync(`${newConfig.paths.cmakeDir}/../../${newConfig.general.name}-${target.runtime}.xcframework`))
+    ));
 
     newConfig.dependencyParameters = calculateDependencyParameters(newConfig);
     // newConfig.cmakeParameters = getCmakeParameters(newConfig);

package/src/state/refreshBuiltDependencies.js

@@ -0,0 +1,20 @@
+import calculateDependencyParameters from './calculateDependencyParameters.js';
+import getAbsolutePath from '../utils/getAbsolutePath.js';
+import getCMakeListsFilePath, { getCliCMakeListsFile } from '../utils/getCMakeListsFilePath.js';
+import getParentPath from '../utils/getParentPath.js';
+
+// A dependency with no build when the config loaded resolved to the CLI's own CMakeLists, which keeps it out of the link
+// and its headers out of the dependency include roots: a process that outlives the build, such as a Metro server, takes it
+// in here. Says whether it took one in.
+export default function refreshBuiltDependencies(config) {
+    const built = (config.allDependencies ?? [])
+        .filter((dep) => dep !== config && ['cmake', 'cargo'].includes(dep.export?.type) && dep.paths.cmake === config.paths.cliCMakeListsTxt)
+        .map((dep) => ({ dep, cmake: getCMakeListsFilePath(dep.paths.output) }))
+        .filter(({ cmake }) => cmake !== getCliCMakeListsFile());
+    built.forEach(({ dep, cmake }) => {
+        dep.paths.cmake = getAbsolutePath(dep.paths.project, cmake);
+        dep.paths.cmakeDir = getParentPath(dep.paths.cmake);
+    });
+    if (built.length > 0) config.dependencyParameters = calculateDependencyParameters(config);
+    return built.length > 0;
+}

package/src/state/refreshConanDependencies.js

@@ -0,0 +1,17 @@
+import attachConanDependencies from './attachConanDependencies.js';
+import { conanStageDir } from '../utils/conanImport.js';
+import { conanManifestsStamp } from '../utils/conanStage.js';
+
+const attachedFrom = new WeakMap();
+
+// Attaches what a build staged since this config last attached: a process that loaded state before
+// the build, such as a Metro server, would otherwise bind headers without the packages. Says whether
+// it attached again.
+export default function refreshConanDependencies(config) {
+    if (Object.keys(config.conanDependencies ?? {}).length === 0) return false;
+    const stamp = conanManifestsStamp(conanStageDir(config.paths.cache));
+    if (attachedFrom.get(config) === stamp) return false;
+    attachedFrom.set(config, stamp);
+    attachConanDependencies(config);
+    return true;
+}

package/src/utils/androidToolchain.js

@@ -0,0 +1,4 @@
+// The android image's NDK, and the API level every Android archive is built against: port archives
+// and Conan packages link into the same library, so they move together.
+export const ANDROID_NDK = '/opt/android-sdk/ndk/current';
+export const ANDROID_API_LEVEL = 33;

package/src/utils/appRustCrates.js

@@ -4,7 +4,7 @@ import { cargoTripleFor } from './cargoTarget.js';
 import { isMtWasm, assertMtRustToolchain, cargoTargetDirFor, cargoBuildInvocation } from './rustMt.js';
 import runCargo from './runCargo.js';
 import { sysrootFor } from './rustSysroot.js';
-import { relPath } from './rustBridgeGen.js';
+import { keepSymbolName, relPath } from './rustBridgeGen.js';
 import writeIfChanged from './writeIfChanged.js';
 
 const SUPER = '_app_super';
@@ -56,6 +56,13 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
     if (isMt && !sysroot) assertMtRustToolchain();
 
     const superDir = `${root}/${SUPER}`;
+    // A link that cannot load the super whole pins its keep symbol, which reaches each bridge's; one object per
+    // bridge, so that symbol brings the bridge's registrations. A bridge an older crossbind wrote has none.
+    const hasKeepSymbol = (c) => {
+        const libRs = `${root}/${c}/src/lib.rs`;
+        return fs.existsSync(libRs) && fs.readFileSync(libRs, 'utf8').includes(`fn ${keepSymbolName(`${c}_crossbind_app`)}(`);
+    };
+    const kept = crates.filter(hasKeepSymbol);
     const manifest = [
         '# Generated by crossbind - do not edit. Bundles every app-local Rust surface.',
         '[package]',
@@ -73,6 +80,7 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
         '[profile.release]',
         'panic = "abort"',
         '',
+        ...crates.flatMap((c) => [`[profile.release.package.${c.replaceAll('_', '-')}-crossbind-app]`, 'codegen-units = 1', '']),
         '[workspace]',
         '',
     ].join('\n');
@@ -81,6 +89,12 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
         '// its init-array registrations) into this single staticlib.',
         ...crates.map((c) => `use ${c}_crossbind_app as _;`),
         '',
+        '#[no_mangle]',
+        `pub extern "C" fn ${keepSymbolName('crossbind_app_super')}() {`,
+        `    let keep: [extern "C" fn(); ${kept.length}] = [${kept.map((c) => `${c}_crossbind_app::${keepSymbolName(`${c}_crossbind_app`)}`).join(', ')}];`,
+        '    std::hint::black_box(keep);',
+        '}',
+        '',
     ].join('\n');
     writeIfChanged(`${superDir}/Cargo.toml`, manifest);
     writeIfChanged(`${superDir}/src/lib.rs`, lib);

package/src/utils/appSources.js

@@ -1,21 +1,112 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 
-const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.vue', '.svelte']);
-// Native projects and build outputs: large, and never the app's JavaScript.
-const SKIPPED_DIRECTORIES = new Set(['node_modules', 'dist', 'build', 'ios', 'android', 'Pods', 'target']);
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts', '.vue', '.svelte', '.html', '.astro', '.mdx']);
+// Skip root outputs, while allowing source folders named e.g. src/build or src/android.
+const ROOT_OUTPUTS = new Set(['dist', 'build', 'ios', 'android', 'Pods', 'target']);
+const IMPORT = /\b(?:from|import\s*\(?|require\s*\()\s*(['"])([^'"\n]+)\1/g;
+const packageName = (specifier) => specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
 
-// The app's own JavaScript and TypeScript sources, whose import statements say what the app uses.
+function sourceFile(file) {
+    const candidates = [file, ...[...SOURCE_EXTENSIONS].map((ext) => `${file}${ext}`), ...[...SOURCE_EXTENSIONS].map((ext) => path.join(file, `index${ext}`))];
+    return candidates.find((candidate) => {
+        if (!SOURCE_EXTENSIONS.has(path.extname(candidate))) return false;
+        try { return fs.statSync(candidate, { throwIfNoEntry: false })?.isFile(); } catch { return false; }
+    });
+}
+
+// require.resolve selects CommonJS conditions. Also read runtime export branches: a bundler may
+// choose an import/browser entry whose header imports are absent from the CommonJS entry.
+function dependencySources(specifier, importer) {
+    const name = packageName(specifier);
+    const subpath = specifier.slice(name.length);
+    for (let dir = path.dirname(importer); ; dir = path.dirname(dir)) {
+        const root = path.join(dir, 'node_modules', name);
+        const manifest = path.join(root, 'package.json');
+        if (fs.existsSync(manifest)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+                let entry = pkg.exports;
+                let wildcard;
+                if (entry && typeof entry === 'object' && !Array.isArray(entry) && Object.keys(entry).some((key) => key.startsWith('.'))) {
+                    const key = `.${subpath}`;
+                    entry = entry[key];
+                    if (entry === undefined) {
+                        for (const pattern of Object.keys(pkg.exports).filter((key) => key.includes('*')).sort((a, b) => b.length - a.length)) {
+                            const [before, after] = pattern.split('*');
+                            if (key.startsWith(before) && key.endsWith(after) && key.length >= before.length + after.length) {
+                                wildcard = key.slice(before.length, key.length - after.length);
+                                entry = pkg.exports[pattern];
+                                break;
+                            }
+                        }
+                    }
+                } else if (subpath) entry = undefined;
+                const targets = (value) => typeof value === 'string' ? [value]
+                    : Array.isArray(value) ? value.flatMap(targets)
+                    : value && typeof value === 'object' ? Object.entries(value).filter(([condition]) => condition !== 'types').flatMap(([, branch]) => targets(branch)) : [];
+                const entries = pkg.exports ? targets(entry)
+                    : subpath ? [`.${subpath}`] : [pkg.module, typeof pkg.browser === 'string' ? pkg.browser : null, pkg.main ?? 'index.js'];
+                return entries.filter(Boolean).flatMap((target) => {
+                    const file = path.resolve(root, wildcard === undefined ? target : target.replaceAll('*', wildcard));
+                    if (path.relative(root, file).startsWith('..')) return [];
+                    return sourceFile(file) ?? [];
+                });
+            } catch { return []; }
+        }
+        if (path.dirname(dir) === dir) return [];
+    }
+}
+
+// Own sources and the dependency modules they reach. Follow imports rather than walking every installed package.
 export default function appSourceFiles(projectDir) {
     const files = [];
     const walk = (dir) => {
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            if (entry.name.startsWith('.') || SKIPPED_DIRECTORIES.has(entry.name)) continue;
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || (dir === projectDir && ROOT_OUTPUTS.has(entry.name))) continue;
             const full = path.join(dir, entry.name);
             if (entry.isDirectory()) walk(full);
             else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name))) files.push(full);
         }
     };
-    walk(projectDir);
+    if (projectDir && fs.existsSync(projectDir)) walk(projectDir);
+    let dependencies = {};
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8'));
+        dependencies = { ...pkg.dependencies, ...pkg.optionalDependencies, ...pkg.peerDependencies };
+    } catch { /* A source-only project has no package manifest. */ }
+    const ownFiles = new Set(files);
+    const visited = new Set(files.map((file) => fs.realpathSync(file)));
+    for (let i = 0; i < files.length; i += 1) {
+        const importer = files[i];
+        const require = createRequire(importer);
+        const text = fs.readFileSync(importer, 'utf8');
+        for (const [, , specifier] of text.matchAll(IMPORT)) {
+            const relative = specifier.startsWith('.');
+            if (!relative && ownFiles.has(importer) && !Object.hasOwn(dependencies, packageName(specifier))) continue;
+            const resolvedFiles = relative ? [] : dependencySources(specifier, importer);
+            try { resolvedFiles.push(require.resolve(specifier)); } catch {
+                if (relative) resolvedFiles.push(sourceFile(path.resolve(path.dirname(importer), specifier)));
+            }
+            for (const resolved of resolvedFiles) {
+                if (!resolved || !SOURCE_EXTENSIONS.has(path.extname(resolved)) || !fs.existsSync(resolved)) continue;
+                const real = fs.realpathSync(resolved);
+                if (visited.has(real)) continue;
+                visited.add(real);
+                files.push(resolved);
+            }
+        }
+    }
     return files;
 }
+
+// Whether a changed file is one of those sources.
+export function isAppSource(projectDir, file) {
+    const relative = path.relative(projectDir, file);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return false;
+    const parts = relative.split(path.sep);
+    return SOURCE_EXTENSIONS.has(path.extname(file))
+        && parts.every((part) => !part.startsWith('.'))
+        && !ROOT_OUTPUTS.has(parts[0]);
+}

package/src/utils/archiveFlags.js

@@ -0,0 +1,12 @@
+// Every archive linked into one wasm module must agree on exception handling, SIMD, threads and
+// 64-bit memory, or wasm-ld refuses it. Port recipes, the app's own libraries and Conan packages all
+// take their flags from here.
+export const WASM_EXCEPTION_FLAGS = ['-fwasm-exceptions'];
+
+export function targetArchiveFlags(target) {
+    return [
+        ...(target.runtime === 'mt' ? ['-pthread'] : []),
+        ...(target.platform === 'wasm' ? ['-msimd128'] : []),
+        ...(target.platform === 'wasm' && target.arch === 'wasm64' ? ['-sMEMORY64=1'] : []),
+    ];
+}

package/src/utils/boundHeaders.js

@@ -0,0 +1,79 @@
+// Headers of dependencies that a build binds whole (export.bindings.headers), the way an app's
+// `import * as x from '<pkg>/<header>'` would: a package that ships prebuilt bindings has no app
+// importing them. An entry is a header path, or a package name standing for every header the package
+// lists in export.publicHeaders.
+
+import { releaseTargetOf } from './targets.js';
+
+const isName = (entry) => typeof entry === 'string' && entry.length > 0;
+
+function publicHeadersOf(packageName, dependencies) {
+    const owner = dependencies.find((d) => [d.package?.name, d.general?.alias?.package].includes(packageName)
+        && d.export?.publicHeaders?.length);
+    if (!owner) {
+        throw new Error(`crossbind: export.bindings.headers names ${packageName}, but no dependency of that name lists export.publicHeaders.`);
+    }
+    return owner.export.publicHeaders.map((header) => `${packageName}/${header}`);
+}
+
+export function boundHeaderSpecifiers({ export: exportConfig, ext, allDependencies }) {
+    const entries = exportConfig.bindings?.headers ?? [];
+    if (!Array.isArray(entries) || !entries.every(isName)) {
+        throw new Error('crossbind: export.bindings.headers must list header paths or package names.');
+    }
+    const isHeader = new RegExp(`\\.(${ext.header.join('|')})$`);
+    return [...new Set(entries.flatMap((entry) => (isHeader.test(entry) ? [entry] : publicHeadersOf(entry, allDependencies))))];
+}
+
+// The bridges come from one target's headers and macros. A linux target goes first, since every host
+// builds one, so a package comes out the same on any machine.
+const BRIDGE_PLATFORM_ORDER = ['linux', 'linuxmusl', 'win32', 'darwin'];
+const bridgeRank = ({ platform }) => {
+    const rank = BRIDGE_PLATFORM_ORDER.indexOf(platform);
+    return rank < 0 ? BRIDGE_PLATFORM_ORDER.length : rank;
+};
+export const bridgeTargetOrder = (targets) => [...targets].sort((a, b) => bridgeRank(a) - bridgeRank(b));
+
+// A macOS host without Docker builds no linux addon, so the targets of the runtime environment it does not
+// build are candidates too: a linux package installed beside it gives the same bridges a linux build made.
+export const bridgeTargets = (buildTargets, allTargets) => bridgeTargetOrder([
+    ...buildTargets,
+    ...allTargets.filter((target) => target.platform !== 'wasm' && !buildTargets.includes(target)
+        && buildTargets.some((built) => built.runtimeEnv === target.runtimeEnv)),
+]);
+
+// A Node build reads the app's headers for the first of its own targets, in its release form, since Conan
+// packages are staged for release targets only.
+export const nodeBridgeTarget = (targets) => releaseTargetOf(bridgeTargetOrder(targets)[0]);
+
+function resolveOrNull(resolve, specifier, target) {
+    try {
+        return resolve(specifier, target);
+    } catch {
+        return null;
+    }
+}
+
+// A desktop build has no target that every platform package covers, so each header resolves under
+// the first target whose dependency ships it.
+export function resolveBoundHeaders(specifiers, targets, resolve) {
+    return specifiers.map((specifier) => {
+        const target = targets.find((t) => resolveOrNull(resolve, specifier, t));
+        if (!target) {
+            throw new Error(`crossbind: export.bindings.headers: no dependency ships ${specifier} for ${targets.map((t) => t.path).join(', ')}.`);
+        }
+        return { specifier, file: resolve(specifier, target), target };
+    });
+}
+
+const OBJECT_LIKE_RENAME = /^\s*#\s*define\s+([A-Za-z_]\w*)\s+([A-Za-z_]\w*)\s*$/gm;
+const localOf = (name) => (typeof name === 'string' ? name : name.local);
+
+// A header that renames a bound function with an object-like macro (GNU libiconv binds libiconv_open as iconv_open)
+// is called by the macro's name, so the entry exports that name too.
+export function headerAliases(headerText, names) {
+    const bound = new Set(names.map(localOf));
+    return [...headerText.matchAll(OBJECT_LIKE_RENAME)]
+        .filter(([, local, wire]) => bound.has(wire) && !bound.has(local))
+        .map(([, local, wire]) => ({ local, wire }));
+}