xbintsc 0.3.79 → 0.3.87

package/src/driver/compiler.ts

@@ -8,7 +8,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { basename, extname, join, resolve } from "node:path";
+import { basename, dirname, extname, join, resolve } from "node:path";
 import { DiagnosticBag, DiagnosticCode, type Diagnostic } from "../diagnostics/diagnostic.js";
 import { SourceFile } from "../diagnostics/source.js";
 import { sourceTextBytes } from "../diagnostics/source-text.js";
@@ -18,6 +18,7 @@ import { SyntaxKind } from "../ast/nodes.js";
 import { bundleModules } from "./modules.js";
 import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
 import { BuildCache, hashParts } from "./cache.js";
+import { compilerFingerprint, registryFingerprint, runtimeFingerprint } from "./fingerprint.js";
 import { findRuntimeDir } from "./paths.js";
 import { findRuntimeLibrary } from "./runtime-lib.js";
 import { resolveToolchain } from "./toolchain-provider.js";
@@ -31,10 +32,17 @@ import {
   compileIr,
   link,
   realRunner,
+  RUNTIME_CFLAGS,
   type Runner,
 } from "./toolchain.js";
 
-export const COMPILER_VERSION = "0.1.0";
+/**
+ * The compiler's own version. It is part of the incremental cache key, so it
+ * must be bumped for every release (a test enforces that it matches
+ * `package.json`); a stale version would let an upgraded compiler reuse binaries
+ * produced by the previous one.
+ */
+export const COMPILER_VERSION = "0.3.87";
 
 export type EmitKind = "exe" | "obj" | "ir";
 
@@ -57,6 +65,14 @@ export interface BuildOptions {
   readonly icon?: string;
   /** Application metadata: name, icon and macOS bundle settings. */
   readonly app?: AppConfig;
+  /** Emit LLVM debug metadata so `-g` produces DWARF/CodeView (default false). */
+  readonly debug?: boolean;
+}
+
+/** One phase of a build, in milliseconds (reported by `--time`). */
+export interface PhaseTiming {
+  readonly phase: "frontend" | "codegen" | "runtime" | "clang" | "link";
+  readonly ms: number;
 }
 
 export interface BuildResult {
@@ -67,6 +83,8 @@ export interface BuildResult {
   readonly ir?: string;
   /** macOS `.app` bundle produced by `app.bundle` (darwin only). */
   readonly bundlePath?: string;
+  /** Per-phase timings, collected for `xbintsc build --time`. */
+  readonly timings?: readonly PhaseTiming[];
 }
 
 export interface CompileStringResult {
@@ -75,7 +93,12 @@ export interface CompileStringResult {
 }
 
 /** Compile TypeScript source text to LLVM IR without touching the toolchain. */
-export function compileString(source: string, fileName = "input.ts", extensions?: ExtensionRegistry): CompileStringResult {
+export function compileString(
+  source: string,
+  fileName = "input.ts",
+  extensions?: ExtensionRegistry,
+  options: { readonly debug?: boolean } = {},
+): CompileStringResult {
   const file = new SourceFile(fileName, source);
   const diagnostics = new DiagnosticBag();
   const parser = new Parser(file, diagnostics);
@@ -85,6 +108,7 @@ export function compileString(source: string, fileName = "input.ts", extensions?
     builtins: registry.builtins(),
     modules: registry.modules(),
     moduleHints: registry.moduleHints(),
+    debug: options.debug === true,
   });
   return { ir, diagnostics: diagnostics.diagnostics };
 }
@@ -106,7 +130,11 @@ function externalModuleSpecifiers(registry: ExtensionRegistry): Set<string> {
  * Compile a file to LLVM IR, bundling every reachable relative module first so
  * that imports from other TypeScript sources resolve exactly like `build`.
  */
-export function compileEntry(entryPath: string, extensions?: ExtensionRegistry): CompileStringResult {
+export function compileEntry(
+  entryPath: string,
+  extensions?: ExtensionRegistry,
+  options: { readonly debug?: boolean } = {},
+): CompileStringResult {
   const absoluteEntry = resolve(entryPath);
   const sourceText = sourceTextBytes(readFileSync(absoluteEntry, "utf8"));
   const file = new SourceFile(absoluteEntry, sourceText);
@@ -128,6 +156,7 @@ export function compileEntry(entryPath: string, extensions?: ExtensionRegistry):
     builtins: registry.builtins(),
     modules: registry.modules(),
     moduleHints: registry.moduleHints(),
+    debug: options.debug === true,
   });
   return { ir, diagnostics: diagnostics.diagnostics };
 }
@@ -173,6 +202,8 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
 
   const absoluteEntry = resolve(entryPath);
   const sourceText = sourceTextBytes(readFileSync(absoluteEntry, "utf8"));
+  const buildStarted = Date.now();
+  const timings: PhaseTiming[] = [];
 
   const baseName = basename(absoluteEntry, extname(absoluteEntry));
   const outputPath =
@@ -203,6 +234,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
       cacheText = bundled.text;
     }
   }
+  timings.push({ phase: "frontend", ms: Date.now() - buildStarted });
 
   const app = options.app ?? {};
   const iconPath = options.icon ?? app.icon;
@@ -222,6 +254,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   const runtimeDir = findRuntimeDir();
   const cacheKey = hashParts([
     COMPILER_VERSION,
+    compilerFingerprint(),
     cacheText,
     emit,
     optimize,
@@ -232,6 +265,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     app.name ?? "",
     String(app.bundle ?? false),
     app.bundleId ?? "",
+    String(options.debug === true),
   ]);
 
   // A `.app` bundle is deterministic from the output path and name, so it can be
@@ -243,34 +277,43 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   const cache = new BuildCache(cacheDir);
   const outputs = bundle ? [outputPath, bundle] : [outputPath];
   if (!options.force && !diagnostics.hasErrors && cache.isFresh(cacheKey, outputs)) {
-    return { outputPath, cached: true, diagnostics: [], ...(bundle ? { bundlePath: bundle } : {}) };
+    return { outputPath, cached: true, diagnostics: [], timings, ...(bundle ? { bundlePath: bundle } : {}) };
   }
 
+  const codegenStarted = Date.now();
   const { ir } = generate(sourceFile, diagnostics, {
     builtins: registry.builtins(),
     modules: registry.modules(),
     moduleHints: registry.moduleHints(),
+    debug: options.debug === true,
   });
+  timings.push({ phase: "codegen", ms: Date.now() - codegenStarted });
 
   if (options.verbose) {
     process.stderr.write(`xbintsc: generated ${ir.length} bytes of LLVM IR\n`);
   }
 
   if (diagnostics.hasErrors) {
-    return { outputPath, cached: false, diagnostics: diagnostics.diagnostics, ir };
+    return { outputPath, cached: false, diagnostics: diagnostics.diagnostics, ir, timings };
   }
 
   mkdirSync(outDir, { recursive: true });
+  /* An explicit `-o path/to/app.exe` (or `output` in the config) may name a
+   * directory that does not exist yet: the IR and object files land in `outDir`,
+   * but clang writes the *executable* to `outputPath`, and a missing parent
+   * directory there makes the link fail with `LNK1104: cannot open file`. */
+  mkdirSync(dirname(outputPath), { recursive: true });
   const irPath = resolve(outDir, basename(absoluteEntry, extname(absoluteEntry)) + ".ll");
   writeFileSync(irPath, ir);
 
   if (emit === "ir") {
     cache.record(cacheKey, outputs);
     cache.save();
-    return { outputPath, irPath, cached: false, diagnostics: [], ir };
+    return { outputPath, irPath, cached: false, diagnostics: [], ir, timings };
   }
 
   // -- toolchain -----------------------------------------------------------
+  const clangStarted = Date.now();
   const toolchain = options.clang
     ? { clang: options.clang, linkerArgs: [] as string[], env: {} as Record<string, string> }
     : resolveToolchain(runner);
@@ -278,14 +321,16 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   mkdirSync(cacheDir, { recursive: true });
 
   const objectPath = emit === "obj" ? outputPath : resolve(outDir, baseName + ".o");
-  compileIr(runner, { clang, irPath, objectPath, optimize, env: toolchain.env });
+  compileIr(runner, { clang, irPath, objectPath, optimize, env: toolchain.env, debug: options.debug === true });
+  timings.push({ phase: "clang", ms: Date.now() - clangStarted });
 
   if (emit === "obj") {
     cache.record(cacheKey, outputs);
     cache.save();
-    return { outputPath, irPath, cached: false, diagnostics: [], ir };
+    return { outputPath, irPath, cached: false, diagnostics: [], ir, timings };
   }
 
+  const runtimeStarted = Date.now();
   const { runtimeObjects, extensionObjects, nativeObjects } = ensureRuntimeObjects(
     runner,
     clang,
@@ -295,6 +340,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     resolvePreferPrebuilt(options.preferPrebuilt),
     toolchain.env,
   );
+  timings.push({ phase: "runtime", ms: Date.now() - runtimeStarted });
 
   /* On Windows a GUI program links as a **Windows-subsystem** executable, so
    * launching it does not flash a console window. That subsystem's C runtime
@@ -331,6 +377,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     }
   }
 
+  const linkStarted = Date.now();
   link(runner, {
     clang,
     objectPaths: [
@@ -355,6 +402,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     optimize,
     env: toolchain.env,
   });
+  timings.push({ phase: "link", ms: Date.now() - linkStarted });
 
   const bundlePath =
     bundle !== undefined
@@ -370,7 +418,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
 
   cache.record(cacheKey, outputs);
   cache.save();
-  return { outputPath, irPath, cached: false, diagnostics: [], ir, ...(bundlePath ? { bundlePath } : {}) };
+  return { outputPath, irPath, cached: false, diagnostics: [], ir, timings, ...(bundlePath ? { bundlePath } : {}) };
 }
 
 /** Default `CFBundleIdentifier` for a bundle when none is configured. */
@@ -404,51 +452,6 @@ export const RUNTIME_SOURCES = [
   "xt_io.c",
 ] as const;
 
-/**
- * Fingerprint every runtime artifact that can change a linked executable: the
- * C sources, shared headers and `#include`d `.inc` fragments plus the shipped
- * prebuilt archives. It feeds the executable cache key, so a runtime change
- * invalidates a cached binary even when the entry source is untouched — the
- * per-object cache cannot express that, because the freshness check runs before
- * any compilation.
- */
-function runtimeFingerprint(runtimeDir: string): string {
-  if (!existsSync(runtimeDir)) return "";
-  const parts: string[] = [];
-  const walk = (dir: string): void => {
-    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(full);
-      } else if (/\.(c|h|inc)$/.test(entry.name)) {
-        parts.push(entry.name, readFileSync(full, "utf8"));
-      } else {
-        parts.push(entry.name, readFileSync(full).toString("base64"));
-      }
-    }
-  };
-  walk(runtimeDir);
-  return hashParts(parts);
-}
-
-/**
- * Fingerprint everything an extension contributes that can change the linked
- * executable but does not live under `runtime/`: its name, linker flags and the
- * contents of any pre-built C++/Rust objects. Keeps a cached binary fresh when
- * a native extension is rebuilt, or when `--ext-native` flags change.
- */
-function registryFingerprint(registry: ExtensionRegistry): string {
-  const parts: string[] = [];
-  for (const extension of registry.all()) {
-    parts.push(extension.name);
-    parts.push(...(extension.linkerFlags?.() ?? []));
-    for (const object of extension.nativeObjects?.() ?? []) {
-      parts.push(object, existsSync(object) ? readFileSync(object).toString("base64") : "");
-    }
-  }
-  return hashParts(parts);
-}
-
 /**
  * Compile the core runtime and every extension source, reusing cached object
  * files keyed on the C source hash. Returns the object paths to link.
@@ -482,7 +485,16 @@ function ensureRuntimeObjects(
 
   const compileOne = (sourcePath: string, tag: string): string => {
     const body = readFileSync(sourcePath, "utf8");
-    const key = hashParts(["runtime", COMPILER_VERSION, tag, headerStamp, body, clang, process.platform]);
+    const key = hashParts([
+      "runtime",
+      COMPILER_VERSION,
+      RUNTIME_CFLAGS.join(" "),
+      tag,
+      headerStamp,
+      body,
+      clang,
+      process.platform,
+    ]);
     const objectPath = join(cacheDir, `${tag}-${key}.o`);
     if (!existsSync(objectPath)) {
       compileC(runner, clang, sourcePath, objectPath, runtimeDir, env);

package/src/driver/fingerprint.ts

@@ -0,0 +1,85 @@
+/**
+ * Content fingerprints for the incremental cache.
+ *
+ * The executable cache is keyed on everything that can change the linked
+ * binary but is not part of the entry source: the C runtime, the compiler's own
+ * sources, and whatever a native extension contributes. The per-object cache
+ * cannot express these, because the freshness check runs before compilation.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionRegistry } from "../extensions/registry.js";
+import { hashParts } from "./cache.js";
+
+/** Runtime sources, headers and `#include`d `.inc` fragments, plus prebuilt archives. */
+export function runtimeFingerprint(runtimeDir: string): string {
+  if (!existsSync(runtimeDir)) return "";
+  const parts: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (/\.(c|h|inc)$/.test(entry.name)) {
+        parts.push(entry.name, readFileSync(full, "utf8"));
+      } else {
+        parts.push(entry.name, readFileSync(full).toString("base64"));
+      }
+    }
+  };
+  walk(runtimeDir);
+  return hashParts(parts);
+}
+
+/**
+ * Content hash of the compiler's own TypeScript sources, when they are present.
+ *
+ * `COMPILER_VERSION` is bumped per release, but a developer editing codegen
+ * between releases would otherwise reuse a binary produced by the previous
+ * compiler for the same input. Hashing `src/` closes that hole in a source
+ * checkout. A released archive ships only `bin/` and `runtime/`, so the marker
+ * check fails there and the version alone keys the cache — which is correct,
+ * because release automation keeps it in sync with package.json.
+ */
+export function compilerFingerprint(): string {
+  try {
+    // In a checkout this module is `<root>/src/driver/fingerprint.ts`.
+    const sourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    if (!existsSync(join(sourceRoot, "codegen", "llvm.ts"))) return "";
+    if (!existsSync(join(sourceRoot, "driver", "compiler.ts"))) return "";
+    const parts: string[] = [];
+    const walk = (dir: string): void => {
+      for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+        } else if (entry.name.endsWith(".ts")) {
+          parts.push(relative(sourceRoot, full).replace(/\\/g, "/"), readFileSync(full, "utf8"));
+        }
+      }
+    };
+    walk(sourceRoot);
+    return hashParts(parts);
+  } catch {
+    // A self-hosted or packaged compiler may not expose its sources.
+    return "";
+  }
+}
+
+/**
+ * Everything an extension contributes besides its C sources: name, linker flags
+ * and the contents of pre-built C++/Rust objects.
+ */
+export function registryFingerprint(registry: ExtensionRegistry): string {
+  const parts: string[] = [];
+  for (const extension of registry.all()) {
+    parts.push(extension.name);
+    parts.push(...(extension.linkerFlags?.() ?? []));
+    for (const object of extension.nativeObjects?.() ?? []) {
+      parts.push(object, existsSync(object) ? readFileSync(object).toString("base64") : "");
+    }
+  }
+  return hashParts(parts);
+}

package/src/driver/toolchain-provider.ts

@@ -6,18 +6,23 @@
  * *which* driver to use, in a fixed priority order:
  *
  *   1. an explicit `xbintsc_CLANG` / `xbintsc_TOOLCHAIN`
- *   2. the system `PATH` (`findClang`)
+ *   2. the system `PATH` (`findClang`), preferring a clang >= 16
+ *   3. the LLVM build bundled with Visual Studio on Windows
  *
  * xbintsc does not ship a compiler. Every host must provide a clang-compatible
  * toolchain (see `doc/requirements.md`): the Xcode Command Line Tools on macOS,
  * the distribution's clang/lld on Linux, and LLVM plus the Visual Studio C++
  * build tools (the MSVC ABI) on Windows.
  *
+ * The version is checked here, not left to the first failed C compile: the
+ * emitted IR needs LLVM 16+ (opaque pointers), and a "clang 15 is too old"
+ * error up front is far more actionable than a wall of IR type errors later.
+ *
  * Extra linker arguments (for example `-fuse-ld=lld`) can be supplied through
  * `xbintsc_LINKER_ARGS`.
  */
 
-import { findClang, realRunner, type Runner } from "./toolchain.js";
+import { locateClang, realRunner, type ClangVersion, type Runner } from "./toolchain.js";
 
 export type ToolchainSource = "env" | "system";
 
@@ -26,6 +31,8 @@ export interface ResolvedToolchain {
   readonly clang: string;
   /** Where the driver came from. */
   readonly source: ToolchainSource;
+  /** Parsed `clang --version`, when the driver prints one. */
+  readonly version?: ClangVersion;
   /** Extra arguments to pass to the link step. */
   readonly linkerArgs: readonly string[];
   /** Extra environment for the toolchain subprocesses, merged over the current
@@ -33,14 +40,6 @@ export interface ResolvedToolchain {
   readonly env: Record<string, string>;
 }
 
-function works(runner: Runner, command: string): boolean {
-  try {
-    return runner.run(command, ["--version"]).status === 0;
-  } catch {
-    return false;
-  }
-}
-
 function linkerArgs(fallback: readonly string[]): string[] {
   const raw = process.env.xbintsc_LINKER_ARGS;
   if (raw) return raw.split(" ").filter((part) => part.length > 0);
@@ -49,10 +48,12 @@ function linkerArgs(fallback: readonly string[]): string[] {
 
 /** Resolve the toolchain that `build` should use. See the module docblock. */
 export function resolveToolchain(runner: Runner = realRunner): ResolvedToolchain {
-  const explicit = process.env.xbintsc_CLANG ?? process.env.xbintsc_TOOLCHAIN;
-  if (explicit && works(runner, explicit)) {
-    return { clang: explicit, source: "env", linkerArgs: linkerArgs([]), env: {} };
-  }
-
-  return { clang: findClang(runner), source: "system", linkerArgs: linkerArgs([]), env: {} };
+  const location = locateClang(runner);
+  return {
+    clang: location.command,
+    source: location.source,
+    ...(location.version ? { version: location.version } : {}),
+    linkerArgs: linkerArgs([]),
+    env: {},
+  };
 }