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

package/src/utils/remoteRunner.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DOCKER_BASE } from './replaceBasePathForDocker.js';
+import { remoteVariables } from './selectRunner.js';
+
+const CLIENT = fileURLToPath(new URL('./remoteClient.js', import.meta.url));
+
+// Only native inputs travel to the runner; the application's JavaScript and credential files stay on the
+// machine. A cargo target folder stays on the runner, and only the static libraries crossbind links come back from it.
+export const REMOTE_EXCLUDE_RULES = Object.freeze({
+    dirs: Object.freeze(['node_modules', '.git']),
+    files: Object.freeze(['.env', '.env.*', '.npmrc', '.yarnrc', '.yarnrc.yml', '.netrc']),
+    extensions: Object.freeze(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']),
+    serverOnly: Object.freeze({ names: Object.freeze(['target', 'target-mt']), marker: 'Cargo.toml', keep: Object.freeze(['*/release/*.a']) }),
+});
+
+const TOKEN_VARIABLE = 'CROSSBIND_TOKEN';
+
+const LOOPBACK = /^(localhost|127(\.\d{1,3}){3}|\[::1\])$/;
+const warnedUrls = new Set();
+
+// Plain http to another machine carries the token and the sources unencrypted.
+function warnIfPlainHttp(url) {
+    const { protocol, hostname } = new URL(url);
+    if (protocol !== 'http:' || LOOPBACK.test(hostname) || warnedUrls.has(url)) return;
+    warnedUrls.add(url);
+    console.warn(`crossbind: ${url} is plain http to another machine - the token and your sources travel unencrypted; put TLS in front of the runner.`);
+}
+
+const isInside = (rel, root) => root === '.' || rel === root || rel.startsWith(`${root}/`);
+
+// Null for a folder outside the base: a local docker run mounts only the base, so it never sees one either.
+function relativeToBase(base, folder) {
+    const rel = path.relative(base, folder);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+    return rel.split(path.sep).join('/') || '.';
+}
+
+function foldNested(roots) {
+    const unique = [...new Set(roots)].sort((a, b) => a.length - b.length);
+    return unique.filter((root, i) => !unique.slice(0, i).some((outer) => isInside(root, outer)));
+}
+
+// A file the command line names may include its neighbours (`#include "../include/x.h"`), so unless a
+// configured folder holds it, the package that holds it travels: the nearest folder below the base with a
+// package.json. Its JavaScript stays behind, as everywhere else.
+function packageOf(base, configured, file) {
+    if (configured.some((root) => isInside(relativeToBase(base, file), root))) return file;
+    for (let dir = path.dirname(file); ![null, '.'].includes(relativeToBase(base, dir)); dir = path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    }
+    return file;
+}
+
+// What a toolchain step may read (inputRoots) and where it writes (outputRoots), relative to paths.base,
+// the folder a local docker run mounts. `extraInputs` are only read (a file the link names);
+// `extraOutputs` are read and written, like a crate's folder and its Cargo.lock.
+export function remoteRoots(config, { extraInputs = [], extraOutputs = [] } = {}) {
+    const { paths, allDependencies = [] } = config;
+    const relOf = (folder) => relativeToBase(paths.base, folder);
+    const isBelowBase = (folder) => Boolean(folder) && relOf(folder) !== null;
+    const dependencyFolders = allDependencies.flatMap((d) => [d.paths.output, ...(d.paths.native ?? []), ...(d.paths.header ?? [])]);
+    const configured = [...paths.native, ...paths.header, paths.cache, paths.output, `${paths.cli}/assets`, ...dependencyFolders].filter(isBelowBase).map(relOf);
+    const outputs = [paths.cache, paths.output, ...extraOutputs].filter(isBelowBase).map(relOf);
+    return {
+        inputRoots: foldNested([...configured, ...extraInputs.filter(isBelowBase).map((file) => relOf(packageOf(paths.base, configured, file))), ...outputs]),
+        outputRoots: foldNested(outputs),
+    };
+}
+
+export function baseMount(config, extra = {}) {
+    return { host: config.paths.base, container: DOCKER_BASE, ...remoteRoots(config, extra) };
+}
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Paths a command line names below the base (a source the link adds, an include folder, a preload file)
+// travel even when no configured folder holds them. The base itself is never one: it would send everything.
+export function referencedPaths(base, values) {
+    const pattern = new RegExp(`${escapeRegExp(base)}(?:/[^@=;:,'"\\s]*)?`, 'g');
+    const found = values.flatMap((value) => String(value).match(pattern) ?? []);
+    return [...new Set(found)].filter((candidate) => candidate !== base && fs.existsSync(candidate));
+}
+
+// Arguments for execFileSync/spawnSync: the client runs as its own process, so the caller stays
+// synchronous as it is with docker. The token reaches it through its environment, never its command line.
+export function remoteExecParams({ remote, role, image, mounts, cwd, argv, env }, options) {
+    if (!remote) {
+        throw new Error(`crossbind: RUNNER=REMOTE, but the ${role} image has no runner address - set ${remoteVariables(role).key} (or REMOTE_URL), or build with CROSSBIND_RUNNER=DOCKER_RUN. A machine that names no runner address builds on crossbind cloud after crossbind login.`);
+    }
+    const { url, token, tokenVariable } = remote;
+    if (!token) throw new Error(`crossbind: the ${role} runner at ${url} needs a token - set ${tokenVariable}.`);
+    warnIfPlainHttp(url);
+    const payload = { url, role, image, mounts, cwd, argv, env, rules: REMOTE_EXCLUDE_RULES };
+    return [process.execPath, [CLIENT, JSON.stringify(payload)], { ...options, env: { ...process.env, [TOKEN_VARIABLE]: token } }];
+}

package/src/utils/remoteUpload.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Raw bytes per upload request, a batch of small files or a part of a large one. With base64 a batch stays below the
+// 32 MiB a Cloud Run request may carry, and a part below Cloudflare's 100 MB as well.
+const UPLOAD_BATCH_BYTES = 16 * 1024 * 1024;
+// The first runner protocol that joins a file sent in parts.
+const PARTS_PROTOCOL = 2;
+const MB = 1024 * 1024;
+// A long upload to a hosted runner now and then loses its connection: a request goes again this many times, waiting a
+// second longer each time.
+const UPLOAD_RETRIES = 4;
+const RETRY_DELAY_MS = 1000;
+// Failures before a connection opened, such as a name lookup that failed for a moment: the request never reached the
+// runner, so it goes again this many times. After a connection opened it never does, since a step may have started.
+const UNSENT_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ENETUNREACH', 'EHOSTUNREACH', 'UND_ERR_CONNECT_TIMEOUT']);
+const UNSENT_RETRIES = 2;
+
+const wait = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+
+export async function request(url, route, init = {}) {
+    const token = process.env.CROSSBIND_TOKEN;
+    const headers = { ...(token ? { authorization: `Bearer ${token}` } : {}), ...init.headers };
+    for (let attempt = 1; ; attempt += 1) {
+        try {
+            // A redirect would send the request, sources included, to an address nobody configured.
+            return await fetch(`${url}${route}`, { ...init, headers, redirect: 'error' });
+        } catch (error) {
+            if (!UNSENT_CODES.has(error.cause?.code) || attempt > UNSENT_RETRIES) {
+                throw new Error(`crossbind: the remote runner at ${url} is unreachable (${error.cause?.code ?? error.message}).`, { cause: error });
+            }
+            await wait(RETRY_DELAY_MS * attempt);
+        }
+    }
+}
+
+export async function expectOk(response, what) {
+    if (response.ok) return response.json();
+    const body = await response.json().catch(() => ({}));
+    throw new Error(`crossbind: the remote runner failed ${what}: ${body.error ?? response.status}.`);
+}
+
+async function requestWithRetries(url, route, init) {
+    for (let attempt = 1; ; attempt += 1) {
+        const response = await request(url, route, init).catch((error) => error);
+        const failed = response instanceof Error || response.status >= 500;
+        if (!failed || attempt > UPLOAD_RETRIES) {
+            if (response instanceof Error) throw response;
+            return response;
+        }
+        await wait(RETRY_DELAY_MS * attempt);
+    }
+}
+
+async function runnerProtocol(url) {
+    const health = await expectOk(await request(url, '/v1/health'), 'to answer its health check');
+    return health.protocol ?? 1;
+}
+
+// One request per part, in order; the runner checks the joined file against its hash. After a part whose connection
+// dropped, the upload goes on from where the runner says it stands. The upload is named after the file, so a later
+// attempt, or another client sending the same file, goes on with what the runner holds.
+async function uploadInParts(url, hash, file, total, partBytes) {
+    const upload = hash.slice(0, 32);
+    const fd = fs.openSync(file, 'r');
+    let resumes = 0;
+    try {
+        for (let start = 0; start < total;) {
+            const part = Buffer.alloc(Math.min(partBytes, total - start));
+            fs.readSync(fd, part, 0, part.length, start);
+            const response = await requestWithRetries(url, `/v1/blobs/${hash}`, {
+                method: 'PUT',
+                body: part,
+                headers: { 'content-range': `bytes ${start}-${start + part.length - 1}/${total}`, 'x-crossbind-upload': upload },
+            });
+            if (response.status === 413) {
+                throw new Error(`crossbind: the remote runner at ${url} took no part of ${path.basename(file)}: it refused a part of ${part.length} bytes, so the proxy in front of it takes less in one request.`);
+            }
+            if (response.status === 409 && resumes < UPLOAD_RETRIES) {
+                const { received } = await response.json();
+                if (!Number.isSafeInteger(received) || received < 0 || received >= total) throw new Error(`crossbind: the remote runner holds ${received} bytes of ${path.basename(file)}, which has ${total}.`);
+                resumes += 1;
+                start = received;
+                continue;
+            }
+            const answer = await expectOk(response, `to receive ${path.basename(file)}`);
+            if (response.status === 201) return;
+            start = answer.received;
+        }
+    } finally {
+        fs.closeSync(fd);
+    }
+}
+
+// A runner deployed before uploads in parts takes a large file in one request, which a body limit in front of it refuses.
+async function uploadWhole(url, hash, file, total) {
+    const response = await request(url, `/v1/blobs/${hash}`, { method: 'PUT', body: fs.readFileSync(file) });
+    if (response.status === 413) {
+        throw new Error(`crossbind: the remote runner at ${url} refused ${path.basename(file)} (${Math.ceil(total / MB)} MB) as too large for one request; deploy the runner again with this crossbind version, which sends large files in parts.`);
+    }
+    await expectOk(response, `to receive ${path.basename(file)}`);
+}
+
+// `sources` maps each hash to a file holding it; only what the runner lacks travels, small files in a few batches and a
+// large one on its own.
+export async function uploadMissing(url, sources, partBytes = UPLOAD_BATCH_BYTES) {
+    const listing = await request(url, '/v1/missing', { method: 'POST', body: JSON.stringify({ hashes: [...sources.keys()] }) });
+    const { missing } = await expectOk(listing, 'to list the files it lacks');
+    let protocol;
+    let batch = [];
+    let size = 0;
+    const flush = async () => {
+        if (batch.length === 0) return;
+        const body = batch.map(({ hash, data }) => JSON.stringify({ sha256: hash, data: data.toString('base64') })).join('\n');
+        await expectOk(await requestWithRetries(url, '/v1/blobs', { method: 'POST', body }), `to receive ${batch.length} files`);
+        batch = [];
+        size = 0;
+    };
+    for (const hash of missing) {
+        const file = sources.get(hash);
+        const fileSize = fs.statSync(file).size;
+        if (fileSize > partBytes) {
+            protocol ??= await runnerProtocol(url);
+            if (protocol >= PARTS_PROTOCOL) await uploadInParts(url, hash, file, fileSize, partBytes);
+            else await uploadWhole(url, hash, file, fileSize);
+            continue;
+        }
+        const data = fs.readFileSync(file);
+        if (size > 0 && size + data.length > partBytes) await flush();
+        batch.push({ hash, data });
+        size += data.length;
+    }
+    await flush();
+}

package/src/utils/replaceFile.js

@@ -0,0 +1,8 @@
+import fs from 'node:fs';
+
+// macOS keeps the code signature of a loaded binary per inode: a rebuilt addon or command copied over
+// one that already ran gets the next process that loads it killed. A new file gets a new inode.
+export default function replaceFile(source, destination) {
+    fs.rmSync(destination, { force: true });
+    fs.copyFileSync(source, destination);
+}

package/src/utils/resetCMakeCacheForSource.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import state from '../state/index.js';
+import replaceBasePathForDocker from './replaceBasePathForDocker.js';
+import { isLocalRunner } from './selectRunner.js';
+import { HOST_BUILT_PLATFORMS } from './targets.js';
+
+const normalize = (dir) => dir.replaceAll('\\', '/').replace(/\/+$/, '');
+
+// The directory as the cmake run() starts sees it: a container, Docker or a remote runner, has the project at
+// DOCKER_BASE; macOS and iOS builds and the LOCAL runner see this machine's paths.
+function seenByCMake(dir, target) {
+    const isLocal = HOST_BUILT_PLATFORMS.includes(target.platform) || isLocalRunner(state.config.system);
+    return isLocal ? dir : replaceBasePathForDocker(dir, state.config.paths.base);
+}
+
+// A CMake build tree remembers the source directory it was configured from and refuses another one. The CMake
+// projects crossbind ships move with its version (node_modules/.pnpm/crossbind@<version>/...), so a tree configured
+// from another directory starts afresh, as `cmake --fresh` would.
+export default function resetCMakeCacheForSource(buildPath, sourceDir, target) {
+    const cache = `${buildPath}/CMakeCache.txt`;
+    if (!fs.existsSync(cache)) return;
+    const configuredFrom = fs.readFileSync(cache, 'utf8').match(/^CMAKE_HOME_DIRECTORY:INTERNAL=(.*)$/m)?.[1];
+    if (configuredFrom !== undefined && normalize(configuredFrom) === normalize(seenByCMake(sourceDir, target))) return;
+    fs.rmSync(cache, { force: true });
+    fs.rmSync(`${buildPath}/CMakeFiles`, { recursive: true, force: true });
+}

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);
+}