Wing 云编程语言本地开发指南:从环境搭建到编译器调试的完整工作流

原创2026-10-12 18:36:251,869 阅读
文章标签:编程语言编译器云原生语言运行时

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 验证的道路将变得清晰而顺畅。

登录后查看全文
wing