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

package/src/utils/conanStage.js

@@ -0,0 +1,292 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import upath from 'upath';
+import loadJson from './loadJson.js';
+import writeIfChanged from './writeIfChanged.js';
+import makeTreeWritable from './makeTreeWritable.js';
+import logger from './logger.js';
+import { libNameOf } from './linkLayout.js';
+import { CONAN_NAME, conanPackageDir } from './conanImport.js';
+import { CONAN_VERSION } from './conanDependencies.js';
+
+const MANIFESTS = 'manifests';
+const LIB_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.+-]*$/;
+// A macro name with a plain value, if any (a path or a list too): one compiler argument, in a list CMake
+// splits on ';'.
+const DEFINE = /^[A-Za-z_]\w*(=[\w.+/,:-]*)?$/;
+// What may follow name/version in a reference: a user/channel and a recipe revision.
+const REFERENCE_TAIL = /^(@[A-Za-z0-9_][A-Za-z0-9_.+-]*\/[A-Za-z0-9_][A-Za-z0-9_.+-]*)?(#[0-9a-f]+)?$/;
+const URL = /^https?:\/\/[^\s"'<>`\\]+$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const MAX_TEXT = 1000;
+const TARGET_PATH = /^[A-Za-z0-9_-]+$/;
+// The prefix of the variables a package's CMakeLists names each target's libraries by.
+const HOST_LIBS = 'CROSSBIND_CONAN_LIBS_';
+
+// The CMake target of a package; Conan names may carry '.', '+' and '-'.
+export const conanTargetName = (name) => `conan_${name.replace(/[^A-Za-z0-9_]/g, '_')}`;
+
+const matches = (pattern, value) => typeof value === 'string' && pattern.test(value);
+const isListOf = (pattern, values) => Array.isArray(values) && values.every((value) => matches(pattern, value));
+const shown = (value) => `${JSON.stringify(value)}`.slice(0, 200);
+// C0 and C1 controls, which carry terminal escape sequences.
+export const isControlCharacter = (char) => char < ' ' || (char >= '\u007f' && char <= '\u009f');
+// Recipe text ends up in notices and terminals: one line, no control characters.
+const textOf = (value) => (typeof value === 'string' && value.length <= MAX_TEXT && ![...value].some(isControlCharacter) ? value : null);
+const urlOf = (value) => (matches(URL, value) && value.length <= MAX_TEXT ? value : null);
+
+// A list means every license applies; an item that offers a choice stays one term of it.
+function licenseOf(license) {
+    const parts = Array.isArray(license) ? license.map(textOf) : [textOf(license)];
+    if (parts.length === 0 || !parts.every(Boolean)) return null;
+    return parts.length === 1 ? parts[0] : parts.map((part) => (part.includes(' OR ') ? `(${part})` : part)).join(' AND ');
+}
+
+// The fields of a package that crossbind keeps. Conan's JSON comes from recipe code and these fields
+// end up in paths, CMake files and notices, so they are checked where they come in and again where
+// the manifest is read back.
+export function conanPackageEntry(entry) {
+    const fail = (field) => {
+        throw new Error(`crossbind: the Conan package ${shown(entry.ref ?? entry.name)} has an invalid ${field}: ${shown(entry[field])}.`);
+    };
+    if (!matches(CONAN_NAME, entry.name)) fail('name');
+    if (!matches(CONAN_VERSION, entry.version)) fail('version');
+    const reference = `${entry.name}/${entry.version}`;
+    if (typeof entry.ref !== 'string' || !entry.ref.startsWith(reference) || !REFERENCE_TAIL.test(entry.ref.slice(reference.length))) fail('ref');
+    if (!isListOf(LIB_NAME, entry.libs)) fail('libs');
+    if (!isListOf(CONAN_NAME, entry.requires)) fail('requires');
+    // They become linker and compiler arguments. A manifest an older crossbind wrote has none of them.
+    const systemLibs = entry.systemLibs ?? [];
+    const frameworks = entry.frameworks ?? [];
+    const defines = entry.defines ?? [];
+    if (!isListOf(LIB_NAME, systemLibs)) fail('systemLibs');
+    if (!isListOf(LIB_NAME, frameworks)) fail('frameworks');
+    if (!isListOf(DEFINE, defines)) fail('defines');
+    const url = urlOf(entry.source?.url);
+    return {
+        name: entry.name,
+        version: entry.version,
+        ref: entry.ref,
+        license: licenseOf(entry.license),
+        homepage: urlOf(entry.homepage),
+        source: url ? { url, sha256: matches(SHA256, entry.source.sha256) ? entry.source.sha256 : null } : null,
+        libs: [...entry.libs],
+        requires: [...entry.requires],
+        systemLibs: [...systemLibs],
+        frameworks: [...frameworks],
+        defines: [...defines],
+    };
+}
+
+function sourceOf(entry) {
+    const source = Array.isArray(entry) ? entry[0] : entry;
+    if (!source?.url) return null;
+    return { url: Array.isArray(source.url) ? source.url[0] : source.url, sha256: source.sha256 ?? null };
+}
+
+// A define crossbind cannot pass as one plain argument was left out before crossbind took defines at all,
+// so it stays out, with a notice, instead of stopping the build.
+function plainDefinesOf(node, defines) {
+    return defines.filter((define) => {
+        if (matches(DEFINE, define)) return true;
+        logger.info(`crossbind: ${shown(node.ref)} asks the code that uses it to compile with ${shown(define)}, which crossbind leaves out: a define passes as a plain name with a plain value.`);
+        return false;
+    });
+}
+
+function packageOf(node, requires) {
+    const components = Object.values(node.cpp_info ?? {});
+    const collect = (key) => [...new Set(components.flatMap((component) => component?.[key] ?? []))];
+    const folders = (key) => {
+        const values = collect(key);
+        if (!values.every((value) => typeof value === 'string')) {
+            throw new Error(`crossbind: the Conan package ${shown(node.ref)} has invalid ${key}.`);
+        }
+        return values;
+    };
+    if (typeof node.package_folder !== 'string') {
+        throw new Error(`crossbind: conan reported the package ${shown(node.ref)} without a package folder.`);
+    }
+    return {
+        ...conanPackageEntry({
+            name: node.name,
+            version: node.version,
+            ref: node.ref,
+            license: node.license,
+            homepage: node.homepage,
+            source: sourceOf(node.conandata?.sources?.[node.version]),
+            libs: collect('libs'),
+            requires,
+            systemLibs: collect('system_libs'),
+            frameworks: collect('frameworks'),
+            defines: plainDefinesOf(node, collect('defines')),
+        }),
+        packageFolder: node.package_folder,
+        includedirs: folders('includedirs'),
+        libdirs: folders('libdirs'),
+    };
+}
+
+// One entry per package name, each before the packages it requires: the order a static link takes
+// them in.
+function linkOrder(packages) {
+    const byName = new Map(packages.map((pkg) => [pkg.name, pkg]));
+    const order = [];
+    const visited = new Set();
+    const visit = (name) => {
+        if (visited.has(name) || !byName.has(name)) return;
+        visited.add(name);
+        byName.get(name).requires.forEach(visit);
+        order.push(byName.get(name));
+    };
+    byName.forEach((pkg, name) => visit(name));
+    return order.reverse();
+}
+
+// Host packages of a `conan install --format=json` graph in link order. Left out are the consumer,
+// build tools, test requirements and packages conan skipped because the consumer needs nothing of them.
+export function conanPackagesOf(graph) {
+    const nodes = graph?.nodes;
+    if (!nodes || typeof nodes !== 'object' || !graph.root) {
+        throw new Error('crossbind: conan install printed a graph without nodes or a root.');
+    }
+    const [root] = Object.keys(graph.root);
+    const isPackage = (id) => id !== root && nodes[id]?.context === 'host' && !nodes[id].test && nodes[id].binary !== 'Skip';
+    const ids = Object.keys(nodes).filter(isPackage);
+    const requiresOf = (id) => Object.entries(nodes[id].dependencies ?? {})
+        .filter(([dependency, edge]) => !edge?.build && !edge?.test && ids.includes(dependency))
+        .map(([dependency]) => nodes[dependency].name);
+    return linkOrder(ids.map((id) => packageOf(nodes[id], requiresOf(id))));
+}
+
+// The real path of a file conan reported, or null when there is none; refused when it resolves
+// outside `root`.
+function realPathWithin(file, root, pkg) {
+    if (!fs.existsSync(file)) return null;
+    const real = fs.realpathSync(file);
+    const relative = path.relative(root, real);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`crossbind: the Conan package ${pkg.ref} reports ${file}, which resolves outside ${root}.`);
+    }
+    return real;
+}
+
+// Packages link files to each other (libpng.a -> libpng16.a), so links are followed, but only to
+// directories and regular files inside the package, and into each linked directory once: a link out
+// of the package could point the copy at any file the host can read, and links back up the tree
+// would copy it without end.
+function copyTree(from, to, packageRoot, pkg) {
+    const linked = new Set([from]);
+    fs.cpSync(from, to, {
+        recursive: true,
+        dereference: true,
+        filter: (source) => {
+            const entry = fs.lstatSync(source);
+            if (!entry.isSymbolicLink()) return entry.isDirectory() || entry.isFile();
+            const real = realPathWithin(source, packageRoot, pkg);
+            const target = real && fs.statSync(real);
+            if (!target?.isDirectory()) return Boolean(target?.isFile());
+            if (linked.has(real)) return false;
+            linked.add(real);
+            return true;
+        },
+    });
+    makeTreeWritable(to);
+}
+
+// The package's own folder: no link, and below the store's own layout, so it cannot take in the
+// store or another package.
+function packageRootOf(pkg, folder, store) {
+    const real = realPathWithin(folder, store, pkg);
+    if (!real || fs.lstatSync(folder).isSymbolicLink() || path.relative(store, real).split(path.sep).length < 2) {
+        throw new Error(`crossbind: the Conan package ${pkg.ref} has no package folder crossbind can use at ${pkg.packageFolder}.`);
+    }
+    return real;
+}
+
+// A package lands where a published port keeps its prebuilt (<dir>/dist/prebuilt/<target>/{include,lib}),
+// so the dependency machinery links it and SWIG treats its headers as one across targets. Everything
+// is read from inside the package's own folder in the store.
+export function stageConanPackage(pkg, {
+    stageDir, targetPath, toHost, store, distCmake,
+}) {
+    const packageRoot = packageRootOf(pkg, toHost(pkg.packageFolder), fs.realpathSync(store));
+    const reported = (folder) => realPathWithin(toHost(upath.isAbsolute(folder) ? folder : upath.join(pkg.packageFolder, folder)), packageRoot, pkg);
+    const dir = conanPackageDir(stageDir, pkg.name);
+    const prebuilt = upath.join(dir, 'dist', 'prebuilt');
+    const prefix = upath.join(prebuilt, targetPath);
+
+    fs.rmSync(prefix, { recursive: true, force: true });
+    fs.mkdirSync(upath.join(prefix, 'include'), { recursive: true });
+    fs.mkdirSync(upath.join(prefix, 'lib'), { recursive: true });
+    pkg.includedirs.map(reported).filter(Boolean).forEach((folder) => copyTree(folder, upath.join(prefix, 'include'), packageRoot, pkg));
+    const libdirs = pkg.libdirs.map(reported).filter(Boolean);
+    pkg.libs.forEach((lib) => {
+        const archive = libdirs.map((folder) => realPathWithin(path.join(folder, `lib${lib}.a`), packageRoot, pkg))
+            .find((file) => file && fs.statSync(file).isFile());
+        if (!archive) {
+            throw new Error(`crossbind: the Conan package ${pkg.ref} declares the library ${lib}, but its package has no lib${lib}.a.`);
+        }
+        fs.copyFileSync(archive, upath.join(prefix, 'lib', `lib${lib}.a`));
+    });
+
+    const licenses = upath.join(dir, 'licenses');
+    fs.rmSync(licenses, { recursive: true, force: true });
+    const shipped = realPathWithin(path.join(packageRoot, 'licenses'), packageRoot, pkg);
+    if (shipped && fs.statSync(shipped).isDirectory()) copyTree(shipped, licenses, packageRoot, pkg);
+    writeIfChanged(upath.join(dir, 'package.json'), `${JSON.stringify({
+        name: `conan:${pkg.name}`, version: pkg.version, nativeVersion: pkg.version, license: pkg.license, private: true,
+    }, null, 4)}\n`);
+
+    const hosts = fs.readdirSync(prebuilt, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && TARGET_PATH.test(entry.name)).map((entry) => entry.name).sort();
+    // A recipe can name its libraries otherwise on another platform (libpng is png16 on Windows), so each
+    // target links the archives staged for it.
+    const archivesOf = (host) => {
+        const libdir = upath.join(prebuilt, host, 'lib');
+        if (!fs.existsSync(libdir)) return [];
+        return fs.readdirSync(libdir).filter((file) => file.endsWith('.a')).map(libNameOf).filter((name) => matches(LIB_NAME, name)).sort();
+    };
+    writeIfChanged(upath.join(prebuilt, 'CMakeLists.txt'), [
+        ...hosts.map((host) => `set(${HOST_LIBS}${host} "${archivesOf(host).join(';')}")`),
+        distCmake
+            .replace('___PROJECT_NAME___', () => conanTargetName(pkg.name))
+            .replace('___PROJECT_HOST___', () => hosts.join(';'))
+            .replace('___PROJECT_LIBS___', () => `\${${HOST_LIBS}\${PROJECT_TARGET_HOST}}`)
+            .replace('___PROJECT_WHOLE_ARCHIVE___', () => ''),
+    ].join('\n'));
+}
+
+const manifestsOf = (stageDir) => upath.join(stageDir, MANIFESTS);
+const manifestFileOf = (stageDir, targetPath) => upath.join(manifestsOf(stageDir), `${targetPath}.json`);
+
+// One manifest per target: a recipe can require other packages on another platform.
+export function writeConanManifest(stageDir, targetPath, manifest) {
+    writeIfChanged(manifestFileOf(stageDir, targetPath), `${JSON.stringify(manifest, null, 4)}\n`);
+}
+
+// The packages staged for one target, or for every target staged so far, in link order, and each
+// target's own list. A manifest staged for other conanDependencies describes packages the config no
+// longer asks for.
+export function readConanManifest(stageDir, key, targetPath = null) {
+    const dir = manifestsOf(stageDir);
+    let files = [];
+    if (targetPath) files = [manifestFileOf(stageDir, targetPath)];
+    else if (fs.existsSync(dir)) files = fs.readdirSync(dir).filter((name) => name.endsWith('.json')).sort().map((name) => upath.join(dir, name));
+    const manifests = files.map((file) => ({ target: upath.basename(file, '.json'), manifest: loadJson(file) }))
+        .filter(({ manifest }) => manifest?.key === key);
+    if (manifests.length === 0) return null;
+    try {
+        const targets = Object.fromEntries(manifests.map(({ target, manifest }) => [target, manifest.packages.map(conanPackageEntry)]));
+        return { key, packages: linkOrder(Object.values(targets).flat()), targets };
+    } catch (e) {
+        throw new Error(`crossbind: ${dir} lists a package crossbind will not use - delete ${stageDir} and build again. ${e.message}`, { cause: e });
+    }
+}
+
+// Changes whenever a build stages packages, so a process that attached before can tell.
+export function conanManifestsStamp(stageDir) {
+    const dir = manifestsOf(stageDir);
+    if (!fs.existsSync(dir)) return '';
+    return fs.readdirSync(dir).sort().map((name) => `${name}@${fs.statSync(upath.join(dir, name)).mtimeMs}`).join('|');
+}

package/src/utils/copyToDistSource.js

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import upath from 'upath';
+
+const NODE_MODULES = 'node_modules/';
+
+// A copyToDist source names another package's file as node_modules/<package>/<file>. npm may hoist that package
+// above the one being built, so a path missing beside the package resolves the way Node finds the package.
+export default function copyToDistSource(projectDir, key) {
+    const local = upath.join(projectDir, key);
+    if (fs.existsSync(local) || !key.startsWith(NODE_MODULES)) return local;
+    return upath.normalize(createRequire(upath.join(projectDir, 'package.json')).resolve(key.slice(NODE_MODULES.length)));
+}

package/src/utils/cppDts.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { stripComments } from './swigInterface.js';
 import writeIfChanged from './writeIfChanged.js';
+import { conanImportOfHeader, conanStageDir } from './conanImport.js';
 
 // Best-effort .d.ts for `.h` imports, the C++ analog of the Rust emitDts: parse the
 // binding-rules surface (classes, public methods, primitives/string/shared_ptr), skip
@@ -34,7 +35,7 @@ function tsType(raw, classNames, { isReturn = false } = {}) {
     if (t === 'void') return 'void';
     if (t === 'bool') return 'boolean';
     if (NUMBER_TYPES.has(t)) return 'number';
-    if (t === 'std::string') return 'string';
+    if (t === 'std::string' || t === 'std::u16string') return 'string';
     if (classNames.has(t)) return t;
     return null;
 }
@@ -133,8 +134,12 @@ function typedefNamesAfter(text, from) {
     return tail ? tail[1].split(',').map((part) => part.trim()).filter((part) => /^[A-Za-z_]\w*$/.test(part)) : [];
 }
 
+// A brace inside a string or character literal is text; the model needs no literal's contents.
+const LITERAL = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g;
+const blankLiterals = (text) => text.replace(LITERAL, (literal) => `${literal[0]}${' '.repeat(literal.length - 2)}${literal[0]}`);
+
 export function parseCppSurface(source, log = console.log) {
-    const clean = stripComments(source).replace(/^[ \t]*#[^\n]*$/gm, ' ');
+    const clean = blankLiterals(stripComments(source)).replace(/^[ \t]*#[^\n]*$/gm, ' ');
 
     const classes = [];
     const classNames = new Set();
@@ -154,13 +159,18 @@ export function parseCppSurface(source, log = console.log) {
     for (const cls of found) {
         let access = cls.kind === 'class' ? 'private' : 'public';
         let ctor = null;
+        let declaresCtor = false;
+        let isAbstract = false;
         const methods = [];
         const fields = [];
         for (let statement of bodyStatements(cls.body)) {
             const sections = statement.match(/\b(public|private|protected)\s*:\s*([\s\S]*)$/);
             if (sections) { access = sections[1]; statement = sections[2].trim(); }
+            if (new RegExp(`^(?:explicit\\s+)?${cls.name}\\s*\\(`).test(statement)) declaresCtor = true;
+            if (/\)\s*(?:const\s*)?(?:override\s*)?=\s*0$/.test(statement)) isAbstract = true;
             if (!statement || access !== 'public') continue;
-            statement = statement.replace(/\)\s*:\s*[\s\S]*$/, ')').replace(/\)\s*const$/, ')').trim();
+            const isDeleted = /=\s*delete$/.test(statement);
+            statement = statement.replace(/\s*=\s*(?:default|delete)$/, '').replace(/\)\s*:\s*[\s\S]*$/, ')').replace(/\)\s*const$/, ')').trim();
 
             const sig = statement.match(/^(static\s+)?(?:explicit\s+)?([\w:<>,\s*&]*?)\s*\b([A-Za-z_]\w*)\s*\(([\s\S]*)\)$/);
             if (!sig) {
@@ -172,12 +182,17 @@ export function parseCppSurface(source, log = console.log) {
             const [, staticKw, retRaw, name, argsRaw] = sig;
             const args = parseArgs(argsRaw, classNames);
             if (args.includes(null)) { log(`crossbind: dts: skipped ${cls.name}::${name} (unsupported parameter type)`); continue; }
-            if (name === cls.name && retRaw.trim() === '') { ctor = { args }; continue; }
+            if (name === cls.name && retRaw.trim() === '') {
+                if (!isDeleted) ctor = { args };
+                continue;
+            }
             if (name.startsWith('~')) continue;
             const ret = tsType(retRaw, classNames, { isReturn: true });
             if (ret === null) { log(`crossbind: dts: skipped ${cls.name}::${name} (unsupported return type '${retRaw.trim()}')`); continue; }
             methods.push({ name, isStatic: Boolean(staticKw), args, ret });
         }
+        // The bridge binds the implicit default constructor of a class that declares none, unless it is abstract.
+        if (!declaresCtor && !isAbstract) ctor = { args: [] };
         classes.push({ name: cls.name, aliases: cls.aliases, ctor, methods, fields });
     }
     return { classes };
@@ -221,20 +236,48 @@ export function emitCppDts(model, exportNames, mode = 'sync') {
     return out.join('\n');
 }
 
-// Mirror the declaration under <cache>/types/<project-relative>.d.ts - never next to the
-// user's header. Package headers are skipped: their types ship with the package itself.
-export function writeHeaderDts({ headerFile, exportsFile, projectPath, cacheDir, dtsMode = 'sync', log = () => {} }) {
-    if (!fs.existsSync(exportsFile)) return;
-    const relative = path.relative(projectPath, headerFile);
-    if (relative.startsWith('..')) return;
-    let exportNames;
+function readExportNames(exportsFile, log) {
+    if (!fs.existsSync(exportsFile)) return null;
     try {
-        exportNames = JSON.parse(fs.readFileSync(exportsFile, 'utf8'));
+        const exportNames = JSON.parse(fs.readFileSync(exportsFile, 'utf8'));
+        return Array.isArray(exportNames) ? exportNames : null;
     } catch (e) {
         log(`crossbind: dts: unreadable exports file ${exportsFile} (${e.message})`);
-        return;
+        return null;
     }
-    if (!Array.isArray(exportNames)) return;
+}
+
+function declarationsOf(headerFile, exportNames, dtsMode, log) {
     const model = headerFile.endsWith('.i') ? { classes: [] } : parseCppSurface(fs.readFileSync(headerFile, 'utf8'), log);
-    writeIfChanged(`${cacheDir}/types/${relative}.d.ts`, emitCppDts(model, exportNames, dtsMode));
+    return emitCppDts(model, exportNames, dtsMode);
+}
+
+// Mirror the declaration under <cache>/types/<project-relative>.d.ts - never next to the
+// user's header. Package headers are skipped: their types ship with the package itself, and a
+// header staged from Conan is typed by its conan: module instead.
+export function writeHeaderDts({ headerFile, exportsFile, projectPath, cacheDir, dtsMode = 'sync', log = () => {} }) {
+    const relative = path.relative(projectPath, headerFile);
+    if (relative.startsWith('..') || headerFile.startsWith(`${conanStageDir(cacheDir)}/`)) return;
+    const exportNames = readExportNames(exportsFile, log);
+    if (!exportNames) return;
+    writeIfChanged(`${cacheDir}/types/${relative}.d.ts`, declarationsOf(headerFile, exportNames, dtsMode, log));
+}
+
+// A conan: specifier names no file the editor could map, so it is typed by an ambient module that
+// @crossbind/typescript-config includes. `declare` is an error inside one (TS1038).
+export function writeConanImportDts({ headerFile, exportsFile, declarationsFile = exportsFile, cacheDir, dtsMode = 'sync', log = () => {} }) {
+    const conanImport = conanImportOfHeader(headerFile, cacheDir);
+    const declared = conanImport && readExportNames(declarationsFile, log);
+    if (!declared) return;
+    // The bridge also binds macros and variadic functions the app imports, which the whole header's SWIG run skips.
+    const exportNames = [...new Set([...declared, ...(readExportNames(exportsFile, log) ?? [])])];
+    const body = declarationsOf(headerFile, exportNames, dtsMode, log)
+        .replaceAll('export declare ', 'export ')
+        .split('\n')
+        .map((line) => (line ? `    ${line}` : line))
+        .join('\n');
+    writeIfChanged(
+        `${conanStageDir(cacheDir)}/types/${conanImport.name}/${conanImport.header}.d.ts`,
+        `declare module 'conan:${conanImport.name}/${conanImport.header}' {\n${body}\n}\n`,
+    );
 }

package/src/utils/darwinToolchain.js

@@ -0,0 +1,11 @@
+// The tools xcode-select picks, behind /usr/bin's shims, which the Command Line Tools alone also provide,
+// and the macOS every macOS archive is built for: port archives and Conan packages link into the same
+// addon, so they move together.
+export const DARWIN_TOOLS_BIN = '/usr/bin';
+export const DARWIN_CC = `${DARWIN_TOOLS_BIN}/clang`;
+export const DARWIN_CXX = `${DARWIN_TOOLS_BIN}/clang++`;
+// Node 22, the oldest supported line, needs macOS 11.
+export const DARWIN_DEPLOYMENT_TARGET = '11.0';
+// Homebrew and MacPorts packages exist on the build machine only: an archive compiled against one fails
+// to link, or to load, anywhere else.
+export const DARWIN_HOST_PACKAGE_PREFIXES = ['/opt/homebrew', '/usr/local', '/opt/local'];

package/src/utils/dirLock.js

@@ -1,24 +1,35 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Worker } from 'node:worker_threads';
 import logger from './logger.js';
 
-// A dependency source build can legitimately run for a long time; anything older
-// is assumed to be a crashed process whose lock must be broken.
-const DEFAULT_STALE_MS = 60 * 60 * 1000;
+// A holder refreshes its lock while it works, so a lock nobody refreshed for this long was left by a crash, even when
+// another process has taken over its PID since.
+const DEFAULT_STALE_MS = 30 * 1000;
+// A crossbind from before the refreshing kept its lock as long as its PID ran, and one whose PID cannot be read this long.
+const LEGACY_STALE_MS = 60 * 60 * 1000;
 const DEFAULT_POLL_MS = 2000;
+const DEFAULT_HELD_BY = 'another build is working on this dependency';
+// Breaking a lock takes no time, so a break file this old was left by a waiter that died breaking one.
+const BREAK_STALE_MS = 10 * 1000;
+// Windows keeps the name of a deleted file while another handle has it open.
+const DELETE_PENDING_MS = 2 * 1000;
 
 const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
-// Reads the PID recorded in the lock file and reports whether that process is
-// still running: 'alive' (signal delivered, or owned by another user), 'dead'
-// (no such process), or 'unknown' (missing/unparseable PID).
-export function lockHolderStatus(lockPath) {
-    let pid;
+// The holder's PID, and from this crossbind on the token of its acquisition on the next line.
+function readLock(lockPath) {
     try {
-        pid = Number.parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
+        const [pid, token] = fs.readFileSync(lockPath, 'utf8').split('\n').map((line) => line.trim());
+        return { pid: Number.parseInt(pid, 10), token: token || undefined, isLegacy: Boolean(pid) && !token };
     } catch {
-        return 'unknown';
+        return {};
     }
+}
+
+function statusOf(pid) {
     if (!Number.isInteger(pid) || pid <= 0) return 'unknown';
     try {
         process.kill(pid, 0);
@@ -30,42 +41,140 @@ export function lockHolderStatus(lockPath) {
     }
 }
 
-export default async function withDirLock(lockPath, fn, options = {}) {
+// Reads the PID recorded in the lock file and reports whether that process is
+// still running: 'alive' (signal delivered, or owned by another user), 'dead'
+// (no such process), or 'unknown' (missing/unparseable PID).
+export function lockHolderStatus(lockPath) {
+    return statusOf(readLock(lockPath).pid);
+}
+
+let refresher;
+
+// Refreshes the held locks from a thread of its own, so a holder blocked in execFileSync still shows it is working.
+function lockRefresher() {
+    if (!refresher) {
+        refresher = new Worker(`
+            const fs = require('node:fs');
+            const { parentPort } = require('node:worker_threads');
+            const timers = new Map();
+            parentPort.on('message', ({ hold, release, everyMs }) => {
+                clearInterval(timers.get(hold ?? release));
+                timers.delete(hold ?? release);
+                if (!hold) return;
+                timers.set(hold, setInterval(() => {
+                    const now = new Date();
+                    try {
+                        fs.utimesSync(hold, now, now);
+                    } catch {
+                        // released since the last refresh
+                    }
+                }, everyMs));
+            });
+        `, { eval: true, execArgv: [] });
+        refresher.on('error', (error) => logger.info(`crossbind: cannot refresh held locks (${error.message}); a waiting process may take one over.`));
+        refresher.unref();
+    }
+    return refresher;
+}
+
+// Takes the lock, yielding each wait so the async and the sync lock share one procedure.
+function* acquire(lockPath, token, options) {
     const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
     const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
 
     let hasWarned = false;
+    let deniedSince;
+    let suspect;
     for (;;) {
         try {
             const fd = fs.openSync(lockPath, 'wx');
-            fs.writeSync(fd, String(process.pid));
+            fs.writeSync(fd, `${process.pid}\n${token}\n`);
             fs.closeSync(fd);
-            break;
+            lockRefresher().postMessage({ hold: lockPath, everyMs: staleMs / 6 });
+            return;
         } catch (e) {
+            if (e.code === 'EPERM' && process.platform === 'win32') {
+                deniedSince ??= performance.now();
+                if (performance.now() - deniedSince < DELETE_PENDING_MS) {
+                    yield pollMs;
+                    continue;
+                }
+            }
             if (e.code !== 'EEXIST') throw e;
-            const status = lockHolderStatus(lockPath);
-            const mtimeMs = fs.statSync(lockPath, { throwIfNoEntry: false })?.mtimeMs;
-            const mtimeStale = mtimeMs !== undefined && Date.now() - mtimeMs > staleMs;
-            // A provably-dead holder (e.g. a Ctrl-C that skipped the finally cleanup) is broken
-            // at once; a live holder is never stolen, even past the stale window; when the holder
-            // can't be determined we fall back to the mtime age.
-            if (status === 'dead' || (status !== 'alive' && mtimeStale)) {
-                logger.info(`crossbind: breaking stale lock ${lockPath} (holder ${status}).`);
-                fs.rmSync(lockPath, { force: true });
+        }
+        // The file is read before its holder, so a lock another waiter took meanwhile never passes for the stale one.
+        const lock = fs.statSync(lockPath, { throwIfNoEntry: false });
+        const holder = readLock(lockPath);
+        const status = statusOf(holder.pid);
+        // A provably-dead holder (e.g. a Ctrl-C that skipped the finally cleanup) is broken at once. Any other goes once
+        // nobody refreshed it within the stale window for two refreshes in a row, so a holder waking from sleep refreshes
+        // it first; an older crossbind's lock only once its holder is gone.
+        if (lock && status === 'dead' && breakStaleLock(lockPath, lock, 'its holder is gone')) continue;
+        const age = lock ? Date.now() - lock.mtimeMs : 0;
+        const isUnrefreshed = holder.isLegacy ? status !== 'alive' && age > LEGACY_STALE_MS : age > staleMs;
+        if (lock && isUnrefreshed) {
+            if (suspect?.ino !== lock.ino || suspect.mtimeMs !== lock.mtimeMs) {
+                suspect = { ino: lock.ino, mtimeMs: lock.mtimeMs, since: performance.now() };
+            } else if (performance.now() - suspect.since >= staleMs / 3 && breakStaleLock(lockPath, lock, 'nobody refreshes it')) {
                 continue;
             }
-            if (!hasWarned) {
-                logger.info(`crossbind: waiting for ${lockPath} (another build is working on this dependency)…`);
-                hasWarned = true;
-            }
-            await sleep(pollMs);
         }
+        if (!hasWarned) {
+            logger.info(`crossbind: waiting for ${lockPath} (${options.heldBy ?? DEFAULT_HELD_BY})…`);
+            hasWarned = true;
+        }
+        yield pollMs;
     }
+}
 
+// Waiters that all saw the stale holder break the lock one at a time, and only the file they saw: otherwise one removes
+// the lock another has just taken. False while another waiter is breaking it.
+function breakStaleLock(lockPath, stale, reason) {
+    const breakPath = `${lockPath}.break`;
+    try {
+        fs.closeSync(fs.openSync(breakPath, 'wx'));
+    } catch (e) {
+        if (e.code !== 'EEXIST') throw e;
+        const mtimeMs = fs.statSync(breakPath, { throwIfNoEntry: false })?.mtimeMs;
+        if (mtimeMs !== undefined && Date.now() - mtimeMs > BREAK_STALE_MS) fs.rmSync(breakPath, { force: true });
+        return false;
+    }
+    try {
+        const lock = fs.statSync(lockPath, { throwIfNoEntry: false });
+        if (lock?.ino === stale.ino && lock.mtimeMs === stale.mtimeMs) {
+            logger.info(`crossbind: breaking stale lock ${lockPath} (${reason}).`);
+            fs.rmSync(lockPath, { force: true });
+        }
+    } finally {
+        fs.rmSync(breakPath, { force: true });
+    }
+    return true;
+}
+
+// A holder that stopped refreshing may have lost the lock to another process, whose lock it must leave.
+function release(lockPath, token) {
+    lockRefresher().postMessage({ release: lockPath });
+    if (readLock(lockPath).token === token) fs.rmSync(lockPath, { force: true });
+}
+
+export default async function withDirLock(lockPath, fn, options = {}) {
+    const token = randomUUID();
+    for (const ms of acquire(lockPath, token, options)) await sleep(ms);
     try {
         return await fn();
     } finally {
-        fs.rmSync(lockPath, { force: true });
+        release(lockPath, token);
+    }
+}
+
+// For a caller that holds the lock across execFileSync, where the event loop cannot run anyway.
+export function withDirLockSync(lockPath, fn, options = {}) {
+    const token = randomUUID();
+    for (const ms of acquire(lockPath, token, options)) sleepSync(ms);
+    try {
+        return fn();
+    } finally {
+        release(lockPath, token);
     }
 }