企业官网建设流程全解析

如何转储Cangjie文件的AST树？CJASTHelper --dump-ast完全使用指南

【免费下载链接】CJASTHelperCangjie Abstract Syntax Tree Helper项目地址: https://gitcode.com/Cangjie-SIG/CJASTHelper

CJASTHelper（Cangjie Abstract Syntax Tree Helper，简称 cjah）是基于 Cangjie 开源编译器前端的 AST 操作工具，它的--dump-ast选项可以把任意 Cangjie 源文件（.cj）的 AST 树以纯文本形式转储到文件，方便新手观察编译器如何"理解"你的代码。本指南带你在 3 步内完成第一次 AST 转储。

为什么需要查看 AST 树？

AST（Abstract Syntax Tree，抽象语法树）是编译器把源码解析后得到的树形结构：每一个变量、函数、表达式都对应树上一个节点。

对新手来说，转储 AST 有三个直接好处：

• 🧭理解代码结构：看看for循环、泛型函数在编译器眼中变成了什么样的节点树；
• 🐛定位语法问题：当语义报错令人困惑时，AST 文本能帮你确认"编译器到底把哪段代码解析成了什么"；
• 📚学习编译器原理：AST 是理解编译前端最直观的素材，比凭空想象容易得多。

小知识：--dump-ast输出的是parse（语法解析）之后、语义分析之前的 AST，即纯语法层面的树结构，因此无需配置输出类型即可使用。

准备工作：获取并构建 cjah

cjah 依赖 Cangjie SDK（编译器前端libcangjie-lsp），需要先构建。快速路径如下（完整步骤见 README.md 与 doc/usage.md）：

# 1. 准备环境（Cangjie 源码路径 + 前端环境变量） export CANGJIE_SRC_HOME=${xxx}/cangjie_compiler source ${yyy}/cangjie/envsetup.sh # 2. 构建（Linux/macOS） bash build.sh -t Release -b

构建完成后，可执行文件位于build/bin/cjah（Windows 为cjah.exe）。

三步转储你的第一个 AST 文件

第 1 步：创建输出目录

--dump-ast要求目标目录必须已存在：

mkdir -p ast_out

第 2 步：执行转储命令

./build/bin/cjah --dump-source=parse --dump-ast=ast_out main.cj

参数说明：

第 3 步：查看输出文件

产物为ast_out/main.cj.ast—— 文件名取源文件全名加.ast后缀：

cat ast_out/main.cj.ast

文件内容是一棵缩进的节点树，每个节点标注了类型（如函数声明、变量、表达式），可以直观看到源码的层级结构。

输出约定与命名规则

了解以下约定，可以少走弯路：

• 📁输出位置：<dump-ast 路径>/<源文件名>.ast，例如main.cj → ast_out/main.cj.ast；
• 📁目录必须预先存在，cjah 不会自动创建；
• 📄包模式（-p）下：目录包中的每个.cj文件各自生成一份.ast文件。

相关实现可参考 src/core/AstHelper.cpp 中的DumpAst()与 src/wrapper/Wrapper.cpp 中的节点打印逻辑。

与其他选项的组合用法

配合宏展开控制

如果代码里用了宏，可以先用--dump-source=macro查看宏展开后的源码，再用--dump-ast对照 AST；没有宏时可加--enable-macro=false跳过宏展开提速：

# 无宏场景，跳过宏展开 ./build/bin/cjah --dump-source=parse --dump-ast=ast_out --enable-macro=false main.cj

以包目录为输入

用透传的 cjc 选项-p把整个包交给前端，包内每个源文件都会生成一份 AST：

./build/bin/cjah --dump-source=parse --dump-ast=ast_out -p <pkg-dir>

与纯语法检查的区别

--check-syntax=true只做语法检查并提前结束，会跳过 AST 转储，两者不要混用：

# 语法检查（不产生 .ast 文件） ./build/bin/cjah --check-syntax=true main.cj

常见问题速查（FAQ）

Q1：提示打开输出文件失败？检查--dump-ast后的目录是否已创建、路径拼写是否正确。

Q2：为什么建议同时传--dump-source=parse？不带任何阶段选项时 cjah 会打印帮助信息；--dump-ast本身不隐含阶段，需配合--dump-source触发前端解析管线。

Q3：输出目录和--output-dir是什么关系？--dump-ast自带独立目录；--output-dir是透传给前端、用于源码打印等产物的目录，二者互不影响。

Q4：sema 阶段的源码打印需要额外参数吗？需要。sema/desugared-sema阶段要透传--output-type=dylib，但--dump-ast走 parse 阶段，无此要求。

更多资源

• 完整选项与阶段说明：doc/usage.md
• 架构与阶段管线设计：doc/design.md
• 选项定义（dump-ast注册处）：config/valid_options.json
• 参数解析入口：src/core/ArgHelper.cpp

掌握--dump-ast后，你可以继续探索--dump-source的多阶段源码打印，甚至用 Pass 插件管线做自定义 AST 分析，把 CJASTHelper 变成你的 Cangjie 编译前端调试利器。

【免费下载链接】CJASTHelperCangjie Abstract Syntax Tree Helper项目地址: https://gitcode.com/Cangjie-SIG/CJASTHelper