开发工具CLI代码质量【免费下载链接】cangjie_tools仓颉编程语言命令行工具包括仓颉包管理工具、仓颉格式化工具、仓颉多语言桥接工具及仓颉语言服务。项目地址https://gitcode.com/Cangjie/cangjie_tools点击查看免费下载cjheadCangjie Head是 cangjie_tools 仓库中负责生成仓颉头文件的命令行工具它扫描仓颉源文件仅保留对外可见的声明剥离函数体与实现细节输出对应的头文件cj.d。本文以 cjhead/doc/developer_guide.md 为主线系统讲解 cjhead 的导出规则、代码目录结构、命令行参数与两种编译构建方式并结合仓库源码FileHandler.cpp、HeadFileVisitor.cpp 等深入剖析其底层实现原理帮助开发者理解该工具如何工作、如何构建以及如何在二次开发或集成中正确使用。图cjhead 整体软件架构设计图见 cjhead/figures/cjhead软件架构.png一、项目定位什么是 cjheadCJHead(Cangjie Head)是仓颉 header file 生成工具扫描仓颉源文件生成对应头文件 cj.d。其作用类似于 C/C 生态中的头文件导出将源文件中“对外可见的 API 骨架”单独提取出来形成不包含实现体的声明文件供其他模块或工具链消费。从源码结构看cjhead 的实现路径非常清晰入口 main.cpp 构造FileHandler解析命令行参数后调用Run()FileHandler负责目录遍历、参数解析、package 模式下的文件合并与最终输出FileHandler.cppCJHeadCompilerInstance继承仓颉编译器的CompilerInstance将源码编译到SEMA语义分析阶段得到带注释信息的 ASTCJHeadCompilerInstance.cppHeadFileVisitor基于 AST 遍历节点按导出规则裁剪不可见声明、清空函数体生成头文件内容HeadFileVisitor.cpp格式化环节复用仓库内独立的cjhead/fmt子目录一套基于 AST 的代码格式化组件将裁剪后的 AST 重新序列化为规范文本见 src/CMakeLists.txt 中对该目录源文件的收集。二、源码目录结构cjhead 源码目录的主要构成及其职责如下与 developer_guide.md 中目录说明对应cjhead/ |-- build # 构建脚本build.py 一键构建 |-- config # 配置文件config.ini |-- doc # 介绍文档 |-- fmt # 格式化工具独立复用的 AST 格式化组件 |-- include # 头文件 |-- src # 源码其中核心源文件与职责文件职责src/main.cpp程序入口转换 argv、解析参数、执行生成流程src/FileHandler.cpp参数解析、目录递归遍历、package 模式合并、exclude 正则过滤、文件输出src/HeadFileVisitor.cppAST 访问器按导出规则裁剪声明、清空函数体、收集注释/注解/importsrc/CJHeadCompilerInstance.cpp封装编译器实例编译至 SEMA 阶段获取源包 ASTsrc/CJHeadCompilerInvocation.cpp配置编译选项CANGJIE_HOME、importPaths、compilePackage 等src/CJHeadUtil.cpp工具函数获取注释 Token、路径校验、帮助信息输出三、导出规则什么会进 cj.dcjhead 的核心价值在于“导出规则”只有对外可见、可被其他包/模块引用的声明才会出现在头文件中。规则按声明类别划分如下以下规则完整继承自原文档并在每条后补充源码实现佐证。3.1 Package无修饰符的 package默认 publicpublic 修饰的 packageprotected package 里面按下述规则对外可见的 API且该 API 在其他 public 包内被 public import。源码层面HeadFileVisitor::VisitPackage会输出package fullPackageName行宏包则额外带macro前缀HeadFileVisitor.cppstd::string package_info (package-isMacroPackage ? macro : ); package_info package package-fullPackageName \n;3.2 Import无修饰符的 importpublic importprotected/internal/private import。VisitPackage同时会逐个保留当前文件的 import 语句含 import 前的注释并利用SourceManager截取 import 的原始源码区间保证import xxx as yyy这类写法原样进入头文件。3.3 Macropublic 修饰的全局 macro。源码中对应VisitMacroDecl保留宏声明的签名同时清空宏的函数体HeadFileVisitor.cpp。3.4 Class / Struct / Enum / Interfacepublic/sealed 修饰的 classpublic 修饰的 structpublic 修饰的 enumpublic/sealed 修饰的 interface。源码实现要点HeadFileVisitor.cpp所有类型声明都会剔除继承类型列表中的Objectinherited_types.erase(... x-ToString() Object)避免导出无意义的基类class 的成员先按“public 或open/abstract 且 protected”过滤再剔除编译器自动生成的成员TestAttr(Attribute::COMPILER_ADD)如编译器合成的initstruct/enum 仅保留 public 成员interface 的成员则无条件遍历interface 中无修饰符成员默认即 public通过from_interface true传递。3.5 Variablepublic 修饰的全局变量public class/struct 中 public 修饰的成员变量sealed class 中 public 修饰的成员变量public(但非 sealed) open/abstract class 的 protected 成员变量因为在子类中可见。源码中VisitVarDecl会跳过编译器自动生成的变量COMPILER_ADD成员过滤逻辑与 3.4 一致。3.6 Type Aliaspublic 修饰的全局类型别名。VisitTypealiasDecl记录类型别名信息内容、行号、是否出现、关联注释用于在公开 API 中引用时保留HeadFileVisitor头部维护了typealias_to_content_、typealias_to_line_、typealias_to_appear_、typealias_to_comment_四张静态表来追踪别名使用情况HeadFileVisitor.h。3.7 Functionpublic 修饰的全局函数public/sealed 修饰的 class/struct/interface/enum 中的 public 修饰的成员函数public/sealed interface 中无修饰符的成员函数interface 中无修饰符 publicpublic(但非 sealed) open/abstract class 的 protected 修饰的成员函数因为在子类中可见。源码中VisitFuncDecl的关键动作是清空函数体——将funcBody中 block 的 body 置空HeadFileVisitor.cpp从而实现“只留签名、不留实现”OwnedPtrBlock func_block func_body-body; if (func_block) func_block-body std::vectorOwnedPtrNode();此外GetSignature会利用GetContentBetween(decl-begin, func_block-leftCurlPos)截取函数签名文本HeadFileVisitor.cpp。3.8 Propertypublic/sealed class/struct/interface/enum 中的 public 修饰的成员 proppublic/sealed interface 中无修饰符成员 propinterface 中无修饰符 publicpublic(但非 sealed) open/abstract class 的 protect 修饰的成员 prop因为在子类中可见。源码中VisitPropDecl将 getter/setter 列表清空prop_decl-getters ...; prop_decl-setters ...保留 prop 声明本身HeadFileVisitor.cpp。3.9 Extendextend 的 public 成员extend 与被扩展类型在同一个包无论是否是接口扩展被扩展类型是 public 的扩展的泛型约束里用到的类型是 public 的extend 的 public 成员extend 是接口扩展接口与被扩展的类型不在同一个包被扩展类型是 public 的接口是 public 的扩展的泛型约束中用到的类型也是 public 的且该成员继承自被扩展的 public 接口extend 的 protected 成员extend 与被扩展类型在同一个包无论是否是接口扩展被扩展类型是 public(但非 sealed) open/abstract class扩展的泛型约束里用到的类型是 public 的。源码中VisitExtendDecl有一套去重逻辑若被扩展类型本身已被裁剪记录在function_map中则将该 extend 整体标记进removed_extend最终在Run()末尾统一移除HeadFileVisitor.cpp否则按“public 或 abstract 类的 protected”过滤成员后逐个访问。3.10 Comment Annotation单行注释、多行注释可见声明对应的注解。实现上CJHeadCompilerInvocation构造时即开启enableAddCommentToAst确保注释挂接到 AST 节点CJHeadCompilerInvocation.cppVisitFirstComment会保留文件首行首列的头部注释HeadFileVisitor.cppGetAnnotationString将声明上的注解含Deprecated[...]等参数原样导出HeadFileVisitor.cpp。3.11 Macro Expansion宏展开的函数。VisitMacroExpandDecl会递归访问宏展开产生的真实声明并借助FindCommentsInMacroCall把宏调用上下文中的注释回填到展开后的声明上保证宏展开函数的文档注释不丢失HeadFileVisitor.cpp。3.12 可见性判定的源码落点导出规则最终由HeadFileVisitor的可见性判断函数落实IsPublic存在public或sealed修饰符即为 publicEXTEND_DECL恒视为 publicMACRO_EXPAND_DECL递归判断其展开的真实声明HeadFileVisitor.cppIsProtected/IsPrivate分别检测protected/private修饰符IsAbstractOrOpen检测open/abstract但遇sealed直接返回 falseHeadFileVisitor.cpp与“sealed class 不导出 protected 成员”的规则一致。Run()的顶层流程是先移除所有非 public 的顶层声明再遍历访问剩余声明HeadFileVisitor.cpp。四、命令行参数与使用示例cjhead 的命令行参数在 CJHeadUtil.cpp 的PrintHelp中定义运行时直接通过 FileHandler.cpp 的option_map_解析$ ./bin/cjhead -h Usage: cjhead [OPTION...] OPTION: -i, Input directory -o, Output directory(default: .\) -p, Enable package mode, save all content in one package to one file --import-path, Cjo path to scan --macro-path, Macro path to resolve the macro --exclude, Config file describe files not to scan -h, Print help各参数说明与源码行为参数含义源码行为FileHandler.cpp-i输入目录也可以是单个文件CheckPath校验存在性若为普通文件则取其所在目录作为扫描根L102-L111-o输出目录默认当前目录单文件模式下输出路径为输出目录 相对路径 .d自动创建缺失目录L379-L396-p开启 package 模式同包所有 cj 文件合并输出为一个fullPackageName.cj.d文件L280-L288--import-path需要扫描的 Cjo 路径通过SetImportPath追加到globalOptions.importPaths帮助正确识别依赖L61-L64--macro-path宏定义文件路径同上追加进 importPaths用于正确解析宏--exclude描述不扫描文件的配置文件每行作为一个正则regex_search命中即跳过L124-L146-h打印帮助直接输出帮助并返回典型运行方式cjhead -i Input Dir -o Output Dir -p --import-path Your CJO Path --macro-path Your Macro path其中-p表示开启 package 模式此时所有位于相同包下的 cj 文件会被整合到一个 cjd 文件中--import-path指定 cjo 文件的位置能够帮助 cjhead 正确识别 cj 文件的依赖信息--macro-path指定宏定义文件的位置能够帮助 cjhead 正确地识别并解析宏。示例 1class 导出输入/** * Rectangle */ public class Rectangle { // width let width: Int64 let height: Int64 /** * Rectangle::init */ public init(width: Int64, height: Int64) { this.width width this.height height } /** * Rectangle::area */ public func area() { width * height } }输出函数体被移除仅保留签名与注释// width这类普通行内注释不进入头文件/** * Rectangle */ public class Rectangle { /** * Rectangle::init */ public init(width: Int64, height: Int64) /** * Rectangle::area */ public func area() }示例 2interface 与带注解的全局函数导出输入/** * The Digest interface */ public interface Digest { prop size: Int64 prop blockSize: Int64 prop algorithm: String func write(buffer: ArrayByte): Unit func finish(to!: ArrayByte): Unit func finish(): ArrayByte { let buf ArrayByte(size, repeat: 0) this.finish(to: buf) return buf } func reset(): Unit } /** * The function is to calculate the digest of data * * param algorithm - digest type * param data - data to be digested * * return message-digested data */ Deprecated[message: Use global function public func digestT(algorithm: T, input: InputStream): ArrayByte where T : Digest instead.] public func digestT(algorithm: T, data: String): ArrayByte where T : Digest { digest(algorithm, data.toArray()) }输出interface 中有实现的finish()也只保留签名注解被保留并规范格式化/** * The Digest interface */ public interface Digest { prop size: Int64 prop blockSize: Int64 prop algorithm: String func write(buffer: ArrayByte): Unit func finish(to!: ArrayByte): Unit func finish(): ArrayByte func reset(): Unit } /** * The function is to calculate the digest of data * * param algorithm - digest type * param data - data to be digested * * return message-digested data */ Deprecated[ message: Use global function public func digestT(algorithm: T, input: InputStream): ArrayByte where T : Digest instead. ] public func digestT(algorithm: T, data: String): ArrayByte where T : Digest两个示例来自 cjhead/doc/user_guide.md可结合上文导出规则自行验证let width/let height等非 public 成员被过滤Deprecated注解与文档注释被完整保留。五、编译构建cjhead 的构建依赖仓颉编译器cangjie本体它会复用仓颉的编译器库libcangjie-lsp来完成词法、语法、语义分析并生成带注释的 AST见 CMakeLists.txt 与 src/CMakeLists.txt 中对${CANGJIE_ROOT}/build/build/lib/libcangjie-lsp.a的链接。因此构建前必须先准备好 cangjie 的源码与构建产物。5.1 基于源代码构建第一步下载并编译 cangjie将其置于third_party/cangjie下git clone your cangjie repo ./third_party/cangjie cd ./third_party/cangjie ./build.py build --no-tests --cjnative -t release --enable-assert ./build.py install source ./output/envsetup.sh第二步编译 cjhead在 cjhead 源码根目录下执行mkdir output cd output cmake .. make构建产物输出在output目录下的bin即output/bin/cjhead。需要说明的是CMakeLists.txt 在检测不到${CANGJIE_ROOT}/build时还会自动触发一次./build.py build --no-js --no-tests --llvmgc -t ${CMAKE_BUILD_TYPE}即 cmake 阶段也具备一定的自举构建能力。5.2 基于构建脚本构建仓库提供了build/build.py一键构建脚本执行python build/build.py该脚本build.py的完整流程为读取并校验 cjhead/config/config.iniload_configL15-L64若third_party/cangjie不存在则按配置的repo/branch自动git cloneensure_cangjie_installedL122-L133构建并安装 cangjiebuild_cangjieL135-L148随后提示source abs/output/envsetup.sh清理并重建build目录执行cmake ..与make -j32最后对build/bin/cjhead执行strip --strip-all去掉符号build_cjheadL150-L168。配置文件内容如下对应原文档中的完整示例[project] # 构建环境的根目录 root ./ [cangjie] # repo of cangjie. repo Your Cangjie repo # branch of cangjie repo. branch dev [paths] # 拷贝的 cangjie repo 存储路径 cangjie_dir third_party/cangjie # build 产物的存储路径 build_dir build cangjie_build_script build.py envsetup_sh output/envsetup.sh cjhead_src_dir third_party [build] # 是否在构建时开启 test 模式 no_tests true # 是否在构建时开启 cjnative 模式 cjnative true # 是否在构建时开启 debug 模式 target debug # 是否在构建时开启 assert enable_assert true各节参数含义与脚本的对应关系配置项说明脚本中的使用build.py[project] root构建环境根目录脚本会将其解析为绝对路径并校验可写L25-L56所有相对路径的基准[cangjie] repocangjie 仓库地址无本地仓库时git clone -b branch repoL125[cangjie] branchcangjie 仓库分支同上[paths] cangjie_dir拷贝的 cangjie repo 存储路径CANGJIE_DIRL70[paths] build_dircjhead 构建产物目录cmake .. make的工作目录L71、L158-L159[paths] cangjie_build_scriptcangjie 构建脚本名默认build.pyL72[paths] envsetup_shcangjie 环境脚本路径构建完成后提示sourceL146[paths] cjhead_src_dircjhead 源码目录CJHEAD_SRC_DIRL74[build] no_tests构建 cangjie 时是否跳过测试追加--no-testsL81-L82[build] cjnative是否开启 cjnative 模式追加--cjnativeL83-L84[build] targetdebug/release 目标追加-t targetL85[build] enable_assert是否开启 assert追加--enable-assertL86-L87补充说明仓库当前 cjhead/config/config.ini 的实际取值与文档示例略有差异root ../、build_dir output、cjnative false、target release、enable_assert false使用时以仓库内实际配置文件为准可按需修改后重新执行python build/build.py。5.3 运行前提CANGJIE_HOME无论采用哪种方式构建运行 cjhead 都要求环境变量CANGJIE_HOME指向 cangjie 的安装目录。CJHeadCompilerInvocation::SetCangjieHome会从环境变量中读取该值并解析为绝对路径若缺失会直接报错退出if (environment_vars.find(CANGJIE_HOME) environment_vars.end()) { std::cerr can not find CANGJIE_HOME, please setup CANGJIE_HOME\n; exit(1); }并以此设置globalOptions.executablePath为CANGJIE_HOME/bin/cjcLinux或CANGJIE_HOME/bin/cjc.exeWindowsCJHeadCompilerInvocation.cpp。因此手动构建方式下执行source ./output/envsetup.sh正是为了完成CANGJIE_HOME的初始化。六、核心流程源码级解读6.1 参数解析与目录遍历FileHandler::ParseArgumentsFileHandler.cpp完成参数解析后Run()调用TraverseAllFiles递归遍历输入目录对目录节点先调用HandlePackage处理当前目录视为一个 package再递归子目录对文件节点若命中--exclude正则则跳过否则为每个文件创建CJHeadCompilerInvocationCJHeadCompilerInstance编译至CompileStage::SEMA再对每个源文件执行裁剪与输出。值得注意的是单文件遍历路径中同时调用了SetImportPath(import_path_)与SetImportPath(macro_path_)L177-L178即将宏路径与 cjo 路径都注入编译器 importPaths——这与--import-path、--macro-path两个参数的语义一致。6.2 package 模式的文件合并开启-p后HandlePackageFileHandler.cpp会将同包所有裁剪后的文件收集到pruned_files然后MergeFiles把后续文件的decls追加到首文件import 通过import_set去重后统一合并并调用SortImports按 import 首词排序FileHandler.cpp最终输出到output_dir / (full_package_name .cj.d)。6.3 头文件版权头HandleSingleFileFileHandler.cpp在输出正文前会尝试读取可执行文件同级目录resources/COPYRIGHT.txt若存在且非空则将其作为版权头拼接到生成内容之前copyright_content \n formatted_content。这解释了为什么构建产物通常需要附带 resources 目录。6.4 格式化链路裁剪后的 AST 通过FormatCodeProcessor来自cjhead/fmt子目录的TransformAstToText重新序列化FileHandler.cpp。cjhead/fmt复用了完整的格式化组件DocProcessor文档处理器、NodeFormatter按 Decl/Expr/Node/Pattern/Type 分类的节点格式化器以及CommentHandler、TomlParser等见 cjhead/fmt/include/Format 与 cjhead/fmt/src/Format因此 cj.d 输出的排版与仓颉代码风格保持一致。七、常见问题与注意事项必须先构建 cangjiecjhead 链接libcangjie-lsp.a并依赖其 AST/词法器/诊断引擎脱离 cangjie 产物无法独立编译src/CMakeLists.txt。CANGJIE_HOME必须设置否则运行即报can not find CANGJIE_HOME。--exclude是正则文件文件内每行一个正则表达式regex_search命中即跳过该文件无效正则会在解析时打印invalid regex提示FileHandler.cpp。输出路径规则非 package 模式下输出文件为输入文件的相对路径追加.d后缀如foo.cj→foo.cj.d并自动创建中间目录FileHandler.cpppackage 模式下为包名.cj.d。源码研究入口理解导出规则建议从 HeadFileVisitor.h 的访问器清单入手VisitClassDecl、VisitFuncDecl、VisitExtendDecl等一一对应导出规则各小节理解构建链路则从 build.py 与 CMakeLists.txt 入手。结语cjhead 通过“编译到 SEMA → 按可见性规则裁剪 AST → 清空实现体 → 格式化重排”的流水线将仓颉源文件浓缩为对外可见的cj.d头文件。本文从导出规则、命令行使用到源码实现与构建配置完整还原了 cjhead/doc/developer_guide.md 的技术骨架并结合仓库源码给出了可验证的实现依据。开发者既可参照构建章节快速产出可执行文件也可沿 cjhead/src 目录深入研读各访问器的具体裁剪逻辑为二次开发或集成提供参考。赞分享开发工具CLI代码质量【免费下载链接】cangjie_tools仓颉编程语言命令行工具包括仓颉包管理工具、仓颉格式化工具、仓颉多语言桥接工具及仓颉语言服务。项目地址https://gitcode.com/Cangjie/cangjie_tools点击查看免费下载相关推荐大型仓颉项目进阶实战用cjhead实现多包依赖管理与头文件自动化构建大型仓颉项目进阶实战用cjhead实现多包依赖管理与头文件自动化构建 cjhead 是一款面向仓颉语言Cangjie的命令行构建工具专为大型多包项目打造标准库仓颉格式化工具 cjfmt 开发者指南架构原理、源码构建与命令行实践仓颉格式化工具 cjfmt 开发者指南架构原理、源码构建与命令行实践 本文围绕 cangjie_tools 仓库中 cjfmt 模块 开发者指南 https开发工具CLI代码质量kubernetes-ingress 仓库开发导航NGINX Ingress Controller 的架构、构建测试与代码生成规范kubernetes ingress 仓库开发导航NGINX Ingress Controller 的架构、构建测试与代码生成规范 本文面向希望深入 kubeAPI网关云原生负载均衡可观测性微服务上一篇Home Assistant 中 Insteon 的 Print All-Link Database 操作读取与排查设备链接数据库下一篇GeoLibre 数据集成全指南云目录、自托管目录、Web 服务与多后端地理编码实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
开发工具CLI代码质量【免费下载链接】cangjie_tools仓颉编程语言命令行工具包括仓颉包管理工具、仓颉格式化工具、仓颉多语言桥接工具及仓颉语言服务。项目地址https://gitcode.com/Cangjie/cangjie_tools点击查看免费下载cjheadCangjie Head是 cangjie_tools 仓库中负责生成仓颉头文件的命令行工具它扫描仓颉源文件仅保留对外可见的声明剥离函数体与实现细节输出对应的头文件cj.d。本文以 cjhead/doc/developer_guide.md 为主线系统讲解 cjhead 的导出规则、代码目录结构、命令行参数与两种编译构建方式并结合仓库源码FileHandler.cpp、HeadFileVisitor.cpp 等深入剖析其底层实现原理帮助开发者理解该工具如何工作、如何构建以及如何在二次开发或集成中正确使用。图cjhead 整体软件架构设计图见 cjhead/figures/cjhead软件架构.png一、项目定位什么是 cjheadCJHead(Cangjie Head)是仓颉 header file 生成工具扫描仓颉源文件生成对应头文件 cj.d。其作用类似于 C/C 生态中的头文件导出将源文件中“对外可见的 API 骨架”单独提取出来形成不包含实现体的声明文件供其他模块或工具链消费。从源码结构看cjhead 的实现路径非常清晰入口 main.cpp 构造FileHandler解析命令行参数后调用Run()FileHandler负责目录遍历、参数解析、package 模式下的文件合并与最终输出FileHandler.cppCJHeadCompilerInstance继承仓颉编译器的CompilerInstance将源码编译到SEMA语义分析阶段得到带注释信息的 ASTCJHeadCompilerInstance.cppHeadFileVisitor基于 AST 遍历节点按导出规则裁剪不可见声明、清空函数体生成头文件内容HeadFileVisitor.cpp格式化环节复用仓库内独立的cjhead/fmt子目录一套基于 AST 的代码格式化组件将裁剪后的 AST 重新序列化为规范文本见 src/CMakeLists.txt 中对该目录源文件的收集。二、源码目录结构cjhead 源码目录的主要构成及其职责如下与 developer_guide.md 中目录说明对应cjhead/ |-- build # 构建脚本build.py 一键构建 |-- config # 配置文件config.ini |-- doc # 介绍文档 |-- fmt # 格式化工具独立复用的 AST 格式化组件 |-- include # 头文件 |-- src # 源码其中核心源文件与职责文件职责src/main.cpp程序入口转换 argv、解析参数、执行生成流程src/FileHandler.cpp参数解析、目录递归遍历、package 模式合并、exclude 正则过滤、文件输出src/HeadFileVisitor.cppAST 访问器按导出规则裁剪声明、清空函数体、收集注释/注解/importsrc/CJHeadCompilerInstance.cpp封装编译器实例编译至 SEMA 阶段获取源包 ASTsrc/CJHeadCompilerInvocation.cpp配置编译选项CANGJIE_HOME、importPaths、compilePackage 等src/CJHeadUtil.cpp工具函数获取注释 Token、路径校验、帮助信息输出三、导出规则什么会进 cj.dcjhead 的核心价值在于“导出规则”只有对外可见、可被其他包/模块引用的声明才会出现在头文件中。规则按声明类别划分如下以下规则完整继承自原文档并在每条后补充源码实现佐证。3.1 Package无修饰符的 package默认 publicpublic 修饰的 packageprotected package 里面按下述规则对外可见的 API且该 API 在其他 public 包内被 public import。源码层面HeadFileVisitor::VisitPackage会输出package fullPackageName行宏包则额外带macro前缀HeadFileVisitor.cppstd::string package_info (package-isMacroPackage ? macro : ); package_info package package-fullPackageName \n;3.2 Import无修饰符的 importpublic importprotected/internal/private import。VisitPackage同时会逐个保留当前文件的 import 语句含 import 前的注释并利用SourceManager截取 import 的原始源码区间保证import xxx as yyy这类写法原样进入头文件。3.3 Macropublic 修饰的全局 macro。源码中对应VisitMacroDecl保留宏声明的签名同时清空宏的函数体HeadFileVisitor.cpp。3.4 Class / Struct / Enum / Interfacepublic/sealed 修饰的 classpublic 修饰的 structpublic 修饰的 enumpublic/sealed 修饰的 interface。源码实现要点HeadFileVisitor.cpp所有类型声明都会剔除继承类型列表中的Objectinherited_types.erase(... x-ToString() Object)避免导出无意义的基类class 的成员先按“public 或open/abstract 且 protected”过滤再剔除编译器自动生成的成员TestAttr(Attribute::COMPILER_ADD)如编译器合成的initstruct/enum 仅保留 public 成员interface 的成员则无条件遍历interface 中无修饰符成员默认即 public通过from_interface true传递。3.5 Variablepublic 修饰的全局变量public class/struct 中 public 修饰的成员变量sealed class 中 public 修饰的成员变量public(但非 sealed) open/abstract class 的 protected 成员变量因为在子类中可见。源码中VisitVarDecl会跳过编译器自动生成的变量COMPILER_ADD成员过滤逻辑与 3.4 一致。3.6 Type Aliaspublic 修饰的全局类型别名。VisitTypealiasDecl记录类型别名信息内容、行号、是否出现、关联注释用于在公开 API 中引用时保留HeadFileVisitor头部维护了typealias_to_content_、typealias_to_line_、typealias_to_appear_、typealias_to_comment_四张静态表来追踪别名使用情况HeadFileVisitor.h。3.7 Functionpublic 修饰的全局函数public/sealed 修饰的 class/struct/interface/enum 中的 public 修饰的成员函数public/sealed interface 中无修饰符的成员函数interface 中无修饰符 publicpublic(但非 sealed) open/abstract class 的 protected 修饰的成员函数因为在子类中可见。源码中VisitFuncDecl的关键动作是清空函数体——将funcBody中 block 的 body 置空HeadFileVisitor.cpp从而实现“只留签名、不留实现”OwnedPtrBlock func_block func_body-body; if (func_block) func_block-body std::vectorOwnedPtrNode();此外GetSignature会利用GetContentBetween(decl-begin, func_block-leftCurlPos)截取函数签名文本HeadFileVisitor.cpp。3.8 Propertypublic/sealed class/struct/interface/enum 中的 public 修饰的成员 proppublic/sealed interface 中无修饰符成员 propinterface 中无修饰符 publicpublic(但非 sealed) open/abstract class 的 protect 修饰的成员 prop因为在子类中可见。源码中VisitPropDecl将 getter/setter 列表清空prop_decl-getters ...; prop_decl-setters ...保留 prop 声明本身HeadFileVisitor.cpp。3.9 Extendextend 的 public 成员extend 与被扩展类型在同一个包无论是否是接口扩展被扩展类型是 public 的扩展的泛型约束里用到的类型是 public 的extend 的 public 成员extend 是接口扩展接口与被扩展的类型不在同一个包被扩展类型是 public 的接口是 public 的扩展的泛型约束中用到的类型也是 public 的且该成员继承自被扩展的 public 接口extend 的 protected 成员extend 与被扩展类型在同一个包无论是否是接口扩展被扩展类型是 public(但非 sealed) open/abstract class扩展的泛型约束里用到的类型是 public 的。源码中VisitExtendDecl有一套去重逻辑若被扩展类型本身已被裁剪记录在function_map中则将该 extend 整体标记进removed_extend最终在Run()末尾统一移除HeadFileVisitor.cpp否则按“public 或 abstract 类的 protected”过滤成员后逐个访问。3.10 Comment Annotation单行注释、多行注释可见声明对应的注解。实现上CJHeadCompilerInvocation构造时即开启enableAddCommentToAst确保注释挂接到 AST 节点CJHeadCompilerInvocation.cppVisitFirstComment会保留文件首行首列的头部注释HeadFileVisitor.cppGetAnnotationString将声明上的注解含Deprecated[...]等参数原样导出HeadFileVisitor.cpp。3.11 Macro Expansion宏展开的函数。VisitMacroExpandDecl会递归访问宏展开产生的真实声明并借助FindCommentsInMacroCall把宏调用上下文中的注释回填到展开后的声明上保证宏展开函数的文档注释不丢失HeadFileVisitor.cpp。3.12 可见性判定的源码落点导出规则最终由HeadFileVisitor的可见性判断函数落实IsPublic存在public或sealed修饰符即为 publicEXTEND_DECL恒视为 publicMACRO_EXPAND_DECL递归判断其展开的真实声明HeadFileVisitor.cppIsProtected/IsPrivate分别检测protected/private修饰符IsAbstractOrOpen检测open/abstract但遇sealed直接返回 falseHeadFileVisitor.cpp与“sealed class 不导出 protected 成员”的规则一致。Run()的顶层流程是先移除所有非 public 的顶层声明再遍历访问剩余声明HeadFileVisitor.cpp。四、命令行参数与使用示例cjhead 的命令行参数在 CJHeadUtil.cpp 的PrintHelp中定义运行时直接通过 FileHandler.cpp 的option_map_解析$ ./bin/cjhead -h Usage: cjhead [OPTION...] OPTION: -i, Input directory -o, Output directory(default: .\) -p, Enable package mode, save all content in one package to one file --import-path, Cjo path to scan --macro-path, Macro path to resolve the macro --exclude, Config file describe files not to scan -h, Print help各参数说明与源码行为参数含义源码行为FileHandler.cpp-i输入目录也可以是单个文件CheckPath校验存在性若为普通文件则取其所在目录作为扫描根L102-L111-o输出目录默认当前目录单文件模式下输出路径为输出目录 相对路径 .d自动创建缺失目录L379-L396-p开启 package 模式同包所有 cj 文件合并输出为一个fullPackageName.cj.d文件L280-L288--import-path需要扫描的 Cjo 路径通过SetImportPath追加到globalOptions.importPaths帮助正确识别依赖L61-L64--macro-path宏定义文件路径同上追加进 importPaths用于正确解析宏--exclude描述不扫描文件的配置文件每行作为一个正则regex_search命中即跳过L124-L146-h打印帮助直接输出帮助并返回典型运行方式cjhead -i Input Dir -o Output Dir -p --import-path Your CJO Path --macro-path Your Macro path其中-p表示开启 package 模式此时所有位于相同包下的 cj 文件会被整合到一个 cjd 文件中--import-path指定 cjo 文件的位置能够帮助 cjhead 正确识别 cj 文件的依赖信息--macro-path指定宏定义文件的位置能够帮助 cjhead 正确地识别并解析宏。示例 1class 导出输入/** * Rectangle */ public class Rectangle { // width let width: Int64 let height: Int64 /** * Rectangle::init */ public init(width: Int64, height: Int64) { this.width width this.height height } /** * Rectangle::area */ public func area() { width * height } }输出函数体被移除仅保留签名与注释// width这类普通行内注释不进入头文件/** * Rectangle */ public class Rectangle { /** * Rectangle::init */ public init(width: Int64, height: Int64) /** * Rectangle::area */ public func area() }示例 2interface 与带注解的全局函数导出输入/** * The Digest interface */ public interface Digest { prop size: Int64 prop blockSize: Int64 prop algorithm: String func write(buffer: ArrayByte): Unit func finish(to!: ArrayByte): Unit func finish(): ArrayByte { let buf ArrayByte(size, repeat: 0) this.finish(to: buf) return buf } func reset(): Unit } /** * The function is to calculate the digest of data * * param algorithm - digest type * param data - data to be digested * * return message-digested data */ Deprecated[message: Use global function public func digestT(algorithm: T, input: InputStream): ArrayByte where T : Digest instead.] public func digestT(algorithm: T, data: String): ArrayByte where T : Digest { digest(algorithm, data.toArray()) }输出interface 中有实现的finish()也只保留签名注解被保留并规范格式化/** * The Digest interface */ public interface Digest { prop size: Int64 prop blockSize: Int64 prop algorithm: String func write(buffer: ArrayByte): Unit func finish(to!: ArrayByte): Unit func finish(): ArrayByte func reset(): Unit } /** * The function is to calculate the digest of data * * param algorithm - digest type * param data - data to be digested * * return message-digested data */ Deprecated[ message: Use global function public func digestT(algorithm: T, input: InputStream): ArrayByte where T : Digest instead. ] public func digestT(algorithm: T, data: String): ArrayByte where T : Digest两个示例来自 cjhead/doc/user_guide.md可结合上文导出规则自行验证let width/let height等非 public 成员被过滤Deprecated注解与文档注释被完整保留。五、编译构建cjhead 的构建依赖仓颉编译器cangjie本体它会复用仓颉的编译器库libcangjie-lsp来完成词法、语法、语义分析并生成带注释的 AST见 CMakeLists.txt 与 src/CMakeLists.txt 中对${CANGJIE_ROOT}/build/build/lib/libcangjie-lsp.a的链接。因此构建前必须先准备好 cangjie 的源码与构建产物。5.1 基于源代码构建第一步下载并编译 cangjie将其置于third_party/cangjie下git clone your cangjie repo ./third_party/cangjie cd ./third_party/cangjie ./build.py build --no-tests --cjnative -t release --enable-assert ./build.py install source ./output/envsetup.sh第二步编译 cjhead在 cjhead 源码根目录下执行mkdir output cd output cmake .. make构建产物输出在output目录下的bin即output/bin/cjhead。需要说明的是CMakeLists.txt 在检测不到${CANGJIE_ROOT}/build时还会自动触发一次./build.py build --no-js --no-tests --llvmgc -t ${CMAKE_BUILD_TYPE}即 cmake 阶段也具备一定的自举构建能力。5.2 基于构建脚本构建仓库提供了build/build.py一键构建脚本执行python build/build.py该脚本build.py的完整流程为读取并校验 cjhead/config/config.iniload_configL15-L64若third_party/cangjie不存在则按配置的repo/branch自动git cloneensure_cangjie_installedL122-L133构建并安装 cangjiebuild_cangjieL135-L148随后提示source abs/output/envsetup.sh清理并重建build目录执行cmake ..与make -j32最后对build/bin/cjhead执行strip --strip-all去掉符号build_cjheadL150-L168。配置文件内容如下对应原文档中的完整示例[project] # 构建环境的根目录 root ./ [cangjie] # repo of cangjie. repo Your Cangjie repo # branch of cangjie repo. branch dev [paths] # 拷贝的 cangjie repo 存储路径 cangjie_dir third_party/cangjie # build 产物的存储路径 build_dir build cangjie_build_script build.py envsetup_sh output/envsetup.sh cjhead_src_dir third_party [build] # 是否在构建时开启 test 模式 no_tests true # 是否在构建时开启 cjnative 模式 cjnative true # 是否在构建时开启 debug 模式 target debug # 是否在构建时开启 assert enable_assert true各节参数含义与脚本的对应关系配置项说明脚本中的使用build.py[project] root构建环境根目录脚本会将其解析为绝对路径并校验可写L25-L56所有相对路径的基准[cangjie] repocangjie 仓库地址无本地仓库时git clone -b branch repoL125[cangjie] branchcangjie 仓库分支同上[paths] cangjie_dir拷贝的 cangjie repo 存储路径CANGJIE_DIRL70[paths] build_dircjhead 构建产物目录cmake .. make的工作目录L71、L158-L159[paths] cangjie_build_scriptcangjie 构建脚本名默认build.pyL72[paths] envsetup_shcangjie 环境脚本路径构建完成后提示sourceL146[paths] cjhead_src_dircjhead 源码目录CJHEAD_SRC_DIRL74[build] no_tests构建 cangjie 时是否跳过测试追加--no-testsL81-L82[build] cjnative是否开启 cjnative 模式追加--cjnativeL83-L84[build] targetdebug/release 目标追加-t targetL85[build] enable_assert是否开启 assert追加--enable-assertL86-L87补充说明仓库当前 cjhead/config/config.ini 的实际取值与文档示例略有差异root ../、build_dir output、cjnative false、target release、enable_assert false使用时以仓库内实际配置文件为准可按需修改后重新执行python build/build.py。5.3 运行前提CANGJIE_HOME无论采用哪种方式构建运行 cjhead 都要求环境变量CANGJIE_HOME指向 cangjie 的安装目录。CJHeadCompilerInvocation::SetCangjieHome会从环境变量中读取该值并解析为绝对路径若缺失会直接报错退出if (environment_vars.find(CANGJIE_HOME) environment_vars.end()) { std::cerr can not find CANGJIE_HOME, please setup CANGJIE_HOME\n; exit(1); }并以此设置globalOptions.executablePath为CANGJIE_HOME/bin/cjcLinux或CANGJIE_HOME/bin/cjc.exeWindowsCJHeadCompilerInvocation.cpp。因此手动构建方式下执行source ./output/envsetup.sh正是为了完成CANGJIE_HOME的初始化。六、核心流程源码级解读6.1 参数解析与目录遍历FileHandler::ParseArgumentsFileHandler.cpp完成参数解析后Run()调用TraverseAllFiles递归遍历输入目录对目录节点先调用HandlePackage处理当前目录视为一个 package再递归子目录对文件节点若命中--exclude正则则跳过否则为每个文件创建CJHeadCompilerInvocationCJHeadCompilerInstance编译至CompileStage::SEMA再对每个源文件执行裁剪与输出。值得注意的是单文件遍历路径中同时调用了SetImportPath(import_path_)与SetImportPath(macro_path_)L177-L178即将宏路径与 cjo 路径都注入编译器 importPaths——这与--import-path、--macro-path两个参数的语义一致。6.2 package 模式的文件合并开启-p后HandlePackageFileHandler.cpp会将同包所有裁剪后的文件收集到pruned_files然后MergeFiles把后续文件的decls追加到首文件import 通过import_set去重后统一合并并调用SortImports按 import 首词排序FileHandler.cpp最终输出到output_dir / (full_package_name .cj.d)。6.3 头文件版权头HandleSingleFileFileHandler.cpp在输出正文前会尝试读取可执行文件同级目录resources/COPYRIGHT.txt若存在且非空则将其作为版权头拼接到生成内容之前copyright_content \n formatted_content。这解释了为什么构建产物通常需要附带 resources 目录。6.4 格式化链路裁剪后的 AST 通过FormatCodeProcessor来自cjhead/fmt子目录的TransformAstToText重新序列化FileHandler.cpp。cjhead/fmt复用了完整的格式化组件DocProcessor文档处理器、NodeFormatter按 Decl/Expr/Node/Pattern/Type 分类的节点格式化器以及CommentHandler、TomlParser等见 cjhead/fmt/include/Format 与 cjhead/fmt/src/Format因此 cj.d 输出的排版与仓颉代码风格保持一致。七、常见问题与注意事项必须先构建 cangjiecjhead 链接libcangjie-lsp.a并依赖其 AST/词法器/诊断引擎脱离 cangjie 产物无法独立编译src/CMakeLists.txt。CANGJIE_HOME必须设置否则运行即报can not find CANGJIE_HOME。--exclude是正则文件文件内每行一个正则表达式regex_search命中即跳过该文件无效正则会在解析时打印invalid regex提示FileHandler.cpp。输出路径规则非 package 模式下输出文件为输入文件的相对路径追加.d后缀如foo.cj→foo.cj.d并自动创建中间目录FileHandler.cpppackage 模式下为包名.cj.d。源码研究入口理解导出规则建议从 HeadFileVisitor.h 的访问器清单入手VisitClassDecl、VisitFuncDecl、VisitExtendDecl等一一对应导出规则各小节理解构建链路则从 build.py 与 CMakeLists.txt 入手。结语cjhead 通过“编译到 SEMA → 按可见性规则裁剪 AST → 清空实现体 → 格式化重排”的流水线将仓颉源文件浓缩为对外可见的cj.d头文件。本文从导出规则、命令行使用到源码实现与构建配置完整还原了 cjhead/doc/developer_guide.md 的技术骨架并结合仓库源码给出了可验证的实现依据。开发者既可参照构建章节快速产出可执行文件也可沿 cjhead/src 目录深入研读各访问器的具体裁剪逻辑为二次开发或集成提供参考。赞分享开发工具CLI代码质量【免费下载链接】cangjie_tools仓颉编程语言命令行工具包括仓颉包管理工具、仓颉格式化工具、仓颉多语言桥接工具及仓颉语言服务。项目地址https://gitcode.com/Cangjie/cangjie_tools点击查看免费下载相关推荐大型仓颉项目进阶实战用cjhead实现多包依赖管理与头文件自动化构建大型仓颉项目进阶实战用cjhead实现多包依赖管理与头文件自动化构建 cjhead 是一款面向仓颉语言Cangjie的命令行构建工具专为大型多包项目打造标准库仓颉格式化工具 cjfmt 开发者指南架构原理、源码构建与命令行实践仓颉格式化工具 cjfmt 开发者指南架构原理、源码构建与命令行实践 本文围绕 cangjie_tools 仓库中 cjfmt 模块 开发者指南 https开发工具CLI代码质量kubernetes-ingress 仓库开发导航NGINX Ingress Controller 的架构、构建测试与代码生成规范kubernetes ingress 仓库开发导航NGINX Ingress Controller 的架构、构建测试与代码生成规范 本文面向希望深入 kubeAPI网关云原生负载均衡可观测性微服务上一篇Home Assistant 中 Insteon 的 Print All-Link Database 操作读取与排查设备链接数据库下一篇GeoLibre 数据集成全指南云目录、自托管目录、Web 服务与多后端地理编码实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
