xbintsc 0.3.18 → 0.3.35

package/src/driver/compiler.ts

@@ -9,7 +9,7 @@
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
-import { DiagnosticBag, type Diagnostic } from "../diagnostics/diagnostic.js";
+import { DiagnosticBag, DiagnosticCode, type Diagnostic } from "../diagnostics/diagnostic.js";
 import { SourceFile } from "../diagnostics/source.js";
 import { Parser } from "../parser/parser.js";
 import { generate } from "../codegen/llvm.js";
@@ -20,6 +20,10 @@ import { BuildCache, hashParts } from "./cache.js";
 import { findRuntimeDir } from "./paths.js";
 import { findRuntimeLibrary } from "./runtime-lib.js";
 import { resolveToolchain } from "./toolchain-provider.js";
+import { ensureIconObject, readIcon, EMPTY_ICON, IconError, type IconInfo } from "./icon.js";
+import { ensureWindowsIconResource, resolveResourceCompiler } from "./win-icon.js";
+import { bundlePathFor, packageMacApp } from "./mac-bundle.js";
+import type { AppConfig } from "./config.js";
 import {
   compileC,
   compileIr,
@@ -47,6 +51,10 @@ export interface BuildOptions {
   /** Prefer a prebuilt `runtime/lib/<os>-<arch>/*.a` archive when present (default true). */
   readonly preferPrebuilt?: boolean;
   readonly write?: boolean;
+  /** Application icon embedded into the binary (shorthand for `app.icon`). */
+  readonly icon?: string;
+  /** Application metadata: name, icon and macOS bundle settings. */
+  readonly app?: AppConfig;
 }
 
 export interface BuildResult {
@@ -55,6 +63,8 @@ export interface BuildResult {
   readonly cached: boolean;
   readonly diagnostics: readonly Diagnostic[];
   readonly ir?: string;
+  /** macOS `.app` bundle produced by `app.bundle` (darwin only). */
+  readonly bundlePath?: string;
 }
 
 export interface CompileStringResult {
@@ -109,7 +119,7 @@ export function compileEntry(entryPath: string, extensions?: ExtensionRegistry):
       statement.kind === SyntaxKind.ExportAssignment,
   );
   if (isModule) {
-    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry));
+    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry), registry.assetLoaders());
     if (bundled) sourceFile = bundled.sourceFile;
   }
   const { ir } = generate(sourceFile, diagnostics, {
@@ -185,13 +195,28 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   );
   let cacheText = sourceText;
   if (isModule) {
-    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry));
+    const bundled = bundleModules(absoluteEntry, diagnostics, externalModuleSpecifiers(registry), registry.assetLoaders());
     if (bundled) {
       sourceFile = bundled.sourceFile;
       cacheText = bundled.text;
     }
   }
 
+  const app = options.app ?? {};
+  const iconPath = options.icon ?? app.icon;
+  let icon: IconInfo | undefined;
+  if (iconPath) {
+    try {
+      icon = readIcon(iconPath);
+    } catch (error) {
+      if (error instanceof IconError) {
+        diagnostics.error(DiagnosticCode.IOError, error.message);
+        return { outputPath, cached: false, diagnostics: diagnostics.diagnostics };
+      }
+      throw error;
+    }
+  }
+
   const runtimeDir = findRuntimeDir();
   const cacheKey = hashParts([
     COMPILER_VERSION,
@@ -201,12 +226,22 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     process.platform,
     registryFingerprint(registry),
     runtimeFingerprint(runtimeDir),
+    icon ? hashParts(["icon", icon.format, Buffer.from(icon.bytes).toString("base64")]) : "",
+    app.name ?? "",
+    String(app.bundle ?? false),
+    app.bundleId ?? "",
   ]);
 
+  // A `.app` bundle is deterministic from the output path and name, so it can be
+  // part of the cache key before the bundle actually exists.
+  const bundle =
+    process.platform === "darwin" && emit === "exe" && app.bundle === true
+      ? bundlePathFor(outputPath, app.name ?? baseName)
+      : undefined;
   const cache = new BuildCache(cacheDir);
-  const outputs = [outputPath];
+  const outputs = bundle ? [outputPath, bundle] : [outputPath];
   if (!options.force && !diagnostics.hasErrors && cache.isFresh(cacheKey, outputs)) {
-    return { outputPath, cached: true, diagnostics: [] };
+    return { outputPath, cached: true, diagnostics: [], ...(bundle ? { bundlePath: bundle } : {}) };
   }
 
   const { ir } = generate(sourceFile, diagnostics, {
@@ -259,9 +294,32 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     toolchain.env,
   );
 
+  const iconObjects: string[] = [];
+  // The GUI extension references the icon symbols unconditionally, so a GUI
+  // program gets an (empty) icon object even with no icon configured.
+  if (icon !== undefined || registry.has("gui")) {
+    try {
+      iconObjects.push(ensureIconObject(runner, clang, cacheDir, icon ?? EMPTY_ICON, toolchain.env));
+      if (icon && process.platform === "win32") {
+        const resourceCompiler = resolveResourceCompiler(runner, clang);
+        if (resourceCompiler) {
+          iconObjects.push(ensureWindowsIconResource(runner, cacheDir, icon, resourceCompiler, toolchain.env));
+        } else if (options.verbose) {
+          process.stderr.write("xbintsc: no llvm-rc/windres found; skipping the embedded .exe icon\n");
+        }
+      }
+    } catch (error) {
+      if (error instanceof IconError) {
+        diagnostics.error(DiagnosticCode.ToolchainError, error.message);
+        return { outputPath, irPath, cached: false, diagnostics: diagnostics.diagnostics, ir };
+      }
+      throw error;
+    }
+  }
+
   link(runner, {
     clang,
-    objectPaths: [objectPath, ...runtimeObjects, ...extensionObjects, ...nativeObjects],
+    objectPaths: [objectPath, ...runtimeObjects, ...extensionObjects, ...nativeObjects, ...iconObjects],
     outputPath,
     linkerFlags: [
       ...toolchain.linkerArgs,
@@ -272,9 +330,27 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     env: toolchain.env,
   });
 
+  const bundlePath =
+    bundle !== undefined
+      ? packageMacApp({
+          executablePath: outputPath,
+          name: app.name ?? baseName,
+          bundleId: app.bundleId ?? defaultBundleId(baseName),
+          ...(icon ? { icon } : {}),
+          runner,
+          env: toolchain.env,
+        })
+      : undefined;
+
   cache.record(cacheKey, outputs);
   cache.save();
-  return { outputPath, irPath, cached: false, diagnostics: [], ir };
+  return { outputPath, irPath, cached: false, diagnostics: [], ir, ...(bundlePath ? { bundlePath } : {}) };
+}
+
+/** Default `CFBundleIdentifier` for a bundle when none is configured. */
+function defaultBundleId(name: string): string {
+  const sanitized = name.replace(/[^A-Za-z0-9.-]/g, "");
+  return `com.xbintsc.${sanitized || "app"}`;
 }
 
 interface RuntimeObjects {
@@ -290,11 +366,13 @@ export const RUNTIME_SOURCES = [
   "xt_values.c",
   "xt_bigint.c",
   "xt_containers.c",
+  "xt_typed_array.c",
   "xt_stdlib.c",
   "xt_stdlib2.c",
   "xt_promise.c",
   "xt_loop.c",
   "xt_generator.c",
+  "xt_fetch.c",
   "xt_symbol.c",
   "xt_builtins.c",
   "xt_io.c",

package/src/driver/config.ts

@@ -0,0 +1,173 @@
+/**
+ * Project build configuration (`xbintsc.config.json`).
+ *
+ * A single checked-in file makes a build reproducible and shareable:
+ * `xbintsc build` with no arguments reads the config, so options like the entry
+ * file, output directory, extensions and the application icon are not repeated
+ * on every command line. CLI flags always override the config.
+ *
+ * The schema is intentionally small and strict JSON (no comments) so it needs
+ * no parser beyond `JSON.parse`. Relative paths resolve against the config
+ * file's directory, not the current working directory.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+/** Well-known file name searched for by {@link findProjectConfig}. */
+export const CONFIG_FILE_NAME = "xbintsc.config.json";
+
+/** Application-level metadata, shared by the icon and (future) packaging. */
+export interface AppConfig {
+  readonly name?: string;
+  readonly icon?: string;
+  /** macOS only: produce a `<name>.app` bundle. */
+  readonly bundle?: boolean;
+  readonly bundleId?: string;
+}
+
+/** The on-disk schema of `xbintsc.config.json`. Every field is optional. */
+export interface ProjectConfig {
+  readonly entry?: string;
+  readonly outDir?: string;
+  readonly output?: string;
+  readonly optimize?: "0" | "1" | "2" | "3";
+  readonly extensions?: readonly string[];
+  readonly extNative?: readonly string[];
+  readonly force?: boolean;
+  readonly app?: AppConfig;
+}
+
+export class ProjectConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProjectConfigError";
+  }
+}
+
+export interface LoadedProjectConfig {
+  readonly config: ProjectConfig;
+  readonly path: string;
+  /** Directory the config lives in; the base for every relative path. */
+  readonly directory: string;
+}
+
+function expectObject(value: unknown, what: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ProjectConfigError(`${what} must be a JSON object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function readString(root: Record<string, unknown>, key: string, where: string): string | undefined {
+  const value = root[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw new ProjectConfigError(`${where}: '${key}' must be a string`);
+  return value;
+}
+
+function readBoolean(root: Record<string, unknown>, key: string, where: string): boolean | undefined {
+  const value = root[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new ProjectConfigError(`${where}: '${key}' must be a boolean`);
+  return value;
+}
+
+function readStringArray(root: Record<string, unknown>, key: string, where: string): string[] | undefined {
+  const value = root[key];
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw new ProjectConfigError(`${where}: '${key}' must be an array of strings`);
+  }
+  return value as string[];
+}
+
+/** Parse and validate config text. Throws {@link ProjectConfigError}. */
+export function parseProjectConfig(text: string, where: string = CONFIG_FILE_NAME): ProjectConfig {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new ProjectConfigError(`${where}: invalid JSON (${(error as Error).message})`);
+  }
+  const root = expectObject(raw, where);
+
+  const optimize = readString(root, "optimize", where);
+  if (optimize !== undefined && !["0", "1", "2", "3"].includes(optimize)) {
+    throw new ProjectConfigError(`${where}: 'optimize' must be one of "0", "1", "2", "3"`);
+  }
+
+  let app: AppConfig | undefined;
+  if (root.app !== undefined) {
+    const appRoot = expectObject(root.app, `${where}: 'app'`);
+    app = {
+      name: readString(appRoot, "name", `${where}: 'app'`),
+      icon: readString(appRoot, "icon", `${where}: 'app'`),
+      bundle: readBoolean(appRoot, "bundle", `${where}: 'app'`),
+      bundleId: readString(appRoot, "bundleId", `${where}: 'app'`),
+    };
+    for (const key of Object.keys(app) as (keyof AppConfig)[]) {
+      if (app[key] === undefined) delete app[key];
+    }
+  }
+
+  const config: ProjectConfig = {
+    entry: readString(root, "entry", where),
+    outDir: readString(root, "outDir", where),
+    output: readString(root, "output", where),
+    optimize: optimize as ProjectConfig["optimize"],
+    extensions: readStringArray(root, "extensions", where),
+    extNative: readStringArray(root, "extNative", where),
+    force: readBoolean(root, "force", where),
+    app,
+  };
+  for (const key of Object.keys(config) as (keyof ProjectConfig)[]) {
+    if (config[key] === undefined) delete config[key];
+  }
+  return config;
+}
+
+/** Read and parse a config file. Throws {@link ProjectConfigError}. */
+export function loadProjectConfig(path: string): LoadedProjectConfig {
+  const absolute = resolve(path);
+  if (!existsSync(absolute)) {
+    throw new ProjectConfigError(`Project config not found: ${absolute}`);
+  }
+  const config = parseProjectConfig(readFileSync(absolute, "utf8"), absolute);
+  return { config, path: absolute, directory: dirname(absolute) };
+}
+
+/** Walk up from `startDir` looking for {@link CONFIG_FILE_NAME}. */
+export function findProjectConfig(startDir: string): string | undefined {
+  let dir = resolve(startDir);
+  for (;;) {
+    const candidate = join(dir, CONFIG_FILE_NAME);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+function resolvePath(base: string, value: string): string {
+  return isAbsolute(value) ? value : resolve(base, value);
+}
+
+/**
+ * Resolve every path in a loaded config against the config file's directory, so
+ * downstream code can treat them as absolute regardless of the cwd.
+ */
+export function resolveConfigPaths(loaded: LoadedProjectConfig): ProjectConfig {
+  const { config, directory } = loaded;
+  const app: AppConfig | undefined = config.app
+    ? { ...config.app, ...(config.app.icon ? { icon: resolvePath(directory, config.app.icon) } : {}) }
+    : undefined;
+  return {
+    ...config,
+    ...(config.entry ? { entry: resolvePath(directory, config.entry) } : {}),
+    ...(config.outDir ? { outDir: resolvePath(directory, config.outDir) } : {}),
+    ...(config.output ? { output: resolvePath(directory, config.output) } : {}),
+    ...(config.extNative ? { extNative: config.extNative.map((path) => resolvePath(directory, path)) } : {}),
+    ...(app ? { app } : {}),
+  };
+}

package/src/driver/icon.ts

@@ -0,0 +1,184 @@
+/**
+ * Compile-time application icons.
+ *
+ * `--icon <file>` (or `app.icon` in `xbintsc.config.json`) reads an icon,
+ * validates it and embeds the raw bytes into the produced binary as a small
+ * linkable object. The `gui` extension picks the symbols up (weakly) to set the
+ * window / Dock icon; the Windows driver additionally turns the icon into a PE
+ * resource so Explorer and the taskbar show it. The core compiler never sees
+ * any of this — it is a driver concern, exactly like the per-platform linker
+ * flags.
+ *
+ * Supported inputs: `.png` (canonical), `.ico` and `.icns` (best effort on their
+ * home platform).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { hashParts } from "./cache.js";
+import { compileC, type Runner } from "./toolchain.js";
+
+export type IconFormat = "png" | "ico" | "icns";
+
+export interface IconInfo {
+  /** Absolute path the icon was read from. */
+  readonly path: string;
+  readonly format: IconFormat;
+  readonly bytes: Uint8Array;
+  /** Intrinsic size where it is cheap to sniff (0 when unknown, e.g. `.icns`). */
+  readonly width: number;
+  readonly height: number;
+}
+
+export class IconError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IconError";
+  }
+}
+
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+function startsWith(bytes: Uint8Array, magic: readonly number[]): boolean {
+  if (bytes.length < magic.length) return false;
+  return magic.every((value, index) => bytes[index] === value);
+}
+
+function readUInt32BE(bytes: Uint8Array, offset: number): number {
+  return (
+    ((bytes[offset]! << 24) | (bytes[offset + 1]! << 16) | (bytes[offset + 2]! << 8) | bytes[offset + 3]!) >>> 0
+  );
+}
+
+/**
+ * Sniff the format from the magic bytes and validate the file. Throws
+ * {@link IconError} with an actionable message for missing, empty or
+ * unsupported files.
+ */
+export function readIcon(path: string): IconInfo {
+  const absolute = resolve(path);
+  if (!existsSync(absolute)) {
+    throw new IconError(`Icon file not found: ${absolute}`);
+  }
+  const bytes = readFileSync(absolute);
+  if (bytes.length === 0) {
+    throw new IconError(`Icon file is empty: ${absolute}`);
+  }
+
+  if (startsWith(bytes, PNG_MAGIC)) {
+    // IHDR: width/height are big-endian at offsets 16 and 20.
+    const width = bytes.length >= 24 ? readUInt32BE(bytes, 16) : 0;
+    const height = bytes.length >= 24 ? readUInt32BE(bytes, 20) : 0;
+    return { path: absolute, format: "png", bytes, width, height };
+  }
+
+  // ICO / CUR: reserved(2) type(2) count(2), then ICONDIRENTRY[].
+  if (bytes.length >= 6 && bytes[0] === 0 && bytes[1] === 0 && bytes[2] === 1 && bytes[3] === 0) {
+    const width = bytes.length >= 7 ? bytes[6]! || 256 : 0;
+    const height = bytes.length >= 8 ? bytes[7]! || 256 : 0;
+    return { path: absolute, format: "ico", bytes, width, height };
+  }
+
+  if (startsWith(bytes, [0x69, 0x63, 0x6e, 0x73])) {
+    return { path: absolute, format: "icns", bytes, width: 0, height: 0 };
+  }
+
+  throw new IconError(
+    `Unsupported icon format: ${absolute} (expected a PNG, ICO or ICNS file)`,
+  );
+}
+
+/** The C symbols the embedded icon exposes to the runtime (and native code). */
+export const ICON_SYMBOLS = {
+  data: "xt_app_icon_data",
+  size: "xt_app_icon_size",
+  format: "xt_app_icon_format",
+  width: "xt_app_icon_width",
+  height: "xt_app_icon_height",
+} as const;
+
+/**
+ * A zero-length icon. The GUI extension references {@link ICON_SYMBOLS}
+ * unconditionally, so the driver links this object into GUI programs even when
+ * no icon is configured; `size == 0` tells the runtime to skip it.
+ */
+export const EMPTY_ICON: IconInfo = {
+  path: "",
+  format: "png",
+  bytes: Buffer.alloc(0),
+  width: 0,
+  height: 0,
+};
+
+/** Generate the C translation unit embedding the icon bytes. */
+export function iconSource(icon: IconInfo): string {
+  const lines: string[] = [];
+  const bytes = icon.bytes;
+  for (let offset = 0; offset < bytes.length; offset += 16) {
+    const chunk = Array.from(bytes.subarray(offset, offset + 16), (byte) => `0x${byte.toString(16).padStart(2, "0")}`);
+    lines.push("  " + chunk.join(", ") + ",");
+  }
+  // A zero-length array is not portable C, so an empty icon still emits one
+  // placeholder byte while reporting `size == 0`.
+  if (lines.length === 0) lines.push("  0x00,");
+  return [
+    "/* Generated by xbintsc - embedded application icon. Do not edit. */",
+    `const unsigned char ${ICON_SYMBOLS.data}[] = {`,
+    ...lines,
+    "};",
+    `const unsigned long long ${ICON_SYMBOLS.size} = ${bytes.length}ull;`,
+    `const char ${ICON_SYMBOLS.format}[] = "${icon.format}";`,
+    `const unsigned int ${ICON_SYMBOLS.width} = ${icon.width}u;`,
+    `const unsigned int ${ICON_SYMBOLS.height} = ${icon.height}u;`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Compile the icon into an object exposing {@link ICON_SYMBOLS}. Cached by the
+ * icon contents, so an unchanged icon is never recompiled.
+ */
+export function ensureIconObject(
+  runner: Runner,
+  clang: string,
+  cacheDir: string,
+  icon: IconInfo,
+  env?: Record<string, string>,
+): string {
+  const key = hashParts(["icon", process.platform, Buffer.from(icon.bytes).toString("base64")]);
+  const sourcePath = join(cacheDir, `icon-${key}.c`);
+  const objectPath = join(cacheDir, `icon-${key}.o`);
+  if (!existsSync(objectPath)) {
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(sourcePath, iconSource(icon));
+    compileC(runner, clang, sourcePath, objectPath, cacheDir, env);
+  }
+  return objectPath;
+}
+
+/**
+ * Wrap a PNG in a minimal ICO container. Vista+ accepts a PNG payload directly,
+ * so the PE resource path needs no BMP encoder.
+ */
+export function pngToIco(png: Uint8Array, width: number, height: number): Uint8Array {
+  const header = Buffer.alloc(22);
+  header.writeUInt16LE(0, 0); // reserved
+  header.writeUInt16LE(1, 2); // type: icon
+  header.writeUInt16LE(1, 4); // image count
+  header.writeUInt8(width >= 256 || width <= 0 ? 0 : width, 6);
+  header.writeUInt8(height >= 256 || height <= 0 ? 0 : height, 7);
+  header.writeUInt8(0, 8); // palette size
+  header.writeUInt8(0, 9); // reserved
+  header.writeUInt16LE(1, 10); // color planes
+  header.writeUInt16LE(32, 12); // bits per pixel
+  header.writeUInt32LE(png.length, 14);
+  header.writeUInt32LE(22, 18); // payload offset
+  return Buffer.concat([header, Buffer.from(png)]);
+}
+
+/** Normalize any supported icon to ICO bytes (used for the PE resource). */
+export function toIcoBytes(icon: IconInfo): Uint8Array {
+  if (icon.format === "ico") return icon.bytes;
+  if (icon.format === "png") return pngToIco(icon.bytes, icon.width, icon.height);
+  throw new IconError(`Cannot embed a .${icon.format} icon as a Windows PE resource; use a PNG or ICO.`);
+}

package/src/driver/index.ts

@@ -9,3 +9,33 @@ export {
   type Runner,
 } from "./toolchain.js";
 export { resolveToolchain, type ResolvedToolchain, type ToolchainSource } from "./toolchain-provider.js";
+export {
+  CONFIG_FILE_NAME,
+  findProjectConfig,
+  loadProjectConfig,
+  parseProjectConfig,
+  resolveConfigPaths,
+  ProjectConfigError,
+  type AppConfig,
+  type LoadedProjectConfig,
+  type ProjectConfig,
+} from "./config.js";
+export {
+  ensureIconObject,
+  iconSource,
+  readIcon,
+  toIcoBytes,
+  pngToIco,
+  ICON_SYMBOLS,
+  EMPTY_ICON,
+  IconError,
+  type IconFormat,
+  type IconInfo,
+} from "./icon.js";
+export {
+  ensureWindowsIconResource,
+  resolveResourceCompiler,
+  type ResourceCompiler,
+  type ResourceCompilerKind,
+} from "./win-icon.js";
+export { bundlePathFor, infoPlist, packageMacApp, type MacBundleOptions } from "./mac-bundle.js";