命令行参考

CLI 共有四个命令。scriptc --help 打印的就是下面这份接口。

$ scriptc --help
scriptc：将 TypeScript/JavaScript 编译为原生与 WebAssembly 可执行文件（实验性）

Usage:
  scriptc build <file.ts|.js> [options]     编译为可执行文件或源码产物
  scriptc run <file.ts|.js> [options]       编译并运行
  scriptc coverage <file.ts|.js>            统计可静态编译的比例，以及不能的原因
  scriptc coverage <file.ts|.js> --dynamic  查看 --dynamic 构建能编译什么、还有什么在阻碍
  scriptc coverage <file.ts|.js> --external-types <specifier=file.d.ts>
                                            为分析而类型解析嵌入方提供的模块
  scriptc cache warm [runtime|tls|dynamic…] 为当前编译器/SDK/目标预构建开销大的原生缓存族

scriptc build

把 TypeScript（或 JavaScript）入口文件编译为序列化的带类型 IR、可读的 C、文本形式的 LLVM IR、原生汇编、可重定位目标文件、原生可执行文件；选择 wasm32-wasi 目标时则编译为 WebAssembly 模块。程序会先经过类型检查，由真正的 TypeScript 编译器完成，并遵循最近的 tsconfig.json。任何没有 lowering 的构造都会成为编译错误，带有 SC 前缀的错误码、代码帧，通常还附带重写提示。

$ scriptc build fib.ts -o fib
$ ./fib
832040

不带 -o 时，主产物落在输入文件旁边的 .scriptc/ 目录中。源码级输出有固定的后缀，并在原生编译之前停止：

$ scriptc build fib.ts --emit=ir >/dev/null
$ ls .scriptc/
fib.ir.json
$ scriptc build fib.ts --emit=c >/dev/null
$ ls .scriptc/
fib.c
fib.ir.json
$ scriptc build fib.ts --emit=llvm >/dev/null
$ ls .scriptc/
fib.c
fib.ir.json
fib.ll
$ scriptc build fib.ts --emit=asm >/dev/null
$ ls .scriptc/
fib.c
fib.ir.json
fib.ll
fib.s
$ scriptc build fib.ts --emit=obj >/dev/null
$ ls .scriptc/
fib.c
fib.ir.json
fib.ll
fib.o
fib.s

不同类型的产物会累积在 .scriptc/ 目录中；重新构建某一类型会更新对应的文件。

三种源码级输出只需要 Node。在 macOS 15 及以上、arm64 架构上，汇编和对象输出使用随 scriptc 安装的匹配原生辅助程序，不会调用外部编译器、归档器、链接器或 SDK。产出的对象文件是带有未定义 scr_* 运行时符号和必需的 scr_runtime_abi_v1 标记的可重定位程序对象，不是独立的库。外部消费仍处于实验阶段，且要求使用 --print=native-link-info 报告的确切运行时版本。该选项仍会写出对象文件，不执行链接，并打印一份带版本的 JSON 配方，其中包含目标平台、main 入口、已安装的源码运行时包、FFI 输入以及系统库。它绝不会报告 scriptc 的私有缓存路径。完整的 C 驱动与直接调用链接器的示例参见 原生程序对象。--emit=exe 是默认值。在 macOS 15 及以上、arm64 架构上，LLVM 层构建通过辅助程序产出程序对象，并链接以 release 构建的运行时目标文件；显式 C 构建、LLVM 回退构建和 sanitizer 构建仍会编译运行时 C。

scriptc run

先执行 build，再运行生成的二进制，stdio 直接继承。对于 wasm32-wasi，CLI 通过 Node 的 WASI Preview 1 宿主启动模块，把当前工作目录预挂载为 /，并把宿主机的 /tmp 暴露为客户机的 /tmp。

$ scriptc run fib.ts
832040

注意：run 不会把多余的命令行参数转发给程序。若要传参，请先 build 出可执行文件，再直接调用它。

scriptc coverage

分析程序但不产出二进制，逐语句报告哪些可以静态编译、哪些需要内嵌的动态引擎、哪些完全被阻碍。加上 --dynamic 则回答另一个问题：--dynamic 构建能编译什么，还有什么在阻碍。两种形态都会在 覆盖率报告 中详细讲解。

scriptc cache warm

为那些仍在本地编译运行时 C 的目标，预构建 release 运行时对象以及原生 TLS/动态引擎归档。macOS 15 及以上、arm64 的安装已自带以 release 构建的运行时包，会跳过自动预热；更早的 macOS 宿主仍保留面向源码工具链路径的预热。在为其他受支持的目标准备容器镜像或 CI runner 时使用此命令。传入 runtime、tls、dynamic 中的一个或多个，可只为这些族播种缓存。

选项

环境变量

$ SCRIPTC_CC=zigcc SCRIPTC_TARGET=aarch64-linux-gnu.2.36 scriptc build fib.ts -o fib-linux
$ file fib-linux
fib-linux: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 2.0.0, with debug_info, not stripped

后端

默认后端产出文本形式的 LLVM IR。在受支持的平台上，它由内置辅助程序降级为目标文件，并与匹配的预编译运行时包一起链接；SCRIPTC_LINKER 独立于 C 编译，控制平台链接驱动。超出 LLVM 层范围的程序绝不会被错误编译：原生构建会透明地回退到 C 后端，并在 stderr 输出一行说明。生产用的 wasm32-wasi 目标使用 LLVM 的 32 位 ABI 路径，从不回退；LLVM 覆盖缺口会成为一条构建诊断信息。动态 npm 内嵌在所有目标上都属于 LLVM 层面。

若要在 Xcode 或 LLDB 中设置源码断点，请用 --optimization=dev 构建。在 Xcode 自定义构建规则中，把该选项加到 scriptc build 调用里，并把可执行文件及其 .dSYM 包都列为输出。将 .dSYM 包保持在可执行文件旁边，并让原始源码文件保留在构建时的路径上。LLVM 和 C 后端都会跨导入模块保留源码位置。

C 后端是一个调试辅助：它刻意产出可读的、带源码行注释的输出，并在两者重叠之处与 LLVM 做差分测试。当你想检查程序变成了什么时，可以钉住它：

$ scriptc build fib.ts --backend c -o fib
$ ./fib
832040
$ head -1 fib.c
/* Generated by scriptc from fib.ts. Do not edit. */

显式的 --backend llvm 会钉住 LLVM 后端：遇到本应回退的情况时，它不再回退，而是以诊断信息 SC3001 失败并指明不受支持的构造。这适合那些必须察觉层级变化的 CI 通道。

工具要求