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

package/src/utils/runCargo.js

@@ -1,4 +1,4 @@
-import { spawnSync, execFileSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -8,6 +8,9 @@ import replaceBasePathForDockerUtil, { DOCKER_BASE } from './replaceBasePathForD
 import pullDockerImage, { getDockerImage, getDockerContainerName, imageRoleFor } from './pullDockerImage.js';
 import { DOCKER_RUN_SECURITY_ARGS } from './dockerSecurity.js';
 import { HOST_BUILT_PLATFORMS } from './targets.js';
+import assertExecContainer from './execContainer.js';
+import { remoteExecParams, baseMount } from './remoteRunner.js';
+import { runnerFor } from './selectRunner.js';
 
 // Every cargo invocation crossbind makes goes through here.
 //
@@ -60,6 +63,26 @@ const CONFIG_NAMES = ['config.toml', 'config'];
 // cargo's upward config search finds nothing.
 const CONTAINER_CARGO_HOME = '/var/cache/crossbind/cargo';
 const CONTAINER_CWD = '/tmp/crossbind-cargo';
+// What the host reads out of the registry a remote runner keeps: crate sources, for bridge generation, one
+// folder per crate version or git revision.
+const REMOTE_CARGO_HOME_OUTPUTS = ['registry/src/*/*', 'git/checkouts/*/*'];
+
+// The crate a cargo call names travels whole, with every crate its `path =` dependencies reach (embind-rs,
+// the generated bridges); their target folders stay on a remote runner. A `path` naming a file ([lib]
+// path) holds no Cargo.toml and is skipped.
+function crateFolders(args) {
+    const at = args.indexOf('--manifest-path');
+    if (at === -1) return [];
+    const folders = new Set();
+    const visit = (dir) => {
+        const manifest = path.join(dir, 'Cargo.toml');
+        if (folders.has(dir) || !fs.existsSync(manifest)) return;
+        folders.add(dir);
+        for (const [, rel] of fs.readFileSync(manifest, 'utf8').matchAll(/\bpath\s*=\s*"([^"]+)"/g)) visit(path.resolve(dir, rel));
+    };
+    visit(path.dirname(path.resolve(args[at + 1])));
+    return [...folders];
+}
 
 // Crossbind-owned and machine-wide: $CARGO_HOME/config.toml is one of the discovery legs, so the
 // registry cache lives somewhere we can assert is clean instead of in the user's ~/.cargo. It is
@@ -111,9 +134,8 @@ export function assertCleanConfigChain(home, cwd) {
 // Apple targets link with Xcode, which is in no image, so their Rust stays on the host - as does
 // every build under RUNNER=LOCAL.
 export function cargoRunner(target) {
-    if (HOST_BUILT_PLATFORMS.includes(target?.platform)) return 'LOCAL';
-    const runner = state.config?.system?.RUNNER;
-    return runner === 'DOCKER_RUN' || runner === 'DOCKER_EXEC' ? runner : 'LOCAL';
+    const { runner } = runnerFor(imageRoleFor(target), state.config?.system);
+    return HOST_BUILT_PLATFORMS.includes(target?.platform) ? 'LOCAL' : runner;
 }
 
 function allowedEnv() {
@@ -154,52 +176,6 @@ function createHint(name, base, home, image) {
     ].join('\n');
 }
 
-function samePath(a, b) {
-    const real = (p) => {
-        try {
-            return fs.realpathSync(p);
-        } catch {
-            return path.resolve(p);
-        }
-    };
-    return real(a) === real(b);
-}
-
-function assertExecContainer(name, base, home, image) {
-    const hint = createHint(name, base, home, image);
-    let info;
-    try {
-        // stderr is dropped: docker's own "No such container" would land before the message below.
-        info = JSON.parse(execFileSync('docker', ['container', 'inspect', name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }))[0];
-    } catch {
-        throw new Error(`crossbind: RUNNER=DOCKER_EXEC needs a container named '${name}', which does not exist.\n${hint}`);
-    }
-    if (!info?.State?.Running) {
-        throw new Error(
-            `crossbind: the container '${name}' exists but is not running. Start it with \`docker start ${name}\`, or recreate it.\n${hint}`,
-        );
-    }
-    for (const [destination, source] of [
-        [DOCKER_BASE, base],
-        [CONTAINER_CARGO_HOME, home],
-    ]) {
-        const mount = (info.Mounts ?? []).find((m) => m.Destination === destination);
-        if (!mount || !samePath(mount.Source, source)) {
-            const found = mount ? ` - it mounts ${mount.Source} there` : '';
-            throw new Error(
-                `crossbind: the container '${name}' does not mount ${source} at ${destination}${found}. It predates the cargo mount, so recreate it.\n${hint}`,
-            );
-        }
-    }
-    // `docker run --workdir` creates the directory; `docker exec --workdir` does not, and cargo
-    // dies with an OCI "chdir to cwd" error that names nothing the user can act on.
-    try {
-        execFileSync('docker', ['exec', '--user', getOsUserAndGroupId(), name, 'mkdir', '-p', CONTAINER_CWD], { stdio: 'ignore' });
-    } catch (e) {
-        throw new Error(`crossbind: could not create the working directory ${CONTAINER_CWD} inside '${name}'.\n${hint}`, { cause: e });
-    }
-}
-
 export default function runCargo(args, { cwd, rustflags = [], panic, capture = false, maxBuffer, allowUnstable = false, target } = {}) {
     const home = cargoHome();
     const workdir = cwd ?? neutralCwd();
@@ -233,12 +209,33 @@ export default function runCargo(args, { cwd, rustflags = [], panic, capture = f
         panic,
         allowUnstable,
     });
+    if (runner === 'REMOTE') {
+        return spawnSync(...remoteExecParams({
+            remote: runnerFor(role, state.config.system).remote,
+            role,
+            image: getDockerImage(role, platform),
+            mounts: [
+                baseMount(state.config, { extraOutputs: crateFolders(args) }),
+                { host: home, container: CONTAINER_CARGO_HOME, inputRoots: [], outputRoots: REMOTE_CARGO_HOME_OUTPUTS },
+            ],
+            cwd: CONTAINER_CWD,
+            argv: ['cargo', ...replaceBasePathForDockerUtil(args, base)],
+            env,
+        }, options));
+    }
+
     const envArgs = Object.entries(env).flatMap(([key, value]) => ['-e', `${key}=${value}`]);
 
     let runnerArgs;
     if (runner === 'DOCKER_EXEC') {
         const name = getDockerContainerName(base, role);
-        assertExecContainer(name, base, home, getDockerImage(role, platform));
+        assertExecContainer({
+            name,
+            mounts: [[DOCKER_BASE, base], [CONTAINER_CARGO_HOME, home]],
+            workdir: CONTAINER_CWD,
+            hint: createHint(name, base, home, getDockerImage(role, platform)),
+            mountNote: 'It predates the cargo mount, so recreate it.',
+        });
         runnerArgs = ['exec', ...envArgs, '--user', getOsUserAndGroupId(), '--workdir', CONTAINER_CWD, name];
     } else {
         pullDockerImage(role, platform);

package/src/utils/runConan.js

@@ -0,0 +1,257 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import getOsUserAndGroupId from './getOsUserAndGroupId.js';
+import makeTreeWritable from './makeTreeWritable.js';
+import pullDockerImage, { getDockerImage, getDockerContainerName, imageRoleFor } from './pullDockerImage.js';
+import { DOCKER_RUN_SECURITY_ARGS } from './dockerSecurity.js';
+import assertExecContainer from './execContainer.js';
+import { IOS_DEVELOPER_DIR, XCODE_TOOLCHAIN_BIN } from './iosToolchain.js';
+import { DARWIN_CC, DARWIN_TOOLS_BIN } from './darwinToolchain.js';
+import { HOST_BUILT_PLATFORMS } from './targets.js';
+import { remoteExecParams } from './remoteRunner.js';
+import { runnerFor } from './selectRunner.js';
+
+// Every conan invocation crossbind makes goes through here. The config is passed in instead of read
+// from state, because state attaches the staged Conan packages while it is still being built.
+//
+// A Conan home holds code conan runs (plugins, hooks) and settings every recipe obeys (global.conf,
+// remotes), and the recipes it builds can write to it. So every run gets a home of its own, made in a
+// fresh work directory and deleted with it; only the package store outlives a run. On the host the
+// environment is rebuilt from an allowlist, so CONAN_DEFAULT_PROFILE, a stray CC or a remote's
+// credentials never reach conan.
+const ALLOWED_ENV = [
+    /^PATH$/,
+    /^HOME$/,
+    /^USER$/,
+    /^LOGNAME$/,
+    /^SHELL$/,
+    /^TERM$/,
+    /^TMPDIR$/,
+    /^TEMP$/,
+    /^TMP$/,
+    /^LANG$/,
+    /^LC_[A-Z_]+$/,
+    /^(HTTP|HTTPS|ALL|NO)_PROXY$/i,
+    /^SSL_CERT_(FILE|DIR)$/,
+    /^REQUESTS_CA_BUNDLE$/,
+    // A host Emscripten under RUNNER=LOCAL.
+    /^EMSDK(_NODE|_PYTHON)?$/,
+    /^EM_(CONFIG|CACHE)$/,
+    /^SYSTEMROOT$/i,
+    /^WINDIR$/i,
+    /^USERPROFILE$/i,
+    /^PROGRAMDATA$/i,
+];
+
+// What conan can build on the host: wasm with a host Emscripten, iOS and macOS with Xcode.
+const HOST_PLATFORMS = ['wasm', 'ios', 'darwin'];
+const APPLE_PLATFORM_NAMES = { ios: 'iOS', darwin: 'macOS' };
+// Where a container sees conanRoot(): an exec container mounts all of it here, a run container only
+// the store and its own work directory, at the same places.
+const CONTAINER_ROOT = '/var/cache/crossbind/conan';
+// The package folders conan reports, which the host stages from: downloaded binaries sit in p/<ref>/p, ones
+// conan built in b/<ref>/p. Sources and build folders stay on a remote runner.
+const REMOTE_STORE_OUTPUTS = ['p/*/p', 'b/*/p'];
+// A recipe's build log is the whole compiler output of a library.
+const MAX_BUFFER = 256 * 1024 * 1024;
+// The JSON graph carries conandata, the source URL and SHA-256 of the license rows, from 2.19 on.
+const MIN_CONAN_VERSION = [2, 19];
+
+export function conanRunner(config, target) {
+    const { runner } = runnerFor(imageRoleFor(target), config.system);
+    // Xcode runs on the Mac alone, so iOS and macOS packages build there whatever runner the rest use.
+    return HOST_BUILT_PLATFORMS.includes(target?.platform) ? 'LOCAL' : runner;
+}
+
+// Machine-wide like the cargo cache: built packages are reused by every project, and `pnpm run clear`
+// in one project must not throw them away. Containers write to the store and conan runs the recipes
+// it keeps there, so conan on the host never shares a store with them.
+export function conanRoot(runner = 'DOCKER_RUN') {
+    return path.join(os.homedir(), '.crossbind', runner === 'LOCAL' ? 'conan-local' : 'conan');
+}
+
+// The directory one conan run reads its inputs from and writes its outputs to, with the home it runs
+// with. conanPath names a file of it as conan sees it.
+export function createConanWork(runner) {
+    const root = conanRoot(runner);
+    const store = path.join(root, 'store');
+    fs.mkdirSync(store, { recursive: true });
+    fs.mkdirSync(path.join(root, 'work'), { recursive: true });
+    const dir = fs.mkdtempSync(path.join(root, 'work', 'run-'));
+    const conanDir = runner === 'LOCAL' ? dir : `${CONTAINER_ROOT}/work/${path.basename(dir)}`;
+    const conanPath = (file) => (runner === 'LOCAL' ? path.join(dir, file) : `${conanDir}/${file}`);
+    // conan takes its home from the first .conanrc at or above its working directory, ahead of
+    // CONAN_HOME; one in the working directory itself is always that first one.
+    fs.writeFileSync(path.join(dir, '.conanrc'), 'conan_home=./home\n');
+    fs.mkdirSync(path.join(dir, 'home'));
+    fs.writeFileSync(path.join(dir, 'home', 'global.conf'), [
+        `core.cache:storage_path=${runner === 'LOCAL' ? store : `${CONTAINER_ROOT}/store`}`,
+        'core:non_interactive=True',
+        '',
+    ].join('\n'));
+    return {
+        runner, root, store, dir, conanDir, conanPath,
+    };
+}
+
+function removeTree(dir) {
+    if (!fs.existsSync(dir)) return;
+    makeTreeWritable(dir);
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+
+export const removeConanWork = (work) => removeTree(work.dir);
+
+// What runs that were killed left behind. Only while holding the install lock: no run is going then.
+export const clearConanWork = (runner) => removeTree(path.join(conanRoot(runner), 'work'));
+
+// conan reports paths as it sees them. In a container that is through the mounts, which all sit under
+// CONTAINER_ROOT, so mapping the prefix back is exact; a path anywhere else is none crossbind gave it.
+export function toHostPath(reported, work) {
+    if (work.runner === 'LOCAL') return path.resolve(reported);
+    const clean = path.posix.normalize(reported);
+    // A backslash is a separator again once the path is joined on a Windows host.
+    if (reported.includes('\\') || !clean.startsWith(`${CONTAINER_ROOT}/`)) {
+        throw new Error(`crossbind: conan reported ${JSON.stringify(reported)}, outside the directories crossbind mounts for it.`);
+    }
+    return path.join(work.root, clean.slice(CONTAINER_ROOT.length + 1));
+}
+
+function allowedEnv() {
+    return Object.fromEntries(Object.entries(process.env).filter(([key]) => ALLOWED_ENV.some((allowed) => allowed.test(key))));
+}
+
+// The Xcode every crossbind iOS archive builds with, whichever one xcode-select points at.
+const iosEnv = () => ({ ...allowedEnv(), DEVELOPER_DIR: IOS_DEVELOPER_DIR });
+
+// A GNU ar or nm ahead of Apple's on a Mac's PATH (Homebrew's binutils) writes archives Apple's linker
+// cannot read, and recipes, the build tools they build and Meson all take these tools by name. So the
+// run gets links to Xcode's first on its PATH; for macOS to the ones xcode-select picks, as the macOS
+// ports are built with.
+const APPLE_TOOLS = {
+    ar: 'ar', as: 'as', nm: 'llvm-nm', ranlib: 'ranlib', strip: 'strip',
+};
+const appleToolOf = (target, name) => (target.platform === 'darwin'
+    ? path.join(DARWIN_TOOLS_BIN, name)
+    : path.join(XCODE_TOOLCHAIN_BIN, APPLE_TOOLS[name]));
+
+function withAppleTools(work, env, target) {
+    if (process.platform !== 'darwin') return env;
+    const dir = path.join(work.dir, 'apple-tools');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir);
+        Object.keys(APPLE_TOOLS).forEach((name) => fs.symlinkSync(appleToolOf(target, name), path.join(dir, name)));
+    }
+    return { ...env, PATH: [dir, env.PATH].filter(Boolean).join(path.delimiter) };
+}
+
+const toolVersions = new Map();
+// The first line a tool prints for --version, asked once.
+function toolVersion(command, env = allowedEnv(), cwd = undefined) {
+    const key = command.join(' ');
+    if (!toolVersions.has(key)) {
+        const [program, ...args] = command;
+        const result = spawnSync(program, [...args, '--version'], { encoding: 'utf8', env, cwd });
+        toolVersions.set(key, `${result.stdout ?? ''}`.split('\n')[0].trim());
+    }
+    return toolVersions.get(key);
+}
+
+// conan migrates the home it starts in, even for --version, so it is asked from a home of crossbind's
+// instead of the user's ~/.conan2.
+function conanVersion() {
+    const dir = path.join(conanRoot('LOCAL'), 'probe');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, '.conanrc'), 'conan_home=./home\n');
+    return toolVersion(['conan'], allowedEnv(), dir);
+}
+
+function compilerIdentity(target) {
+    if (target?.platform === 'ios') return toolVersion(['xcrun', 'clang'], iosEnv());
+    if (target?.platform === 'darwin') return toolVersion([DARWIN_CC]);
+    return toolVersion(['emcc']);
+}
+
+// What a host conan builds with; for a container the image digest says the same.
+export function localToolchainIdentity(target) {
+    return `${compilerIdentity(target)}\n${conanVersion()}`;
+}
+
+function assertLocalConan(target) {
+    const conan = conanVersion();
+    const [major, minor] = (conan.match(/(\d+)\.(\d+)/) ?? []).slice(1).map(Number);
+    const [needMajor, needMinor] = MIN_CONAN_VERSION;
+    if (major > needMajor || (major === needMajor && minor >= needMinor)) return;
+    const need = `Conan ${MIN_CONAN_VERSION.join('.')} or later; found ${conan || 'none'}.`;
+    throw new Error(HOST_BUILT_PLATFORMS.includes(target.platform)
+        ? `crossbind: Conan packages for ${APPLE_PLATFORM_NAMES[target.platform]} build on this Mac, with the conan on the PATH, which must be ${need} Install or upgrade it with \`brew install conan\` (\`brew upgrade conan\`) or \`pipx install conan\`.`
+        : `crossbind: RUNNER=LOCAL runs conan from the PATH and needs ${need}`);
+}
+
+export default function runConan(args, { config, target, work }) {
+    const options = { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', maxBuffer: MAX_BUFFER };
+    const role = imageRoleFor(target);
+    if (work.runner === 'LOCAL') {
+        if (!HOST_PLATFORMS.includes(target.platform)) {
+            throw new Error(`crossbind: Conan packages for ${target.platform} build in the ${role} image, which RUNNER=LOCAL does not use.`);
+        }
+        if (HOST_BUILT_PLATFORMS.includes(target.platform) && process.platform !== 'darwin') {
+            throw new Error(`crossbind: Conan packages for ${APPLE_PLATFORM_NAMES[target.platform]} build with Xcode, on a Mac.`);
+        }
+        assertLocalConan(target);
+        const env = withAppleTools(work, { ...(target.platform === 'ios' ? iosEnv() : allowedEnv()), CONAN_HOME: path.join(work.dir, 'home') }, target);
+        return spawnSync('conan', args, { ...options, cwd: work.dir, env });
+    }
+
+    // Google ships the linux NDK for x86_64 only.
+    const platform = target.platform === 'android' ? 'linux/amd64' : undefined;
+    if (work.runner === 'REMOTE') {
+        return spawnSync(...remoteExecParams({
+            remote: runnerFor(role, config.system).remote,
+            role,
+            image: getDockerImage(role, platform),
+            mounts: [
+                { host: work.store, container: `${CONTAINER_ROOT}/store`, inputRoots: [], outputRoots: REMOTE_STORE_OUTPUTS },
+                { host: work.dir, container: work.conanDir, inputRoots: ['.'], outputRoots: ['.'] },
+            ],
+            cwd: work.conanDir,
+            argv: ['conan', ...args],
+            env: { CONAN_HOME: work.conanPath('home') },
+        }, options));
+    }
+
+    const env = ['-e', `CONAN_HOME=${work.conanPath('home')}`];
+    let runnerArgs;
+    if (work.runner === 'DOCKER_EXEC') {
+        const name = getDockerContainerName(config.paths.base, role);
+        assertExecContainer({
+            name,
+            mounts: [[CONTAINER_ROOT, work.root]],
+            workdir: work.conanDir,
+            hint: `Recreate it with \`crossbind docker stop ${role}\`, \`crossbind docker delete ${role}\` and \`crossbind docker create ${role}\`, which mount ${work.root} at ${CONTAINER_ROOT}.`,
+            mountNote: 'It predates the conan mount.',
+        });
+        runnerArgs = ['exec', ...env, '--user', getOsUserAndGroupId(), '--workdir', work.conanDir, name];
+    } else {
+        pullDockerImage(role, platform);
+        runnerArgs = [
+            'run',
+            '--rm',
+            ...(platform ? ['--platform', platform] : []),
+            ...DOCKER_RUN_SECURITY_ARGS,
+            '-v',
+            `${work.store}:${CONTAINER_ROOT}/store`,
+            '-v',
+            `${work.dir}:${work.conanDir}`,
+            ...env,
+            '--user',
+            getOsUserAndGroupId(),
+            '--workdir',
+            work.conanDir,
+            getDockerImage(role, platform),
+        ];
+    }
+    return spawnSync('docker', [...runnerArgs, 'conan', ...args], options);
+}

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

@@ -179,6 +179,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 +196,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 +238,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 +285,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);
@@ -367,7 +372,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 });
     }

package/src/utils/rustMt.js

@@ -4,6 +4,9 @@ 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
@@ -66,6 +69,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/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) {