xbintsc 0.5.45 → 0.5.52

package/src/cli/main.ts

@@ -31,9 +31,7 @@ import {
   toolchainPointer,
   UNEXPECTED_FAILURE_HINT,
 } from "./hints.js";
-import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
-import { bundledExtensions } from "../extensions/catalog.js";
-import { nativeExtensionFromManifest } from "../extensions/native.js";
+import { buildRegistry, normalizeExtensions } from "./extensions.js";
 import { resolveResourceCompiler } from "../driver/win-icon.js";
 import {
   CONFIG_FILE_NAME,
@@ -80,6 +78,8 @@ const VALUE_FLAGS = new Set([
   "optimize",
   "ext",
   "ext-native",
+  "feature",
+  "no-feature",
   "config",
   "icon",
   "app-id",
@@ -138,27 +138,6 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
   return { command: positionals.shift(), positionals, flags, passthrough };
 }
 
-function buildRegistry(extNames: readonly string[], nativeManifests: readonly string[]): ExtensionRegistry {
-  const registry = createDefaultRegistry();
-  const bundled = bundledExtensions();
-  for (const name of extNames) {
-    const extension = bundled.find((candidate) => candidate.name === name);
-    if (!extension) throw new Error(`Unknown extension '${name}'`);
-    registry.register(extension);
-  }
-  // Each manifest describes a pre-built C++ or Rust library.
-  for (const manifest of nativeManifests) {
-    registry.register(nativeExtensionFromManifest(manifest));
-  }
-  // Hint the extensions that ship with xbintsc but were not enabled, so a
-  // missing `import` of a known module points at the flag that enables it
-  // (`pass --ext node`) instead of failing later with a confusing error.
-  for (const extension of bundled) {
-    if (!registry.has(extension.name)) registry.hintExtension(extension);
-  }
-  return registry;
-}
-
 function printDiagnostics(diagnostics: readonly Diagnostic[], fileName: string, io: CliIo): void {
   /* A diagnostic can come from any module in a bundled program, so load (and
    * cache) the source of the file it names instead of always using the entry:
@@ -404,7 +383,8 @@ function dispatch(argv: readonly string[], io: CliIo): number {
     }
     const extNames = listFlag(args.flags, "ext") ?? resolved.config.extensions ?? [];
     const nativeManifests = listFlag(args.flags, "ext-native") ?? resolved.config.extNative ?? [];
-    const registry = buildRegistry(extNames, nativeManifests);
+    const { extensions: registryExtensions } = normalizeExtensions(extNames, io);
+    const registry = buildRegistry(registryExtensions, nativeManifests);
     /* Front-end only: parse, bundle, check and lower far enough to report
      * semantic / unsupported-feature diagnostics, but never invoke clang or
      * write output. The checker is on unless `--no-check` is passed. */
@@ -458,7 +438,8 @@ function dispatch(argv: readonly string[], io: CliIo): number {
     }
     const extNames = listFlag(args.flags, "ext") ?? resolved.config.extensions ?? [];
     const nativeManifests = listFlag(args.flags, "ext-native") ?? resolved.config.extNative ?? [];
-    const registry = buildRegistry(extNames, nativeManifests);
+    const { extensions: registryExtensions } = normalizeExtensions(extNames, io);
+    const registry = buildRegistry(registryExtensions, nativeManifests);
     const { ir, diagnostics } = compileEntry(entry, registry, {
       debug: Boolean(args.flags.get("debug")),
       check: !args.flags.has("no-check"),
@@ -490,7 +471,13 @@ function dispatch(argv: readonly string[], io: CliIo): number {
     const optimize = (args.flags.get("optimize") as string | undefined) ?? config.optimize ?? "2";
     const extNames = listFlag(args.flags, "ext") ?? config.extensions ?? [];
     const nativeManifests = listFlag(args.flags, "ext-native") ?? config.extNative ?? [];
-    const registry = buildRegistry(extNames, nativeManifests);
+    const normalized = normalizeExtensions(extNames, io);
+    const registry = buildRegistry(normalized.extensions, nativeManifests);
+    const features = [
+      ...normalized.features,
+      ...(listFlag(args.flags, "feature") ?? config.features ?? []),
+    ];
+    const noFeatures = listFlag(args.flags, "no-feature") ?? config.noFeatures ?? [];
     const pgoGenerate = args.flags.get("pgo-generate");
     const pgoUse = args.flags.get("pgo-use");
     if (pgoGenerate !== undefined && pgoUse !== undefined) {
@@ -524,6 +511,8 @@ function dispatch(argv: readonly string[], io: CliIo): number {
       lto: Boolean(args.flags.get("lto")) || config.lto === true,
       ...(pgo ? { pgo } : {}),
       ...(pgoDir ? { pgoDir } : {}),
+      ...(features.length > 0 ? { features } : {}),
+      ...(noFeatures.length > 0 ? { noFeatures } : {}),
     });
 
     if (result.diagnostics.some((d) => d.category === "error")) {
@@ -535,6 +524,11 @@ function dispatch(argv: readonly string[], io: CliIo): number {
       return 1;
     }
 
+    /* A detected-but-unavailable feature is a warning, not a failure: the
+     * program still links and the capability degrades at run time. */
+    const warnings = result.diagnostics.filter((d) => d.category === "warning");
+    if (warnings.length > 0) printDiagnostics(warnings, entry, io);
+
     if (args.flags.has("time") && result.timings) printTimings(result.timings, io);
 
     if (command === "build") {

package/src/diagnostics/diagnostic.ts

@@ -44,6 +44,8 @@ export enum DiagnosticCode {
   ToolchainError = 6003,
   IncrementalCacheError = 6004,
   CircularDependency = 6005,
+  /** An optional link feature was requested but its archive is unavailable. */
+  LinkFeatureUnavailable = 6006,
 }
 
 export interface Diagnostic {

package/src/driver/build-key.ts

@@ -31,6 +31,8 @@ export interface CacheKeyInput {
   readonly check?: boolean;
   readonly pgo?: PgoMode;
   readonly pgoDir: string;
+  /** Active optional link features; they change which objects/archives link. */
+  readonly features?: readonly string[];
 }
 
 /** Hash every input that can change the produced binary. */
@@ -54,5 +56,6 @@ export function buildCacheKey(input: CacheKeyInput): string {
     String(input.check !== false),
     pgo ?? "",
     pgo ? input.pgoDir : "",
+    [...(input.features ?? [])].sort().join(","),
   ]);
 }

package/src/driver/compiler.ts

@@ -28,6 +28,8 @@ import { parseEntry } from "./frontend.js";
 import { ensureRuntimeObjects } from "./runtime-objects.js";
 import { ensureAppArtifacts } from "./app-artifacts.js";
 import { buildCacheKey } from "./build-key.js";
+import { collectUsage } from "./usage.js";
+import { resolveLinkFeatures, type ResolvedLinkFeature } from "./link-features.js";
 import type { BuildOptions, BuildResult, EmitKind, PhaseTiming } from "./options.js";
 
 export { COMPILER_VERSION } from "./version.js";
@@ -102,8 +104,35 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     return { outputPath, cached: false, diagnostics: diagnostics.diagnostics, timings };
   }
 
+  /* Optional link features are selected from the bundled program before the
+   * cache key: they change which registration objects and archives link. Only
+   * a linked `exe` has features; `emit obj`/`ir` produce toolchain input that
+   * the caller may link itself. */
   const app: AppConfig = options.app ?? {};
   const iconPath = options.icon ?? app.icon;
+  /* An app icon is decoded through the image pipeline, so force `images` even
+   * when the bundled HTML has no `<img>` — but only when the enabled extensions
+   * actually declare that feature (a non-GUI program may still embed an icon). */
+  const hasImagesFeature = registry.linkFeatures().some((entry) => entry.feature.name === "images");
+  const featureRequest = {
+    features: [
+      ...(options.features ?? []),
+      ...(iconPath !== undefined && hasImagesFeature ? ["images"] : []),
+    ],
+    noFeatures: options.noFeatures,
+  };
+  const linkFeatures: readonly ResolvedLinkFeature[] =
+    emit === "exe"
+      ? resolveLinkFeatures(registry, collectUsage(parsed.sourceFile), featureRequest, diagnostics)
+      : [];
+  if (diagnostics.hasErrors) {
+    return { outputPath, cached: false, diagnostics: diagnostics.diagnostics, timings };
+  }
+  if (options.verbose) {
+    const names = linkFeatures.map((feature) => feature.name);
+    process.stderr.write(`xbintsc: link features: ${names.length > 0 ? names.join(", ") : "none"}\n`);
+  }
+
   let icon: IconInfo | undefined;
   if (iconPath) {
     try {
@@ -131,6 +160,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     check: options.check !== false,
     pgo,
     pgoDir,
+    features: linkFeatures.map((feature) => feature.name),
   });
 
   // A `.app` bundle is deterministic from the output path and name, so it can be
@@ -144,7 +174,14 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   /* PGO profile data can change without the cache key changing, so always
    * rebuild a `--pgo-use` binary; it is an explicit optimization step. */
   if (!options.force && pgo !== "use" && !diagnostics.hasErrors && cache.isFresh(cacheKey, outputs)) {
-    return { outputPath, cached: true, diagnostics: [], timings, ...(bundle ? { bundlePath: bundle } : {}) };
+    return {
+      outputPath,
+      cached: true,
+      diagnostics: [],
+      timings,
+      features: linkFeatures.map((feature) => feature.name),
+      ...(bundle ? { bundlePath: bundle } : {}),
+    };
   }
 
   const codegenStarted = Date.now();
@@ -220,7 +257,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   }
 
   const runtimeStarted = Date.now();
-  const { runtimeObjects, extensionObjects, nativeObjects } = ensureRuntimeObjects({
+  const { runtimeObjects, extensionObjects, featureObjects, nativeObjects } = ensureRuntimeObjects({
     runner,
     clang,
     runtimeDir,
@@ -231,6 +268,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     lto,
     pgo,
     pgoDir,
+    features: linkFeatures,
   });
   timings.push({ phase: "runtime", ms: Date.now() - runtimeStarted });
 
@@ -254,17 +292,25 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     clang,
     objectPaths: [
       objectPath,
-      ...runtimeObjects,
-      ...extensionObjects,
-      ...nativeObjects,
-      ...(artifacts.entryObject !== undefined ? [artifacts.entryObject] : []),
-      ...artifacts.iconObjects,
+      /* Feature archives come after their bridges (which reference the
+       * implementation) and before the extensions' own archives (`gui.a`
+       * provides symbols the bridges call back into). `Set` keeps that order
+       * and drops an archive two features or an extension share. */
+      ...new Set([
+        ...runtimeObjects,
+        ...extensionObjects,
+        ...featureObjects,
+        ...nativeObjects,
+        ...(artifacts.entryObject !== undefined ? [artifacts.entryObject] : []),
+        ...artifacts.iconObjects,
+      ]),
     ],
     outputPath,
     linkerFlags: [
       ...toolchain.linkerArgs,
       ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm", "-pthread"]),
       ...registry.linkerFlags(),
+      ...linkFeatures.flatMap((feature) => feature.linkerFlags),
       /* A GUI program is a Windows-subsystem executable: no console window is
        * created when it is launched. Console output (stdout/stderr) is lost in
        * that subsystem, so a program that wants to report things opts back in
@@ -292,7 +338,16 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
 
   cache.record(cacheKey, outputs);
   cache.save();
-  return { outputPath, irPath, cached: false, diagnostics: [], ir, timings, ...(bundlePath ? { bundlePath } : {}) };
+  return {
+    outputPath,
+    irPath,
+    cached: false,
+    diagnostics: [],
+    ir,
+    timings,
+    features: linkFeatures.map((feature) => feature.name),
+    ...(bundlePath ? { bundlePath } : {}),
+  };
 }
 
 /** Default `CFBundleIdentifier` for a bundle when none is configured. */

package/src/driver/config.ts

@@ -44,6 +44,10 @@ export interface ProjectConfig {
   readonly pgoDir?: string;
   readonly extensions?: readonly string[];
   readonly extNative?: readonly string[];
+  /** Optional link features to force on (`media`, `gpu`, `images`, `shaping`, `webgl`, `all`). */
+  readonly features?: readonly string[];
+  /** Optional link features to keep out even when auto-detection finds a use. */
+  readonly noFeatures?: readonly string[];
   readonly force?: boolean;
   readonly app?: AppConfig;
 }
@@ -135,6 +139,8 @@ export function parseProjectConfig(text: string, where: string = CONFIG_FILE_NAM
     pgoDir: readString(root, "pgoDir", where),
     extensions: readStringArray(root, "extensions", where),
     extNative: readStringArray(root, "extNative", where),
+    features: readStringArray(root, "features", where),
+    noFeatures: readStringArray(root, "noFeatures", where),
     force: readBoolean(root, "force", where),
     app,
   };

package/src/driver/link-features.ts

@@ -0,0 +1,163 @@
+/**
+ * Resolving optional link features for one build.
+ *
+ * The registry knows which features the *enabled* extensions can provide; this
+ * module decides which of them a program may use (from {@link ProgramUsage}),
+ * applies the `--feature` / `--no-feature` overrides, and turns an unavailable
+ * archive into either a warning (auto-detected) or an error (explicitly forced).
+ *
+ * Keeping the decision here — not in codegen — means the produced LLVM IR is
+ * independent of the feature set: the only difference is which registration
+ * objects and archives reach the linker.
+ */
+
+import { DiagnosticCode, type DiagnosticBag } from "../diagnostics/diagnostic.js";
+import type { ExtensionRegistry } from "../extensions/registry.js";
+import type { LinkFeature, ProgramUsage } from "../extensions/link-feature.js";
+
+/** The user's explicit feature overrides (`--feature` / `--no-feature`). */
+export interface LinkFeatureRequest {
+  readonly features?: readonly string[];
+  readonly noFeatures?: readonly string[];
+}
+
+/** One active feature, with everything the driver needs to link it. */
+export interface ResolvedLinkFeature {
+  readonly name: string;
+  readonly description: string;
+  readonly runtimeSources: readonly string[];
+  readonly nativeObjects: readonly string[];
+  readonly linkerFlags: readonly string[];
+}
+
+/** `--feature all` / `--no-feature all`; specific names override it. */
+const ALL = "all";
+
+/** Human-readable list of the features the enabled extensions provide. */
+function availableList(names: readonly string[]): string {
+  if (names.length === 0) return "none (enable an extension that provides one, e.g. --ext gui)";
+  return names.join(", ");
+}
+
+/**
+ * Pick the active features for `usage`.
+ *
+ * Precedence: a specific `--feature x` beats `--no-feature all`, and a specific
+ * `--no-feature x` beats `--feature all`; the same name on both sides is an
+ * error. Diagnosed errors are left in `diagnostics`; the caller must stop when
+ * it has errors.
+ */
+export function resolveLinkFeatures(
+  registry: ExtensionRegistry,
+  usage: ProgramUsage,
+  request: LinkFeatureRequest,
+  diagnostics: DiagnosticBag,
+): readonly ResolvedLinkFeature[] {
+  const declarations = registry.linkFeatures();
+  const byName = new Map<string, LinkFeature>();
+  for (const declaration of declarations) byName.set(declaration.feature.name, declaration.feature);
+  const available = [...byName.keys()].sort();
+  const requested = new Set(request.features ?? []);
+  const disabled = new Set(request.noFeatures ?? []);
+
+  for (const name of [...requested, ...disabled]) {
+    if (name === ALL || byName.has(name)) continue;
+    diagnostics.error(
+      DiagnosticCode.LinkFeatureUnavailable,
+      `unknown link feature '${name}'; available: ${availableList(available)}`,
+    );
+  }
+  if (requested.has(ALL) && disabled.has(ALL)) {
+    diagnostics.error(
+      DiagnosticCode.LinkFeatureUnavailable,
+      "link features cannot be both forced and disabled with 'all' (--feature all --no-feature all)",
+    );
+  }
+  if (diagnostics.hasErrors) return [];
+
+  const forceAll = requested.has(ALL);
+  const disableAll = disabled.has(ALL);
+
+  /* Start from the explicitly forced set, then pull in `requires`. A specific
+   * `--no-feature` wins over `--feature all`, so it is excluded from the base
+   * set; a dependency it blocks is an error rather than a silent omission. */
+  const forced = new Set<string>();
+  for (const { feature } of declarations) {
+    const specificallyForced = requested.has(feature.name);
+    const specificallyBlocked = disabled.has(feature.name);
+    if (specificallyForced && specificallyBlocked) {
+      diagnostics.error(
+        DiagnosticCode.LinkFeatureUnavailable,
+        `link feature '${feature.name}' is both forced (--feature) and disabled (--no-feature)`,
+      );
+      continue;
+    }
+    if (specificallyForced || (forceAll && !specificallyBlocked)) forced.add(feature.name);
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const { feature } of declarations) {
+      if (!forced.has(feature.name)) continue;
+      for (const dependency of feature.requires ?? []) {
+        if (!byName.has(dependency)) {
+          diagnostics.error(
+            DiagnosticCode.LinkFeatureUnavailable,
+            `link feature '${feature.name}' requires unknown feature '${dependency}'`,
+          );
+          continue;
+        }
+        if (disabled.has(dependency)) {
+          diagnostics.error(
+            DiagnosticCode.LinkFeatureUnavailable,
+            `link feature '${feature.name}' requires '${dependency}', which --no-feature disables`,
+          );
+          continue;
+        }
+        if (!forced.has(dependency)) {
+          forced.add(dependency);
+          changed = true;
+        }
+      }
+    }
+  }
+  if (diagnostics.hasErrors) return [];
+
+  const resolved: ResolvedLinkFeature[] = [];
+
+  for (const { feature } of declarations) {
+    const specificallyBlocked = disabled.has(feature.name);
+    const forcedHere = forced.has(feature.name);
+    const blocked = specificallyBlocked || (disableAll && !requested.has(feature.name) && !forcedHere);
+    if (!forcedHere && blocked) continue;
+    if (!forcedHere && !feature.used(usage)) continue;
+
+    let runtimeSources: readonly string[];
+    let nativeObjects: readonly string[];
+    try {
+      runtimeSources = feature.runtimeSources?.() ?? [];
+      nativeObjects = feature.nativeObjects?.() ?? [];
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (forcedHere) {
+        diagnostics.error(DiagnosticCode.LinkFeatureUnavailable, message);
+      } else {
+        diagnostics.warning(
+          DiagnosticCode.LinkFeatureUnavailable,
+          `link feature '${feature.name}' was detected but is unavailable: ${message}`,
+        );
+      }
+      continue;
+    }
+
+    resolved.push({
+      name: feature.name,
+      description: feature.description,
+      runtimeSources: [...runtimeSources],
+      nativeObjects: [...nativeObjects],
+      linkerFlags: [...(feature.linkerFlags?.() ?? [])],
+    });
+  }
+
+  return resolved;
+}

package/src/driver/options.ts

@@ -50,6 +50,14 @@ export interface BuildOptions {
   readonly pgo?: PgoMode;
   /** Profile directory (default: `<outDir>/pgo`). */
   readonly pgoDir?: string;
+  /**
+   * Optional link features to force on (`media`, `gpu`, `images`, `shaping`, `webgl`, or `all`). Features are
+   * otherwise selected from a static scan of the bundled program; forcing one
+   * is the escape hatch for HTML/CSS built from runtime data.
+   */
+  readonly features?: readonly string[];
+  /** Optional link features to keep out even when the scan detects a use. */
+  readonly noFeatures?: readonly string[];
 }
 
 /** One phase of a build, in milliseconds (reported by `--time`). */
@@ -68,6 +76,8 @@ export interface BuildResult {
   readonly bundlePath?: string;
   /** Per-phase timings, collected for `xbintsc build --time`. */
   readonly timings?: readonly PhaseTiming[];
+  /** Active optional link features (only for a linked `exe` build). */
+  readonly features?: readonly string[];
 }
 
 export interface CompileStringResult {

package/src/driver/runtime-objects.ts

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import type { ExtensionRegistry } from "../extensions/registry.js";
+import type { ResolvedLinkFeature } from "./link-features.js";
 import { hashParts } from "./cache.js";
 import { findRuntimeLibrary } from "./runtime-lib.js";
 import { compileC, optimizationFlags, RUNTIME_CFLAGS, type PgoMode, type Runner } from "./toolchain.js";
@@ -46,6 +47,8 @@ export const RUNTIME_SOURCES = [
 export interface RuntimeObjects {
   readonly runtimeObjects: readonly string[];
   readonly extensionObjects: readonly string[];
+  /** Objects/archives contributed by active optional link features. */
+  readonly featureObjects: readonly string[];
   /** Pre-built C++/Rust objects and archives contributed by native extensions. */
   readonly nativeObjects: readonly string[];
 }
@@ -61,6 +64,8 @@ export interface RuntimeObjectsOptions {
   readonly lto: boolean;
   readonly pgo: PgoMode | undefined;
   readonly pgoDir: string;
+  /** Optional link features selected for this program. */
+  readonly features?: readonly ResolvedLinkFeature[];
 }
 
 /**
@@ -131,5 +136,25 @@ export function ensureRuntimeObjects(options: RuntimeObjectsOptions): RuntimeObj
     }
   }
   // A native archive may be shared by several manifests; link each once.
-  return { runtimeObjects, extensionObjects, nativeObjects: [...new Set(registry.nativeObjects())] };
+  const featureObjects: string[] = [];
+  for (const feature of options.features ?? []) {
+    /* Feature bridges are always compiled: they are not part of any prebuilt
+     * archive, and their references are what make the linker extract the
+     * feature's implementation. */
+    for (const sourcePath of feature.runtimeSources) {
+      const dedupeKey = resolve(sourcePath);
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      extensionObjects.push(
+        compileOne(sourcePath, `feature_${feature.name}_${basename(sourcePath, ".c")}`),
+      );
+    }
+    featureObjects.push(...feature.nativeObjects);
+  }
+  return {
+    runtimeObjects,
+    extensionObjects,
+    featureObjects: [...new Set(featureObjects)],
+    nativeObjects: [...new Set(registry.nativeObjects())],
+  };
 }