Files
cocos4/scripts/ensure-pal.cjs
T
llsansun 2157fd176d Multithreading (#322)
* worker pool

* opt

* backup

* worker and worker backend

* worker fallback

* opt

* opt

* remove meta

* opt

* worker export

* testcase fix

* worker js template

* worker pal

* worker opt

* test

* Replace error messages with error codes

* Package size reduction

* Package size reduction

* revert

* Restore editor asset .meta files to the base branch state

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014HAtWwr4dy5azfpccweh1g

* bugfix

* Split into two features: Worker and Worker Pool

* worker option

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 16:35:14 +08:00

193 lines
8.6 KiB
JavaScript

const fs = require('fs');
const path = require('path');
// `pal/` is a generated copy of a PAL dist directory (see spread-pal.cjs). Every build entry calls
// this module first so a checkout keeps building even when dependencies changed without a fresh
// `npm install` (or postinstall was skipped). Checks run in order; each receives palRoot, returns
// true if it changed files, and throws when the build cannot continue. Checks must be safe to repeat.
const checks = [
syncInstalledPackage,
ensureWorker,
];
// Written by spread-pal.cjs: where pal/ was copied from, and the package version at that time.
const STAMP = '.pal-source.json';
const FALLBACK_MARKER = '// Compatibility only: real platform implementations remain in cocos-pal.';
const FALLBACK_TEMPLATE = path.join(__dirname, 'pal-worker-fallback');
const PLATFORMS = ['web', 'minigame', 'native', 'nodejs'];
// The shared compatibility implementation is deliberately NOT named `index.js`: a file at
// pal/worker/index.js lets resolvers (the editor/preview quick compiler, tsconfig baseUrl) turn the
// bare `pal/worker` import into that directory file instead of the per-platform override from
// cc.config.json, and a cached resolution then keeps pointing at the fallback even after the real
// PAL worker is installed. Real PAL packages have no root index either.
const FALLBACK_FILE = 'compat.js';
const FORWARDER = `export { createWorkerBackend } from '../${FALLBACK_FILE}';\n`;
// Layout generated by earlier engine versions (root index.js); recognised so it can be migrated.
const LEGACY_FALLBACK_FILE = 'index.js';
const LEGACY_FORWARDER = "export { createWorkerBackend } from '../index.js';\n";
// Shared entry for installation and every engine build path.
function ensurePal(palRoot = path.join(__dirname, '..', 'pal')) {
if (!fs.existsSync(palRoot) || !fs.statSync(palRoot).isDirectory()) {
throw new Error(`PAL directory is missing: ${palRoot}. Install engine dependencies first.`);
}
let changed = false;
for (const check of checks) {
// Always execute every check, even if an earlier one changed files.
if (check(palRoot)) changed = true;
}
return changed;
}
// ---------------------------------------------------------------- PAL copy helpers (spread-pal)
function packageDist(palRoot) {
return path.join(path.dirname(palRoot), 'node_modules', '@cocos', 'engine-pal', 'dist');
}
function readJson(file) {
try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return null; }
}
function packageVersion(dist) {
const pkg = readJson(path.join(dist, '..', 'package.json'));
return pkg && typeof pkg.version === 'string' ? pkg.version : null;
}
function readStamp(palRoot) {
return readJson(path.join(palRoot, STAMP));
}
// Remove a path; a symlink is unlinked without touching its target (historical pal symlinks).
function removeExisting(p) {
let st;
try { st = fs.lstatSync(p); } catch (e) { return; }
if (st.isSymbolicLink()) fs.unlinkSync(p);
else fs.rmSync(p, { recursive: true, force: true });
}
function copyDir(src, dst) {
let count = 0;
fs.mkdirSync(dst, { recursive: true });
for (const name of fs.readdirSync(src)) {
const sp = path.join(src, name);
const dp = path.join(dst, name);
if (fs.statSync(sp).isDirectory()) count += copyDir(sp, dp);
else { fs.copyFileSync(sp, dp); count++; }
}
return count;
}
// Replace palRoot with a fresh copy of src and record where it came from. `fromPackage` marks the
// installed npm package (the postinstall default), which later builds keep in sync automatically;
// an explicit local source (PAL development) is never replaced behind the developer's back.
function spread(src, palRoot, fromPackage) {
removeExisting(palRoot);
const count = copyDir(src, palRoot);
const stamp = fromPackage
? { package: '@cocos/engine-pal', version: packageVersion(src) }
// Relative to the engine root so the record stays valid if the checkout is moved or mounted elsewhere.
: { source: path.relative(path.dirname(palRoot), path.resolve(src)).split(path.sep).join('/') };
fs.writeFileSync(path.join(palRoot, STAMP), `${JSON.stringify(stamp, null, 4)}\n`);
return count;
}
// ---------------------------------------------------------------- checks
// pal/ was copied from the npm package, but a different version is installed now (dependencies
// were updated with --ignore-scripts, or postinstall failed after npm replaced the package).
// Re-copy the whole directory so no module is left from the old version.
function syncInstalledPackage(palRoot) {
const stamp = readStamp(palRoot);
if (!stamp || !stamp.package) return false;
const dist = packageDist(palRoot);
const installed = packageVersion(dist);
if (!installed || !fs.existsSync(dist) || installed === stamp.version) return false;
spread(dist, palRoot, true);
console.log(`[spread-pal] pal/ was copied from @cocos/engine-pal ${stamp.version}, `
+ `installed is ${installed}; re-synchronized.`);
return true;
}
// 'real' : a PAL worker implementation (never modified, even if only partially present).
// 'fallback' : the engine-generated single-thread compatibility module.
// 'missing' : no worker directory.
function workerState(workerRoot) {
if (!fs.existsSync(workerRoot)) return 'missing';
const generated = (file, forwarder) => {
const shared = path.join(workerRoot, file);
return fs.existsSync(shared)
&& fs.readFileSync(shared, 'utf8').startsWith(FALLBACK_MARKER)
&& PLATFORMS.every((platform) => {
const entry = path.join(workerRoot, platform, 'index.js');
return fs.existsSync(entry) && fs.readFileSync(entry, 'utf8') === forwarder;
});
};
return generated(FALLBACK_FILE, FORWARDER) || generated(LEGACY_FALLBACK_FILE, LEGACY_FORWARDER)
? 'fallback' : 'real';
}
// Where a real worker module can be taken from: the recorded spread source, or the installed
// package for pal/ copies predating the stamp. Never mixes an explicit local source with npm.
function workerSource(palRoot) {
const stamp = readStamp(palRoot);
const dist = stamp && stamp.source ? path.resolve(path.dirname(palRoot), stamp.source) : packageDist(palRoot);
const worker = path.join(dist, 'worker');
return fs.existsSync(worker) && workerState(worker) === 'real' ? worker : null;
}
function listFiles(dir, base = dir, out = {}) {
for (const name of fs.readdirSync(dir)) {
const p = path.join(dir, name);
if (fs.statSync(p).isDirectory()) listFiles(p, base, out);
else out[path.relative(base, p).split(path.sep).join('/')] = fs.readFileSync(p, 'utf8');
}
return out;
}
function fallbackFiles() {
const files = { [FALLBACK_FILE]: fs.readFileSync(path.join(FALLBACK_TEMPLATE, FALLBACK_FILE), 'utf8') };
for (const platform of PLATFORMS) files[`${platform}/index.js`] = FORWARDER;
return files;
}
// PAL packages before 1.0.5 have no worker module. Keep `pal/worker` resolvable for builds that
// enable the optional `worker` feature: prefer a real implementation whenever one is available,
// otherwise supply a platform-independent unavailable backend (WorkerPool then runs inline).
// Nothing here includes Worker in builds without either optional Worker feature.
// Types come from @types/pal/worker.d.ts, so the compatibility module is JS only.
function ensureWorker(palRoot) {
const workerRoot = path.join(palRoot, 'worker');
const state = workerState(workerRoot);
if (state === 'real') return false;
const source = workerSource(palRoot);
if (source) {
removeExisting(workerRoot);
copyDir(source, workerRoot);
console.log(`[pal-worker] Restored the platform worker module from ${source}.`);
return true;
}
const expected = fallbackFiles();
if (state === 'fallback') {
const actual = listFiles(workerRoot);
const same = Object.keys(actual).length === Object.keys(expected).length
&& Object.keys(expected).every((file) => actual[file] === expected[file]);
if (same) return false;
}
removeExisting(workerRoot);
for (const [file, content] of Object.entries(expected)) {
const target = path.join(workerRoot, file);
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, content);
}
console.log('[pal-worker] PAL has no worker module; installed single-thread compatibility backend. '
+ 'Run `npm install` to pick up @cocos/engine-pal with platform workers.');
return true;
}
module.exports = ensurePal;
module.exports.spread = spread;
module.exports.packageDist = packageDist;