Wing 云编程语言本地开发指南:从环境搭建到编译器调试的完整工作流
Wing 云编程语言本地开发指南:从环境搭建到编译器调试的完整工作流
本篇技术指南面向希望参与 Wing 项目开发的贡献者,系统讲解如何在本地构建、测试与调试这个云编程语言仓库。你将掌握完整的环境准备步骤、Turbo 驱动的 monorepo 构建体系、端到端测试与性能基准的运行方法,以及单独面向 Rust 编译器(wingc)、tree-sitter 语法、VSCode 扩展的专项开发工作流,最终能够独立完成从"克隆仓库"到"提交可验证改动"的全过程。
环境准备:构建 Wing 仓库所需的最小工具集
Wing 仓库的构建涉及 Node.js(CLI 与 SDK)、Rust(编译器 wingc)与 WASM(编译器运行时)三条技术栈,因此在动手前需要准备好以下工具。下表按"必需 / 按需"区分,并注明各自的用途:
| 工具 | 版本要求 | 必需性 | 用途 |
|---|---|---|---|
| [Node.js] | v20(推荐) | 必需 | 运行 CLI、SDK 及全部 TypeScript 代码,建议用 volta 管理版本 |
| [PNPM] | v8(推荐) | 必需 | monorepo 包管理器,根目录的 packageManager 字段固定为 pnpm@8.15.1 |
| [Rust] | 1.82+(推荐) | 必需 | 编译 wingc 编译器,建议用 rustup 管理,注意避免与 Homebrew 安装的 Rust 冲突 |
| [AWS CLI] | 任意兼容版本 | 仅集成测试 | 执行需要真实云资源的集成测试,需先完成凭证配置 |
| [Terraform CLI] | 任意兼容版本 | 仅集成测试 | 用于生成与验证 Terraform 后端产物 |
| [Docker] | 任意兼容版本 | 部分必需 | 将语法构建为 WASM(供 Web 端 playground 使用)并运行部分单元测试 |
对于 Windows 用户,官方建议在 WSL 中搭建工具链:仓库中的部分脚本依赖 Unix 工具链,并不支持 Windows 原生环境。完成安装后,可以按以下方式验证版本(任何兼容版本均可):
$ node --version
v20.17.0
$ pnpm --version
8.15.1
$ rustc --version
rustc 1.82.0 (f6e511eec 2024-10-15)
克隆与安装:构建仓库的第一步
安装流程非常简洁,在仓库根目录依次执行克隆、进入目录、安装依赖三步:
git clone https://github.com/winglang/wing
cd wing
pnpm install
根目录的 package.json 中隐藏着三个值得注意的细节:
preinstall脚本执行npx only-allow pnpm,强制使用 pnpm 安装,防止误用 npm/yarn 破坏 monorepo 依赖结构;install脚本会执行bash scripts/setup_wasi.sh,首次pnpm install因此可能耗时较长——脚本会为你下载并安装 wasi-sdk(当前脚本固定版本为 24.0)以及 binaryen 的wasm-opt工具,用于将 Wing 编译为 WASM 目标;postinstall会执行link-bundles与generate-workspace,负责链接工作区内的本地包并生成工作区配置。
如果你希望手动安装 WASM 工具链,也可以随时单独运行仓库根目录下的 scripts/setup_wasi.sh。该脚本会自动识别 Linux/macOS 与 x86_64/arm64 架构,将工具下载到仓库内的 .cargo 目录。
理解 Turbo 命令约定
Wing 仓库使用 Turbo 在 monorepo 的多个包之间编排任务。文档中的 Turbo 命令统一采用两种结构:
turbo <task>
# 或
turbo <task> -F <project> -- <args>
需要掌握的几个约定:
- 若 Turbo 未全局安装,可用
pnpm turbo代替(根 package.json 已把turbo@^2声明为依赖); -F <project>用于把任务过滤到某个具体项目及其依赖项;- 在某个项目目录内直接运行
turbo <task>,会自动过滤到该项目; - Turbo 使用构建缓存加速重复构建,若希望强制全量重建,追加
--force即可。
根目录的 turbo.json 定义了各任务的依赖关系与输入输出:例如 test 任务依赖 compile,输出包含 **/__snapshots__/** 与 **/*.snap(快照文件);wing:e2e 任务依赖 hangar#test,wing:bench 任务依赖 hangar#bench。理解这些定义,有助于判断改动能触发哪些下游任务。
完整构建:一键复现 CI 流程
如果你希望执行一次与 CI 完全一致的完整构建,在仓库根目录运行:
pnpm build
根 package.json 中 build 脚本实际指向 projen build,它会依次完成编译、Lint、测试与打包全部模块。CI 使用的 test:ci 脚本则进一步串起了 turbo default、compile、post-compile、lint、eslint、test 与 test:playwright 等任务(--concurrency 1 顺序执行并排除 hangar)。
推荐的日常开发工作流:pnpm wing
日常迭代时,你大概率会高频使用 pnpm wing 命令。它在根 package.json 中定义为:
turbo compile -F winglang --output-logs=new-only && ./packages/winglang/bin/wing
也就是说,它先通过 Turbo 只编译发生变更的组件,再调用 Wing CLI。这样你就可以在改动任意一层的源码后,直接用带参数的 CLI 验证行为,例如:
pnpm wing -- test tests/valid/captures.test.w
该命令会以完整 Wing CLI 运行给定参数,Turbo 保证 CLI 构建始终是最新的。
获取完整诊断信息:调试 Rust 侧问题时,建议先导出以下两个环境变量,以获得完整的堆栈回溯:
export NODE_OPTIONS=--stack-trace-limit=100
export RUST_BACKTRACE=full
直接调用本地 CLI 二进制:当需要跳过 Turbo 反复验证本地改动时,可以先只编译 winglang 包:
npx turbo compile -F winglang
然后直接运行 CLI 二进制(入口脚本见 packages/winglang/bin/wing,它仅负责 require("../dist/cli.js") 加载编译产物):
./packages/winglang/bin/wing
更高效的做法是在 shell 的 rc 文件中创建一个别名,例如:
alias mywing=/<PATH_TO_WING_REPO>/packages/winglang/bin/wing
之后即可用 mywing 随时调用你本地构建的 Wing CLI。
仓库结构:monorepo 布局一览
Wing 仓库是一个典型的 monorepo:包含多个独立发布的包,绝大部分位于 packages 目录下,每个包自带 README 说明其功能与用法。所有包通过 Turbo 统一编排任务,共同构成完整工具链——编译器(@winglang/wingc,Rust)、标准库(@winglang/sdk)、CLI(winglang)、语法(@winglang/tree-sitter-wing)、IDE 扩展(vscode-wing)、端到端测试套件(tools/hangar)等,构建与发布流程由这些包共同协作完成。
Turbo 在根目录执行 pnpm install 后随项目依赖一并安装,可通过 pnpm turbo 访问。
运行端到端测试:hangar 测试套件
端到端测试托管在 tools/hangar(名字取自机库/仓库之意)。开始前请确保 Wing 可以正常构建。在 monorepo 任意位置执行:
turbo wing:e2e
这是 turbo test -F hangar 的快捷写法。hangar 的 package.json 显示其 test 脚本为 vitest run --update,即运行测试的同时更新快照。
运行单个测试:与前面一致,从仓库根目录用 wing test 并指向具体测试文件:
pnpm wing -- test tests/valid/optionals.test.w
说明:原文档中引用的测试路径为
examples/tests/valid,当前仓库已将测试语料迁移至根目录的 tests/valid(合法用例)、tests/invalid(非法用例,验证编译必须失败)与 tests/sdk_tests(SDK 行为测试),请以当前目录结构为准。
测试元注释(Test Meta-Comments)
在合法测试语料(如 tests/valid)的 .w 文件中,可以添加一段特殊格式的注释,为 hangar 提供额外控制信息。注释内部嵌有一段会被解析的 YAML 块,例如:
/*\
skipPlatforms:
- win32
- darwin
\*/
当前常规测试唯一支持的元注释键是 skipPlatforms,用于在 CI 上跳过指定平台(可选值为 win32、darwin、linux)。例如某个测试依赖 Docker,而 CI 中只有 Linux 支持 Docker,就可以用它排除 macOS/Windows runner。
实现层面,该逻辑位于 tools/hangar/src/meta_comment.ts:parseMetaComment 用正则 ^\/\*\\\n(.+)\\\*\/$ 提取注释内的 YAML 文本并调用 YAML.parse,shouldSkipTest 则在 metadata.skipPlatforms 包含当前平台且 process.env.CI 为真时跳过测试。值得注意的是,该文件还定义了 cases(每个测试的编译目标与最大平均耗时)、skip(全环境跳过)与 env、args 等其他元注释字段,说明测试框架对更细粒度控制已有预留。
性能基准测试
基准测试文件位于 tests/valid/benchmarks,当前包含 hello_world、functions_1、functions_10、jsii_small、jsii_big、empty 等用例。运行方式(monorepo 任意位置):
turbo wing:bench
这是 turbo bench -F hangar 的快捷写法,实际执行 vitest bench --run 并通过 tools/hangar/src/benchmarking/compare_script.ts 对比结果。在 CI 中(见 .github/workflows/build.yml 的 benchmark job),若基准相比 main 分支回归幅度过大(环境变量 BENCH_FAIL_THRESHOLD_PERCENT 设为 25,即超过 25% 的劣化会使构建失败),构建将直接失败,以守住性能底线。
只改编译器:wingc 的测试、编译与 Lint
当你的改动集中在编译器时,可以完全绕开 Node 层,直接驱动 wingc:
turbo test -F @winglang/wingc
该命令运行 wingc 的 Rust 测试(packages/@winglang/wingc/package.json 中 test 即 cargo test),包括验证合法用例可以编译、非法用例编译失败,以及所有用例都不会 panic,并自动更新快照。
在单个文件上运行编译(从仓库根目录执行):
pnpm wing -- compile <path to a .w file (full path, or relative to the location of the packages/winglang folder)>
编译产物可在 packages/winglang/target 目录中查看。wingc 同时提供了独立的 Rust 示例程序 packages/@winglang/wingc/examples/compile.rs,可通过 cargo run --example compile <source_file> 直接编译源码文件并把诊断信息按行号排序输出到 stderr,适合在无 Node 环境下快速验证。
Lint 检查:
turbo lint -F @winglang/wingc
编译器开发的 VSCode 扩展配置
- 安装 rust-analyzer 扩展后,将设置项
"Rust-analyzer › Check: Command"从check改为clippy,即可在 IDE 中直接显示 clippy 错误; - 安装 insta 扩展,可以在测试文件中可视化浏览快照(insta 是 wingc 测试使用的快照工具,CI 的 globalDependencies 中也包含
insta.yaml)。
在 VSCode 中调试 Wing 编译器
要调试 Rust 编译器,首先安装 CodeLLDB 扩展。仓库自带 .vscode/launch.json,其中已提供 Debug Wing Compiler 启动配置:它会以 LLDB 附加到 cargo build --example compile 进程,并把当前打开的文件作为编译参数传入。
操作步骤:打开你想调试编译过程的 .w 文件(例如 tests/valid/hello.test.w),按下 F5 即可开始调试。同文件还内置了若干实用配置:wing compile tf-aws、wing compile tf-azure、wing compile sim、wing test sim、wing test tf-aws(均为 node-terminal 类型)以及用于调试扩展本身的 Debug Extension。
修改 Wing 语法(tree-sitter)
Wing 的语法定义位于 packages/@winglang/tree-sitter-wing/grammar.js(配套 C 扫描器在 src/scanner.c)。修改 grammar.js 后依次执行:
turbo compile -F @winglang/tree-sitter-wing
运行语法测试(测试语料位于 test/corpus):
turbo test -F @winglang/tree-sitter-wing
如需在浏览器中探索 AST 并验证高亮查询(需要先构建 WASM 版本的语法),运行:
turbo playground -F @winglang/tree-sitter-wing
该包的 package.json 同时提供了 build:wasm(tree-sitter build-wasm --docker,即需要 Docker 的原因之一)与 test:watch、build:watch 等便捷脚本。语法包通过 queries/highlights.scm 提供 source.wing 作用域高亮,这也是 VSCode 扩展语法高亮的来源。
构建 VSCode 扩展
VSCode 扩展位于 packages/vscode-wing,其大部分"逻辑"在语言服务器(LSP)中实现,而 LSP 实现在 Wing CLI 的 packages/winglang/src/commands/lsp.ts 内——该文件加载编译为 WASM 的 wingc(wingCompiler.load),并通过 send_diagnostic 回调把编译器吐出的诊断信息转发为 LSP 诊断,实现类型检查能力的复用。
编译扩展(同时生成可安装的 .vsix 文件):
turbo compile -F vscode-wing
按 packages/vscode-wing/turbo.json 的 package 任务定义,最终产物会输出到仓库根目录的 dist/vscode-wing.vsix。
启动一个安装了该扩展的隔离 VSCode 实例:
turbo dev -F vscode-wing
若需修改扩展的 package.json(发布元信息等),应编辑 .projenrc.ts 并重新构建——扩展由 projen 管理,直接手改 package.json 会在下次构建时被覆盖。
开发小贴士:需要在代码中打印调试信息时,Rust 侧应使用 dbg! 宏而非 print!/println!,以便输出附带文件名与行号、便于定位。
代码 Lint
对 Rust 代码执行 Lint 目标(wingc 或 wingii 两个项目均支持):
turbo lint -F @winglang/wingc
也可以直接运行 cargo clippy。wingc 的 lint 脚本实际执行 cargo fmt && cargo clippy --fix --no-deps --allow-dirty --target wasm32-wasi --release,即先格式化、再以 wasm32-wasi 目标运行 clippy 并自动修复。若希望在 IDE 中实时显示 Lint 错误,在 VSCode 设置中加入:
// in your VS Code settings
"rust-analyzer.check.command": "clippy",
为 wing CLI 添加 quickstart 模板
Wing CLI 的 wing new 命令支持从模板初始化项目。每个模板由 packages/winglang/project-templates 下的一个文件夹表示,文件夹内包含该模板初始化所需的全部文件。当前仓库已内置 wing(原生语言)与 typescript 两种语言方向,其中 wing 方向包含 empty、http-api、private-api、react-vite、slack 五个模板。
添加新模板的步骤:在 packages/winglang/project-templates 下以模板名新建文件夹,放入模板运行所需的全部代码文件即可。运行 turbo test(或提交 PR 后在 GitHub Actions 中)触发的单元测试会自动校验新模板的合法性——模板会被实际初始化并验证其能够通过编译。
模板机制的底层实现在 packages/winglang/src/commands/init.ts,理解它有助于写出合规的模板:
- 模板清单由
projectTemplateNames()动态枚举(见 packages/winglang/src/util.ts,PROJECT_TEMPLATES_DIR指向packages/winglang/project-templates); - 支持
--language wing|typescript参数与--list-templates列出模板,未指定模板时通过 inquirer 交互式选择; - 复制模板前会检查目标目录中是否已存在同名文件(防止覆盖);复制后会替换
package.json中的#WING_VERSION#占位符——开发版本(版本号以0.0.0开头)会改为指向本地工作区的file:依赖,便于本地联调; - 随后自动执行
npm install并提示后续可用wing compile、wing it、wing test继续开发。
以 http-api 模板 为例,模板主体是一个 cloud.Api 加 inflight 路由处理器,并内置两个 test 块验证 POST /greet/:name 与带 all-caps 查询参数的响应——新模板可以参照这种"资源 + 内联测试"的组织方式,确保模板开箱即测。
通过以上工作流,你可以从零搭建 Wing 的开发环境,并针对编译器、语法、扩展、测试与模板等不同子系统各取所需地开展贡献。回顾全文要点:环境层面依托 Node v20 + PNPM v8 + Rust + Docker 四件套;日常迭代以 pnpm wing 与 turbo -F 组合驱动增量构建;验证层面由 turbo wing:e2e(hangar 端到端)与 turbo wing:bench(性能基准)兜底;深层调试则可借助 CodeLLDB 直接附加 Rust 编译器。掌握这套流程后,从提交代码到通过 CI 验证的道路将变得清晰而顺畅。