/**
* @license
* Copyright 2010 The Emscripten Authors
* SPDX-License-Identifier: MIT
*/
// Convert analyzed data to javascript. Everything has already been calculated
// before this stage, which just does the final conversion to JavaScript.
import assert from 'node:assert';
import * as fs from 'node:fs/promises';
import * as acorn from 'acorn';
import {
ATMODULES,
ATEXITS,
ATINITS,
ATPOSTCTORS,
ATPRERUNS,
ATMAINS,
ATPOSTRUNS,
defineI64Param,
indentify,
makeReturn64,
modifyJSFunction,
preprocess,
processMacros,
receiveI64ParamAsI53,
} from './parseTools.mjs';
import {
addToCompileTimeContext,
debugLog,
error,
errorOccured,
extraLibraryFuncs,
isDecorator,
isJsOnlySymbol,
compileTimeContext,
readFile,
runInMacroContext,
warn,
warnOnce,
warningOccured,
localFile,
timer,
} from './utility.mjs';
import {
addedLibraryItems,
extraExports,
LibraryManager,
librarySymbols,
nativeAliases,
shouldExportLibrarySymbol,
} from './modules.mjs';
// Debug-only mode (`EMCC_CHECK_DEPS=1` in the environment) that performs a full
// AST parse on JS library items and reports an error if any local binding
// shadows a library symbol (which could cause false positives in the
// token-based `calcImplicitDeps` scanner above).
const CHECK_DEPS = process.env.EMCC_CHECK_DEPS;
// Some JS-implemented library functions are proxied to be called on the main
// browser thread, if the Emscripten runtime is executing in a Web Worker.
// Each such proxied function is identified via an ordinal number (this is not
// the same namespace as function pointers in general).
const proxiedFunctionTable = [];
// Mangles the given C/JS side function name to assembly level function name (adds an underscore)
function mangleCSymbolName(f) {
if (f === '__main_argc_argv') {
f = 'main';
}
return f[0] == '$' ? f.slice(1) : '_' + f;
}
// Splits out items that pass filter. Returns also the original sans the filtered
function splitter(array, filter) {
const splitOut = array.filter(filter);
const leftIn = array.filter((x) => !filter(x));
return {leftIn, splitOut};
}
function escapeJSONKey(x) {
if (/^[\d\w_]+$/.exec(x) || x[0] === '"' || x[0] === "'") return x;
assert(!x.includes("'"), 'cannot have internal single quotes in keys: ' + x);
return "'" + x + "'";
}
// JSON.stringify will completely omit function objects. This function is
// similar but preserves functions.
function stringifyWithFunctions(obj) {
if (typeof obj === 'function') return obj.toString();
if (obj === null || typeof obj !== 'object') return JSON.stringify(obj);
if (Array.isArray(obj)) {
return '[' + obj.map(stringifyWithFunctions).join(',') + ']';
}
// preserve the type of the object if it is one of [Map, Set, WeakMap, WeakSet].
const builtinContainers = runInMacroContext('[Map, Set, WeakMap, WeakSet]', {
filename: '<internal>',
});
for (const container of builtinContainers) {
if (obj instanceof container) {
const className = container.name;
assert(!obj.size, `cannot stringify ${className} with data`);
return `new ${className}`;
}
}
var rtn = '{\n';
for (const [key, value] of Object.entries(obj)) {
var str = stringifyWithFunctions(value);
// Handle JS method syntax where the function property starts with its own
// name. e.g. `foo(a) {}` (or `async foo(a) {}`)
if (typeof value === 'function' && (str.startsWith(key) || str.startsWith('async ' + key))) {
rtn += str + ',\n';
} else {
rtn += `${escapeJSONKey(key)}:${str},\n`;
}
}
return rtn + '}';
}
function isDefined(symName) {
if (WASM_EXPORTS.has(symName) || SIDE_MODULE_EXPORTS.has(symName)) {
return true;
}
if (symName == '__main_argc_argv' && SIDE_MODULE_EXPORTS.has('main')) {
return true;
}
// 'invoke_' symbols are created at runtime in library_dylink.py so can
// always be considered as defined.
if (MAIN_MODULE && symName.startsWith('invoke_')) {
return true;
}
return false;
}
function getTransitiveDeps(symbol) {
// TODO(sbc): Use some kind of cache to avoid quadratic behaviour here.
const transitiveDeps = new Set();
const seen = new Set();
const toVisit = [symbol];
while (toVisit.length) {
const sym = toVisit.pop();
if (!seen.has(sym)) {
let directDeps = LibraryManager.library[sym + '__deps'] ?? [];
directDeps = directDeps.filter((d) => typeof d === 'string');
for (const dep of directDeps) {
if (!transitiveDeps.has(dep)) {
debugLog(`adding dependency ${symbol} -> ${dep}`);
}
transitiveDeps.add(dep);
toVisit.push(dep);
}
seen.add(sym);
}
}
return Array.from(transitiveDeps);
}
function shouldPreprocess(fileName) {
var content = readFile(fileName).trim();
return content.startsWith('#preprocess\n') || content.startsWith('#preprocess\r\n');
}
function getIncludeFile(fileName, alwaysPreprocess, shortName) {
shortName ??= fileName;
let result = `// include: ${shortName}\n`;
const doPreprocess = alwaysPreprocess || shouldPreprocess(fileName);
if (doPreprocess) {
result += processMacros(preprocess(fileName), fileName);
} else {
result += readFile(fileName);
}
result += `// end include: ${shortName}\n`;
return result;
}
function getSystemIncludeFile(fileName) {
return getIncludeFile(localFile(fileName), /*alwaysPreprocess=*/ true, /*shortName=*/ fileName);
}
function preJS() {
let result = '';
for (const fileName of PRE_JS_FILES) {
result += getIncludeFile(fileName);
}
return result;
}
// Check if tokens[i] is the name of an object/class method definition `foo(...) {`
function isMethodDef(tokens, i) {
if (tokens[i + 1]?.type.label !== '(') {
return false;
}
let depth = 1;
for (let j = i + 2; j < tokens.length; j++) {
const label = tokens[j].type.label;
if (label === '(') {
depth++;
} else if (label === ')') {
depth--;
if (depth === 0) {
return tokens[j + 1]?.type.label === '{';
}
}
}
return false;
}
// Unlike JS library symbols, user code in `--pre-js`, `--post-js`, and
// `EM_JS`/`EM_ASM` snippets does not automatically pull in arbitrary JS
// library symbols (users must pass `-sDEFAULT_LIBRARY_FUNCS_TO_INCLUDE` or
// `-sEXPORTED_RUNTIME_METHODS`). Only these common runtime helpers and heap
// views are implicitly included when referenced in those snippets.
const implicitSnippetDeps = new Set([
'getDynCaller',
'getWasmTableEntry',
'makeBigInt',
'runtimeKeepalivePush',
'runtimeKeepalivePop',
'UTF8ToString',
// TODO: Consider removing getValue and setValue if they are rarely used implicitly.
'getValue',
'setValue',
'HEAP8',
'HEAP16',
'HEAPU8',
'HEAPU16',
'HEAP32',
'HEAPU32',
'HEAPF32',
'HEAPF64',
'HEAP64',
'HEAPU64',
]);
function findLibrarySymbol(name, isUserSnippet = false) {
let sym;
if ('$' + name in LibraryManager.library) {
sym = '$' + name;
} else if (!isUserSnippet && name.startsWith('_') && name.slice(1) in LibraryManager.library) {
sym = name.slice(1);
}
// $noExitRuntime cannot be referenced via __deps (it must be included via
// DEFAULT_LIBRARY_FUNCS_TO_INCLUDE or EXPORTED_RUNTIME_METHODS).
if (sym && sym !== '$noExitRuntime') {
return sym;
}
}
// Scan a JS snippet for references to JS library symbols using `acorn.tokenizer`.
// Because this uses a flat token scan rather than full AST/scope analysis (for
// speed and to handle partial JS fragments in `--pre-js`/`--post-js`), it is
// conservative and can produce false positives if local variables or parameters
// shadow a library symbol name. (We use a full AST walk in EMCC_CHECK_DEPS to
// detect such shadowing in system libraries).
function calcImplicitDeps(snippet, isUserSnippet = false) {
const found = new Set();
const typeofSyms = new Set();
const tokens = Array.from(acorn.tokenizer(snippet, {ecmaVersion: 2022}));
for (let i = 0; i < tokens.length; i++) {
const tok = tokens[i];
if (tok.type.label !== 'name') {
continue;
}
const name = tok.value;
const prevToken = tokens[i - 1];
const nextToken = tokens[i + 1];
// Ignore property accesses (e.g. `obj.foo` or `obj?.foo`)
if (prevToken?.type.label === '.' || prevToken?.type.label === '?.') {
continue;
}
// Ignore function or class declarations' own name (e.g. `function foo()` or `class Foo`)
if (prevToken?.type.keyword === 'function' || prevToken?.type.keyword === 'class') {
continue;
}
// Ignore object literal property keys (e.g. `{ foo: 123 }`)
if (nextToken?.type.label === ':' && (prevToken?.type.label === '{' || prevToken?.type.label === ',')) {
continue;
}
// Ignore object/class shorthand method definitions (e.g. `foo() { ... }`)
if (isMethodDef(tokens, i)) {
continue;
}
// Ignore `typeof foo` existence checks (e.g. `if (typeof SDL !== 'undefined') SDL.foo()`).
if (prevToken?.type.keyword === 'typeof') {
if (nextToken?.type.label !== '.') {
typeofSyms.add(name);
}
continue;
}
if (typeofSyms.has(name)) {
continue;
}
// If the snippet contains eval(), it may dynamically evaluate code loaded from memory at runtime
// (for example, in emscripten_run_script where the snippet is eval(UTF8ToString(ptr))).
// Because static analysis cannot inspect what strings are stored in memory or evaluated
// at runtime, we must conservatively include all heap views whenever a snippet uses eval().
if (name === 'eval' && nextToken?.type.label === '(') {
found.add('$HEAP8');
found.add('$HEAPU8');
found.add('$HEAP16');
found.add('$HEAPU16');
found.add('$HEAP32');
found.add('$HEAPU32');
found.add('$HEAPF32');
found.add('$HEAPF64');
if (WASM_BIGINT || MEMORY64) {
found.add('$HEAP64');
found.add('$HEAPU64');
}
continue;
}
// When scanning `--pre-js`, `--post-js`, or `EM_JS`/`EM_ASM`,
// only auto-include symbols from `implicitSnippetDeps`.
if (isUserSnippet && !implicitSnippetDeps.has(name)) {
continue;
}
const dep = findLibrarySymbol(name, isUserSnippet);
if (dep) {
found.add(dep);
}
}
return found;
}
function checkShadowing(symbol, mangled, contentText) {
function checkBoundName(name) {
if (name === mangled) return;
const shadowed = findLibrarySymbol(name);
if (shadowed) {
error(`${symbol}: local binding '${name}' shadows library symbol '${shadowed}'`);
}
}
function walkPattern(node) {
if (!node) return;
switch (node.type) {
case 'Identifier':
checkBoundName(node.name);
break;
case 'AssignmentPattern':
walkPattern(node.left);
break;
case 'ArrayPattern':
node.elements.forEach(walkPattern);
break;
case 'ObjectPattern':
node.properties.forEach((p) => walkPattern(p.value || p.argument));
break;
case 'RestElement':
walkPattern(node.argument);
break;
}
}
function walk(node) {
switch (node.type) {
case 'VariableDeclarator':
walkPattern(node.id);
break;
case 'FunctionDeclaration':
case 'FunctionExpression':
case 'ArrowFunctionExpression':
if (node.id) checkBoundName(node.id.name);
node.params.forEach(walkPattern);
break;
case 'ClassDeclaration':
case 'ClassExpression':
if (node.id) checkBoundName(node.id.name);
break;
case 'CatchClause':
walkPattern(node.param);
break;
}
for (const child of Object.values(node)) {
if (typeof child?.type === 'string') {
walk(child);
} else if (Array.isArray(child)) {
for (const elem of child) {
if (typeof elem?.type === 'string') walk(elem);
}
}
}
}
walk(acorn.parse(contentText, {ecmaVersion: 2022}));
}
function sigToArgs(sig) {
const args = []
for (var i = 1; i < sig.length; i++) {
args.push(`a${i}`);
}
return args.join(',');
}
function handleI64Signatures(symbol, snippet, sig, i53abi, isAsyncFunction) {
// Handle i64 parameters and return values.
//
// When WASM_BIGINT is enabled these arrive as BigInt values which we
// convert to int53 JS numbers. If necessary, we also convert the return
// value back into a BigInt.
//
// When WASM_BIGINT is not enabled we receive i64 values as a pair of i32
// numbers which is converted to single int53 number. In necessary, we also
// split the return value into a pair of i32 numbers.
return modifyJSFunction(snippet, (args, body, async_, oneliner) => {
let argLines = args.split('\n');
argLines = argLines.map((line) => line.split('//')[0]);
const argNames = argLines
.join(' ')
.split(',')
.map((name) => name.trim());
const newArgs = [];
let argConversions = '';
if (sig.length > argNames.length + 1) {
error(`handleI64Signatures: signature '${sig}' too long for ${symbol}(${argNames.join(', ')})`);
return snippet;
}
for (const [i, name] of argNames.entries()) {
// If sig is shorter than argNames list then argType will be undefined
// here, which will result in the default case below.
const argType = sig[i + 1];
if (WASM_BIGINT && ((MEMORY64 && argType == 'p') || (i53abi && argType == 'j'))) {
argConversions += ` ${receiveI64ParamAsI53(name, undefined, false)}\n`;
} else {
if (argType == 'j' && i53abi) {
argConversions += ` ${receiveI64ParamAsI53(name, undefined, false)}\n`;
newArgs.push(defineI64Param(name));
} else if (argType == 'p' && CAN_ADDRESS_2GB) {
argConversions += ` ${name} >>>= 0;\n`;
newArgs.push(name);
} else {
newArgs.push(name);
}
}
}
if (!WASM_BIGINT) {
args = newArgs.join(',');
}
if ((sig[0] == 'j' && i53abi) || (sig[0] == 'p' && MEMORY64)) {
// For functions that where we need to mutate the return value, we
// also need to wrap the body in an inner function.
// If the inner function is marked as `__async` then we need to `await`
// the result before casting it to BigInt. Note that we use the `__async`
// attribute here rather than the presence of the `async` JS keyword
// because this is what tells us that the function is going to return
// a promise. i.e. we support async functions that return promises but
// are not marked with the `async` keyword (the latter is only necessary
// if the function uses the `await` keyword))
const await_ = isAsyncFunction ? 'await ' : '';
const orig_async_ = async_;
async_ = isAsyncFunction ? 'async ' : async_;
// An 'auto' body may return a Promise even without ASYNCIFY (on a
// pthread's behalf, which awaits it), which must not be cast but
// resolve to the cast value.
const maybePromise = !isAsyncFunction && LibraryManager.library[symbol + '__async'] == 'auto';
const convert = (v) => maybePromise ?
`(${v} instanceof Promise ? ${v}.then((v) => ${makeReturn64('v')}) : ${makeReturn64(v)})` :
makeReturn64(await_ + v);
if (oneliner) {
// Special case for abort(), this a noreturn function and but closure
// compiler doesn't have a way to express that, so it complains if we
// do `BigInt(abort(..))`.
if (body.startsWith('abort(')) {
return snippet;
}
if (argConversions || maybePromise) {
return `${async_}(${args}) => {
${argConversions}
var ret = ${body};
return ${convert('ret')};
}`;
}
return `${async_}(${args}) => ${makeReturn64(await_ + body)};`;
}
return `\
${async_}function(${args}) {
${argConversions}
var ret = (${orig_async_}() => { ${body} })();
return ${convert('ret')};
}`;
}
// Otherwise no inner function is needed and we covert the arguments
// before executing the function body.
if (oneliner) {
body = `return ${body}`;
}
return `\
${async_}function(${args}) {
${argConversions}
${body};
}`;
});
}
// An `__async: 'auto'` body returns a value or a Promise, as it can. A body
// whose last parameter is named `sync` receives there whether it must complete
// synchronously on this call, as a returned Promise could not be waited for.
// That is never the case under ASYNCIFY/JSPI, nor on behalf of a sync-proxied
// pthread caller, which awaits it; otherwise it is.
function handleSyncArg(symbol, snippet, sig, proxyingMode) {
const sync = ASYNCIFY ? 'false' :
PTHREADS && proxyingMode == 'sync' ? '!PThread.currentProxiedOperationCallerThread' : 'true';
return modifyJSFunction(snippet, (args, body, async_, oneliner) => {
const params = args.split(',').map((a) => a.trim()).filter((a) => a);
if (params.at(-1) != 'sync') return snippet;
if (sig && params.length != sig.length) {
error(`JS library error: '${symbol}' must take 'sync' as parameter ${sig.length}, after the ${sig.length - 1} of its '__sig'`);
return snippet;
}
if (!oneliner) body = `{\n${body}\n}`;
const outer = params.slice(0, -1).join(', ');
return `\
function(${outer}) {
return (${async_}(${args}) => ${body})(${outer}${outer ? ', ' : ''}${sync});
}\n`;
});
}
function handleAsyncFunction(snippet, sig, proxied) {
const return64 = sig && (MEMORY64 && sig.startsWith('p') || sig.startsWith('j'))
let handleAsync = 'Asyncify.handleAsync(innerFunc)'
if (return64 && ASYNCIFY == 1) {
handleAsync = makeReturn64(handleAsync);
}
// When dispatching on behalf of a proxied caller (PROXY_SYNC_ASYNC), the
// caller awaits the returned promise, so return it directly rather than
// suspending the main thread.
let proxiedDispatch = '';
if (ASYNCIFY == 1 && PTHREADS && proxied) {
proxiedDispatch = 'if (PThread.currentProxiedOperationCallerThread) return innerFunc();\n ';
}
return modifyJSFunction(snippet, (args, body, async_, oneliner) => {
if (!oneliner) {
body = `{\n${body}\n}`;
}
return `\
function(${args}) {
let innerFunc = ${async_} () => ${body};
${proxiedDispatch}return ${handleAsync};
}\n`;
});
}
// The three different inter-thread proxying methods.
// See system/lib/pthread/proxying.c
const PROXY_ASYNC = 0;
const PROXY_SYNC = 1;
const PROXY_SYNC_ASYNC = 2;
export async function runJSify(outputFile, symbolsOnly) {
const libraryItems = [];
const libraryAliases = [];
const asyncFuncs = [];
let postSets = [];
LibraryManager.load();
let outputHandle = process.stdout;
if (outputFile) {
outputHandle = await fs.open(outputFile, 'w');
}
async function writeOutput(str) {
// Unmangle previously mangled `import.meta` references.
// See also: `mangleUnsupportedSyntax` in parseTools.mjs.
if (EXPORT_ES6) {
str = str.replaceAll('EMSCRIPTEN$IMPORT$META', 'import.meta');
}
await outputHandle.write(str + '\n');
}
const symbolsNeeded = DEFAULT_LIBRARY_FUNCS_TO_INCLUDE;
symbolsNeeded.push(...extraLibraryFuncs);
if (!symbolsOnly) {
for (const fileName of [...PRE_JS_FILES, ...POST_JS_FILES]) {
const content = getIncludeFile(fileName);
if (!errorOccured()) {
symbolsNeeded.push(...calcImplicitDeps(content, /*isUserSnippet=*/ true));
}
}
for (const snippet of EM_JS_SNIPPETS) {
symbolsNeeded.push(...calcImplicitDeps(snippet, /*isUserSnippet=*/ true));
}
}
for (const sym of EXPORTED_RUNTIME_METHODS) {
if ('$' + sym in LibraryManager.library) {
symbolsNeeded.push('$' + sym);
}
}
for (const key of Object.keys(LibraryManager.library)) {
if (!isDecorator(key) && !LibraryManager.library[key + '__const']) {
if (INCLUDE_FULL_LIBRARY || EXPORTED_FUNCTIONS.has(mangleCSymbolName(key))) {
symbolsNeeded.push(key);
}
}
}
function processLibraryFunction(snippet, symbol, mangled, deps, isStub) {
// It is possible that when printing the function as a string on Windows,
// the js interpreter we are in returns the string with Windows line endings
// \r\n. This is undesirable, since line endings are managed in the form \n
// in the output for binary file writes, so make sure the endings are
// uniform.
snippet = snippet.toString().replace(/\r\n/gm, '\n');
// Is this a shorthand `foo() {}` method syntax?
// If so, prepend a function keyword so that it's valid syntax when extracted.
if (snippet.startsWith(symbol)) {
snippet = 'function ' + snippet;
}
if (isStub) {
return snippet;
}
// apply LIBRARY_DEBUG if relevant
if (LIBRARY_DEBUG && !isJsOnlySymbol(symbol)) {
snippet = modifyJSFunction(snippet, (args, body, _async, oneliner) => {
var run_func;
if (oneliner) {
run_func = `var ret = ${body}`;
} else {
run_func = `var ret = (() => { ${body} })();`;
}
return `\
function(${args}) {
dbg("[library call:${mangled}: " + Array.from(arguments, prettyPrint) + "]");
${run_func}
dbg(" [ return:" + prettyPrint(ret));
return ret;
}`;
});
}
const sig = LibraryManager.library[symbol + '__sig'];
const isAsyncFunction = ASYNCIFY && LibraryManager.library[symbol + '__async'];
const i53abi = LibraryManager.library[symbol + '__i53abi'];
if (i53abi) {
if (!sig) {
error(`JS library error: '__i53abi' decorator requires '__sig' decorator: '${symbol}'`);
}
if (!sig.includes('j')) {
error(`JS library error: '__i53abi' only makes sense when '__sig' includes 'j' (int64): '${symbol}'`);
}
}
if (
sig &&
((i53abi && sig.includes('j')) || ((MEMORY64 || CAN_ADDRESS_2GB) && sig.includes('p')))
) {
snippet = handleI64Signatures(symbol, snippet, sig, i53abi, isAsyncFunction);
}
const proxyingMode = LibraryManager.library[symbol + '__proxy'];
if (LibraryManager.library[symbol + '__async'] == 'auto') {
snippet = handleSyncArg(symbol, snippet, sig, proxyingMode);
}
if (ASYNCIFY && isAsyncFunction == 'auto') {
snippet = handleAsyncFunction(snippet, sig, proxyingMode == 'sync');
}
if (proxyingMode) {
if (!['sync', 'async', 'none'].includes(proxyingMode)) {
error(`JS library error: invalid proxying mode '${symbol}__proxy: ${proxyingMode}' specified`);
}
if (SHARED_MEMORY && proxyingMode != 'none') {
if (PTHREADS) {
snippet = modifyJSFunction(snippet, (args, body, async_, oneliner) => {
if (oneliner) {
body = `return ${body}`;
}
let proxyMode = PROXY_ASYNC;
if (proxyingMode === 'sync') {
const isAsyncFunction = LibraryManager.library[symbol + '__async'];
if (isAsyncFunction) {
proxyMode = PROXY_SYNC_ASYNC;
} else {
proxyMode = PROXY_SYNC;
}
}
const rtnType = sig?.[0];
const proxyFunc =
MEMORY64 && rtnType == 'p' ? 'proxyToMainThreadPtr' : 'proxyToMainThread';
return `
${async_}function(${args}) {
if (ENVIRONMENT_IS_PTHREAD)
return ${proxyFunc}(${proxiedFunctionTable.length}, 0, ${proxyMode}${args ? ', ' : ''}${args});
${body}
}\n`;
});
} else if (WASM_WORKERS && ASSERTIONS) {
// In ASSERTIONS builds add runtime checks that proxied functions are not attempted to be called in Wasm Workers
// (since there is no automatic proxying architecture available)
snippet = modifyJSFunction(
snippet,
(args, body) => `
function(${args}) {
assert(!ENVIRONMENT_IS_WASM_WORKER, "attempt to call proxied function '${mangled}' from a Wasm Worker (where proxying is not possible)");
${body}
}\n`,
);
}
proxiedFunctionTable.push(mangled);
}
}
return snippet;
}
function symbolHandler(symbol) {
// In LLVM, exceptions generate a set of functions of form
// __cxa_find_matching_catch_1(), __cxa_find_matching_catch_2(), etc. where
// the number specifies the number of arguments. In Emscripten, route all
// these to a single function 'findMatchingCatch' that takes an array
// of argument.
if (LINK_AS_CXX && !WASM_EXCEPTIONS && symbol.startsWith('__cxa_find_matching_catch_')) {
if (DISABLE_EXCEPTION_THROWING) {
error('DISABLE_EXCEPTION_THROWING was set (likely due to -fno-exceptions), which means no C++ exception throwing support code is linked in, but exception catching code appears. Either do not set DISABLE_EXCEPTION_THROWING (if you do want exception throwing) or compile all source files with -fno-exceptions (so that no exceptions support code is required); also make sure DISABLE_EXCEPTION_CATCHING is set to the right value - if you want exceptions, it should be off, and vice versa.');
return;
}
if (!(symbol in LibraryManager.library)) {
// Create a new __cxa_find_matching_catch variant on demand.
const num = +symbol.split('_').slice(-1)[0];
compileTimeContext.addCxaCatch(num);
}
// Continue, with the code below emitting the proper JavaScript based on
// what we just added to the library.
}
function addFromLibrary(symbol, dependent) {
// don't process any special identifiers. These are looked up when
// processing the base name of the identifier.
if (isDecorator(symbol)) {
return;
}
// if the function was implemented in compiled code, there is no need to
// include the js version
if (WASM_EXPORTS.has(symbol)) {
return;
}
if (symbol in addedLibraryItems) {
return;
}
addedLibraryItems[symbol] = true;
const deps = LibraryManager.library[symbol + '__deps'] ??= [];
const explicitDeps = new Set(deps);
let sig = LibraryManager.library[symbol + '__sig'];
if (!WASM_BIGINT && sig && sig[0] == 'j') {
// Without WASM_BIGINT functions that return i64 depend on setTempRet0
// to return the upper 32-bits of the result.
// See makeReturn64 in parseTools.py.
deps.push('setTempRet0');
}
const isAsyncFunction = LibraryManager.library[symbol + '__async'];
if (ASYNCIFY && isAsyncFunction) {
asyncFuncs.push(symbol);
}
const isUserSymbol = LibraryManager.library[symbol + '__user'];
function addImplicitDeps(snippet) {
for (const dep of calcImplicitDeps(snippet)) {
if (dep === symbol) continue;
if (explicitDeps.has(dep)) {
if (!symbolsOnly && (STRICT || !isUserSymbol) && LibraryManager.library[symbol] !== dep) {
warn(`${symbol}: redundant __deps entry: ${dep}`);
explicitDeps.delete(dep);
}
} else if (!deps.includes(dep)) {
if (!symbolsOnly) {
debugLog(`auto-detected dependency: ${symbol} -> ${dep}`);
}
deps.push(dep);
}
}
}
const postsetId = symbol + '__postset';
const postset = LibraryManager.library[postsetId];
const isConst = LibraryManager.library[symbol + '__const'];
if (symbolsOnly) {
if (Object.hasOwn(LibraryManager.library, symbol)) {
let snippet = LibraryManager.library[symbol];
if (isConst || !LibraryManager.isAlias(snippet)) {
if (typeof snippet === 'object') {
snippet = stringifyWithFunctions(snippet);
} else if (typeof snippet === 'function') {
snippet = snippet.toString();
} else if (typeof snippet === 'string') {
if (!isConst || snippet.startsWith('=')) {
snippet = snippet.replace(/^[=;]/, '');
} else {
snippet = '';
}
}
if (typeof snippet === 'string' && snippet) {
addImplicitDeps(snippet);
}
}
if (typeof postset === 'string') {
addImplicitDeps(postset);
}
}
return;
}
// This gets set to true in the case of dynamic linking for symbols that
// are undefined in the main module. In this case we create a stub that
// will resolve the correct symbol at runtime, or assert if its missing.
let isStub = false;
const mangled = mangleCSymbolName(symbol);
let snippet = LibraryManager.library[symbol];
if (!Object.hasOwn(LibraryManager.library, symbol)) {
const isWeakImport = WEAK_IMPORTS.has(symbol);
if (!isDefined(symbol) && !isWeakImport) {
if (PROXY_TO_PTHREAD && !MAIN_MODULE && symbol == '__main_argc_argv') {
error('PROXY_TO_PTHREAD proxies main() for you, but no main exists');
return;
}
let undefinedSym = symbol;
if (symbol === '__main_argc_argv') {
undefinedSym = 'main/__main_argc_argv';
}
let msg = 'undefined symbol: ' + undefinedSym;
if (dependent) msg += ` (referenced by ${dependent})`;
if (ERROR_ON_UNDEFINED_SYMBOLS) {
error(msg);
warnOnce(
'To disable errors for undefined symbols use `-sERROR_ON_UNDEFINED_SYMBOLS=0`',
);
warnOnce(
mangled +
' may need to be added to EXPORTED_FUNCTIONS if it arrives from a system library',
);
} else if (WARN_ON_UNDEFINED_SYMBOLS) {
warn(msg);
} else {
debugLog(msg);
}
if (symbol === '__main_argc_argv' && STANDALONE_WASM) {
warn('To build in STANDALONE_WASM mode without a main(), use emcc --no-entry');
}
}
// emit a stub that will fail at runtime
var stubFunctionBody = `abort('missing function: ${symbol}');`
if (MAIN_MODULE) {
// Create a stub for this symbol which can later be replaced by the
// dynamic linker. If this stub is called before the symbol is
// resolved assert in debug builds or trap in release builds.
let target = `wasmImports['${symbol}']`;
if (ASYNCIFY) {
// See the definition of asyncifyStubs in preamble.js for why this
// is needed.
target = `asyncifyStubs['${symbol}']`;
}
let assertion = '';
if (ASSERTIONS) {
assertion += `if (!${target} || ${target}.stub) abort("external symbol '${symbol}' is missing. perhaps a side module was not linked in? if this function was expected to arrive from a system library, try to build the MAIN_MODULE with EMCC_FORCE_STDLIBS=1 in the environment");\n`;
}
stubFunctionBody = assertion + `return ${target}(...args);`;
}
isStub = true;
snippet = new Function('...args', stubFunctionBody);
}
if (!isConst) {
librarySymbols.push(mangled);
}
if (!isStub && LibraryManager.library[symbol + '__export']) {
extraExports.add(mangled);
}
let isFunction = typeof snippet === 'function';
let isNativeAlias = false;
if (postset) {
// A postset is either code to run right now, or some text we should emit.
// If it's code, it may return some text to emit as well.
const postsetString = typeof postset === 'function' ? postset() : postset;
if (postsetString && !addedLibraryItems[postsetId]) {
addedLibraryItems[postsetId] = true;
postSets.push(postsetString + ';');
if (typeof postset === 'string') {
addImplicitDeps(postsetString);
}
}
}
let aliasTarget;
if (!isConst && LibraryManager.isAlias(snippet)) {
// Redirection for aliases. We include the parent, and at runtime
// make ourselves equal to it. This avoid having duplicate
// functions with identical content.
aliasTarget = snippet;
if (WASM_EXPORTS.has(aliasTarget)) {
debugLog(`native alias: ${mangled} -> ${aliasTarget}`);
nativeAliases[mangled] = aliasTarget;
snippet = undefined;
isNativeAlias = true;
} else {
debugLog(`js alias: ${mangled} -> ${aliasTarget}`);
snippet = mangleCSymbolName(aliasTarget);
// When we have an alias for another JS function we can normally
// point them at the same function. However, in some cases (where
// signatures are relevant and they differ between and alais and
// it's target) we need to construct a forwarding function from
// one to the other.
const isSigRelevant = MAIN_MODULE || MEMORY64 || CAN_ADDRESS_2GB || sig?.includes('j');
const targetSig = LibraryManager.library[aliasTarget + '__sig'];
if (isSigRelevant && sig && targetSig && sig != targetSig) {
debugLog(`${symbol}: Alias target (${aliasTarget}) has different signature (${sig} vs ${targetSig})`)
isFunction = true;
snippet = `(${sigToArgs(sig)}) => ${snippet}(${sigToArgs(targetSig)})`;
}
}
} else if (typeof snippet === 'object') {
if (isConst) {
error(`JS library error: '__const' decorator cannot be used with objects: '${symbol}'`);
}
snippet = stringifyWithFunctions(snippet);
addImplicitDeps(snippet);
} else if (typeof snippet === 'string') {
if (snippet.match(/^\s*\([^}]*\)\s*=>/) || snippet.match(/^function\b/)) {
// Support functions that are already "stringified"
isFunction = true;
} else if (!isConst || snippet.startsWith('=')) {
addImplicitDeps(snippet.replace(/^[=;]/, ''));
}
}
if (isFunction) {
snippet = processLibraryFunction(snippet, symbol, mangled, deps, isStub);
if (!isStub) {
addImplicitDeps(snippet);
}
}
// Check for dependencies on `__internal` symbols from user libraries.
if (isUserSymbol) {
for (const dep of deps) {
if (LibraryManager.library[dep + '__internal'] && !LibraryManager.library[dep + '__user']) {
warn(`user library symbol '${symbol}' depends on internal symbol '${dep}'`);
}
}
}
debugLog(`adding ${symbol} (referenced by ${dependent})`);
function addDependency(dep) {
// dependencies can be JS functions, which we just run
if (typeof dep === 'function') {
return dep();
}
// $noExitRuntime is special since there are conditional usages of it
// in libcore.js and libpthread.js. These happen before deps are
// processed so depending on it via `__deps` doesn't work.
if (dep === '$noExitRuntime') {
error('noExitRuntime cannot be referenced via __deps mechanism. Use DEFAULT_LIBRARY_FUNCS_TO_INCLUDE or EXPORTED_RUNTIME_METHODS');
}
return addFromLibrary(dep, `${symbol}, referenced by ${dependent}`);
}
let contentText;
if (isFunction) {
if (isConst) {
error(`JS library error: '__const' decorator cannot be used with functions: '${symbol}'`);
}
// Emit the body of a JS library function.
if ((USE_ASAN || USE_LSAN) && LibraryManager.library[symbol + '__noleakcheck']) {
contentText = modifyJSFunction(
snippet,
(args, body) => `(${args}) => noLeakCheck(() => {${body}})`,
);
deps.push('$noLeakCheck');
} else {
contentText = snippet; // Regular JS function that will be executed in the context of the calling thread.
}
// Give the function the correct (mangled) name. Overwrite it if it's
// already named. This must happen after the last call to
// modifyJSFunction which could have changed or removed the name.
if (contentText.match(/^\s*([^}]*)\s*=>/s)) {
// Handle arrow functions
contentText = `var ${mangled} = ` + contentText + ';';
} else if (contentText.startsWith('class ')) {
// Handle class declarations (which also have typeof == 'function'.)
contentText = contentText.replace(/^class(?:\s+(?!extends\b)[^{\s]+)?/, `class ${mangled}`);
} else {
// Handle regular (non-arrow) functions
contentText = contentText.replace(/function(?:\s+([^(]+))?\s*\(/, `function ${mangled}(`);
}
} else if (typeof snippet === 'string' && snippet.startsWith(';')) {
if (isConst) {
error(`JS library error: '__const' decorator cannot be used with ';'-prefixed snippets: '${symbol}'`);
}
// In JS libraries
// foo: ';[code here verbatim]'
// emits
// 'var foo;[code here verbatim];'
contentText = 'var ' + mangled + snippet;
if (snippet.at(-1) != ';' && snippet.at(-1) != '}') {
contentText += ';';
}
} else if (typeof snippet === 'undefined') {
if (isConst) {
error(`JS library error: '__const' decorator cannot be used with undefined symbols: '${symbol}'`);
}
// For JS library functions that are simply aliases of native symbols,
// we don't need to generate anything here. Instead these get included
// and exported alongside native symbols.
// See `create_receiving` in `tools/emscripten.py`.
if (isNativeAlias) {
contentText = '';
} else {
contentText = `var ${mangled};`;
}
} else {
// In JS libraries
// foo: '=[value]'
// emits
// 'var foo = [value];'
if (typeof snippet === 'string') {
if (snippet[0] == '=') {
snippet = snippet.slice(1);
} else if (isConst) {
snippet = JSON.stringify(snippet);
}
} else if (typeof snippet === 'bigint') {
snippet = `${snippet}n`;
}
const declType = isConst ? 'const' : 'var';
contentText = `${declType} ${mangled} = ${snippet};`;
}
if (CHECK_DEPS && (STRICT || !isUserSymbol) && !isStub && contentText) {
checkShadowing(symbol, mangled, contentText);
}
if (contentText && MODULARIZE == 'instance' && shouldExportLibrarySymbol(mangled) && !isStub && !isConst) {
// In MODULARIZE=instance mode mark JS library symbols are exported at
// the point of declaration.
contentText = 'export ' + contentText;
}
// Dynamic linking needs signatures to create proper wrappers.
if (sig && MAIN_MODULE && !isNativeAlias) {
if (!WASM_BIGINT) {
sig = sig[0].replace('j', 'i') + sig.slice(1).replace(/j/g, 'ii');
}
contentText += `\n${mangled}.sig = '${sig}';`;
}
if (ASYNCIFY && isAsyncFunction) {
assert(isFunction);
contentText += `\n${mangled}.isAsync = true;`;
}
if (isStub) {
contentText += `\n${mangled}.stub = true;`;
if (ASYNCIFY && MAIN_MODULE) {
contentText += `\nasyncifyStubs['${symbol}'] = undefined;`;
}
}
// Add the docs if they exist and if we are actually emitting a declaration.
// See the TODO about wasmTable above.
let docs = LibraryManager.library[symbol + '__docs'];
const commentText = contentText && docs ? docs : '';
if (EMIT_TSD) {
LibraryManager.libraryDefinitions[mangled] = {
docs: docs ?? null,
snippet: snippet ?? null,
};
}
const joinChunks = (chunks) => chunks.filter(Boolean).join('\n');
// Sort string dependencies alphabetically for deterministic output order
// regardless of how __deps are declared or discovered. Keep function
// callbacks after string dependencies in their original order.
const stringDeps = deps.filter((d) => typeof d !== 'function').sort();
const funcDeps = deps.filter((d) => typeof d === 'function');
const depsText = joinChunks([...stringDeps, ...funcDeps].map(addDependency));
// Defer direct JS value aliases (`var _alias = _target;`) to `libraryAliases`
// so the target symbol is guaranteed to be defined first. Skip native
// aliases (which emit no code here) and signature-mismatch aliases (where
// `isFunction` is set because they are emitted as forwarding wrapper
// functions rather than immediate value assignments).
if (aliasTarget && !isNativeAlias && !isFunction) {
libraryAliases.push(joinChunks([commentText, contentText]));
return depsText;
}
return joinChunks([depsText, commentText, contentText]);
}
const JS = addFromLibrary(symbol, 'root reference (e.g. compiled C/C++ code)');
libraryItems.push(JS);
}
function includeSystemFile(fileName) {
writeOutput(getSystemIncludeFile(fileName));
}
function includeFile(fileName) {
writeOutput(getIncludeFile(fileName));
}
function finalCombiner() {
const splitPostSets = splitter(postSets, (x) => x.symbol && x.dependencies);
postSets = splitPostSets.leftIn;
const orderedPostSets = splitPostSets.splitOut;
let limit = orderedPostSets.length * orderedPostSets.length;
for (let i = 0; i < orderedPostSets.length; i++) {
for (let j = i + 1; j < orderedPostSets.length; j++) {
if (orderedPostSets[j].symbol in orderedPostSets[i].dependencies) {
const temp = orderedPostSets[i];
orderedPostSets[i] = orderedPostSets[j];
orderedPostSets[j] = temp;
i--;
limit--;
assert(limit > 0, 'could not sort postsets');
break;
}
}
}
postSets.push(...orderedPostSets);
const shellFile = MINIMAL_RUNTIME ? 'shell_minimal.js' : 'shell.js';
includeSystemFile(shellFile);
const preFile = MINIMAL_RUNTIME ? 'preamble_minimal.js' : 'preamble.js';
includeSystemFile(preFile);
writeOutput('// Begin JS library code\n');
for (const item of [...libraryItems, ...libraryAliases, ...postSets]) {
writeOutput(indentify(item ?? '', 2));
}
writeOutput('// End JS library code\n');
if (!MINIMAL_RUNTIME) {
includeSystemFile('postlibrary.js');
}
if (PTHREADS) {
writeOutput(`
// proxiedFunctionTable specifies the list of functions that can be called
// either synchronously or asynchronously from other threads in postMessage()d
// or internally queued events. This way a pthread in a Worker can synchronously
// access e.g. the DOM on the main thread.
var proxiedFunctionTable = [
${proxiedFunctionTable.join(',\n ')}
];
`);
}
// This is the main 'post' pass. Print out the generated code
// that we have here, together with the rest of the output
// that we started to print out earlier (see comment on the
// "Final shape that will be created").
writeOutput('// EMSCRIPTEN_END_FUNCS\n');
const postFile = MINIMAL_RUNTIME ? 'postamble_minimal.js' : 'postamble.js';
includeSystemFile(postFile);
for (const fileName of POST_JS_FILES) {
includeFile(fileName);
}
if (MODULARIZE && MODULARIZE != 'instance') {
includeSystemFile('postamble_modularize.js');
}
if (errorOccured()) {
throw Error('Aborting compilation due to previous errors');
}
writeOutput(
'//FORWARDED_DATA:' +
JSON.stringify({
librarySymbols,
extraExports: Array.from(extraExports),
nativeAliases,
warnings: warningOccured(),
asyncFuncs,
libraryDefinitions: LibraryManager.libraryDefinitions,
ATPRERUNS: ATPRERUNS.join('\n'),
ATMODULES: ATMODULES.join('\n'),
ATINITS: ATINITS.join('\n'),
ATPOSTCTORS: ATPOSTCTORS.join('\n'),
ATMAINS: ATMAINS.join('\n'),
ATPOSTRUNS: ATPOSTRUNS.join('\n'),
ATEXITS: ATEXITS.join('\n'),
}),
);
}
timer.start('symbolHandler');
for (const sym of symbolsNeeded) {
symbolHandler(sym);
}
timer.stop('symbolHandler');
if (symbolsOnly) {
const symbolDeps = {};
for (const sym of Object.keys(LibraryManager.library)) {
if (!isDecorator(sym) && !LibraryManager.library[sym + '__const']) {
const transitiveDeps = getTransitiveDeps(sym);
symbolDeps[sym] = transitiveDeps.filter(
(d) => !isJsOnlySymbol(d) && !(d in LibraryManager.library),
);
}
}
writeOutput(
JSON.stringify({
deps: symbolDeps,
asyncFuncs,
extraLibraryFuncs,
}),
);
} else {
timer.start('finalCombiner')
finalCombiner();
timer.stop('finalCombiner')
}
if (errorOccured()) {
throw Error('Aborting compilation due to previous errors');
}
if (outputFile) await outputHandle.close();
}
addToCompileTimeContext({
extraLibraryFuncs,
addedLibraryItems,
preJS,
});