xbintsc 0.3.35 → 0.3.49

package/doc/ai/extensions.md

@@ -0,0 +1,148 @@
+# Extensions: Node modules, GUI, C++/Rust libraries
+
+The compiler core is platform-agnostic. Anything platform-specific — Node's
+`fs`, an HTML/CSS renderer, your own C++ library — arrives as an **extension**
+that contributes module bindings plus the C/C++ sources or objects to link.
+
+## The rule that trips people up
+
+**An import of an extension-provided module fails until the extension is
+enabled.** xbintsc knows the module exists and says exactly what to pass:
+
+```bash
+$ xbintsc run app.ts            # app.ts: import { readFileSync } from "fs";
+error TS6001: module 'fs' is provided by the 'node' extension; pass --ext node
+```
+
+```bash
+xbintsc run app.ts --ext node
+```
+
+Enable several at once with a comma-separated list: `--ext node,gui`. In a
+project, put them in `xbintsc.config.json` so no flag is needed:
+
+```json
+{ "entry": "src/app.ts", "outDir": "build", "extensions": ["node"] }
+```
+
+## Bundled extensions
+
+### `node` — Node built-in modules
+
+Enable with `--ext node`. A module is importable by its bare name or the
+`node:` prefix (`import { readFileSync } from "node:fs"`), and both spellings
+resolve to the same implementation.
+
+| Module | Notes |
+| --- | --- |
+| `fs` | **synchronous API only** (`readFileSync`, `writeFileSync`, …); `fs/promises` is separate |
+| `fs/promises` | promise-based file APIs |
+| `path` | also hooks namespace dispatch, so `path.join(...)` works |
+| `os` | |
+| `process` | `process.cwd()`, `argv`, `env`, …; namespace dispatch too |
+| `buffer` | |
+| `crypto` | |
+| `stream`, `stream/promises` | |
+| `events` | |
+| `net`, `dgram`, `http` | sockets and servers on the xbintsc event loop (see the async caveat below) |
+| `child_process` | |
+| `worker_threads` | |
+| `util`, `querystring`, `url`, `assert`, `test`, `zlib` | |
+
+Coverage per module (exact functions and options) is in
+[../node-implemented.md](../node-implemented.md); what is missing is in
+[../node-unimplemented.md](../node-unimplemented.md).
+
+Remember the runtime model before building on `net`/`http`: the event loop runs
+**after** the program body, and `async`/`await` is a synchronous microtask
+model. See [language-support.md](./language-support.md).
+
+### `gui` — HTML/CSS window
+
+Enable with `--ext gui` and import the `gui` module:
+
+```ts
+import { createWindow, run } from "gui";
+```
+
+It is a self-contained GPU-accelerated renderer (own HTML parser, CSS cascade,
+layout and compositor) — not a system WebView. It ships as a per-platform
+prebuilt `gui.a`/`gui.lib` because it is C++. If that archive is missing for
+your platform, the build fails with an actionable message; design and roadmap
+live in [../gui.md](../gui.md), and the scripting surface in
+[../gui-scripts.md](../gui-scripts.md).
+
+## Third-party npm packages
+
+Bare specifiers that no enabled extension claims are looked up in `node_modules`
+and bundled **as source**. A package that is not plain ESM TypeScript/JavaScript
+— or that relies on CommonJS, `require`, `__dirname`, or circular dependencies —
+will not work. `require()` is rejected with a hint to convert to `import`.
+
+Practical consequence: for a Node program, enabling `--ext node` is usually the
+right answer; reach for an npm dependency only when you must.
+
+## Native extensions (C++ / Rust, no compiler changes)
+
+Any code that exposes `extern "C"` entry points with the runtime ABI can be
+linked in:
+
+```c
+xt_value my_fn(int32_t argc, xt_value *argv);
+```
+
+Build it with an **external** toolchain (clang++ or cargo), describe the
+artifacts in a JSON manifest, and pass the manifest:
+
+```bash
+xbintsc build demo.ts --ext-native ./xbintsc.manifest.json
+xbintsc build demo.ts --ext-native a.json,b.json      # several
+```
+
+```jsonc
+{
+  "name": "mathx-cpp",                       // required, unique
+  "objects": ["build/mathx.o"],              // .o / .a / .lib, relative to this file
+  "linkerFlagsByPlatform": {                 // C++/Rust runtimes
+    "linux":  ["-lstdc++", "-lm"],
+    "darwin": ["-lc++"],
+    "win32":  ["-lmsvcprt"]
+  },
+  "builtins": { "cppClamp": { "symbol": "mathx_clamp" } },   // no import needed
+  "modules": {
+    "mathx": { "exports": { "add": { "symbol": "mathx_add" } } }
+  }
+}
+```
+
+`import { add } from "mathx"` then lowers to the native symbol exactly like a C
+runtime binding; `builtins` are globally callable without importing.
+
+Authoring helpers: `runtime/xt_ext.h` (C/C++) and `runtime/xt_ext.rs` (Rust) —
+they wrap the argument and value helpers. Key ABI facts: values are 64-bit
+NaN-boxed words; strings are **not** NUL-terminated, so pair `xt_string_data`
+with `xt_string_length_value`; the runtime never moves or frees memory it handed
+out. Build with the same clang/ABI that xbintsc resolves (`xbintsc doctor`
+prints it), and on Windows build inside an **x64/ARM64 Native Tools Command
+Prompt**.
+
+Working projects to copy: [`examples/extensions/cpp`](../../examples/extensions/cpp)
+and [`examples/extensions/rust`](../../examples/extensions/rust); the full guide
+is [../../examples/extensions/README.md](../../examples/extensions/README.md).
+
+## Programmatic registration
+
+```ts
+import { build, createDefaultRegistry, nativeExtensionFromManifest, nodeExtension } from "xbintsc";
+
+const extensions = createDefaultRegistry()
+  .register(nodeExtension)
+  .register(nativeExtensionFromManifest("./xbintsc.manifest.json"));
+
+build("demo.ts", { extensions });
+```
+
+The registry is also how a host tool hints at a disabled extension, which is what
+produces the "pass `--ext node`" message instead of a confusing downstream error
+([../../src/extensions/catalog.ts](../../src/extensions/catalog.ts)). The list of
+bundled extensions is `bundledExtensions()`.

package/doc/ai/language-support.md

@@ -0,0 +1,152 @@
+# Language support: what compiles, what behaves differently
+
+xbintsc compiles a **practical subset** of TypeScript. Use this page to decide
+what you can write; follow the links for exact wording.
+
+Canonical detail (always current, much longer):
+
+- [../implemented.md](../implemented.md) — everything that works, by compiler stage
+- [../unimplemented.md](../unimplemented.md) — unsupported syntax, deviations, quick reference
+- [../node-implemented.md](../node-implemented.md) / [../node-unimplemented.md](../node-unimplemented.md) — the Node extension
+
+> Chinese: [../zh-CN/implemented.md](../zh-CN/implemented.md), [../zh-CN/unimplemented.md](../zh-CN/unimplemented.md)
+
+## Legend
+
+| Mark | Meaning |
+| --- | --- |
+| ✅ | Works as in Node/TypeScript |
+| ⚠️ | Works but deviates from the standard |
+| 🚫 | Rejected — parse error or `UnsupportedFeature` |
+| — | Parsed and erased, with no runtime effect |
+
+## Statements and declarations
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| `var` / `let` / `const`, blocks, `if`, `for`, `for...of`, `for...in`, `while`, `do...while` | ✅ | `for...in` enumerates own keys only (no prototype chain) |
+| `switch`, `break`, `continue`, labels | ✅ | labeled `break`/`continue` included |
+| `try` / `catch` / `finally`, `throw` | ✅ | `finally` runs on early `return`/`break`/`continue` |
+| `function`, arrow functions, default/rest parameters | ✅ | |
+| `return`, `throw` as expressions' operands | ✅ | |
+| `namespace` / `module` declaration | 🚫 | parse ✓, codegen ✗ |
+| `with`, `debugger` | 🚫 | not supported |
+| Top-level `await` | 🚫 | wrap it in an `async` function |
+
+## Expressions and operators
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| Arithmetic, bitwise, logical, comparison, assignment operators | ✅ | ES `ToPrimitive` / `+` coercion match Node |
+| `===` / `!==` / `==` / `!=` | ✅ | loose equality matches Node |
+| Optional chaining `?.`, nullish `??`, logical assignment `??=` | ✅ | whole-chain short-circuit implemented |
+| Template literals, tagged templates | ✅ | tagged templates have `raw` + `String.raw` |
+| Spread / rest in calls, arrays and object literals | ✅ | |
+| Destructuring (bindings, parameters, nested) | ✅ | defaults + rest supported |
+| `delete`, `in`, `instanceof`, `typeof` | ✅ | |
+| Comma operator, `void` | ✅ | |
+| `new.target` | 🚫 | not implemented |
+| `import.meta` | 🚫 | parsed but has no value |
+| `super` | ⚠️ | single-level inheritance correct; depth > 1 may be inaccurate |
+
+## Functions, classes, objects
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| Closures (capture by reference through boxes) | ✅ | one ABI for direct and closure calls |
+| `this`, method calls, arrow lexical `this` | ✅ | arrow functions get their own `arguments`, unlike JS |
+| `call` / `apply` / `bind`, `fn.name` / `fn.length` | ✅ | a bound closure does not track partial-argument `length` |
+| First-class built-in methods (`arr.map` as a value) | ✅ | exposed as *unbound* method values; a detached call throws like JS |
+| `fn.toString()` | ⚠️ | returns `function name() { [native code] }`, not the source text |
+| Classes: fields, methods, statics, getters/setters, `extends`/`super`, `instanceof` | ✅ | |
+| Constructor parameter properties `constructor(public x: T)` | ✅ | |
+| `#private` fields / methods / statics | ⚠️ | stored under a literal `#x` key; no access enforcement; parent/child name collisions may alias |
+| `enum` / `const enum` | ✅ | forward + reverse mapping |
+| `private` / `protected` / `public` / `readonly` / `abstract` / `implements` | — | erased, no access control |
+| Generators `function*`, `yield`, `yield*` | ✅ | `async` generators are not supported |
+| `arguments` object | ✅ | implicit; arrows see their own parameters |
+| Argument-count validation | 🚫 | never checked, though `fn.length` reports declared arity |
+
+## Async, Promises, event loop
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| `async` / `await`, `Promise`, `Promise.all` | ⚠️ | **synchronous microtask model** — `await` on a settled promise continues synchronously |
+| `setTimeout` and callbacks | ⚠️ | the event loop runs **after** the program body, so a promise settled from a timer cannot be awaited |
+| Sockets / servers (`http`, `net`, `dgram`) | ⚠️ | same model: callbacks run on the event loop after the program body |
+| A real async event loop, worker threads | 🚫 | not implemented |
+
+## Types: parsed, then erased
+
+**No type checking happens.** Type syntax is parsed into the AST and erased
+during binding/codegen:
+
+| Construct | Status |
+| --- | --- |
+| Type annotations, return types, type aliases, interfaces | — parsed, erased, never checked |
+| Generic type parameters and constraints | — no runtime instantiation |
+| `as`, `satisfies`, non-null `!` | — erased, no assertion semantics |
+| Optional-chaining type narrowing | 🚫 |
+| Diagnostics `TS4001`–`TS4004` (`TypeMismatch`, `NotCallable`, `PropertyNotFound`, `ArgumentCountMismatch`) | 🚫 defined but never emitted |
+
+A type error in your source is therefore not a compile error — only runtime
+behaviour is checked. Write the runtime code you mean.
+
+## Standard library
+
+Implemented: `Math`, `JSON`, `Date`, `RegExp`, `Map`, `Set`, `WeakMap`/`WeakSet`,
+`Symbol`, `Error` family, `BigInt`, `Array`/`String`/`Number`/`Object` methods,
+typed arrays, `String.prototype.match`/`split`/`replace` with capture groups,
+immutable array helpers (`toReversed`, `toSorted`, `toSpliced`, `with`), global
+URI functions.
+
+| Missing or different | Status |
+| --- | --- |
+| `String.prototype.normalize`, `structuredClone` | 🚫 |
+| `Error.stack` capture | 🚫 (not captured) |
+| `Object.getPrototypeOf({})` | ⚠️ returns `undefined`, not `Object.prototype` |
+| Global RegExp `lastIndex` | ⚠️ `test`/`exec` ignore it for `/g` and `/y` |
+| Sparse array holes, array out-of-bounds | ⚠️ holes are not tracked distinctly; out-of-bounds reads give `undefined` |
+
+See section 3 of [../unimplemented.md](../unimplemented.md) for the full list.
+
+## Modules
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| ESM `import` / `export` | ✅ | |
+| Relative multi-file bundling | ✅ | a `./helper.js` specifier resolves to `helper.ts` |
+| `import * as ns`, default and named imports | ✅ | |
+| Node built-in modules | ✅ | only with `--ext node` — see [extensions.md](./extensions.md) |
+| Bare third-party npm packages | 🚫 | `node_modules` ESM packages are bundled as source only when no extension claims the specifier |
+| `require()` / CommonJS | 🚫 | rejected with a hint to use `import` |
+| Circular dependencies | 🚫 | |
+| Live bindings | ⚠️ | imports and namespace members are snapshots |
+| `import.meta`, `__dirname`, `__filename` | 🚫 | |
+
+## Strings, numbers, memory
+
+| Item | Behaviour |
+| --- | --- |
+| `String.prototype.length` | ⚠️ **UTF-8 bytes**, not UTF-16 units: `"é".length === 1`, `"😀".length === 4`; `codePointAt` differs accordingly |
+| Number formatting and coercion | ✅ matches Node (`toFixed`, `toPrecision`, hex/octal/binary parsing) |
+| `BigInt` | ✅ implemented |
+| Garbage collection | ✅ non-moving mark-sweep; explicit roots plus a conservative C-stack scan; single-threaded and stop-the-world; no weak references |
+| Threads | 🚫 single-threaded; `worker_threads` exists in the Node extension only |
+
+## Platform
+
+Builds target macOS, Linux and Windows on x64 and arm64. On Windows the target
+is the **MSVC ABI**, so clang needs the MSVC/SDK environment — see
+[../requirements.md](../requirements.md). clang **16 or newer** is required.
+
+## Before you write a large program
+
+1. Skim the table for the features you plan to use; open
+   [../unimplemented.md](../unimplemented.md) for anything marked ⚠️ or 🚫.
+2. Prototype with `xbintsc emit app.ts` — the cheapest way to learn whether a
+   construct is supported, since it needs no clang.
+3. Run the real thing with `xbintsc run app.ts`. If a build fails, go to
+   [troubleshooting.md](./troubleshooting.md).
+4. When exact Node behaviour matters, run the same program under Node and
+   compare output; the project's own test suite does this differential check.

package/doc/ai/troubleshooting.md

@@ -0,0 +1,163 @@
+# Troubleshooting
+
+Start with the command that shows what xbintsc actually resolved:
+
+```bash
+xbintsc doctor
+```
+
+It prints the platform, the toolchain it will use (and where it came from), the
+compiler version, the runtime directory, the runtime library directory and the
+icon resource compiler. Most "it doesn't work" reports are answered here.
+
+## Before anything else: is clang new enough?
+
+**clang/LLVM 16 or newer is required.** Older clang rejects the emitted IR with a
+typed-pointer error:
+
+```
+D:\...\build\app.ll:382:37: error: '@.str.0' defined with type '[6 x i8]*' but expected 'i8*'
+  %r0 = call i64 @xt_string_new(i8* @.str.0, i64 5)
+```
+
+The compiler emits LLVM IR that relies on opaque pointers; typed pointers were
+removed in LLVM 16 ([LLVM release notes](https://github.com/llvm/llvm-project/blob/release/15.x/llvm/docs/ReleaseNotes.rst#changes-to-the-llvm-ir)).
+Confirm with `clang --version`; if the machine has an old system clang, install a
+newer LLVM and point xbintsc at it:
+
+```bash
+export xbintsc_CLANG=/usr/lib/llvm-18/bin/clang     # PowerShell: $env:xbintsc_CLANG = "C:\Program Files\LLVM\bin\clang.exe"
+```
+
+Note that front-end-only work (`xbintsc emit`) never needs clang, so it keeps
+working on an old toolchain.
+
+## Error messages and what they mean
+
+### `module '…' is provided by the 'node' extension; pass --ext node`
+
+The program imports a Node module but the extension is off. Add the flag, or put
+it in `xbintsc.config.json` so it is always on:
+
+```bash
+xbintsc run app.ts --ext node
+```
+
+### `module '<pkg>' is not supported: xbintsc can import built-in platform modules, relative '.ts' files and ESM packages under node_modules; CommonJS packages are not supported`
+
+A bare third-party import that nothing can link. Either the package is CommonJS
+(unsupported), or it is an ESM package that failed to bundle. Prefer a Node
+built-in from the `node` extension; see [extensions.md](./extensions.md) for
+what can actually be bundled.
+
+### ``CommonJS `require()` is not supported``
+
+Convert to ESM: `const fs = require("fs")` becomes `import fs from "fs"` (plus
+`--ext node`). `require` inside `node_modules` packages *is* handled by the
+bundler; it is only rejected in your own source. `require(<non-literal>)` is
+never supported.
+
+### `error TS4005: xbintsc does not yet support this <construct>`
+
+The syntax is parsed but codegen does not implement it. Check
+[language-support.md](./language-support.md) and
+[../unimplemented.md](../unimplemented.md), then rewrite the construct (or
+contribute support). `namespace` declarations and `new.target` are the common
+ones.
+
+### `error TS2xxx` (parser) or `error TS1xxx` (lexer)
+
+A syntax error in the source. The diagnostic prints the file, line, column, the
+offending line and a caret. Note that xbintsc's parser accepts most TypeScript,
+so a parse error usually means genuinely broken syntax rather than an
+unsupported feature.
+
+### `error TS6001: Cannot resolve module './x' from '<file>'` / `Cannot find module`
+
+A relative import that does not resolve. A `./helper.js` specifier maps to
+`helper.ts`, so import the runtime path you actually wrote in TypeScript.
+
+### `Cannot resolve module '…' required from '<file>'`
+
+A `require(...)` inside a bundled `node_modules` package that could not be
+resolved. The package is not usable as-is; prefer the built-in or a different
+dependency.
+
+### `xbintsc: <config path>: invalid JSON (…)` / `Unable to read …`
+
+The project config or a native extension manifest is malformed or missing. Fix
+the JSON, or bypass discovery with `--no-config` / `--config <path>`.
+
+### `error TS6003` / `Command failed (N): clang …`
+
+clang itself failed. The thrown message includes the full clang command and its
+stderr — read the stderr, not just the first line. Frequent causes:
+
+- the toolchain is too old (see above);
+- on Windows, clang cannot find the MSVC/SDK headers or libraries because the
+  environment was not imported. Run from an **x64 Native Tools Command Prompt
+  for VS 2022** (or **ARM64 Native Tools** on Windows on ARM), or import it
+  first:
+  ```powershell
+  & "$env:ProgramFiles\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
+  ```
+- the linker is wrong on Linux — set `xbintsc_CLANG` and/or pass
+  `xbintsc_LINKER_ARGS=-fuse-ld=lld`;
+- `No C compiler found. Set xbintsc_CLANG to a clang binary.` — no clang on
+  `PATH` at all.
+
+### `GUI native library not found at …`
+
+The `gui` extension needs its per-platform prebuilt `gui.a`/`gui.lib`, which is
+not built in a plain source checkout. Drop `--ext gui`, or build the archive as
+described in [../gui.md](../gui.md).
+
+### `Icon file not found` / icon tools missing
+
+`--icon`/`app.icon` paths resolve against the config file's directory. On
+Windows, embedding a PE icon needs `llvm-rc` or `windres`; `doctor` reports which
+one was found, and a missing one is only fatal when an icon was requested.
+
+## Build behaviour that looks wrong but is not
+
+### The build printed `(cached)` and did nothing
+
+The incremental cache matched: same source hash, compiler version, options,
+platform and extension set, with every output still present. That is the feature
+working. Force a rebuild with `--force`.
+
+### Stale output after changing a flag
+
+The object cache key deliberately excludes compiler flags, which is why scripts
+that change flags (such as runtime coverage) use a separate
+`xbintsc_CACHE_DIR`. If you suspect a stale artefact, pass `--force` or delete
+`.xbintsc/`.
+
+### `run` exits with a non-zero status but there is no error message
+
+`run` propagates the **program's** exit status; the compiler succeeded. Run it
+directly (`./build/app`) to see the program's own output.
+
+### `xbintsc: run requires --emit exe`
+
+`run` only executes executables. Use `build --emit ir` or `emit` to inspect IR.
+
+### Program output appears in an unexpected order
+
+`async`/`await` is a synchronous microtask model and the event loop only runs
+after the program body. Timer and socket callbacks therefore fire late; see
+[language-support.md](./language-support.md).
+
+## Where to look in the code
+
+| Symptom | Source |
+| --- | --- |
+| A diagnostic message or code | [../../src/diagnostics/diagnostic.ts](../../src/diagnostics/diagnostic.ts), emit sites under `src/` |
+| A missing feature | [../../src/codegen/](../../src/codegen/) — `UnsupportedFeature` is raised there |
+| An import that will not resolve | [../../src/driver/bundler/](../../src/driver/bundler/) |
+| clang invocation, linker flags | [../../src/driver/toolchain.ts](../../src/driver/toolchain.ts), [../../src/driver/toolchain-provider.ts](../../src/driver/toolchain-provider.ts) |
+| Cache behaviour | [../../src/driver/cache.ts](../../src/driver/cache.ts) |
+| Runtime crashes, GC, values | `runtime/*.c`, `runtime/rt.h` |
+
+If you are changing the compiler rather than using it, read
+[contributing.md](./contributing.md) next.

package/doc/ai/zh-CN/README.md

@@ -0,0 +1,56 @@
+# 面向 AI 的 xbintsc 使用指南
+
+**xbintsc 把 TypeScript 的一个子集直接编译成原生二进制。** 它自己解析
+TypeScript，把程序降级为 LLVM IR 文本，再调用 `clang` 链接一个小型 C 运行时
+（`runtime/`）产出独立可执行文件。产物里没有 Node.js，也没有 TypeScript 编译器。
+
+```
+source.ts --词法分析--> tokens --语法分析--> AST --绑定--> 绑定后的 AST
+          --代码生成--> module.ll --clang--> module.o --链接--> 可执行文件
+```
+
+本目录是**面向 AI、按任务组织**的文档层：刻意写得短，并指向更权威的文档。
+请只读你当前任务需要的那一篇，不要通读整个目录。
+
+| 页面 | 什么时候读 |
+| --- | --- |
+| [build-recipe.md](./build-recipe.md) | 要编译或运行一个程序，需要确切的命令形状 |
+| [cli.md](./cli.md) | 需要完整参数表、项目配置或编程 API |
+| [language-support.md](./language-support.md) | 必须确认某个语法/API 是否存在，或是否与 Node 一致 |
+| [extensions.md](./extensions.md) | 需要 `fs`/`http`/…、GUI，或 C++/Rust 库 |
+| [troubleshooting.md](./troubleshooting.md) | 报错了，要定位原因并修好 |
+
+如果你要改的是**这个仓库本身**（而不是用它编译程序），先读
+[../../AGENTS.md](../../../AGENTS.md)：那里讲了目录结构、构建门禁与改动规则。
+
+## 三个决定一切的事实
+
+1. **只有 TypeScript 的一个子集能编译。** 不支持的语法会被直接拒绝，而不是
+   近似实现。动手写大段代码之前先确认。
+2. **类型全部被擦除，从不做类型检查。** 类型注解、接口、泛型、`as`/`satisfies`、
+   非空断言 `!` 在运行时没有任何作用，也没有类型检查器会跑。只有真实的运行时
+   行为才算数。
+3. **Node 兼容是可选且不完整的。** Node 模块由 `node` 扩展提供（`--ext node`）；
+   不支持直接 import 第三方 npm 包。
+
+## 选一条命令
+
+```bash
+# 直接运行程序（先编译成临时二进制，再执行）
+xbintsc run app.ts
+
+# 产出独立二进制
+xbintsc build app.ts --out build          # -> build/app[.exe]
+
+# 查看会被编译的 LLVM IR
+xbintsc emit app.ts
+
+# 查看 xbintsc 解析到的工具链
+xbintsc doctor
+```
+
+在源码检出里，把 `xbintsc` 换成 `npx tsx src/cli/main.ts`（或
+`npm run xbintsc --`）。发布压缩包里的二进制不需要 Node.js。
+
+下一步：要命令就[build-recipe.md](./build-recipe.md)，要写正经程序就先看
+[language-support.md](./language-support.md)。

package/doc/ai/zh-CN/build-recipe.md

@@ -0,0 +1,132 @@
+# 构建配方
+
+常见任务的可直接复制命令，以及让构建成功的关键前提。完整参数见
+[cli.md](./cli.md)；命令报错见 [troubleshooting.md](./troubleshooting.md)。
+
+## 调用编译器
+
+| 场景 | 调用方式 |
+| --- | --- |
+| 已发布的独立压缩包 | `xbintsc …`（`bin/xbintsc[.exe]` 在 `PATH` 上） |
+| 源码检出，已编译 | `node dist/src/cli/main.js …` |
+| 源码检出，直接跑 TypeScript | `npx tsx src/cli/main.ts …` |
+| 源码检出，npm 脚本 | `npm run xbintsc -- …` |
+| 源码检出，bin 启动器 | `node bin/xbintsc.js …`（会自动回退到 `tsx`） |
+
+下文为简洁统一写作 `xbintsc`。
+
+## 运行程序
+
+```bash
+xbintsc run app.ts
+xbintsc run app.ts -- --flag value        # -- 之后的所有参数传给被运行的程序
+```
+
+`run` 先把程序编译成可执行文件，再以继承 stdio 的方式启动它。它要求
+`--emit exe`；`xbintsc run app.ts --emit ir` 是错误用法。`run` 的退出码就是被运行
+程序的退出码。
+
+## 构建独立二进制
+
+```bash
+xbintsc build app.ts                      # -> build/app（Windows 上是 build/app.exe）
+xbintsc build app.ts --out build/app      # 指定输出目录
+xbintsc build app.ts -o app.bin            # 或指定确切输出路径
+xbintsc build app.ts -O0                   # 优化级别：-O0 .. -O3（默认 -O2）
+xbintsc build app.ts --force               # 忽略增量缓存
+xbintsc build app.ts --verbose             # 输出进度
+```
+
+`build` 会打印产出的文件；如果增量缓存让本次构建无需干活，会额外打印
+`(cached)`：
+
+```
+xbintsc: wrote /abs/path/build/app
+```
+
+其他产出类型用于检查：
+
+```bash
+xbintsc build app.ts --emit ir   # 写出 app.ll
+xbintsc build app.ts --emit obj  # 写出 app.o
+```
+
+## 查看 LLVM IR
+
+```bash
+xbintsc emit app.ts > app.ll     # IR 输出到 stdout，不写任何文件
+```
+
+`emit` 不需要 clang，也不需要运行时库——它是确认"编译器到底理解了什么"最便宜
+的手段，也是不确定某个语法是否被支持时最快的反馈回路。
+
+## 能编译的程序形态
+
+```ts
+// app.ts —— ESM，不用 require()
+import { readFileSync } from "fs";          // 需要 `--ext node`
+
+function main(): void {
+  const text = readFileSync("package.json", "utf8");
+  console.log(text.length);
+}
+
+main();                                     // 顶层代码按顺序执行
+```
+
+- 使用 `import`/`export`；`require()` 会被拒绝。
+- 相对导入会被打包（`import { helper } from "./helper.js"` 会解析到
+  `helper.ts`）。
+- Node 内置模块用裸名（`fs`、`path`、`node:fs`），并且需要开启 `node` 扩展。
+
+## 项目配置：不带参数即可构建
+
+`xbintsc.config.json`（从入口文件所在目录向上查找，或用 `--config <path>` 指定，
+用 `--no-config` 关闭）承载构建选项，因此只敲 `xbintsc build` 就能工作。配置里的
+路径相对该配置文件解析，任何命令行参数都会覆盖对应字段。
+
+```json
+{
+  "entry": "src/app.ts",
+  "outDir": "build",
+  "optimize": "2",
+  "extensions": ["node"],
+  "app": { "name": "Demo", "icon": "assets/app.png" }
+}
+```
+
+机器可读的 schema 见 [../xbintsc.config.schema.json](../../xbintsc.config.schema.json)；
+完整字段表见 [cli.md](./cli.md)。
+
+## 带扩展编译
+
+只要 import 了 Node 模块，就必须开启对应扩展，否则编译失败。可一次开多个，用逗号
+分隔：
+
+```bash
+xbintsc run app.ts --ext node
+xbintsc run app.ts --ext node,gui
+```
+
+C++/Rust 库改用清单注册：
+
+```bash
+xbintsc run app.ts --ext-native ./mathx.manifest.json
+```
+
+两种扩展的编写方式都在 [extensions.md](./extensions.md)。
+
+## 编程 API
+
+写工具而不是写程序时：
+
+```ts
+import { build, compileString } from "xbintsc";
+
+const { ir } = compileString("console.log(1 + 1);");   // IR 文本，不需要 clang
+const result = build("program.ts", { emit: "exe", outDir: "build" });
+```
+
+`build` 返回 `{ outputPath, irPath?, cached, diagnostics, bundlePath? }`，可恢复的
+问题通过 `diagnostics` 报告；但工具链失败会**抛异常**。子路径导出
+`xbintsc/driver` 暴露驱动内部能力。