Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

11.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { spawn } from 'child_process';
import fs, { existsSync } from 'fs';
import os from 'os';
import path from 'path';
import { fileURLToPath } from 'url';
import * as logger from './logger.js';

const MIN_EMSCRIPTEN_VERSION = '5.0.0';

// Repo root, derived from this file's location (build-tools/utils/emscripten.js).
const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
// Per-machine cache of the resolved emsdk path (gitignored). Lets the next build
// skip the directory scan and pins the choice once discovered.
const EMSDK_CACHE_FILE = path.join(REPO_ROOT, '.emsdk-path');

// An emsdk root is usable if it has an activated emscripten install: the
// `upstream/emscripten` tree (emcc/em++/emcmake) plus the generated `.emscripten`
// config that emcc reads via EM_CONFIG.
function isActivatedEmsdk(root) {
    return !!root
        && existsSync(path.join(root, 'upstream', 'emscripten'))
        && existsSync(path.join(root, '.emscripten'));
}

// emsdk ships its own Node under node/<version>/bin — return the first one.
function firstEmsdkNodeBin(root) {
    const nodeDir = path.join(root, 'node');
    if (!existsSync(nodeDir)) return null;
    for (const ver of fs.readdirSync(nodeDir)) {
        const bin = path.join(nodeDir, ver, 'bin');
        if (existsSync(bin)) return bin;
    }
    return null;
}

// Candidate emsdk roots, highest priority first:
//   1. EMSDK env var (explicit, e.g. a sourced emsdk_env)
//   2. .emsdk-path cache written by a previous discovery
//   3. the tools/emsdk submodule (set up via `pnpm emsdk:setup`)
//   4. common install locations (~/emsdk, drive roots on Windows, /opt on *nix)
function candidateEmsdkRoots() {
    const candidates = [];
    if (process.env.EMSDK) candidates.push(process.env.EMSDK);
    try {
        if (existsSync(EMSDK_CACHE_FILE)) {
            const cached = fs.readFileSync(EMSDK_CACHE_FILE, 'utf8').trim();
            if (cached) candidates.push(cached);
        }
    } catch {
        // unreadable cache is non-fatal — fall through to scanning
    }
    candidates.push(path.join(REPO_ROOT, 'tools', 'emsdk'));
    candidates.push(path.join(os.homedir(), 'emsdk'));
    if (process.platform === 'win32') {
        for (const drive of ['C', 'D', 'E', 'F', 'G', 'H']) {
            candidates.push(`${drive}:\\emsdk`);
        }
    } else {
        candidates.push('/opt/emsdk', '/usr/local/emsdk');
    }
    return candidates;
}

/**
 * The `emcc` a gate should run, or null when this machine has no activated
 * emsdk. Same discovery the build uses: a gate that looked only in
 * `tools/emsdk` skipped itself on every machine whose emsdk lives elsewhere —
 * which is the arrangement `pnpm emsdk:setup` itself tells you to prefer.
 */
export function emccPath() {
    for (const root of candidateEmsdkRoots()) {
        if (!isActivatedEmsdk(root)) continue;
        const at = path.join(root, 'upstream', 'emscripten',
            process.platform === 'win32' ? 'emcc.bat' : 'emcc');
        if (existsSync(at)) return at;
    }
    return null;
}

/** How a checkout with no emsdk says so, rather than skipping in silence. */
export const NO_EMCC = 'ESTELLA_NO_EMCC';

/**
 * Prove the machine can compile to wasm before a suite claims it compared
 * anything against a module. A skip reads the same in a summary as a test that
 * ran, so a run either has emcc or declares that it has none.
 */
export function proveEmcc(suite) {
    if (emccPath()) return;
    if (process.env[NO_EMCC] === '1') {
        console.warn(`\n[${suite}] ${NO_EMCC}=1 — nothing that needs emcc ran.\n`
            + '            This run compiled no module, so it compared none.\n');
        return;
    }
    throw new Error(
        'no activated emsdk on this machine.\n'
        + '  The AOT suites build a real module, and skipping them would report a partial run\n'
        + `  as a clean one. Run \`pnpm emsdk:setup\`, or declare the gap with ${NO_EMCC}=1 —\n`
        + '  which the gate runner then counts as something this machine could not answer.');
}

let emsdkActivated = false;

// Bound Binaryen workers on Windows; preserve explicit environment overrides.
export function withBinaryenWorkers(env, platform = process.platform) {
    const result = { ...env };
    if (platform === 'win32' && result.BINARYEN_CORES === undefined) {
        result.BINARYEN_CORES = '1';
    }
    return result;
}

/**
 * Locate an activated emsdk and inject it into this process's environment so
 * `emcc`/`em++`/`emcmake`/`wasm-opt` resolve without the caller having to source
 * `emsdk_env`. Mutates process.env (PATH, EM_CONFIG, EMSDK), which every child
 * spawned via runCommand inherits. Idempotent; returns true once an emsdk is
 * active (either pre-existing on PATH or freshly discovered).
 */
export function ensureEmscriptenEnv() {
    const workers = withBinaryenWorkers(process.env).BINARYEN_CORES;
    if (workers !== undefined) process.env.BINARYEN_CORES = workers;
    if (emsdkActivated) return true;

    let root = null;
    for (const candidate of candidateEmsdkRoots()) {
        if (isActivatedEmsdk(candidate)) {
            root = path.resolve(candidate);
            break;
        }
    }
    if (!root) return false;

    const emscriptenDir = path.join(root, 'upstream', 'emscripten');
    const binDir = path.join(root, 'upstream', 'bin');
    const nodeBin = firstEmsdkNodeBin(root);
    const additions = [root, emscriptenDir, binDir, nodeBin].filter(existsSync);

    process.env.EMSDK = root;
    process.env.EM_CONFIG = path.join(root, '.emscripten');
    if (nodeBin) {
        process.env.EMSDK_NODE = path.join(nodeBin, process.platform === 'win32' ? 'node.exe' : 'node');
    }
    process.env.PATH = additions.join(path.delimiter) + path.delimiter + (process.env.PATH || '');

    try {
        fs.writeFileSync(EMSDK_CACHE_FILE, `${root}\n`);
    } catch {
        // cache is an optimization — a read-only tree is fine
    }

    emsdkActivated = true;
    logger.debug(`Activated emsdk at ${root}`);
    return true;
}

function compareVersions(a, b) {
    const pa = a.split('.').map(Number);
    const pb = b.split('.').map(Number);
    for (let i = 0; i < 3; i++) {
        if (pa[i] > pb[i]) return 1;
        if (pa[i] < pb[i]) return -1;
    }
    return 0;
}

export async function checkEmscripten() {
    // Auto-discover + activate a local emsdk (EMSDK env → .emsdk-path cache →
    // tools/emsdk submodule → common locations) so `emcc` resolves even when the
    // caller never sourced emsdk_env. No-op if emsdk is already on PATH.
    ensureEmscriptenEnv();
    try {
        const result = await runCommand('emcc', ['--version'], { silent: true });
        const versionMatch = result.stdout.match(/(\d+\.\d+\.\d+)/);
        if (!versionMatch) {
            logger.error('Could not determine Emscripten version.');
            return false;
        }

        const version = versionMatch[1];
        logger.debug(`Emscripten version: ${version}`);

        if (compareVersions(version, MIN_EMSCRIPTEN_VERSION) < 0) {
            logger.error(`Emscripten ${version} is too old. Minimum required: ${MIN_EMSCRIPTEN_VERSION}`);
            logger.info(`  Update: emsdk install ${MIN_EMSCRIPTEN_VERSION} && emsdk activate ${MIN_EMSCRIPTEN_VERSION}`);
            logger.info('  Then: source /path/to/emsdk/emsdk_env.sh');
            return false;
        }

        return true;
    } catch {
        return false;
    }
}

let cachedPython = null;

/**
 * Resolve a Python 3 interpreter. Prefers `python3`, falls back to `python`
 * (Windows ships Python as `python`, not `python3`). Verifies the candidate
 * actually reports Python 3 so a Windows Store alias stub doesn't pass.
 * Returns the command name, or null if none found. Cached after first call.
 */
export async function resolvePython() {
    if (cachedPython) return cachedPython;
    for (const candidate of ['python3', 'python']) {
        try {
            const r = await runCommand(candidate, ['--version'], { silent: true });
            if (/Python 3\./.test(`${r.stdout}${r.stderr}`)) {
                cachedPython = candidate;
                return candidate;
            }
        } catch {
            // try next candidate
        }
    }
    return null;
}

export async function checkPython() {
    return (await resolvePython()) !== null;
}

export async function checkEnvironment() {
    const checks = {
        emscripten: await checkEmscripten(),
        python: await checkPython(),
    };

    if (!checks.emscripten) {
        logger.error('Emscripten not found. No activated emsdk was discovered.');
        logger.info(`  Required version: ${MIN_EMSCRIPTEN_VERSION}`);
        logger.info('  Set up the bundled submodule: pnpm emsdk:setup');
        logger.info('  Or point at an existing install: set EMSDK=/path/to/emsdk');
        logger.info('  (auto-discovery checks: $EMSDK → .emsdk-path → tools/emsdk → ~/emsdk)');
        return false;
    }

    if (!checks.python) {
        logger.error('Python 3 not found. Please install Python 3.');
        return false;
    }

    logger.debug('Environment check passed');
    return true;
}

export function runCommand(command, args, options = {}) {
    return new Promise((resolve, reject) => {
        const { cwd, silent = false, env } = options;

        logger.debug(`Running: ${command} ${args.join(' ')}`);

        // Windows runs these through cmd, which re-splits the whole line on spaces:
        // an unquoted `C:\Program Files\...` (where the Android SDK and a bundled
        // JDK normally live) would arrive as two arguments. Quote what needs it —
        // only under the shell, since a direct spawn passes argv through intact.
        const shell = process.platform === 'win32';
        const quoted = (s) => (shell && /\s/.test(s) && !/^".*"$/.test(s) ? `"${s}"` : s);

        // Keep CMake's MSVC prefix probe and Ninja's /showIncludes parser on
        // the same console encoding, including installations with only a
        // localized compiler language pack. English VSLANG cannot fix those.
        const executable = shell ? `chcp 65001>nul && ${quoted(command)}` : command;
        const proc = spawn(executable, args.map(quoted), {
            cwd,
            env: withBinaryenWorkers({ ...process.env, ...env }),
            stdio: silent ? 'pipe' : 'inherit',
            shell,
        });

        let stdout = '';
        let stderr = '';

        if (silent) {
            proc.stdout?.on('data', (data) => {
                stdout += data.toString();
            });
            proc.stderr?.on('data', (data) => {
                stderr += data.toString();
            });
        }

        proc.on('close', (code) => {
            if (code === 0) {
                resolve({ stdout, stderr, code });
            } else {
                const error = new Error(`Command failed with code ${code}`);
                error.code = code;
                error.stdout = stdout;
                error.stderr = stderr;
                reject(error);
            }
        });

        proc.on('error', (err) => {
            reject(err);
        });
    });
}

export function getCpuCount() {
    // ESTELLA_BUILD_JOBS overrides; otherwise leave two cores free — a full-core
    // emcc + LTO link saturates CPU and RAM and can freeze the machine outright.
    const override = Number(process.env.ESTELLA_BUILD_JOBS);
    if (Number.isFinite(override) && override >= 1) return Math.floor(override);
    return Math.max(1, os.cpus().length - 2);
}