emsdk-env 0.8.0 → 0.9.0

package/README.md

@@ -28,6 +28,8 @@ export default defineConfig({
   plugins: [
     // Add as a plugin
     emsdkEnv({
+      // Generate a runtime loader code
+      generatedLoader: { enable: true },
       // Build targets
       targets: {
         // Generate "add.wasm"
@@ -35,7 +37,9 @@ export default defineConfig({
           // Compiler options
           options: ['-O3', '-std=c99'],
           // Linker options
-          linkOptions: ['-s', 'STANDALONE_WASM=1', '--no-entry'],
+          linkOptions: ['--no-entry'],
+          // Linker directives
+          linkDirectives: { STANDALONE_WASM: 1 },
           // Exported symbols
           exports: ['_add'],
         },
@@ -86,12 +90,15 @@ project/
 ├── package.json
 ├── vite.config.ts
 ├── src/
+│   ├── generated/
+│   │   └── wasm-loader.ts   // (Generate automatically)
 │   └── wasm/
-│       └── add.wasm
+│       └── add.wasm         // (Built WASM binary)
 └── wasm/
     └── add.c
 ```
 
+- `wasm-loader.ts` is helper code that loads and makes WASM binaries usable.
 - In addition to the above, a temporary build directory is created under the OS temp directory.
   The default location is `${TMPDIR}/emsdk-env` (typically `/tmp/emsdk-env` on Unix).
   This directory is used during the build process and is typically deleted after the build completes.
@@ -99,7 +106,36 @@ project/
 
 Of course, you can change these. Specify them in the Vite plugin options.
 
-You might find it odd that the built binary is placed in `src/wasm/`, but this is because the Vite server defaults to a path where it can easily access WASM binaries.
+You might find it odd that the built binary is placed in `src/wasm/`,
+but this is because the Vite server defaults to a path where it can easily access WASM binaries.
+
+If `generatedLoader.enable` is set to `true`, emsdk-env also generates a WASM loader helper code by default at `src/generated/wasm-loader.ts`.
+That loader can call the final WASM exports directly:
+
+```typescript
+import { loadAddWasm } from './generated/wasm-loader';
+
+// WASM exported function declaration (You need to define it)
+interface AddExports {
+  add?: (a: number, b: number) => number;
+}
+
+// Load WASM binary and instantiates it
+const wasm = await loadAddWasm<AddExports>();
+
+// Get `add()` function entry point
+const add = wasm.exports.add;
+if (typeof add !== 'function') {
+  throw new Error('add function not found in wasm exports.');
+}
+
+// Then use it now
+const result = add(1, 2);
+```
+
+- You need to define WASM export functions yourself.
+  When doing so, the symbol name for the exported function is the same as the C/C++ function name in TypeScript,
+  but the symbol name specified in `exports: [...]` typically requires an underscore prefix (`add()` --> `_add`).
 
 If you plan to operate with the default settings, there is essentially no configuration work required.
 

package/dist/{build-DzrgEC4A.js → build-BOZTStIM.js}

@@ -1,17 +1,17 @@
 /*!
  * name: emsdk-env
- * version: 0.8.0
+ * version: 0.9.0
  * description: Emscripten environment builder
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/emsdk-env
- * git.commit.hash: 8c3f97866a85cc6c99383eff3526c04077032eac
+ * git.commit.hash: 73d7e217903f020ef22daa9289362dcd19bddac1
  */
 
-import { mkdir, access, constants, mkdtemp, rename, rm, readFile } from "fs/promises";
+import { mkdir, access, constants, mkdtemp, rename, rm, writeFile, readFile } from "fs/promises";
 import { homedir, tmpdir } from "os";
 import { glob } from "glob";
-import { join, resolve, isAbsolute, dirname, relative, parse } from "path";
+import { join, resolve, relative, isAbsolute, dirname, parse } from "path";
 import { spawn } from "child_process";
 const __NOOP_HANDLER = () => {
 };
@@ -552,6 +552,11 @@ const DEFAULT_IMPORT_LIB_DIR = "lib";
 const DEFAULT_WASM_BUILD_DIR = join(tmpdir(), "emsdk-env");
 const DEFAULT_EMSDK_TARGET_VERSION = "latest";
 const DEFAULT_WASM_OPT_ARGS = ["-Oz"];
+const DEFAULT_GENERATED_LOADER_OUT_FILE = join(
+  "src",
+  "generated",
+  "wasm-loader.ts"
+);
 let buildSequence = 0;
 const padNumber = (value, length = 2) => String(value).padStart(length, "0");
 const formatTimestamp = (date) => {
@@ -578,7 +583,7 @@ const normalizePrepareOptions = (options) => {
     ...rest
   };
 };
-const parseKeyValueInput = (values) => {
+const parseStringKeyValueInput = (values) => {
   const parsed = {};
   for (const entry of values) {
     const index = entry.indexOf("=");
@@ -592,24 +597,40 @@ const parseKeyValueInput = (values) => {
   }
   return parsed;
 };
-const isKeyValueMap = (value) => value instanceof Map;
-const normalizeKeyValueInput = (input) => {
+const isDefineMap = (input) => input instanceof Map;
+const normalizeDefineInput = (input) => {
+  if (!input) {
+    return {};
+  }
+  if (Array.isArray(input)) {
+    return parseStringKeyValueInput(input);
+  }
+  if (isDefineMap(input)) {
+    return Object.fromEntries(input);
+  }
+  return { ...input };
+};
+const isLinkDirectiveMap = (input) => input instanceof Map;
+const normalizeLinkDirectiveInput = (input) => {
   if (!input) {
     return {};
   }
   if (Array.isArray(input)) {
-    return parseKeyValueInput(input);
+    return parseStringKeyValueInput(input);
   }
-  if (isKeyValueMap(input)) {
+  if (isLinkDirectiveMap(input)) {
     return Object.fromEntries(input);
   }
   return { ...input };
 };
 const mergeDefines = (common, target) => ({
-  ...normalizeKeyValueInput(common),
-  ...normalizeKeyValueInput(target)
+  ...normalizeDefineInput(common),
+  ...normalizeDefineInput(target)
+});
+const mergeLinkDirectives = (common, target) => ({
+  ...normalizeLinkDirectiveInput(common),
+  ...normalizeLinkDirectiveInput(target)
 });
-const mergeLinkDirectives = (common, target) => mergeDefines(common, target);
 const resolveWasmOptEnabled = (common, target) => {
   var _a, _b;
   return (_b = (_a = target == null ? void 0 : target.enable) != null ? _a : common == null ? void 0 : common.enable) != null ? _b : false;
@@ -693,14 +714,25 @@ const resolveDefines = (defines, env) => {
   }
   return resolved;
 };
+const resolveLinkDirectiveValue = (value, env, label) => {
+  if (typeof value === "string") {
+    return expandPlaceholders(value, env, label);
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (entry, index) => expandPlaceholders(entry, env, `${label}[${index}]`)
+    );
+  }
+  return value;
+};
 const resolveLinkDirectives = (directives, env) => {
   const resolved = {};
   for (const [key, value] of Object.entries(directives)) {
-    if (typeof value === "string") {
-      resolved[key] = expandPlaceholders(value, env, `linkDirectives.${key}`);
-    } else {
-      resolved[key] = value;
-    }
+    resolved[key] = resolveLinkDirectiveValue(
+      value,
+      env,
+      `linkDirectives.${key}`
+    );
   }
   return resolved;
 };
@@ -725,12 +757,13 @@ const resolveSourcesFromPatterns = async (patterns, env, srcDir, label) => {
 const buildDefineFlags = (defines) => Object.entries(defines).flatMap(
   ([key, value]) => value === null || value === void 0 ? [`-D${key}`] : [`-D${key}=${String(value)}`]
 );
+const serializeLinkDirectiveValue = (value) => Array.isArray(value) ? JSON.stringify(value) : String(value);
 const buildLinkDirectiveFlags = (directives) => {
   if (Object.keys(directives).length === 0) {
     return [];
   }
   return Object.entries(directives).flatMap(
-    ([key, value]) => value === null || value === void 0 ? ["-s", key] : ["-s", `${key}=${String(value)}`]
+    ([key, value]) => value === null || value === void 0 ? ["-s", key] : ["-s", `${key}=${serializeLinkDirectiveValue(value)}`]
   );
 };
 const buildExportFlags = (exports$1) => {
@@ -785,6 +818,248 @@ const dedupeValues = (values) => {
   }
   return deduped;
 };
+const isSubPath = (parentDir, targetPath) => {
+  const rel = relative(parentDir, targetPath);
+  if (rel === "") {
+    return true;
+  }
+  return !rel.startsWith("..") && !isAbsolute(rel);
+};
+const readTextIfExists = async (filePath) => {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    const nodeError = error;
+    if (nodeError.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+};
+const writeTextIfChanged = async (filePath, content) => {
+  const existing = await readTextIfExists(filePath);
+  if (existing === content) {
+    return false;
+  }
+  await ensureDirectory(dirname(filePath));
+  await writeFile(filePath, content, "utf8");
+  return true;
+};
+const toPascalCaseIdentifier = (value) => {
+  const tokens = value.split(/[^A-Za-z0-9]+/).map((token) => token.trim()).filter((token) => token.length > 0);
+  if (tokens.length === 0) {
+    throw new Error(`Cannot derive loader function name from target: ${value}`);
+  }
+  const pascal = tokens.map((token) => token.charAt(0).toUpperCase() + token.slice(1)).join("");
+  return /^[0-9]/.test(pascal) ? `Target${pascal}` : pascal;
+};
+const toRelativeImportSpecifier = (fromFile, toFile) => {
+  const rel = relative(dirname(fromFile), toFile).replace(/\\/g, "/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+};
+const buildGeneratedLoaderContent = (generatedLoaderFile, targets) => {
+  const targetBlocks = targets.map((target) => {
+    const specifier = JSON.stringify(
+      toRelativeImportSpecifier(generatedLoaderFile, target.outFile)
+    );
+    return `export const ${target.functionName} = async <T extends object>(
+  options?: TargetWasmLoadOptions
+): Promise<WasmInstance<T>> => {
+  const source = options?.url ?? new URL(${specifier}, import.meta.url);
+  return await loadWasm<T>(source, {
+    imports: options?.imports,
+  });
+};`;
+  }).join("\n\n");
+  return `// Generated by emsdk-env. DO NOT EDIT.
+
+export type WasmSource =
+  | string
+  | URL
+  | ArrayBuffer
+  | ArrayBufferView
+  | Response;
+
+export interface WasmLoadOptions {
+  readonly imports?: WebAssembly.Imports;
+}
+
+export interface TargetWasmLoadOptions extends WasmLoadOptions {
+  readonly url?: string | URL;
+}
+
+export interface WasmInstance<T extends object> {
+  readonly exports: T;
+  readonly memory: WebAssembly.Memory;
+  readonly table: WebAssembly.Table | undefined;
+  readonly rawExports: WebAssembly.Exports;
+  readonly module: WebAssembly.Module;
+  readonly instance: WebAssembly.Instance;
+  readonly initialize: (() => unknown) | undefined;
+  readonly start: (() => unknown) | undefined;
+}
+
+const resolveWasmBytes = async (source: WasmSource): Promise<ArrayBuffer> => {
+  if (typeof Response !== 'undefined' && source instanceof Response) {
+    return await source.arrayBuffer();
+  }
+  if (source instanceof URL || typeof source === 'string') {
+    const response = await fetch(source);
+    if (!response.ok) {
+      throw new Error(\`Failed to fetch wasm: \${response.url}\`);
+    }
+    return await response.arrayBuffer();
+  }
+  if (ArrayBuffer.isView(source)) {
+    const view = new Uint8Array(
+      source.buffer,
+      source.byteOffset,
+      source.byteLength
+    );
+    return view.slice().buffer;
+  }
+  return source;
+};
+
+const getImportValue = (
+  imports: WebAssembly.Imports | undefined,
+  moduleName: string,
+  name: string
+) => {
+  const moduleImports = imports?.[moduleName];
+  if (!moduleImports || typeof moduleImports !== 'object') {
+    return undefined;
+  }
+  return (moduleImports as Record<string, unknown>)[name];
+};
+
+const resolveMemory = (
+  module: WebAssembly.Module,
+  instance: WebAssembly.Instance,
+  imports: WebAssembly.Imports | undefined
+) => {
+  let memory: WebAssembly.Memory | undefined;
+  for (const entry of WebAssembly.Module.exports(module)) {
+    if (entry.kind !== 'memory') {
+      continue;
+    }
+    if (memory) {
+      throw new Error('Multiple wasm memories are not supported.');
+    }
+    const value = instance.exports[entry.name];
+    if (!(value instanceof WebAssembly.Memory)) {
+      throw new Error(\`Export is not a WebAssembly.Memory: \${entry.name}\`);
+    }
+    memory = value;
+  }
+  if (memory) {
+    return memory;
+  }
+  for (const entry of WebAssembly.Module.imports(module)) {
+    if (entry.kind !== 'memory') {
+      continue;
+    }
+    if (memory) {
+      throw new Error('Multiple wasm memories are not supported.');
+    }
+    const value = getImportValue(imports, entry.module, entry.name);
+    if (!(value instanceof WebAssembly.Memory)) {
+      throw new Error(
+        \`Imported value is not a WebAssembly.Memory: \${entry.module}.\${entry.name}\`
+      );
+    }
+    memory = value;
+  }
+  if (!memory) {
+    throw new Error('WASM memory export/import was not resolved.');
+  }
+  return memory;
+};
+
+const resolveTable = (
+  module: WebAssembly.Module,
+  instance: WebAssembly.Instance,
+  imports: WebAssembly.Imports | undefined
+) => {
+  let table: WebAssembly.Table | undefined;
+  for (const entry of WebAssembly.Module.exports(module)) {
+    if (entry.kind !== 'table') {
+      continue;
+    }
+    if (table) {
+      throw new Error('Multiple wasm tables are not supported.');
+    }
+    const value = instance.exports[entry.name];
+    if (!(value instanceof WebAssembly.Table)) {
+      throw new Error(\`Export is not a WebAssembly.Table: \${entry.name}\`);
+    }
+    table = value;
+  }
+  if (table) {
+    return table;
+  }
+  for (const entry of WebAssembly.Module.imports(module)) {
+    if (entry.kind !== 'table') {
+      continue;
+    }
+    if (table) {
+      throw new Error('Multiple wasm tables are not supported.');
+    }
+    const value = getImportValue(imports, entry.module, entry.name);
+    if (!(value instanceof WebAssembly.Table)) {
+      throw new Error(
+        \`Imported value is not a WebAssembly.Table: \${entry.module}.\${entry.name}\`
+      );
+    }
+    table = value;
+  }
+  return table;
+};
+
+export const loadWasm = async <T extends object>(
+  source: WasmSource,
+  options?: WasmLoadOptions
+): Promise<WasmInstance<T>> => {
+  const bytes = await resolveWasmBytes(source);
+  const module = await WebAssembly.compile(bytes);
+  const instance = await WebAssembly.instantiate(module, options?.imports ?? {});
+
+  const functionExports: Record<string, (...args: unknown[]) => unknown> = {};
+  for (const entry of WebAssembly.Module.exports(module)) {
+    if (entry.kind !== 'function') {
+      continue;
+    }
+    const value = instance.exports[entry.name];
+    if (typeof value !== 'function') {
+      throw new Error(\`Export is not a function: \${entry.name}\`);
+    }
+    functionExports[entry.name] = value as (...args: unknown[]) => unknown;
+  }
+
+  const initialize =
+    typeof instance.exports._initialize === 'function'
+      ? (instance.exports._initialize as () => unknown)
+      : undefined;
+  const start =
+    typeof instance.exports._start === 'function'
+      ? (instance.exports._start as () => unknown)
+      : undefined;
+
+  return {
+    exports: functionExports as T,
+    memory: resolveMemory(module, instance, options?.imports),
+    table: resolveTable(module, instance, options?.imports),
+    rawExports: instance.exports,
+    module,
+    instance,
+    initialize,
+    start,
+  };
+};
+
+${targetBlocks}
+`;
+};
 const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const resolvePackageJsonPath = async (startPath, packageName) => {
   let current = dirname(startPath);
@@ -885,6 +1160,42 @@ const resolveImportDirectories = async (rootDir, imports) => {
     libDirs: dedupeValues(libDirs)
   };
 };
+const resolveGeneratedLoaderOutFile = (rootDir, env, generatedLoader) => {
+  var _a;
+  if (!(generatedLoader == null ? void 0 : generatedLoader.enable)) {
+    return void 0;
+  }
+  const rawOutFile = expandPlaceholders(
+    (_a = generatedLoader.outFile) != null ? _a : DEFAULT_GENERATED_LOADER_OUT_FILE,
+    env,
+    "generatedLoader.outFile"
+  );
+  return resolvePath(rootDir, rawOutFile);
+};
+const resolveGeneratedLoaderWatchDirs = (rootDir, srcDir, commonIncludeDirs, env, targetEntries, importIncludeDirs) => {
+  const dirs = [srcDir, ...resolveIncludeDirs(commonIncludeDirs, env, rootDir)];
+  for (const [targetName, target] of targetEntries) {
+    if (!target.includeDirs || target.includeDirs.length === 0) {
+      continue;
+    }
+    const targetEnv = {
+      ...env,
+      TARGET_NAME: targetName
+    };
+    dirs.push(...resolveIncludeDirs(target.includeDirs, targetEnv, rootDir));
+  }
+  dirs.push(...importIncludeDirs);
+  return dedupeValues(dirs);
+};
+const validateGeneratedLoaderOutFile = (generatedLoaderFile, watchDirs) => {
+  for (const dir of watchDirs) {
+    if (isSubPath(dir, generatedLoaderFile)) {
+      throw new Error(
+        `generatedLoader.outFile must not be placed under watched directory: ${generatedLoaderFile}`
+      );
+    }
+  }
+};
 const buildCompileArgs = (options, includeDirs, defines, env, rootDir) => {
   const resolvedOptions = expandArray(options, env, "options");
   const includeArgs = resolveIncludeDirs(includeDirs, env, rootDir).map(
@@ -967,6 +1278,22 @@ const buildWasm = async (options) => {
   const importIncludeDirs = importDirectories.includeDirs;
   const importLibDirs = importDirectories.libDirs;
   const linkLibDirs = dedupeValues([libDir, ...importLibDirs]);
+  const generatedLoaderFile = resolveGeneratedLoaderOutFile(
+    rootDir,
+    envWithDirs,
+    options.generatedLoader
+  );
+  if (generatedLoaderFile) {
+    const watchDirs = resolveGeneratedLoaderWatchDirs(
+      rootDir,
+      srcDir,
+      commonIncludeDirs,
+      envWithDirs,
+      targetEntries,
+      importIncludeDirs
+    );
+    validateGeneratedLoaderOutFile(generatedLoaderFile, watchDirs);
+  }
   logger.debug(`Detected rootDir: '${rootDir}'`);
   logger.debug(`Detected srcDir: '${srcDir}'`);
   logger.debug(`Detected outDir: '${outDir}'`);
@@ -983,6 +1310,9 @@ const buildWasm = async (options) => {
   logger.debug(
     `Detected importLibDirs: [${importLibDirs.map((p) => `'${p}'`).join(",")}]`
   );
+  if (generatedLoaderFile) {
+    logger.debug(`Detected generatedLoaderFile: '${generatedLoaderFile}'`);
+  }
   await ensureDirectory(outDir);
   await ensureDirectory(libDir);
   await ensureDirectory(buildDir);
@@ -1005,6 +1335,7 @@ const buildWasm = async (options) => {
     return wasmOptCommand;
   };
   const outFiles = {};
+  let resultGeneratedLoaderFile;
   const buildTargets = async (expectedType) => {
     var _a2;
     for (const [targetName, target] of targetEntries) {
@@ -1276,6 +1607,40 @@ const buildWasm = async (options) => {
   try {
     await buildTargets("archive");
     await buildTargets("wasm");
+    if (generatedLoaderFile) {
+      const generatedTargets = [];
+      const functionNames = /* @__PURE__ */ new Set();
+      for (const [targetName, target] of targetEntries) {
+        if (resolveTargetType(target.type) !== "wasm") {
+          continue;
+        }
+        const outFile = outFiles[targetName];
+        if (!outFile) {
+          continue;
+        }
+        const functionName = `load${toPascalCaseIdentifier(targetName)}Wasm`;
+        if (functionNames.has(functionName)) {
+          throw new Error(
+            `Generated loader function name collision: ${functionName}`
+          );
+        }
+        functionNames.add(functionName);
+        generatedTargets.push({
+          targetName,
+          functionName,
+          outFile
+        });
+      }
+      const content = buildGeneratedLoaderContent(
+        generatedLoaderFile,
+        generatedTargets
+      );
+      const didWrite = await writeTextIfChanged(generatedLoaderFile, content);
+      logger.info(
+        didWrite ? `Generated loader: ${relative(rootDir, generatedLoaderFile)}` : `Generated loader unchanged: ${relative(rootDir, generatedLoaderFile)}`
+      );
+      resultGeneratedLoaderFile = generatedLoaderFile;
+    }
   } finally {
     if (cleanupBuildDir) {
       await rm(buildRunDir, { recursive: true, force: true });
@@ -1283,7 +1648,8 @@ const buildWasm = async (options) => {
   }
   return {
     emsdkRoot,
-    outFiles
+    outFiles,
+    ...resultGeneratedLoaderFile ? { generatedLoaderFile: resultGeneratedLoaderFile } : {}
   };
 };
 export {
@@ -1291,4 +1657,4 @@ export {
   createConsoleLogger as c,
   prepareEmsdk as p
 };
-//# sourceMappingURL=build-DzrgEC4A.js.map
+//# sourceMappingURL=build-BOZTStIM.js.map