工具与 JSON
Sprig 只有一个命令行程序 sprig,所有功能都是它的子命令。它没有常驻后台的进程,连语言服务器也是一个子命令 sprig lsp,由编辑器自己启动。VS Code 里的支持见 VS Code 插件。
这页按 main 分支维护。当前发布的 v0.9.0-beta.1 包含这里列出的命令,包括 sprig build --bundle、sprig search、sprig publish 和 run --no-cache。安装版本的具体能力以 sprig capabilities --json 为准。
命令一览
写代码时最常用的:
| 命令 | 作用 |
|---|---|
sprig check [文件] | 只检查、不运行,一次列出所有错误 |
sprig run [文件] [-- 参数] | 检查、编译并运行,-- 后面的内容会传给程序 |
sprig test [路径] | 运行项目测试,可以用 --filter 按名字筛选 |
sprig build [文件] | 生成 Java 源码和 class 文件 |
sprig build --bundle [--archive] | 打出一个自带 Java 运行时的目录,没装 JDK 的机器也能运行,见下面 |
sprig fmt <文件或目录> | 格式化代码,加 --check 只检查、不修改 |
项目和依赖:
| 命令 | 作用 |
|---|---|
sprig init [目录] | 新建项目 |
sprig resolve | 解析依赖,写入 sprig.lock |
sprig add、sprig remove | 添加、删除依赖,见项目 |
sprig project | 查看项目信息 |
sprig deps | 列出声明的依赖 |
sprig search [文本] | 列出注册表里的包 |
sprig publish --registry 目录 ... | 在本地注册表目录里写入发布条目,见项目 |
查资料:
| 命令 | 作用 |
|---|---|
sprig explain <错误码> | 解释一个错误码:原因、修法、正反例 |
sprig codes | 列出所有错误码 |
sprig help [主题] | 语法速查;不带主题时会列出所有主题 |
sprig api <Java 类> | 查看一个 Java 类在 Sprig 里的签名 |
sprig api <模块.spr> | 查看一个 Sprig 模块对外提供哪些声明,以及每个声明上方写的注释 |
sprig capabilities | 查看当前编译器实现了哪些功能 |
sprig doctor | 检查 JDK 和编译器等环境 |
其他:
| 命令 | 作用 |
|---|---|
sprig wrap <Java 类> --out <文件> | 为 Java 类生成 Sprig 包装代码,见 JVM 互操作 |
sprig upgrade | 升级 SDK;加 --check 只看有没有新版本 |
sprig lsp | 给编辑器用的语言服务器,见语言服务器 |
sprig version | 显示版本号 |
在项目里,check、run、build 可以不写文件名,默认使用项目的入口。check、build、run、api、wrap 和 doctor 都能用 --classpath 加入本地的 JAR 或目录,可以写多次。这个参数只使用你给的路径,不会下载任何东西。
几个常用选项
check --syntax-only:check本来就不生成代码;加上这个选项更快,只检查词法、缩进和语法。run --keep:保留生成的 Java 文件,方便查看。run --no-cache:即使同一个程序之前跑过,也重新调用 javac。默认情况下run和test会把每个程序编译出的 class 文件留在~/.sprig/cache/javac下(保留最近的 64 个),键由生成的 Java、编译器和 Java 版本、运行时和 classpath 决定,所以再次运行没改过的程序会跳过 javac。真要调用 javac 时,它也只编译你的程序:运行时已经随 SDK 编译好,直接复制到你的 class 文件旁边。如果你用的 JDK 和构建 SDK 的不是同一个版本,第一次运行会把运行时编译一次,放进~/.sprig/cache/runtime。设置SPRIG_JAVAC_CACHE=off关闭程序的缓存,设成一个目录路径则换个位置。run --stacktrace:程序运行时出了没被捕获的错误,Sprig 会报SPR-RUNTIME-ERROR或SPR-RUNTIME-EXCEPTION,并指出是源码的哪一行;错误出在@std的函数里时,指的是你调用它的那一行。需要完整的 JVM 堆栈时,加上这个选项。build -d <目录>:build默认输出到sprig-build/,-d可以换个目录。检查没通过时不会生成 class 文件。build --emit-java-only:只做静态检查和生成 Java,不调用 javac。项目的类生成在sprig.user.<项目名>这个包里(项目名里 Java 包名不能用的字符换成_),项目之外的单个文件生成在sprig.user里。加--json时,结果里会有javaSources、mainClass、generatedPackage、runtimePackage和javacInvoked: false。build --emit-java-only --with-runtime:把运行时的 Java 源码也一起写出来,放在sprig.user.<项目名>.runtime,生成的代码就用这一份。这样得到的源码树可以交给别的构建工具单独编译,和同一个 JVM 里其他用 Sprig 构建的程序没有同名的类。Gradle 插件用的就是它。加--json时结果里多一项runtimeSources。build --bundle:在build的输出目录里再写一个<名字>/目录(名字是--bin、项目名或文件名),交给没装 Java 的人也能运行:bin/<名字>是 POSIX sh 启动器,bin/<名字>.cmd是 Windows 启动器;lib/里是程序的 jar、Sprig 运行时和锁文件里的全部 jar(Maven 依赖也在,按坐标命名);runtime/是用 jlink 从这些 jar 实际用到的模块做出来的 Java 运行时镜像,runtime/legal/里的 JDK 许可声明原样保留(OpenJDK 的 GPLv2 + Classpath Exception 允许连同声明一起分发)。启动器在你当前的目录里运行程序,原样转发参数和退出码,并把程序自己的类做成 class-data-sharing 归档放在用户缓存目录里,第二次启动更快。两个启动器的标准输出和标准错误都是 UTF-8(Windows 的旧控制台显示乱码时先chcp 65001);从别的程序启动bin\<名字>.cmd时直接传启动器路径和参数,不要套一层cmd /c再逐个加引号,那样 cmd.exe 会按它自己的规则去掉首尾的引号。打包时不会运行你的程序。镜像只能在构建它的操作系统和 CPU 架构上运行,命令输出会写明是哪个平台;要给别的平台就在那个平台上构建。加--archive会在旁边再写一个<名字>.zip,解压后启动器照样可执行。需要完整的 JDK:有jdeps和jlink,再加上jmods/目录,或者是 jlink 能直接取用的 JDK 24+ 运行时(Temurin 的 JDK 26 没有jmods/,也能用)。缺工具报SPR-BUNDLE-TOOLS,jdeps分析失败报SPR-BUNDLE-JDEPS,jlink 用不了这个 JDK 或者 jlink 失败报SPR-BUNDLE-LAYOUT,每个都带修法。详见 bundle 说明(英文)。
如果程序定义了 func main,但运行时没有输出,也没有任何顶层语句或其嵌套代码块调用 main,run 会给出提示;嵌套的 if、try 等代码块里的调用也会计入。
每个错误码的含义都可以用 sprig explain 查,完整列表见错误码(英文)。
JSON 输出
几乎每个命令都能加 --json。加了以后,标准输出里只有一个 JSON 文档,程序运行失败时也是这样。程序打印的内容放在 programOutput 里,错误放在 diagnostics 里,两者不会混在一起。从 v0.6.0-beta.1 开始,程序写到标准错误的内容放在 programErrorOutput 里;用 --json 运行时,程序读到的标准输入是空的。
成功运行一个打招呼的小程序:
{
"schemaVersion": 1,
"toolVersion": "sprig-compiler 0.9.0-beta.1",
"command": "run",
"exitCode": 0,
"programOutput": "Hello, Ada!\n",
"environment": {"classpath": []},
"diagnostics": []
}再看一个检查失败的例子。下面这段代码漏掉了 Square:
variant Shape:
Circle(radius: Float)
Square(side: Float)
func area(shape: Shape) -> Float:
return match shape:
case Shape.Circle as circle:
3.14159 * circle.radius * circle.radius普通输出是这样的:
SPR-MATCH-NONEXHAUSTIVE [FLOW] main.spr:6:12: Missing case: Shape.Square
hint: Add 'case Shape.Square:' (there is no default case)
1 error(s); run 'sprig explain <code>' for details on a diagnostic code.加上 --json 以后(uri 本来是完整的 file: 路径,这里缩短了):
{
"schemaVersion": 1,
"toolVersion": "sprig-compiler 0.9.0-beta.1",
"command": "check",
"exitCode": 1,
"environment": {"classpath": []},
"diagnostics": [
{
"code": "SPR-MATCH-NONEXHAUSTIVE",
"phase": "FLOW",
"severity": "error",
"uri": "file:///.../main.spr",
"range": {
"start": {"line": 5, "character": 11},
"end": {"line": 7, "character": 51}
},
"message": "Missing case: Shape.Square",
"hint": "Add 'case Shape.Square:' (there is no default case)",
"relatedHelp": "match",
"repair": {
"kind": "add-explicit-case-for-every-missing-case",
"machineApplicable": false
},
"related": [],
"suggestedEdits": []
}
]
}注意 JSON 里的行号和列号从 0 开始,所以 "line": 5, "character": 11 就是普通输出里的第 6 行第 12 列。relatedHelp 告诉你该看 sprig help 的哪个主题。提示归结为一处机械改写时——比如缺一行 import "@std/files.spr" as files,或者函数头要加 throws Error——suggestedEdits 会直接给出范围和替换文本,照着应用即可。在编辑器里,语言服务器会把同样的改写做成快速修复。
退出码的规则:
- 命令行参数写错,或者工具本身出错,返回
2。 - 源码错误和运行时错误,一般返回
1。 run会把程序自己的退出码原样传出来,所以程序主动退出时,也可能返回2或别的值。从 v0.6.0-beta.1 开始,程序用@std/process的process.exit指定退出码;同一个模块还有写标准错误的print_error,以及读标准输入的read_line、read_lines、read_all。文本模式只传回退出码,不附加编译器错误说明;JSON 模式会用SPR-PROGRAM-EXIT表示非零退出,程序的退出码记在data.programExitCode里。
给 AI 助手用
- 运行之前先跑
sprig check --json。它只做解析、名字和类型检查,不生成也不执行代码,是最快、最可靠的一道检查。 - 每个错误都带着固定的错误码和所属阶段:命令、项目和依赖的问题是
CLI,其余是LEX、SYNTAX、NAME、TYPE、FLOW、JVM、RUNTIME。源码里的错误有准确的位置,很多还带有hint,说明下一步该怎么改。 run --json把程序输出和错误分开,程序运行失败时也能拿到可以解析的结果。
完整的工作方式见和 AI 助手一起写代码。
格式化
sprig fmt 文件.spr 会直接格式化文件;sprig fmt --check . --json 只检查、不修改,适合放进 CI。格式化会保留注释,结果是确定的,没有配置项,也不会激进地折行。除了 fmt,其他命令都不会改动你的源码。详见格式化(英文)。
语言服务器
sprig lsp 通过标准输入输出说 Language Server Protocol(LSP),Neovim、Helix 这类编辑器可以直接用它,VS Code 插件也会自动启动它。它是 v0.6.0-beta.1 新加的。
它提供边写边报错、悬停提示、跳转到定义、查找引用、大纲、补全、格式化、局部变量和参数的重命名,以及快速修复:错误的改法是一处机械改写时,在编辑器里点一下就能改好。这些都来自和 sprig check 同一个编译器,所以编辑器里看到的和命令行永远一致。大多数语义查询需要能解析的源码;参数提示能处理暂时缺少右括号的调用。快速修复、参数提示和语义着色已包含在 v0.8.0-beta.1 中;未完成的调用可以获得参数提示,但其他语法错误仍可能让语义功能失效。
编辑器怎么配置、每项功能的细节,见语言服务器参考(英文)。
还没有的
下面这些都还在计划中,目前没有实现:
- 中心托管的包仓库(带账号和上传):现在的注册表是 Git 或本地目录里的索引,发布靠向
registry/开 pull request,见项目 - 增量检查
早期的设计提案见 Agent 工具协议(英文)。它只是历史提案,不代表现状。sprig api 能查到什么、查不到什么,见 JVM 互操作参考(英文)。
