c-next 0.2.17 → 0.2.18

package/src/transpiler/logic/parser/grammar/CNextVisitor.ts

@@ -45,6 +45,7 @@ import { IfStatementContext } from "./CNextParser.js";
 import { WhileStatementContext } from "./CNextParser.js";
 import { DoWhileStatementContext } from "./CNextParser.js";
 import { ForStatementContext } from "./CNextParser.js";
+import { ForeverStatementContext } from "./CNextParser.js";
 import { ForInitContext } from "./CNextParser.js";
 import { ForVarDeclContext } from "./CNextParser.js";
 import { ForAssignmentContext } from "./CNextParser.js";
@@ -353,6 +354,12 @@ export class CNextVisitor<Result> extends AbstractParseTreeVisitor<Result> {
      * @return the visitor result
      */
     visitForStatement?: (ctx: ForStatementContext) => Result;
+    /**
+     * Visit a parse tree produced by `CNextParser.foreverStatement`.
+     * @param ctx the parse tree
+     * @return the visitor result
+     */
+    visitForeverStatement?: (ctx: ForeverStatementContext) => Result;
     /**
      * Visit a parse tree produced by `CNextParser.forInit`.
      * @param ctx the parse tree

package/src/transpiler/logic/preprocessor/CompileCommandsReader.ts

@@ -0,0 +1,332 @@
+/**
+ * CompileCommandsReader — derive the compiler's own view (include search path,
+ * preprocessor defines, compiler binary) from a `compile_commands.json`
+ * compilation database.
+ *
+ * cnext is a source consumer that must resolve external C/C++ headers exactly as
+ * the compiler will. Rather than couple to any one build system's path logic (or
+ * hand-mirror it in cnext.config.json), it reads the build-system-agnostic
+ * contract every build system converges on: the compiler command line, serialized
+ * per translation unit in `compile_commands.json` (the LLVM compilation database
+ * that clangd/clang-tidy also consume). Framework include paths are project-global
+ * — identical across translation units — so the union of every entry's `-I` set is
+ * the search path cnext needs; defines and the compiler binary come along for free.
+ *
+ * This is the pure parse layer: a database string in, `{ includePaths, defines,
+ * compiler }` out. No filesystem access — the loader layer reads the file.
+ */
+import { readFileSync } from "node:fs";
+import { resolve, isAbsolute } from "node:path";
+import ICompileCommandsResult from "./types/ICompileCommandsResult";
+
+/** One compile_commands.json entry (clang spec: `command` OR `arguments`). */
+interface ICompileCommandsEntry {
+  directory?: string;
+  file?: string;
+  command?: string;
+  arguments?: string[];
+}
+
+/** Mutable state threaded through the POSIX word-splitter. */
+interface ITokenizerState {
+  tokens: string[];
+  current: string;
+  /** Whether a token is in progress (so empty quotes still emit ""). */
+  started: boolean;
+  mode: "normal" | "single" | "double";
+}
+
+/** Mutable state accumulated across every compile-DB entry while parsing. */
+interface ICompileCommandsAccumulator {
+  /** Include search paths in first-seen order, de-duplicated via `seen`. */
+  includePaths: string[];
+  /** Dedup guard for `includePaths`. */
+  seen: Set<string>;
+  /** Preprocessor defines (last write wins across entries). */
+  defines: Record<string, string | boolean>;
+  /** Compiler binary — the first entry-with-args argv[0] wins. */
+  compiler: string | null;
+}
+
+class CompileCommandsReader {
+  /**
+   * Include-search flags whose operand is a directory. Each accepts an operand
+   * attached to the flag or as the following token. `-I` is case-sensitive, so
+   * it never swallows the lowercase `-isystem`/`-iquote`/`-idirafter` flags.
+   */
+  private static readonly INCLUDE_FLAGS = [
+    "-I",
+    "-isystem",
+    "-iquote",
+    "-idirafter",
+  ];
+
+  /**
+   * Read and parse a `compile_commands.json` from disk. Returns null if the file
+   * is missing or malformed, so callers can fall back to configured includes
+   * rather than fail — a missing compile database is a normal, non-fatal state.
+   */
+  static load(path: string): ICompileCommandsResult | null {
+    try {
+      return CompileCommandsReader.parse(readFileSync(path, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Parse a `compile_commands.json` string into the compiler's include search
+   * path, defines, and compiler binary (combined across all entries).
+   */
+  static parse(jsonContent: string): ICompileCommandsResult {
+    const accumulator: ICompileCommandsAccumulator = {
+      includePaths: [],
+      seen: new Set<string>(),
+      defines: {},
+      compiler: null,
+    };
+
+    const entries = JSON.parse(jsonContent) as ICompileCommandsEntry[];
+    for (const entry of entries) {
+      const args = CompileCommandsReader.entryArgs(entry);
+      if (accumulator.compiler === null && args.length > 0) {
+        accumulator.compiler = args[0]; // argv[0] is the compiler binary
+      }
+      CompileCommandsReader.processArgs(
+        accumulator,
+        args,
+        entry.directory ?? "",
+      );
+    }
+
+    return {
+      includePaths: accumulator.includePaths,
+      defines: accumulator.defines,
+      compiler: accumulator.compiler,
+    };
+  }
+
+  /**
+   * Resolve one entry's argv: explicit `arguments` if present, else the
+   * word-split `command` string, else none. `arguments` is used when truthy so a
+   * present-but-empty `[]` is kept (an entry with no compile args) — matching the
+   * clang spec's `command`-OR-`arguments` shape.
+   */
+  private static entryArgs(entry: ICompileCommandsEntry): string[] {
+    if (entry.arguments) return entry.arguments;
+    return entry.command ? CompileCommandsReader.tokenize(entry.command) : [];
+  }
+
+  /** Collect include paths and defines from one entry's argv. */
+  private static processArgs(
+    accumulator: ICompileCommandsAccumulator,
+    args: string[],
+    directory: string,
+  ): void {
+    for (let i = 0; i < args.length; i++) {
+      i += CompileCommandsReader.processArg(accumulator, args, i, directory);
+    }
+  }
+
+  /**
+   * Classify one arg — an include flag or a `-D` define — and collect its
+   * operand. Returns the number of ADDITIONAL tokens consumed (0, or 1 for a
+   * space-separated operand) so the caller advances past it.
+   */
+  private static processArg(
+    accumulator: ICompileCommandsAccumulator,
+    args: string[],
+    index: number,
+    directory: string,
+  ): number {
+    const includeFlag = CompileCommandsReader.matchIncludeFlag(args[index]);
+    if (includeFlag) {
+      const operand = CompileCommandsReader.resolveOperand(
+        args,
+        index,
+        includeFlag.length,
+      );
+      CompileCommandsReader.collectIncludePath(
+        accumulator,
+        directory,
+        operand.value,
+      );
+      return operand.extraConsumed;
+    }
+    if (args[index].startsWith("-D")) {
+      const operand = CompileCommandsReader.resolveOperand(args, index, 2);
+      CompileCommandsReader.collectDefine(accumulator, operand.value);
+      return operand.extraConsumed;
+    }
+    return 0;
+  }
+
+  /**
+   * Resolve a flag's operand: the text attached directly to the flag, or — if
+   * that is empty — the next token (the space-separated `-I foo` form), then
+   * consumed. The next-token form is taken unconditionally when the attached text
+   * is empty, even at the end of argv, so index advancement stays in step.
+   */
+  private static resolveOperand(
+    args: string[],
+    index: number,
+    prefixLength: number,
+  ): { value: string; extraConsumed: number } {
+    const attached = args[index].slice(prefixLength);
+    if (attached === "") {
+      return { value: args[index + 1] ?? "", extraConsumed: 1 };
+    }
+    return { value: attached, extraConsumed: 0 };
+  }
+
+  /**
+   * Collect an include directory (absolute kept verbatim; relative resolved
+   * against the entry `directory`), de-duplicated in first-seen order. An empty
+   * operand (a flag with no directory) is ignored.
+   */
+  private static collectIncludePath(
+    accumulator: ICompileCommandsAccumulator,
+    directory: string,
+    raw: string,
+  ): void {
+    if (raw === "") return;
+    const path = isAbsolute(raw) ? raw : resolve(directory, raw);
+    if (!accumulator.seen.has(path)) {
+      accumulator.seen.add(path);
+      accumulator.includePaths.push(path);
+    }
+  }
+
+  /**
+   * Collect a `-D` define, split on the FIRST `=`: `KEY=VAL` -> `VAL` (a trailing
+   * `KEY=` keeps the empty value), bare `KEY` -> `true`. An empty operand is
+   * ignored.
+   */
+  private static collectDefine(
+    accumulator: ICompileCommandsAccumulator,
+    raw: string,
+  ): void {
+    if (raw === "") return;
+    const eq = raw.indexOf("=");
+    if (eq === -1) {
+      accumulator.defines[raw] = true;
+    } else {
+      accumulator.defines[raw.slice(0, eq)] = raw.slice(eq + 1);
+    }
+  }
+
+  /** Return the include flag `arg` begins with, or null if it is not one. */
+  private static matchIncludeFlag(arg: string): string | null {
+    return (
+      CompileCommandsReader.INCLUDE_FLAGS.find((flag) =>
+        arg.startsWith(flag),
+      ) ?? null
+    );
+  }
+
+  /**
+   * Split a `command` string into argv, matching POSIX shell word-splitting (as
+   * `shlex`/`/bin/sh` do) so tokens equal what the compiler was actually invoked
+   * with. Real quotes are syntax (consumed); backslash-escaped quotes are literal
+   * (kept); whitespace inside quotes is preserved. Only the cases that occur in
+   * real compile databases are handled — no `$`/backtick expansion.
+   */
+  private static tokenize(command: string): string[] {
+    const state: ITokenizerState = {
+      tokens: [],
+      current: "",
+      started: false,
+      mode: "normal",
+    };
+    for (let i = 0; i < command.length; i++) {
+      i += CompileCommandsReader.tokenizeChar(state, command, i);
+    }
+    if (state.started) state.tokens.push(state.current);
+    return state.tokens;
+  }
+
+  /**
+   * Consume one character at `command[i]` in the current tokenizer mode.
+   * Returns the number of ADDITIONAL characters consumed (0 or 1) so the caller
+   * can advance past an escape's target.
+   */
+  private static tokenizeChar(
+    state: ITokenizerState,
+    command: string,
+    i: number,
+  ): number {
+    const ch = command[i];
+    if (state.mode === "single") {
+      if (ch === "'") state.mode = "normal";
+      else state.current += ch;
+      return 0;
+    }
+    if (state.mode === "double") {
+      return CompileCommandsReader.tokenizeDoubleQuoted(state, command, i);
+    }
+    return CompileCommandsReader.tokenizeNormal(state, command, i);
+  }
+
+  /** Handle one character outside quotes; returns extra chars consumed. */
+  private static tokenizeNormal(
+    state: ITokenizerState,
+    command: string,
+    i: number,
+  ): number {
+    const ch = command[i];
+    if (ch === "\\") {
+      const next = command[i + 1];
+      if (next === undefined) return 0; // trailing backslash: nothing follows
+      state.current += next; // outside quotes, backslash escapes any next char
+      state.started = true;
+      return 1;
+    }
+    if (ch === "'" || ch === '"') {
+      state.mode = ch === "'" ? "single" : "double";
+      state.started = true;
+      return 0;
+    }
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      if (state.started) {
+        state.tokens.push(state.current);
+        state.current = "";
+        state.started = false;
+      }
+      return 0;
+    }
+    state.current += ch;
+    state.started = true;
+    return 0;
+  }
+
+  /** Handle one character inside double quotes; returns extra chars consumed. */
+  private static tokenizeDoubleQuoted(
+    state: ITokenizerState,
+    command: string,
+    i: number,
+  ): number {
+    const ch = command[i];
+    if (ch === '"') {
+      state.mode = "normal";
+      return 0;
+    }
+    if (ch === "\\") {
+      const next = command[i + 1];
+      // Match POSIX `shlex` (the reference this tokenizer is validated against):
+      // inside double quotes only `\"` and `\\` are escapes. Before anything else
+      // — `$`, a backtick, a newline — the backslash is a literal character.
+      // shlex and bash disagree there; we pin to shlex for verifiable parity, and
+      // real compile databases never quote those characters anyway.
+      if (next === '"' || next === "\\") {
+        state.current += next;
+        return 1;
+      }
+      state.current += ch;
+      return 0;
+    }
+    state.current += ch;
+    return 0;
+  }
+}
+
+export default CompileCommandsReader;

package/src/transpiler/logic/preprocessor/ExternalDeclarationOracle.ts

@@ -0,0 +1,202 @@
+/**
+ * ExternalDeclarationOracle — recover FULL external symbols (function signatures,
+ * typedefs, opaque structs) from a set of C/C++ headers that cnext's normal,
+ * per-header-standalone symbol collection could not resolve.
+ *
+ * Two things defeat standalone collection of framework headers:
+ *  1. Include-order guards — FreeRTOS `task.h` opens with
+ *     `#ifndef INC_FREERTOS_H / #error`, so it refuses to preprocess unless
+ *     `FreeRTOS.h` ran first.
+ *  2. The parser's twin failure modes on a single header:
+ *     - RAW (unpreprocessed) text still contains function-attribute macros like
+ *       FreeRTOS `PRIVILEGED_FUNCTION` (`void vTaskDelay(...) PRIVILEGED_FUNCTION;`)
+ *       — the trailing token breaks the declaration, so `vTaskDelay` is lost.
+ *     - FULLY preprocessed text inlines the header's entire transitive tree
+ *       (e.g. `driver/twai.h` -> ~100KB of xtensa HAL); ANTLR error-recovery then
+ *       skips tokens in the blob and silently drops later declarations.
+ *
+ * The fix is to preprocess the include set AS A TRANSLATION UNIT (predecessors
+ * first) while KEEPING `#line` directives, then bucket the output BY SOURCE FILE.
+ * Each header's own slice is macro-expanded (PRIVILEGED_FUNCTION is gone) yet
+ * small (no inlined tree), so parsing it robustly yields full signatures. The
+ * caller parses each slice with cnext's real header parser, so recovered symbols
+ * carry their full types — codegen needs these to pass structs by address
+ * (`twai_driver_install(&cfg)`) and treat opaque types as pointers
+ * (`lv_obj_t` -> `lv_obj_t *`).
+ *
+ * Function-like macros (e.g. `pdMS_TO_TICKS`) have no declaration to parse, so
+ * their NAMES are collected separately (`-dM`) for the undeclared-call check
+ * only — a by-value macro invocation is already correct.
+ *
+ * Requires a toolchain that can preprocess the target's headers; for cross
+ * targets (ESP32/xtensa) set CNEXT_CROSS_COMPILER.
+ */
+import Preprocessor from "./Preprocessor";
+import IPreprocessOptions from "./types/IPreprocessOptions";
+
+// Function-like macro definitions from a `-dM` dump: `#define pdMS_TO_TICKS(`.
+const FUNCTION_MACRO = /^#define\s+([A-Za-z_]\w*)\(/gm;
+// gcc/clang line marker: `# 958 "/path/to/task.h" 2`.
+const LINE_MARKER = /^#\s+\d+\s+"([^"]+)"/;
+// Synthetic TU filename (appears in preprocessor errors, keyed on to locate a
+// failing include by its line number).
+const TU_NAME = "cnext-external-decl-oracle.c";
+
+interface IExternalRecovery {
+  /**
+   * Map of source header path -> that header's OWN preprocessed text (its
+   * macro-expanded declarations, without the transitively-inlined tree). Parse
+   * each with the real header parser to register full external symbols.
+   */
+  perFileContent: Map<string, string>;
+  /** Names of function-like macros — no declaration exists to parse. */
+  macroNames: Set<string>;
+}
+
+class ExternalDeclarationOracle {
+  /**
+   * Preprocess `includeDirectives` (e.g. `"<freertos/task.h>"`) as one TU and
+   * return each header's own preprocessed slice plus function-like-macro names.
+   *
+   * @param includeDirectives include specs, in source order (angle- or
+   *   quote-form, e.g. `<Arduino.h>` or `"foo.h"`)
+   * @param preprocessor the shared Preprocessor (uses CNEXT_CROSS_COMPILER)
+   * @param options include paths + defines for the TU
+   */
+  static async recover(
+    includeDirectives: readonly string[],
+    preprocessor: Preprocessor,
+    options: IPreprocessOptions,
+  ): Promise<IExternalRecovery | null> {
+    if (includeDirectives.length === 0 || !preprocessor.isAvailable()) {
+      return null;
+    }
+
+    // KEEP line directives so the output can be split back into per-file slices.
+    const base: IPreprocessOptions = { ...options, keepLineDirectives: true };
+
+    // Build the largest subset that preprocesses cleanly (drop a header that
+    // can't preprocess — e.g. a fragile lvgl.h — instead of losing everything).
+    const working = await ExternalDeclarationOracle.preprocessLargestWorkingTu(
+      [...includeDirectives],
+      preprocessor,
+      base,
+    );
+    if (!working) return null;
+
+    const perFileContent = ExternalDeclarationOracle.splitByFile(
+      working.content,
+    );
+
+    // Function-like macros the plain preprocess would have consumed at use.
+    const macroNames = new Set<string>();
+    const macros = await preprocessor.preprocessString(
+      ExternalDeclarationOracle.buildTu(working.directives),
+      TU_NAME,
+      { ...options, keepLineDirectives: false, dumpMacros: true },
+    );
+    if (macros.success) {
+      for (const match of macros.content.matchAll(FUNCTION_MACRO)) {
+        macroNames.add(match[1]);
+      }
+    }
+
+    return { perFileContent, macroNames };
+  }
+
+  /**
+   * Bucket preprocessed output by originating source file using its `#line`
+   * markers. Synthetic units (`<built-in>`, `<command-line>`, the TU itself) are
+   * skipped. Each real header maps to the concatenation of its own emitted lines.
+   */
+  private static splitByFile(content: string): Map<string, string> {
+    const buckets = new Map<string, string[]>();
+    let current = "";
+    for (const line of content.split("\n")) {
+      const marker = LINE_MARKER.exec(line);
+      if (marker) {
+        current = marker[1];
+        continue;
+      }
+      if (!current || current.startsWith("<") || current.endsWith(TU_NAME)) {
+        continue;
+      }
+      let bucket = buckets.get(current);
+      if (!bucket) {
+        bucket = [];
+        buckets.set(current, bucket);
+      }
+      bucket.push(line);
+    }
+    const perFile = new Map<string, string>();
+    for (const [file, lines] of buckets) {
+      perFile.set(file, lines.join("\n"));
+    }
+    return perFile;
+  }
+
+  private static buildTu(directives: readonly string[]): string {
+    return directives.map((d) => `#include ${d}`).join("\n") + "\n";
+  }
+
+  /**
+   * Preprocess the directives as a TU; on failure, drop the single include that
+   * caused it (identified by its line in the synthetic TU) and retry. Returns
+   * the preprocessed content and the surviving directive list, or null.
+   */
+  private static async preprocessLargestWorkingTu(
+    directives: string[],
+    preprocessor: Preprocessor,
+    base: IPreprocessOptions,
+  ): Promise<{ content: string; directives: string[] } | null> {
+    const remaining = directives;
+    // At most one drop per iteration; bound iterations by the ORIGINAL directive
+    // count, captured once. `remaining` aliases `directives` and shrinks via
+    // splice() below, so re-reading `directives.length` in the bound would halve
+    // the allowed attempts and bail before trying the last surviving includes.
+    const initialCount = directives.length;
+    for (
+      let attempt = 0;
+      remaining.length > 0 && attempt <= initialCount;
+      attempt++
+    ) {
+      const result = await preprocessor.preprocessString(
+        ExternalDeclarationOracle.buildTu(remaining),
+        TU_NAME,
+        base,
+      );
+      if (result.success) {
+        return { content: result.content, directives: remaining };
+      }
+      const failedIndex = ExternalDeclarationOracle.findFailingIncludeIndex(
+        result.error,
+        remaining.length,
+      );
+      if (failedIndex < 0) return null; // can't localize — give up
+      remaining.splice(failedIndex, 1);
+    }
+    return null;
+  }
+
+  /**
+   * From a preprocessor error, find the index of the top-level `#include` that
+   * failed, via its line number in the synthetic TU (directive i is at line
+   * i+1). Returns -1 if it can't be localized.
+   */
+  private static findFailingIncludeIndex(
+    error: string | undefined,
+    count: number,
+  ): number {
+    if (!error) return -1;
+    const escapedTu = TU_NAME.replaceAll(".", String.raw`\.`);
+    const pattern = new RegExp(escapedTu + String.raw`:(\d+)`, "g");
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(error)) !== null) {
+      const line = Number.parseInt(match[1], 10);
+      if (line >= 1 && line <= count) return line - 1;
+    }
+    return -1;
+  }
+}
+
+export default ExternalDeclarationOracle;

package/src/transpiler/logic/preprocessor/Preprocessor.ts

@@ -3,7 +3,7 @@
  * Runs the system preprocessor on C/C++ files before parsing
  */
 
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { writeFile, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -14,7 +14,7 @@ import ISourceMapping from "./types/ISourceMapping";
 import IPreprocessOptions from "./types/IPreprocessOptions";
 import ToolchainDetector from "./ToolchainDetector";
 
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 /**
  * Handles preprocessing of C/C++ files
@@ -153,6 +153,12 @@ class Preprocessor {
       args.pop(); // Remove -P
     }
 
+    // Dump macro definitions (#define list) instead of preprocessed source,
+    // to discover function-like macros the normal preprocess would consume.
+    if (options.dumpMacros) {
+      args.push("-dM");
+    }
+
     // Add include paths
     const includePaths = [
       ...this.defaultIncludePaths,
@@ -175,14 +181,26 @@ class Preprocessor {
       }
     }
 
+    // Import predecessor macros (gcc/clang -imacros) so include-order-dependent
+    // headers get the guards/attribute macros their includer would have defined
+    // first. -imacros keeps only the macros, not the predecessors' declarations,
+    // so the output stays scoped to the target file.
+    if (options.imacros) {
+      for (const macroHeader of options.imacros) {
+        args.push("-imacros", macroHeader);
+      }
+    }
+
     // Add the input file
     args.push(filePath);
 
-    // Build command
-    const command = `${toolchain.cpp} ${args.join(" ")}`;
-
+    // Invoke the preprocessor via argv (execFile, NOT a shell). A shell would
+    // re-parse -D values that legitimately contain spaces / parentheses (e.g.
+    // -DARDUINO_BOARD="Espressif ... (8 MB QD, No PSRAM)"), breaking on the
+    // metacharacters. Passing args directly mirrors how the real compiler is
+    // invoked and is safe for any value the compiler accepts.
     try {
-      const { stdout, stderr } = await execAsync(command, {
+      const { stdout, stderr } = await execFileAsync(toolchain.cpp, args, {
         maxBuffer: 50 * 1024 * 1024, // 50MB buffer for large headers
       });
 

package/src/transpiler/logic/preprocessor/ToolchainDetector.ts

@@ -5,7 +5,7 @@
 
 import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import IToolchain from "./types/IToolchain";
 
 /**
@@ -17,6 +17,16 @@ class ToolchainDetector {
    * Priority: ARM cross-compiler > clang > gcc
    */
   static detect(): IToolchain | null {
+    // Explicit override: a project can name the compiler that owns its target
+    // headers (e.g. a cross-compiler such as xtensa-esp32s3-elf-gcc) via
+    // CNEXT_CROSS_COMPILER. Host gcc/clang lack a cross target's system headers
+    // and predefined macros, so their preprocessing of target headers fails.
+    const override = process.env.CNEXT_CROSS_COMPILER;
+    if (override) {
+      const overridden = ToolchainDetector.fromPath(override);
+      if (overridden) return overridden;
+    }
+
     // Try ARM cross-compiler first (for embedded)
     const arm = this.detectArmToolchain();
     if (arm) return arm;
@@ -50,6 +60,37 @@ class ToolchainDetector {
     return toolchains;
   }
 
+  /**
+   * Build a toolchain from an explicit compiler path or executable name (e.g. a
+   * target cross-compiler such as xtensa-esp32s3-elf-gcc). Used by the
+   * CNEXT_CROSS_COMPILER override so a project can preprocess its target headers with the compiler
+   * that owns them.
+   */
+  static fromPath(compiler: string): IToolchain | null {
+    let cc: string | null;
+    if (compiler.includes("/")) {
+      cc = existsSync(compiler) ? compiler : null;
+    } else {
+      cc = this.findExecutable(compiler);
+    }
+    if (!cc) return null;
+
+    // Best-effort C++ driver alongside the C driver (only cpp is used for
+    // preprocessing; cxx is derived for completeness).
+    const cxxCandidate = cc.replace(/gcc(\.exe)?$/, "g++$1");
+    const cxx =
+      cxxCandidate !== cc && existsSync(cxxCandidate) ? cxxCandidate : cc;
+
+    return {
+      name: basename(cc),
+      cc,
+      cxx,
+      cpp: cc,
+      version: this.getVersion(cc),
+      isCrossCompiler: true,
+    };
+  }
+
   /**
    * Detect ARM cross-compiler (arm-none-eabi-gcc)
    */