crossbind 2.0.0-beta.62 → 2.0.0-beta.64

package/src/utils/runtimeEntries.js

@@ -0,0 +1,56 @@
+// The one module a package publishes per runtime binary, dist/<runtimeEnv>/<format>.mjs. It exports every
+// bound name as an ESM live binding that initNative() fills, the way a bundler's module for a header does,
+// so `import { initNative, X } from '<package>/node/napi'` works with or without init options.
+
+const PROXY_NAMES = new Set(['initNative', 'AllSymbols']);
+
+// A name is a plain string or { local, wire }: the second exports `local` while reading the differently
+// registered `wire` off the module. Two headers may bind one name; the module exports it once.
+export function uniqueBindings(names) {
+    const seen = new Set();
+    return names
+        .map((name) => (typeof name === 'string' ? { local: name, wire: name } : name))
+        .filter(({ local }) => {
+            if (PROXY_NAMES.has(local) || seen.has(local)) return false;
+            seen.add(local);
+            return true;
+        });
+}
+
+// Each runtime's loader, imported as `boot`, and the config it boots with; the binaries sit in dist, one
+// directory above the entry.
+export const ENTRY_RUNTIMES = {
+    // The Node-API loader and the Node wasm build are both CommonJS.
+    node: (loader) => ({
+        imports: ["import { createRequire } from 'node:module';", `const boot = createRequire(import.meta.url)('../${loader}');`],
+        config: 'config',
+    }),
+    // Edge runtimes cannot compile WebAssembly from bytes, so the binary is a module import their bundler resolves.
+    edge: (loader, wasm) => ({
+        imports: [`import boot from '../${loader}';`, `import wasm from '../${wasm}';`],
+        config: '{ getWasmFunction: () => wasm, ...config }',
+    }),
+};
+
+// A bound name may be a JavaScript reserved word, which an export list accepts but a declaration does not.
+export function runtimeEntryModule(names, { imports, config }) {
+    const bindings = uniqueBindings(names);
+    return [
+        '// Generated by crossbind - do not edit.',
+        ...imports,
+        '',
+        'export let AllSymbols = {};',
+        ...bindings.map(({ local }) => `let $${local} = null;`),
+        ...(bindings.length ? [`export { ${bindings.map(({ local }) => `$${local} as ${local}`).join(', ')} };`] : []),
+        '',
+        'export function initNative(config = {}) {',
+        `    return boot(${config}).then((m) => {`,
+        '        AllSymbols = m;',
+        ...bindings.map(({ local, wire }) => `        $${local} = m.${wire};`),
+        '        return m;',
+        '    });',
+        '}',
+        'initNative.terminate = () => boot.terminate();',
+        '',
+    ].join('\n');
+}

package/src/utils/rustBridgeGen.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { followCargoLock } from './cargoLock.js';
 import resolveEmbindRustRoot, { embindRustVersion } from './resolveEmbindRust.js';
 import runCargo, { toHostPath } from './runCargo.js';
 import writeIfChanged from './writeIfChanged.js';
@@ -179,6 +180,10 @@ function matchFnSignature(line) {
     return [line, head[1], params, ret];
 }
 
+// What a lazy link pins to pull a bridge's registrations: the consumer's -u names `crossbind_keep_<lib>`.
+export const keepSymbolName = (libName) => `crossbind_keep_${libName}`;
+const keepSymbol = (libName) => `\n#[no_mangle]\npub extern "C" fn ${keepSymbolName(libName)}() {}\n`;
+
 export default function generateRustBridge({ crateDir, vectors = [], dtsFile = null, keepName = null, dtsMode = 'sync', log = console.log }) {
     const libRsPath = `${crateDir}/src/lib.rs`;
     if (!fs.existsSync(libRsPath)) throw new Error(`crossbind: rust bridge: ${libRsPath} not found`);
@@ -192,7 +197,7 @@ export default function generateRustBridge({ crateDir, vectors = [], dtsFile = n
     // own libstd, and fully loading two of them duplicates thousands of std symbols). Instead the
     // consumer pins this keep symbol (-u/--undefined); codegen-units=1 puts it in the same object
     // as the init-array constructor, so pulling it pulls the registrations - and only them.
-    if (keepName) bridge += `\n#[no_mangle]\npub extern "C" fn crossbind_keep_${keepName}() {}\n`;
+    if (keepName) bridge += keepSymbol(keepName);
     if (dtsFile) writeIfChanged(dtsFile, emitDts(model, vectors, dtsMode));
 
     const bridgeDir = `${crateDir}/.crossbind/bridge-crate`;
@@ -234,7 +239,8 @@ export default function generateRustBridge({ crateDir, vectors = [], dtsFile = n
 // crate: the user file is embedded via `#[path] mod user;` (no copy) and the bridge lives in the
 // same crate, so registrations reference `user::Type` directly. The bundler transformer calls
 // this on import (like createBridgeFile for C++); the native builds compile every crate under
-// <project>/.crossbind/rust-bridges/ and link the staticlibs whole-archive.
+// <project>/.crossbind/rust-bridges/ into one staticlib and link it whole-archive, or on Windows
+// through the keep symbol each bridge exports.
 export function createRustBridgeCrate({ rsFile, cacheDir, projectPath, vectors = [], cargoDependencies = {}, dtsMode = 'sync', log = console.log }) {
     const stem = path.basename(rsFile, '.rs').replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
     const dir = `${cacheDir}/rust-bridges/${stem}`;
@@ -280,7 +286,7 @@ export function createRustBridgeCrate({ rsFile, cacheDir, projectPath, vectors =
     ].join('\n');
 
     writeIfChanged(`${dir}/Cargo.toml`, manifest);
-    writeIfChanged(`${dir}/src/lib.rs`, bridge);
+    writeIfChanged(`${dir}/src/lib.rs`, bridge + keepSymbol(`${stem}_crossbind_app`));
     // Relative `./x.rs` imports are typed by path resolution (ambient declarations only work
     // for non-relative names like `cargo:x`), so the declaration mirrors the project-relative
     // path under the language-neutral <cache>/types/ overlay (same home as .h declarations);
@@ -298,7 +304,9 @@ export function createRustBridgeCrate({ rsFile, cacheDir, projectPath, vectors =
 // through the root and through a module registers once and is the same JS class for both.
 const crateSourceCache = new Map();
 const crateModelCache = new Map();
-export function createCrateImportBridge({ crateName, modulePath = [], spec, cacheDir, dtsMode = 'sync', log = console.log }) {
+export function createCrateImportBridge({
+    crateName, modulePath = [], spec, cacheDir, projectDir, dtsMode = 'sync', log = console.log,
+}) {
     const importName = [crateName, ...modulePath].join('/');
     const crateIdent = crateName.replaceAll('-', '_');
     const stem = `crate_${crateName.replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase()}`;
@@ -338,7 +346,9 @@ export function createCrateImportBridge({ crateName, modulePath = [], spec, cach
     // cargo metadata needs a resolvable lib target before the real bridge exists.
     if (!fs.existsSync(`${dir}/src/lib.rs`)) writeIfChanged(`${dir}/src/lib.rs`, '// crossbind placeholder\n');
 
-    const { srcDir, features } = crateSource({ dir, depLine, crateName, importName });
+    const { srcDir, features } = crateSource({
+        dir, depLine, crateName, importName, projectDir,
+    });
     const ownKey = modulePath.join('::');
     const imports = [];
     for (const importPath of crateImports(cacheDir, crateName, modulePath)) {
@@ -367,7 +377,7 @@ export function createCrateImportBridge({ crateName, modulePath = [], spec, cach
     writeIfChanged(`${dir}/Cargo.toml`, manifestWith(shared.model.usesJson ? jsonDeps : []));
     writeIfChanged(`${dir}/src/lib.rs`, emitBridge(shared.model, {
         userCrate: crateIdent, vectors: [], log, rustPaths: shared.rustPaths, wireNames: shared.wireNames,
-    }));
+    }) + keepSymbol(`${stem}_crossbind_app`));
     for (const { modulePath: importPath } of imports) {
         writeImportDts({ cacheDir, crateName, modulePath: importPath, shared, dtsMode });
     }
@@ -380,10 +390,14 @@ export function createCrateImportBridge({ crateName, modulePath = [], spec, cach
 }
 
 // cargo metadata locates the crate's source and the feature set it resolves to (fetching the crate
-// on first use); both hold for every import of the crate.
-function crateSource({ dir, depLine, crateName, importName }) {
+// on first use); both hold for every import of the crate. It resolves with the project's pins, so
+// the bridge is made from the version the app links.
+function crateSource({
+    dir, depLine, crateName, importName, projectDir,
+}) {
     const cacheKey = `${dir}|${depLine}`;
     if (crateSourceCache.has(cacheKey)) return crateSourceCache.get(cacheKey);
+    followCargoLock(projectDir, dir);
     let meta;
     try {
         const probe = runCargo(['metadata', '--format-version', '1', '--manifest-path', `${dir}/Cargo.toml`], {

package/src/utils/rustMt.js

@@ -1,9 +1,13 @@
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 
 // One argv per flag: runCargo joins these with cargo's 0x1F separator, so a flag must not
 // contain a space of its own.
 const MT_RUSTFLAGS = ['-Ctarget-feature=+atomics,+bulk-memory,+mutable-globals'];
+// A musl std links Rust's own static libunwind under crt-static, its default; the addon's C++ already
+// unwinds through libgcc_s, and one module must not carry two unwinders.
+const MUSL_RUSTFLAGS = ['-Ctarget-feature=-crt-static'];
 
 // mt (shared-memory) wasm needs every Rust object built with the atomics/bulk-memory features,
 // std included - and rustup ships only a featureless std. The nightly-only -Zbuild-std rebuild
@@ -36,6 +40,10 @@ export function cargoTargetDirFor(baseDir, target) {
 // points at whatever version that image pinned, so the CLI carries no version of its own.
 const CONTAINER_SYSROOT = '/opt/crossbind/rust/current';
 
+// True only inside the toolchain image. A CLI running there with RUNNER=LOCAL (the playground
+// compiler) has these trees, but not rustup's stock wasm target.
+export const hasContainerSysroot = () => fs.existsSync(CONTAINER_SYSROOT);
+
 export function cargoBuildInvocation({
     target, triple, targetDir, manifestPath, sysroot = false,
 }) {
@@ -66,6 +74,7 @@ export function cargoBuildInvocation({
         rustflags: [
             ...(wasmSysroot ? ['--sysroot', wasmSysroot] : []),
             ...(isMt ? MT_RUSTFLAGS : []),
+            ...(target.platform === 'linuxmusl' ? MUSL_RUSTFLAGS : []),
         ],
         panic: target.platform === 'wasm' ? 'abort' : undefined,
         // Only the nightly build-std rebuild needs unstable flags; where a sysroot answers, stable

package/src/utils/rustSysroot.js

@@ -5,7 +5,7 @@ import { spawnSync } from 'node:child_process';
 import withDirLock from './dirLock.js';
 import fetchOciLayer from './ociArtifact.js';
 import { cargoRunner } from './runCargo.js';
-import { isMtWasm } from './rustMt.js';
+import { hasContainerSysroot, isMtWasm } from './rustMt.js';
 import PIN from './rustSysrootPin.js';
 
 // The second consumption channel for the Rust sysroots. A containerized build gets them as an image
@@ -149,7 +149,7 @@ let resolved = null;
 // Called from buildDependencies, the one async step every build path awaits before the sync work
 // starts. Only downloads when a target will actually consume it.
 export async function prepareRustSysroot(targets, log = console.log) {
-    if (resolved || !PIN) return resolved;
+    if (resolved || !PIN || hasContainerSysroot()) return resolved;
     if (!targets.some((target) => isMtWasm(target) && cargoRunner(target) === 'LOCAL')) return null;
     try {
         resolved = await ensureRustSysroot({ image: PIN.image, index: PIN.index });
@@ -161,11 +161,13 @@ export async function prepareRustSysroot(targets, log = console.log) {
     return resolved;
 }
 
-// What cargoBuildInvocation takes for `sysroot`: true where the image carries the trees, an
-// absolute path where a downloaded artifact answers, false where mt must rebuild std on nightly.
-// st needs nothing - rustup's stock std is already correct for it.
+// What cargoBuildInvocation takes for `sysroot`: true where the image carries the trees (also a
+// LOCAL build running inside the image), an absolute path where a downloaded artifact answers,
+// false where mt must rebuild std on nightly. st needs nothing - rustup's stock std is already
+// correct for it.
 export function sysrootFor(target) {
     if (cargoRunner(target) !== 'LOCAL') return true;
+    if (target.platform === 'wasm' && hasContainerSysroot()) return true;
     if (!isMtWasm(target)) return false;
     return resolved ?? false;
 }

package/src/utils/scopedEmbind.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+
+// Every package's loader bundles its own embind runtime, which keeps its state, and the functions its addon calls by
+// name, on globalThis and Module. Shadowing both gives each bundle a scope of its own with the real global as its
+// prototype, which the loader hands to its addon: addons of several packages then run in one process.
+export default function scopedEmbind(embindFile) {
+    const realPath = (file) => {
+        try {
+            return fs.realpathSync(file);
+        } catch (e) {
+            return file;
+        }
+    };
+    const embind = realPath(embindFile);
+    return {
+        name: 'crossbind-scoped-embind',
+        transform(code, id) {
+            if (realPath(id) !== embind) return null;
+            return `const globalThis = Object.create(global);\nconst Module = (globalThis.Module = {});\n${code}\nexport { globalThis as crossbindScope };\n`;
+        },
+    };
+}

package/src/utils/selectRunner.js

@@ -0,0 +1,81 @@
+import { cloudCredentials, cloudUrl } from './cloudAccount.js';
+import logger from './logger.js';
+import systemKeys, { assertRunner } from './systemKeys.js';
+
+const RUNNER_VARIABLE = 'CROSSBIND_RUNNER';
+const SYSTEM_CONFIG = '~/.crossbind.json';
+const SHARED = { key: 'REMOTE_URL', url: 'CROSSBIND_REMOTE_URL', token: 'CROSSBIND_TOKEN' };
+
+export const remoteVariables = (role) => {
+    const suffix = `_${role.toUpperCase()}`;
+    return { key: `${SHARED.key}${suffix}`, url: `${SHARED.url}${suffix}`, token: `${SHARED.token}${suffix}` };
+};
+
+// Unchecked, so commands that run no step still work with an invalid RUNNER, `crossbind config set` among them.
+function runnerSetting(system, env) {
+    if (env[RUNNER_VARIABLE]) return { runner: env[RUNNER_VARIABLE], name: RUNNER_VARIABLE };
+    return { runner: system?.RUNNER ?? systemKeys.RUNNER.default, name: `RUNNER in ${SYSTEM_CONFIG}` };
+}
+
+export function chosenRunner(system, env = process.env) {
+    const { runner, name } = runnerSetting(system, env);
+    return assertRunner(runner, name);
+}
+
+export const isLocalRunner = (system, env = process.env) => runnerSetting(system, env).runner === 'LOCAL';
+
+// A variable wins over the same key in the system config, and an image's own address over the shared one.
+// A token goes only to the address it is paired with, so a shared token never reaches the runner of one image.
+function remoteAddress(role, system, env) {
+    for (const names of [remoteVariables(role), SHARED]) {
+        const url = env[names.url] || system?.[names.key];
+        if (url) {
+            const from = env[names.url] ? `$${names.url}` : `${names.key} in ${SYSTEM_CONFIG}`;
+            if (!['http:', 'https:'].includes(URL.parse(url)?.protocol)) {
+                throw new Error(`crossbind: ${from} is ${JSON.stringify(url)}, not an http or https address.`);
+            }
+            return {
+                url, from, token: env[names.token], tokenVariable: names.token,
+            };
+        }
+    }
+    return null;
+}
+
+const announced = new Set();
+
+// Each image says once which runner its steps go to and which settings sent them there.
+function announce(role, remote, env) {
+    const key = `${role} ${remote.url}`;
+    if (announced.has(key)) return;
+    announced.add(key);
+    const chosenBy = env[RUNNER_VARIABLE] ? `$${RUNNER_VARIABLE}` : SYSTEM_CONFIG;
+    const shown = remote.url.replace(/\/\/[^/]*@/, '//');
+    logger.info(`crossbind: ${role} steps run on the runner at ${shown} (RUNNER=REMOTE from ${chosenBy}, address from ${remote.from}).`);
+}
+
+// A runner address named anywhere, for any image, keeps every image off the cloud: the sources go only where the
+// user sends them.
+const namesOwnRunner = (system, env) => Object.keys(systemKeys).some((key) => key.startsWith(SHARED.key) && system?.[key])
+    || Object.keys(env).some((name) => name.startsWith(SHARED.url) && env[name]);
+
+// The sign-in of `crossbind login` carries its own token; a token set for runners never reaches the cloud.
+function cloudAddress(role, system, env) {
+    const url = cloudUrl(system, env);
+    const signedIn = cloudCredentials(url);
+    if (!signedIn) return null;
+    return {
+        url: `${url}/runner/${role}`, from: `crossbind login as ${signedIn.login}`, token: signedIn.token, tokenVariable: null,
+    };
+}
+
+// Under REMOTE, an image runs on its own address, else the shared one; a machine that names no runner address at all
+// runs on crossbind cloud once signed in. Without any it gets no runner: its steps stop instead of running in the
+// local Docker, where the build would only seem to run on a runner.
+export function runnerFor(role, system, env = process.env) {
+    const runner = chosenRunner(system, env);
+    if (runner !== 'REMOTE') return { runner };
+    const remote = remoteAddress(role, system, env) ?? (namesOwnRunner(system, env) ? null : cloudAddress(role, system, env));
+    if (remote) announce(role, remote, env);
+    return { runner, remote };
+}

package/src/utils/sourceFingerprint.js

@@ -6,12 +6,13 @@ import { getContentHash } from './hash.js';
 // version, with provenance and licence metadata already claiming the new one.
 export const SOURCE_FINGERPRINT_FILE = 'crossbind-source.fingerprint';
 
-export function getSourceFingerprint(config) {
+export function getSourceFingerprint(config, target) {
     const nativeVersion = config?.package?.nativeVersion || null;
     const sha256 = config?.build?.sha256 || null;
-    // Packages that build from local sources pin neither; they keep the existence-only behaviour.
+    // Local-source packages pin neither; buildLib checks their native source inventory instead.
     if (!nativeVersion && !sha256) return null;
-    return getContentHash(JSON.stringify({ nativeVersion, sha256 }));
+    const sourceReplacements = target ? config?.build?.sourceReplaceList?.(target, config.allDependencyPaths?.[target.path] ?? {}) : undefined;
+    return getContentHash(JSON.stringify({ nativeVersion, sha256, ...(sourceReplacements?.length ? { sourceReplacements } : {}) }));
 }
 
 export function isSourceFingerprintStale(libdir, fingerprint) {

package/src/utils/swigInterface.js

@@ -16,6 +16,29 @@ export function findIgnoredDeclarations(headerFile, configs, headerPath) {
     return findHeaderOption('ignoredDeclarations', headerFile, configs, headerPath);
 }
 
+// SWIG preprocessor lines a package puts right before one of its public headers, in export.swigPreamble: GDAL hides
+// its C SRS API behind `#ifndef SWIG` for its own bindings, and picks VSIStatBufL's typedef by whether VSI_STAT64_T is
+// defined, which a macro defined as itself answers while each platform's compiler still resolves the name.
+export function findSwigPreamble(headerFile, configs, headerPath) {
+    return findHeaderOption('swigPreamble', headerFile, configs, headerPath);
+}
+
+// Includes SWIG reads inlined into one of a package's headers, in export.swigInlineIncludes. SWIG reads no #include, and
+// libgeotiff fills its key and code enums from .inc files included inside the enum bodies, where the file markers
+// -includeall wraps around an included file do not parse.
+export function findSwigInlineIncludes(headerFile, configs, headerPath) {
+    return findHeaderOption('swigInlineIncludes', headerFile, configs, headerPath);
+}
+
+const INCLUDE_LINE = /^[ \t]*#[ \t]*include[ \t]*"([^"]+)"[^\n]*$/gm;
+
+export function inlineIncludes(headerText, names, readInclude) {
+    const included = new Set([...headerText.matchAll(INCLUDE_LINE)].map(([, name]) => name));
+    const missing = names.filter((name) => !included.has(name));
+    if (missing.length) throw new Error(`crossbind: swigInlineIncludes lists ${missing.join(', ')}, which the header does not include.`);
+    return headerText.replace(INCLUDE_LINE, (line, name) => (names.includes(name) ? readInclude(name) : line));
+}
+
 function findHeaderOption(option, headerFile, configs, headerPath) {
     const file = upath.normalize(headerFile);
     let owner = null;
@@ -40,26 +63,36 @@ export function interfaceIncludes(headerPath, prelude = []) {
 
 // The prelude and the completing includes reach only the compiled wrapper and swigMacros only SWIG's parse: SWIG still
 // wraps just the imported header. The ignored declarations follow the macros, so the retry without macros keeps them.
-export function buildInterfaceContent({ moduleName, headerPath, prelude = [], completing = [], swigMacros = [], ignored = [], constants = [] }) {
+export function buildInterfaceContent({
+    moduleName, headerPath, prelude = [], completing = [], swigMacros = [], ignored = [], constants = [], preamble = [], functions = ALL_NAMES,
+    extras = [],
+}) {
     const includes = [...new Set([...interfaceIncludes(headerPath, prelude), ...completing])]
         .map((header) => `#include "${header}"`)
         .join('\n');
     const macros = swigMacros.length ? `${swigMacros.join('\n')}\n\n` : '';
     const ignores = ignored.length ? `${ignored.map((name) => `%ignore ${name};`).join('\n')}\n\n` : '';
+    // The marker keeps a preamble that starts with #define apart from the macro block the retry drops.
+    const preambleBlock = preamble.length ? `// package preamble\n${preamble.join('\n')}\n\n` : '';
+    const extraBlock = extras.length ? `${extras.join('\n')}\n\n` : '';
+    // Named constants and functions are asked for ahead of the macros, which may define an imported name. Every constant
+    // is asked for after them: SWIG binds an interface's own #define lines, and the prelude only carries other headers'
+    // values for the parse.
+    const everyConstant = constants === ALL_NAMES;
     const module = moduleName.replace(/\W/g, '_');
     return `#ifndef _${module}_I
 #define _${module}_I
 
 %module ${module}
 
-%{
+${extraBlock}%{
 ${includes}
 %}
 
-${constantRequests(constants)}%feature("shared_ptr");
+${everyConstant ? '' : constantRequests(constants)}${functionRequests(functions)}%feature("shared_ptr");
 %feature("polymorphic_shared_ptr");
 
-${macros}${ignores}%include "${headerPath}"
+${macros}${ignores}${preambleBlock}${everyConstant ? constantRequests(constants) : ''}%include "${headerPath}"
 
 #endif
 `;
@@ -71,6 +104,19 @@ function constantRequests(constants) {
     return constants.length ? `${constants.map((name) => `%feature("embind:constant") ${name};`).join('\n')}\n\n` : '';
 }
 
+// SWIG ignores every global function, then wraps the listed names again: class members, enums and constants stay. The
+// package's own ignores come after, since SWIG applies the later of two renames of a name.
+function functionRequests(functions) {
+    if (functions === ALL_NAMES) return '';
+    const names = [...new Set(functions)].sort();
+    return `%rename($ignore, %$isfunction, %$isglobal) "";\n${names.map((name) => `%rename("%s") ${name};\n`).join('')}\n`;
+}
+
+// Editor declarations need the whole header even when the compiled bridge selects functions by import.
+export function interfaceWithAllFunctions(content) {
+    return content.replace(/%rename\(\$ignore, %\$isfunction, %\$isglobal\) "";\n(?:%rename\("%s"\) [A-Za-z_]\w*;\n)*\n/g, '');
+}
+
 export function withoutSwigMacros(content) {
     return content.replace(/(%feature\("polymorphic_shared_ptr"\);\n\n)(?:#define [^\n]*\n)+\n/, '$1');
 }
@@ -333,6 +379,26 @@ function walkScopes(text, visit) {
     });
 }
 
+// Whether the token at `index` sits inside the parentheses of the declaration it belongs to: a prototype's parameter.
+function isInsideParentheses(tokens, index) {
+    let depth = 0;
+    for (let at = index - 1; at >= 0 && ![';', '{', '}'].includes(tokens[at]); at -= 1) {
+        if (tokens[at] === '(') depth += 1;
+        else if (tokens[at] === ')') depth -= 1;
+    }
+    return depth > 0;
+}
+
+// Whether a variable `name` is declared outside every class, namespace and block, as `extern int name;` is.
+export function declaresAtFileScope(text, name) {
+    let found = false;
+    walkScopes(text, (token, index, tokens, scopes) => {
+        if (token === name && scopes.every((scope) => scope.kind === 'extern') && [';', '=', '[', ','].includes(tokens[index + 1])
+            && !isInsideParentheses(tokens, index)) found = true;
+    });
+    return found;
+}
+
 // Classes, structs and enums by qualified name, including the names C typedefs give them, each mapped to the first header
 // defining it. Preprocessor branches are all read.
 export function indexTypeDefinitions(files) {

package/src/utils/systemConfig.js

@@ -0,0 +1,13 @@
+import os from 'node:os';
+import loadJson from './loadJson.js';
+import systemKeys from './systemKeys.js';
+
+export const systemConfigPath = () => `${os.homedir()}/.crossbind.json`;
+
+export default function loadSystemConfig() {
+    const system = loadJson(systemConfigPath()) || {};
+    const defaults = Object.entries(systemKeys)
+        .filter(([key]) => !(key in system))
+        .map(([key, value]) => [key, value.default]);
+    return { ...system, ...Object.fromEntries(defaults) };
+}

package/src/utils/systemKeys.js

@@ -4,12 +4,36 @@ const systemKeys = {
         default: '',
     },
     RUNNER: {
-        description: 'The execution environment for running the application.',
-        options: ['DOCKER_RUN', 'DOCKER_EXEC', 'LOCAL'],
+        description: 'Where toolchain steps run: DOCKER_RUN, DOCKER_EXEC, LOCAL, or REMOTE on the runners REMOTE_URL and REMOTE_URL_<IMAGE> name; a machine that names none builds on crossbind cloud once signed in with crossbind login. The CROSSBIND_RUNNER environment variable overrides it.',
+        options: ['DOCKER_RUN', 'DOCKER_EXEC', 'LOCAL', 'REMOTE'],
         default: 'DOCKER_RUN',
     },
+    REMOTE_URL: {
+        description: 'Under RUNNER=REMOTE, the runner of every image without an address of its own. Its token comes from the CROSSBIND_TOKEN environment variable. The CROSSBIND_REMOTE_URL environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_WEB: {
+        description: 'Under RUNNER=REMOTE, the runner of the web image: wasm builds, wasi builds and the bridge steps of every platform but android. Token: CROSSBIND_TOKEN_WEB. The CROSSBIND_REMOTE_URL_WEB environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_ANDROID: {
+        description: 'Under RUNNER=REMOTE, the runner of the android image. Token: CROSSBIND_TOKEN_ANDROID. The CROSSBIND_REMOTE_URL_ANDROID environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_LINUX: {
+        description: 'Under RUNNER=REMOTE, the runner of the linux image (linux and linuxmusl builds). Token: CROSSBIND_TOKEN_LINUX. The CROSSBIND_REMOTE_URL_LINUX environment variable overrides it.',
+        default: '',
+    },
+    REMOTE_URL_WINDOWS: {
+        description: 'Under RUNNER=REMOTE, the runner of the windows image (win32 builds). Token: CROSSBIND_TOKEN_WINDOWS. The CROSSBIND_REMOTE_URL_WINDOWS environment variable overrides it.',
+        default: '',
+    },
+    CLOUD_URL: {
+        description: 'The crossbind cloud that crossbind login, logout and usage talk to. The CROSSBIND_CLOUD_URL environment variable overrides it.',
+        default: 'https://api.crossbind.dev',
+    },
     WASI_SDK_PATH: {
-        description: 'Path to an extracted wasi-sdk (>= 34, wasm32-wasip3 sysroot) used by platform:\'wasi\' builds. The CROSSBIND_WASI_SDK_PATH environment variable overrides it.',
+        description: 'Path to an extracted wasi-sdk (>= 34, wasm32-wasip3 sysroot) that platform:\'wasi\' builds use under RUNNER=LOCAL; the other runners use the sdk in the image. The CROSSBIND_WASI_SDK_PATH environment variable overrides it.',
         default: '',
     },
     DOCKER_REGISTRY_MIRROR: {
@@ -35,3 +59,11 @@ const systemKeys = {
 };
 
 export default systemKeys;
+
+// Read as LOCAL, a runner crossbind does not know would run recipes and build scripts on the host.
+export function assertRunner(runner, name = 'RUNNER') {
+    if (!systemKeys.RUNNER.options.includes(runner)) {
+        throw new Error(`crossbind: the runner ${runner} is invalid; ${name} is one of ${systemKeys.RUNNER.options.join(', ')}.`);
+    }
+    return runner;
+}

package/src/utils/targets.js

@@ -1,7 +1,7 @@
 // Single source for the build-target matrix and its naming; state/ copies (and then
 // decorates) these entries, and consumer runtimes read them without touching CLI state.
 
-export const TARGETS = [
+const BASE_TARGETS = [
     {
         platform: 'wasm', arch: 'wasm32', runtime: 'st', buildType: 'release', runtimeEnv: 'browser',
     },
@@ -63,10 +63,16 @@ export const TARGETS = [
         platform: 'wasm', arch: 'wasm64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
     },
     {
-        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'release',
+        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'release', runtimeEnv: 'wasi',
+    },
+    {
+        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'debug', runtimeEnv: 'wasi',
     },
     {
-        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'debug',
+        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'release', runtimeEnv: 'http',
+    },
+    {
+        platform: 'wasi', arch: 'wasm32', runtime: 'st', buildType: 'debug', runtimeEnv: 'http',
     },
     {
         platform: 'android', arch: 'arm64-v8a', runtime: 'mt', buildType: 'release',
@@ -116,6 +122,18 @@ export const TARGETS = [
     {
         platform: 'linux', arch: 'x64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
     },
+    {
+        platform: 'linuxmusl', arch: 'arm64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linuxmusl', arch: 'arm64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linuxmusl', arch: 'x64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
+    },
+    {
+        platform: 'linuxmusl', arch: 'x64', runtime: 'mt', buildType: 'debug', runtimeEnv: 'node',
+    },
     {
         platform: 'win32', arch: 'arm64', runtime: 'mt', buildType: 'release', runtimeEnv: 'node',
     },
@@ -130,17 +148,43 @@ export const TARGETS = [
     },
 ];
 
+// A native executable links the same archives as the Node-API addon of its platform and arch.
+export const TARGETS = [
+    ...BASE_TARGETS,
+    ...BASE_TARGETS
+        .filter((target) => target.runtimeEnv === 'node' && target.platform !== 'wasm')
+        .map((target) => ({ ...target, runtimeEnv: 'native' })),
+];
+
 // Built only when named with -p: a plain `crossbind build` keeps producing what it did before
 // native Node.js addons existed.
-export const OPT_IN_PLATFORMS = ['darwin', 'linux', 'win32'];
+export const OPT_IN_PLATFORMS = ['darwin', 'linux', 'linuxmusl', 'win32'];
 
 // Built on the host itself: Apple's linker and SDKs exist in no toolchain image.
 export const HOST_BUILT_PLATFORMS = ['ios', 'darwin'];
 
+// The runtime environment names the binary a build makes; android and ios have none, since
+// React Native links them.
+export const runtimeEnvsOf = (platform) => [
+    ...new Set(TARGETS.filter((target) => target.platform === platform && target.runtimeEnv).map((target) => target.runtimeEnv)),
+];
+
+export const RUNTIME_ENVS = [...new Set(TARGETS.map((target) => target.runtimeEnv).filter(Boolean))];
+
+// A build makes only the binaries it is asked for: -e first, then the config's target.runtimeEnv.
+// Bundler plugins ask through getTargetParams instead.
+export function selectRuntimeEnvs(cliRuntimeEnvs, configRuntimeEnv) {
+    if (cliRuntimeEnvs?.length) return cliRuntimeEnvs;
+    return configRuntimeEnv ? [configRuntimeEnv] : [];
+}
+
 export function targetPathOf(target) {
     return `${target.platform}-${target.arch}-${target.runtime}-${target.buildType}`;
 }
 
+// The release build of a target, whose prebuilts a debug build of it falls back to.
+export const releaseTargetOf = (target) => ({ ...target, buildType: 'release', path: target.releasePath });
+
 // Every platform/arch addon of one build type sits next to a single loader, which fills in
 // {platform} and {arch} from the running process. The loader is CommonJS whatever the package
 // "type" says, since it needs __dirname and process.dlopen.
@@ -154,6 +198,18 @@ export function nodeAddonNamesOf(target, projectName) {
     };
 }
 
+// A wasi build is one component, with no JS glue: the command keeps the plain name, an http component adds its own.
+export const wasiNamesOf = (target, projectName) => ({
+    wasmName: `${projectName}-${targetPathOf(target)}${target.runtimeEnv === 'http' ? '.http' : ''}.wasm`,
+});
+
+// One executable per platform, arch and build type, named like the addons it replaces.
+export function nativeCommandNamesOf(target, projectName) {
+    const suffix = target.buildType === 'debug' ? '.debug' : '';
+    const extension = target.platform === 'win32' ? '.exe' : '';
+    return { commandName: `${projectName}.${target.platform}-${target.arch}${suffix}${extension}` };
+}
+
 export function filterTargetSpecs(targetSpecs, target) {
     return targetSpecs?.filter(t => (
         (!t.platform || t.platform === target.platform)

package/src/utils/toolchainNotices.js

@@ -0,0 +1,5 @@
+// Where a build keeps the notices of the runtime a toolchain image linked into its binaries,
+// relative to the build directory; crossbind licenses reads them from there.
+export default function toolchainNoticesDir(platform) {
+    return `toolchain-licenses/${platform}`;
+}