xbintsc 0.1.0

package/src/codegen/values.ts

@@ -0,0 +1,36 @@
+/**
+ * The NaN-boxed value model shared by the compiler and the runtime.
+ *
+ * A JavaScript value is a 64-bit word. Doubles are stored unboxed; every other
+ * value uses a tag in the high 16 bits plus a 48-bit payload. The compiler
+ * emits these constants directly into LLVM IR, so this module (together with
+ * runtime/rt.h) is the single source of truth for the representation.
+ */
+
+export const XT_TAG_MASK = 0xffff000000000000n;
+export const XT_NUMBER_MASK = 0xfff8000000000000n;
+
+export const XT_UNDEFINED = 0xfff8000000000000n;
+export const XT_NULL = 0xfff9000000000000n;
+export const XT_FALSE = 0xfffa000000000000n;
+export const XT_TRUE = 0xfffb000000000000n;
+export const XT_STRING = 0xfffc000000000000n;
+export const XT_OBJECT = 0xfffd000000000000n;
+export const XT_ARRAY = 0xfffe000000000000n;
+export const XT_FUNCTION = 0xffff000000000000n;
+
+/** Render a 64-bit constant the way LLVM expects signed i64 literals. */
+export function i64(value: bigint): string {
+  return BigInt.asIntN(64, value).toString();
+}
+
+/** The raw 64 bits of an IEEE-754 double, as a signed i64 literal. */
+export function numberLiteral(value: number): string {
+  const view = new DataView(new ArrayBuffer(8));
+  view.setFloat64(0, value);
+  return i64(view.getBigInt64(0));
+}
+
+export function booleanLiteral(value: boolean): string {
+  return i64(value ? XT_TRUE : XT_FALSE);
+}

package/src/diagnostics/diagnostic.ts

@@ -0,0 +1,132 @@
+import type { SourceFile } from "./source.js";
+
+export type DiagnosticCategory = "error" | "warning" | "info";
+
+/** Stable machine readable codes, grouped by pipeline stage. */
+export enum DiagnosticCode {
+  // Lexer 1xxx
+  UnterminatedString = 1001,
+  UnterminatedTemplate = 1002,
+  UnterminatedComment = 1003,
+  InvalidCharacter = 1004,
+  InvalidNumber = 1005,
+  InvalidEscape = 1006,
+
+  // Parser 2xxx
+  UnexpectedToken = 2001,
+  ExpectedToken = 2002,
+  ExpectedIdentifier = 2003,
+  UnexpectedEof = 2004,
+  InvalidAssignmentTarget = 2005,
+  DuplicateDefault = 2006,
+  InvalidTypeSyntax = 2007,
+
+  // Binder 3xxx
+  DuplicateIdentifier = 3001,
+  CannotFindName = 3002,
+  IllegalRedeclaration = 3003,
+
+  // Checker 4xxx
+  TypeMismatch = 4001,
+  NotCallable = 4002,
+  PropertyNotFound = 4003,
+  ArgumentCountMismatch = 4004,
+  UnsupportedFeature = 4005,
+
+  // Codegen 5xxx
+  CodegenError = 5001,
+
+  // Driver 6xxx
+  ModuleNotFound = 6001,
+  IOError = 6002,
+  ToolchainError = 6003,
+  IncrementalCacheError = 6004,
+}
+
+export interface Diagnostic {
+  readonly category: DiagnosticCategory;
+  readonly code: DiagnosticCode;
+  readonly message: string;
+  readonly fileName?: string;
+  readonly start?: number;
+  readonly end?: number;
+}
+
+export class DiagnosticError extends Error {
+  readonly diagnostics: readonly Diagnostic[];
+  constructor(diagnostics: Diagnostic | readonly Diagnostic[]) {
+    const list = Array.isArray(diagnostics) ? diagnostics : [diagnostics];
+    super(list.map((d) => formatDiagnostic(d)).join("\n"));
+    this.name = "DiagnosticError";
+    this.diagnostics = list;
+  }
+}
+
+export class DiagnosticBag {
+  private readonly items: Diagnostic[] = [];
+
+  get diagnostics(): readonly Diagnostic[] {
+    return this.items;
+  }
+
+  get hasErrors(): boolean {
+    return this.items.some((d) => d.category === "error");
+  }
+
+  /** Snapshot the current size so a speculative parse can roll back. */
+  mark(): number {
+    return this.items.length;
+  }
+
+  /** Discard every diagnostic added after `mark()` was taken. */
+  reset(mark: number): void {
+    this.items.length = mark;
+  }
+
+  error(code: DiagnosticCode, message: string, range?: { start: number; end: number }, fileName?: string): void {
+    this.items.push({ category: "error", code, message, fileName, start: range?.start, end: range?.end });
+  }
+
+  warning(code: DiagnosticCode, message: string, range?: { start: number; end: number }, fileName?: string): void {
+    this.items.push({ category: "warning", code, message, fileName, start: range?.start, end: range?.end });
+  }
+
+  add(diagnostic: Diagnostic): void {
+    this.items.push(diagnostic);
+  }
+
+  addAll(diagnostics: readonly Diagnostic[]): void {
+    this.items.push(...diagnostics);
+  }
+
+  throwIfErrors(): void {
+    if (this.hasErrors) throw new DiagnosticError(this.items);
+  }
+}
+
+/**
+ * Render a diagnostic with a source excerpt and a caret underline. Falls back
+ * to a plain "file:line:col" form when no source file is available.
+ */
+export function formatDiagnostic(d: Diagnostic, source?: SourceFile): string {
+  const severity = d.category;
+  let location = d.fileName ?? "<unknown>";
+  let excerpt = "";
+  if (source && d.start !== undefined) {
+    const { line, column } = source.positionAt(d.start);
+    location = `${source.fileName}:${line}:${column}`;
+    const lineText = source.text.split("\n")[line - 1] ?? "";
+    const end = d.end ?? d.start;
+    const endCol = source.positionAt(end).column;
+    const caretPad = " ".repeat(Math.max(0, column - 1));
+    const caret = "^".repeat(Math.max(1, endCol - column));
+    excerpt = `\n${lineText}\n${caretPad}${caret}`;
+  }
+  return `${location} - ${severity} TS${d.code}: ${d.message}${excerpt}`;
+}
+
+export function formatDiagnostics(diagnostics: readonly Diagnostic[], sources?: Map<string, SourceFile>): string {
+  return diagnostics
+    .map((d) => formatDiagnostic(d, d.fileName ? sources?.get(d.fileName) : undefined))
+    .join("\n");
+}

package/src/diagnostics/source.ts

@@ -0,0 +1,97 @@
+/**
+ * Source file abstraction: owns the raw text plus a line-offset index so that
+ * positions (character offsets) can be mapped back to line/column pairs for
+ * diagnostics and for incremental-compilation fingerprints.
+ */
+
+export interface LineAndColumn {
+  /** 1-based line number. */
+  readonly line: number;
+  /** 1-based column number (UTF-16 code units). */
+  readonly column: number;
+}
+
+/**
+ * A text position. `offset` is a UTF-16 code-unit index into the source text,
+ * matching how the JavaScript/TypeScript toolchain measures positions.
+ */
+export interface TextPosition {
+  readonly offset: number;
+}
+
+export interface TextRange {
+  readonly start: number;
+  readonly end: number;
+}
+
+export class SourceFile {
+  readonly fileName: string;
+  readonly text: string;
+  /** Content hash used by the incremental compiler. */
+  readonly hash: string;
+  private lineStarts: number[] | undefined;
+
+  constructor(fileName: string, text: string) {
+    this.fileName = fileName;
+    // Normalize BOM and line endings so downstream stages only deal with "\n".
+    const normalized = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    this.text = normalized.replace(/\r\n?/g, "\n");
+    this.hash = hashText(this.text);
+  }
+
+  get length(): number {
+    return this.text.length;
+  }
+
+  private getLineStarts(): number[] {
+    if (this.lineStarts === undefined) {
+      const starts = [0];
+      const text = this.text;
+      for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10 /* \n */) starts.push(i + 1);
+      }
+      this.lineStarts = starts;
+    }
+    return this.lineStarts;
+  }
+
+  positionAt(offset: number): LineAndColumn {
+    const clamped = Math.max(0, Math.min(offset, this.text.length));
+    const starts = this.getLineStarts();
+    // Binary search for the greatest line start <= clamped.
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (starts[mid]! <= clamped) lo = mid;
+      else hi = mid - 1;
+    }
+    return { line: lo + 1, column: clamped - starts[lo]! + 1 };
+  }
+
+  /** Extract the raw source text covered by a range. */
+  slice(range: TextRange): string {
+    return this.text.slice(range.start, range.end);
+  }
+}
+
+/**
+ * FNV-1a 64-bit content hash rendered as a hex string. Small, dependency free
+ * and stable across platforms which is exactly what the incremental cache
+ * needs. Collision resistance is not a security property here.
+ */
+export function hashText(text: string, seed = 0xcbf29ce484222325n): string {
+  let hash = seed;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= BigInt(text.charCodeAt(i));
+    hash = (hash * prime) & mask;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+/** Combine several hashes/strings into one stable fingerprint. */
+export function combineHashes(parts: readonly string[]): string {
+  return hashText(parts.join("\u0000"));
+}

package/src/driver/cache.ts

@@ -0,0 +1,96 @@
+/**
+ * Content-addressed incremental build cache.
+ *
+ * The cache keys a build on everything that can change the output: the entry
+ * source hash, the compiler version, the resolved options and the set of active
+ * extensions. If nothing changed and the recorded outputs still exist, the
+ * build is skipped entirely.
+ *
+ * It is deliberately a single JSON manifest so it is easy to inspect, diff and
+ * invalidate; a future content-addressed object store can replace it without
+ * touching callers.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface CacheEntry {
+  readonly key: string;
+  readonly outputs: readonly string[];
+  readonly createdAt: number;
+}
+
+export interface CacheManifest {
+  readonly version: 1;
+  readonly entries: Record<string, CacheEntry>;
+}
+
+export function hashString(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 32);
+}
+
+export function hashParts(parts: readonly string[]): string {
+  const hash = createHash("sha256");
+  for (const part of parts) {
+    hash.update(String(part.length));
+    hash.update(":");
+    hash.update(part);
+    hash.update(";");
+  }
+  return hash.digest("hex").slice(0, 32);
+}
+
+export class BuildCache {
+  private manifest: CacheManifest = { version: 1, entries: {} };
+  private dirty = false;
+
+  constructor(private readonly directory: string) {
+    this.load();
+  }
+
+  private get manifestPath(): string {
+    return join(this.directory, "build-cache.json");
+  }
+
+  private load(): void {
+    if (!existsSync(this.manifestPath)) return;
+    try {
+      const parsed = JSON.parse(readFileSync(this.manifestPath, "utf8")) as CacheManifest;
+      if (parsed.version === 1 && parsed.entries) this.manifest = parsed;
+    } catch {
+      // A corrupt cache is never fatal; start from scratch.
+      this.manifest = { version: 1, entries: {} };
+    }
+  }
+
+  save(): void {
+    if (!this.dirty) return;
+    mkdirSync(this.directory, { recursive: true });
+    writeFileSync(this.manifestPath, JSON.stringify(this.manifest, null, 2));
+    this.dirty = false;
+  }
+
+  /** True when `key` was built before and every recorded output still exists. */
+  isFresh(key: string, outputs: readonly string[]): boolean {
+    const entry = this.manifest.entries[key];
+    if (!entry) return false;
+    const recorded = outputs.length > 0 ? outputs : entry.outputs;
+    if (recorded.length === 0) return false;
+    return recorded.every((output) => existsSync(output));
+  }
+
+  record(key: string, outputs: readonly string[]): void {
+    this.manifest.entries[key] = { key, outputs: [...outputs], createdAt: Date.now() };
+    this.dirty = true;
+  }
+
+  clear(): void {
+    this.manifest = { version: 1, entries: {} };
+    this.dirty = true;
+  }
+
+  entries(): readonly CacheEntry[] {
+    return Object.values(this.manifest.entries);
+  }
+}

package/src/driver/compiler.ts

@@ -0,0 +1,197 @@
+/**
+ * The build driver: source file in, native binary out.
+ *
+ * Pipeline: read -> parse -> bind/check -> LLVM IR -> object -> link.
+ * The runtime (and any registered extension sources) are compiled once and
+ * cached, and the whole build is skipped when the incremental cache says
+ * nothing relevant changed.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { DiagnosticBag, type Diagnostic } from "../diagnostics/diagnostic.js";
+import { SourceFile } from "../diagnostics/source.js";
+import { Parser } from "../parser/parser.js";
+import { generate } from "../codegen/llvm.js";
+import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
+import { BuildCache, hashParts } from "./cache.js";
+import { findRuntimeDir } from "./paths.js";
+import {
+  compileC,
+  compileIr,
+  findClang,
+  link,
+  realRunner,
+  type Runner,
+} from "./toolchain.js";
+
+export const COMPILER_VERSION = "0.1.0";
+
+export type EmitKind = "exe" | "obj" | "ir";
+
+export interface BuildOptions {
+  /** Explicit output path (defaults to the source base name in `outDir`). */
+  readonly output?: string;
+  readonly outDir?: string;
+  readonly optimize?: "0" | "1" | "2" | "3";
+  readonly emit?: EmitKind;
+  readonly force?: boolean;
+  readonly verbose?: boolean;
+  readonly cacheDir?: string;
+  readonly extensions?: ExtensionRegistry;
+  readonly runner?: Runner;
+  readonly clang?: string;
+  readonly write?: boolean;
+}
+
+export interface BuildResult {
+  readonly outputPath: string;
+  readonly irPath?: string;
+  readonly cached: boolean;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly ir?: string;
+}
+
+export interface CompileStringResult {
+  readonly ir: string;
+  readonly diagnostics: readonly Diagnostic[];
+}
+
+/** Compile TypeScript source text to LLVM IR without touching the toolchain. */
+export function compileString(source: string, fileName = "input.ts", extensions?: ExtensionRegistry): CompileStringResult {
+  const file = new SourceFile(fileName, source);
+  const diagnostics = new DiagnosticBag();
+  const parser = new Parser(file, diagnostics);
+  const sourceFile = parser.parseSourceFile();
+  const registry = extensions ?? createDefaultRegistry();
+  const { ir } = generate(sourceFile, diagnostics, { builtins: registry.builtins() });
+  return { ir, diagnostics: diagnostics.diagnostics };
+}
+
+function executableName(entry: string, outDir: string, explicit: string | undefined): string {
+  if (explicit) return resolve(explicit);
+  const base = basename(entry, extname(entry));
+  const suffix = process.platform === "win32" ? ".exe" : "";
+  return resolve(outDir, base + suffix);
+}
+
+export function build(entryPath: string, options: BuildOptions = {}): BuildResult {
+  const runner = options.runner ?? realRunner;
+  const registry = options.extensions ?? createDefaultRegistry();
+  const outDir = resolve(options.outDir ?? join(process.cwd(), "build"));
+  const cacheDir = resolve(options.cacheDir ?? join(process.cwd(), ".xbintsc"));
+  const emit: EmitKind = options.emit ?? "exe";
+  const optimize = options.optimize ?? "2";
+
+  const absoluteEntry = resolve(entryPath);
+  const sourceText = readFileSync(absoluteEntry, "utf8");
+
+  const baseName = basename(absoluteEntry, extname(absoluteEntry));
+  const outputPath =
+    emit === "ir"
+      ? resolve(options.output ?? join(outDir, baseName + ".ll"))
+      : emit === "obj"
+        ? resolve(options.output ?? join(outDir, baseName + ".o"))
+        : executableName(absoluteEntry, outDir, options.output);
+
+  const cacheKey = hashParts([
+    COMPILER_VERSION,
+    sourceText,
+    emit,
+    optimize,
+    process.platform,
+    registry.all().map((e) => e.name).join(","),
+  ]);
+
+  const cache = new BuildCache(cacheDir);
+  const outputs = [outputPath];
+  if (!options.force && cache.isFresh(cacheKey, outputs)) {
+    return { outputPath, cached: true, diagnostics: [] };
+  }
+
+  // -- front end -----------------------------------------------------------
+  const file = new SourceFile(absoluteEntry, sourceText);
+  const diagnostics = new DiagnosticBag();
+  const parser = new Parser(file, diagnostics);
+  const sourceFile = parser.parseSourceFile();
+  const { ir } = generate(sourceFile, diagnostics, { builtins: registry.builtins() });
+
+  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 };
+  }
+
+  mkdirSync(outDir, { 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 };
+  }
+
+  // -- toolchain -----------------------------------------------------------
+  const clang = options.clang ?? findClang(runner);
+  const runtimeDir = findRuntimeDir();
+  mkdirSync(cacheDir, { recursive: true });
+
+  const { runtimeObject, extensionObjects } = ensureRuntimeObjects(runner, clang, runtimeDir, cacheDir, registry);
+
+  const objectPath = emit === "obj" ? outputPath : resolve(outDir, baseName + ".o");
+  compileIr(runner, { clang, irPath, objectPath, optimize });
+
+  if (emit === "obj") {
+    cache.record(cacheKey, outputs);
+    cache.save();
+    return { outputPath, irPath, cached: false, diagnostics: [], ir };
+  }
+
+  link(runner, {
+    clang,
+    objectPaths: [objectPath, runtimeObject, ...extensionObjects],
+    outputPath,
+    linkerFlags: [...(process.platform === "win32" ? [] : ["-lm"]), ...registry.linkerFlags()],
+    optimize,
+  });
+
+  cache.record(cacheKey, outputs);
+  cache.save();
+  return { outputPath, irPath, cached: false, diagnostics: [], ir };
+}
+
+interface RuntimeObjects {
+  readonly runtimeObject: string;
+  readonly extensionObjects: readonly string[];
+}
+
+/**
+ * Compile the core runtime and every extension source, reusing cached object
+ * files keyed on the C source hash. Returns the object paths to link.
+ */
+function ensureRuntimeObjects(
+  runner: Runner,
+  clang: string,
+  runtimeDir: string,
+  cacheDir: string,
+  registry: ExtensionRegistry,
+): RuntimeObjects {
+  const compileOne = (sourcePath: string, tag: string): string => {
+    const body = readFileSync(sourcePath, "utf8");
+    const key = hashParts(["runtime", COMPILER_VERSION, tag, body, clang, process.platform]);
+    const objectPath = join(cacheDir, `${tag}-${key}.o`);
+    if (!existsSync(objectPath)) {
+      compileC(runner, clang, sourcePath, objectPath, runtimeDir);
+    }
+    return objectPath;
+  };
+
+  const runtimeObject = compileOne(join(runtimeDir, "xt_runtime.c"), "xt_runtime");
+  const extensionObjects = registry
+    .runtimeSources()
+    .map((sourcePath, index) => compileOne(sourcePath, `ext_${index}_${basename(sourcePath, ".c")}`));
+  return { runtimeObject, extensionObjects };
+}

package/src/driver/index.ts

@@ -0,0 +1,4 @@
+export { build, compileString, COMPILER_VERSION, type BuildOptions, type BuildResult, type EmitKind } from "./compiler.js";
+export { BuildCache, hashParts, hashString } from "./cache.js";
+export { findRuntimeDir, findPackageRoot } from "./paths.js";
+export { findClang, realRunner, ToolchainError, type Runner } from "./toolchain.js";

package/src/driver/paths.ts

@@ -0,0 +1,24 @@
+/** Filesystem locations owned by the compiler package. */
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Directory containing `rt.h` and the runtime/ext C sources. */
+export function findRuntimeDir(): string {
+  const candidates = [
+    resolve(here, "../../runtime"),
+    resolve(here, "../../../runtime"),
+    resolve(process.cwd(), "runtime"),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(join(candidate, "rt.h"))) return candidate;
+  }
+  throw new Error("Unable to locate the xbintsc runtime directory (missing runtime/rt.h)");
+}
+
+export function findPackageRoot(): string {
+  return resolve(findRuntimeDir(), "..");
+}

package/src/driver/toolchain.ts

@@ -0,0 +1,103 @@
+/**
+ * Thin wrappers around the external toolchain (clang) and process execution.
+ *
+ * Everything that shells out lives here so the rest of the driver stays
+ * testable: unit tests can pass a fake `Runner` and never touch the host.
+ */
+
+import { spawnSync, type SpawnSyncOptions } from "node:child_process";
+
+export interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface Runner {
+  run(command: string, args: readonly string[], options?: { cwd?: string }): CommandResult;
+}
+
+export const realRunner: Runner = {
+  run(command, args, options = {}) {
+    const spawnOptions: SpawnSyncOptions = {
+      cwd: options.cwd,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    };
+    const result = spawnSync(command, [...args], spawnOptions);
+    return {
+      status: result.status ?? (result.error ? 1 : 0),
+      stdout: result.stdout?.toString() ?? "",
+      stderr: result.stderr?.toString() ?? (result.error ? String(result.error.message) : ""),
+    };
+  },
+};
+
+export class ToolchainError extends Error {
+  readonly command: string;
+  readonly status: number;
+  readonly stderr: string;
+  constructor(command: string, status: number, stderr: string) {
+    super(`Command failed (${status}): ${command}\n${stderr}`);
+    this.name = "ToolchainError";
+    this.command = command;
+    this.status = status;
+    this.stderr = stderr;
+  }
+}
+
+/** Locate a clang-compatible C compiler, honouring `xbintsc_CLANG`. */
+export function findClang(runner: Runner = realRunner): string {
+  const candidates = [
+    process.env.xbintsc_CLANG,
+    "clang",
+    "clang-18",
+    "clang-17",
+    "clang-16",
+    "cc",
+  ].filter((candidate): candidate is string => Boolean(candidate));
+  for (const candidate of candidates) {
+    const result = runner.run(candidate, ["--version"]);
+    if (result.status === 0) return candidate;
+  }
+  throw new ToolchainError("clang --version", 1, "No C compiler found. Set xbintsc_CLANG to a clang binary.");
+}
+
+export interface CompileIrOptions {
+  readonly clang: string;
+  readonly irPath: string;
+  readonly objectPath: string;
+  readonly optimize: string;
+}
+
+/** Compile an LLVM IR file to a native object file. */
+export function compileIr(runner: Runner, options: CompileIrOptions): void {
+  const result = runner.run(options.clang, [
+    `-O${options.optimize}`,
+    "-c",
+    options.irPath,
+    "-o",
+    options.objectPath,
+  ]);
+  if (result.status !== 0) throw new ToolchainError(`${options.clang} ${options.irPath}`, result.status, result.stderr);
+}
+
+export interface LinkOptions {
+  readonly clang: string;
+  readonly objectPaths: readonly string[];
+  readonly outputPath: string;
+  readonly linkerFlags: readonly string[];
+  readonly optimize: string;
+}
+
+export function link(runner: Runner, options: LinkOptions): void {
+  const args = [`-O${options.optimize}`, ...options.objectPaths, "-o", options.outputPath, ...options.linkerFlags];
+  const result = runner.run(options.clang, args);
+  if (result.status !== 0) throw new ToolchainError(`${options.clang} link`, result.status, result.stderr);
+}
+
+/** Compile a C source to an object file (used for the runtime and extensions). */
+export function compileC(runner: Runner, clang: string, sourcePath: string, objectPath: string, includeDir: string): void {
+  const result = runner.run(clang, ["-O2", "-c", sourcePath, "-o", objectPath, `-I${includeDir}`]);
+  if (result.status !== 0) throw new ToolchainError(`${clang} ${sourcePath}`, result.status, result.stderr);
+}