仓颉编程语言包声明完全指南：语法规则、目录映射与命名冲突

文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载导读包是仓颉编程语言中编译的最小单元而package声明则是每个仓颉源文件的第一道身份标识——它决定源码归属哪个包、编译器如何把它映射到目录结构并进而影响导入、编译产物与命名空间解析。本文以仓颉官方文档中包的声明为核心系统讲解包声明的语法约束、放置位置、与src目录的映射规则以及子包命名冲突等关键知识点并结合本仓库收录的 cjc 编译选项、包的导入 等配套资料让读者在看完后能够正确书写包声明、合理组织源码目录并理解编译器依据包名进行的各类检查。一、先理解包在仓颉中的地位在讨论包声明之前有必要先明确包在整个项目结构中的位置。根据仓颉官方文档 包的概述包package是编译的最小单元。每个包可以单独输出 AST 文件.cjo、静态库文件.a、动态库文件.so/.dll/.dylib等产物每个包拥有自己的名字空间同一个包内不允许存在同名的顶层定义或声明函数重载除外一个包中可以包含多个源文件模块module是若干包的集合是第三方开发者发布的最小单元一个模块的程序入口只能位于其根目录下。因此包声明不仅仅是一行语法它直接决定了源文件属于哪个编译单元源文件在目录结构中的相对路径是否合法其他包能否通过import找到并导入本包中的声明。二、包声明的基本语法2.1package关键字与点分包名仓颉的包声明以关键字package开头后接从 root 包到当前包、由.分隔路径上的所有包的包名。例如package pkg1 // root 包 pkg1 package pkg1.sub1 // root 包 pkg1 的子包 sub1可以看到package pkg1.sub1声明的是位于 root 包pkg1之下的子包sub1完整包名由各级包名以.连接而成这与 Java 的包名风格类似。package是仓颉语言的保留关键字参见 关键字 中的关键字表因此普通标识符不能命名为package。2.2 包名的标识符约束包名必须是合法的普通标识符不含原始标识符。也就是说不能使用反引号包裹的原始标识符如pkg1作为包名包名不能与仓颉关键字相同。关于普通标识符的具体定义可参见 标识符普通标识符由XID_Start字符开头、后接任意长度的XID_Continue字符或者由_开头、后接至少一个XID_Continue字符。仓颉语言采用 Unicode 标准 15.0.0因此理论上普通标识符可以包含中文等 Unicode 字符。注意平台差异当前 Windows 平台版本包名暂不支持使用 Unicode 字符包名必须是一个仅含 ASCII 字符的合法的普通标识符。也就是说在 Windows 上开发时应使用pkg1、pkg1.sub1这类纯 ASCII 包名包含中文等字符的包名在 Windows 平台上暂无法通过编译。三、包声明的放置位置与一致性约束3.1 必须位于源文件的非空非注释首行包声明在源文件中的位置有严格限制包声明必须在源文件的非空非注释的首行。这意味着在包声明之前只允许出现空行或注释不允许出现任何其他声明或定义。下面的反例中file 2在package test之前先出现了一条let变量声明因此编译报错// file 1 // Comments are accepted package test // declarations... // file 2 let a 1 // Error, package declaration must appear first in a file package test // declarations...编译器要求包声明首行的原因很直观只有先确定源码归属的包编译器才能在此基础上解析包内名字空间、处理导入语句、进行符号决议。3.2 同一包内不同源文件的包声明必须一致同一个包可以由多个源文件组成但这些源文件的包声明必须保持一致。这是编译器校验包名与目录归属一致性的前提——如果同一目录下的文件分别声明为不同的包名编译器将无法确定该目录的包身份。另外从 包的导入 的规则可知import语句的位置也必须在包声明之后、其他声明或定义之前这进一步说明包声明是源文件结构的最前置要素。四、包名与目录结构的映射规则仓颉的包名设计采用了目录即包的约定包名必须反映当前源文件相对于项目源码根目录src的路径仓颉的包名需反映当前源文件相对于项目源码根目录src的路径并将其中的路径分隔符替换为小数点。例如包的源代码位于src/directory_0/directory_1下若 root 包名为pkg则其源代码中的包声明应为package pkg.directory_0.directory_1围绕这一映射规则有三个重要约定约定说明文件夹名必须与包名一致包所在的文件夹名必须与包名一致目录层级是包名的物理载体源码根目录默认名为src编译器以src目录作为源码根目录的默认名称根目录下的包可省略声明源码根目录下的包可以没有包声明此时编译器将默认为其指定包名default其中省略声明默认为default是一条容易被忽略但十分重要的规则凡是位于src目录下的源文件若没有显式包声明都会被归入名为default的包其子目录中的文件则对应default.xxx这样的包名。4.1 完整示例目录结构驱动的包声明假设源代码目录结构如下// The directory structure is as follows: src -- directory_0 |-- directory_1 | |-- a.cj | -- b.cj -- c.cj -- main.cj那么各文件的包声明应为src/directory_0/directory_1/a.cj与b.cj同处directory_0/directory_1目录且该目录不在src根目录下因此包名为default.directory_0.directory_1// a.cj // in file a.cj, the declared package name must correspond to relative path directory_0/directory_1. package default.directory_0.directory_1// b.cj // in file b.cj, the declared package name must correspond to relative path directory_0/directory_1. package default.directory_0.directory_1src/directory_0/c.cj位于directory_0目录对应包名为default.directory_0// c.cj // in file c.cj, the declared package name must correspond to relative path directory_0. package default.directory_0src/main.cj位于模块根目录即src根目录可以省略包声明编译器会将其归入默认的default包// main.cj // file main.cj is in the module root directory and may omit package declaration. main() { return 0 }需要特别注意a.cj与b.cj处于同一目录因此二者的包声明必须完全一致都是default.directory_0.directory_1这正是前面同一包内不同源文件的包声明必须一致规则在目录组织上的体现。五、包声明与命名冲突5.1 子包不能与当前包的顶层声明同名包声明还隐含一条命名约束包声明不能引起命名冲突——子包不能和当前包的顶层声明同名。以 root 包a为例若a包内声明了一个名为B的类同时a包又存在子包a.B那么B这一名字既指代顶层类B又指代子包a.B会造成歧义。5.2 冲突反例逐行解析以下三个文件构成了一个完整的冲突场景文件一a.cj声明 root 包a下的顶层类B// a.cj package a public class B { // Error, B is conflicted with sub-package a.B public static func f() {} }文件二b.cj声明子包a.B// b.cj package a.B public func f {}文件三main.cj导入并使用a.B// main.cj import a.B // ambiguous use of a.B main() { a.B.f() return 0 }编译结果分析文件一中的类B与文件二中的子包a.B同名冲突类声明处报错文件三中import a.B因名字歧义报错ambiguous use of a.B——因为a.B既可以理解为包a中的顶层类B也可以理解为子包a.B编译器无法唯一解析。这一规则的实践启示是在设计包名时要避免子包名与父包内任何顶层声明的名字重合否则会触发歧义编译错误。六、包声明的访问修饰符包声明本身也可以带访问修饰符。根据 顶层声明的可见性 的说明package支持internal、protected、public三种访问修饰符默认修饰符为public与普通顶层声明默认internal不同package不支持private修饰因为包是最小的编译单元若包本身私有则无法被任何单元引用。例如在 包的导入 中就有internal package a.b的写法——使用internal修饰的包a.b仅在当前模块内可见其他模块无法导入它。这意味着包声明的可见性直接决定了该包能否被其他模块通过import引用是包级封装的关键手段。七、包声明与编译实践的衔接包声明写对了还需要配合正确的编译方式才能产出预期的产物。以下编译选项与包声明直接相关详见 cjc 编译选项7.1 使用-p编译整个包--package短选项-p用于编译包使用时需要指定一个目录作为输入目录中的源码文件需要属于同一个包。例如log/printer.cj声明package log后可编译为静态库cjc -p log --output-typestaticlib编译完成后会在当前目录生成liblog.a文件之后其他源文件如声明了import log.*的main.cj可以通过链接该库来使用cjc main.cj liblog.a这里-p log中的log必须与源文件中的package log声明一致这正是文件夹名必须与包名一致规则在命令行层面的体现。7.2 用--module-name指定模块名包名之外模块名通过--module-name指定。例如my_module/src/log/printer.cj声明package log编译时指定模块名my_modulecjc -p my_module/src/log --module-name my_module --output-typestaticlib -o my_module/liblog.a之后其他文件需通过完整路径导入import my_module.log.*。可见完整包名 模块名 包名包声明中的各级名字共同构成import时使用的完整路径包名。7.3--no-sub-pkg与包结构优化--no-sub-pkg表明当前编译包没有子包。开启该选项后编译器可以进一步缩减 code size 大小。如果你的包结构是扁平的没有子目录/子包可以显式声明这一事实帮助编译器做优化。7.4 在cjpm项目中组织包如果使用仓颉官方包管理工具cjpm参见 cjpm 介绍cjpm init会默认在当前文件夹创建cjpm.toml配置文件并新建src源码文件夹、在src下生成默认的main.cj。其中cjpm.toml中[package]段的name字段即模块名及模块 root 包名src-dir字段可指定源码存放路径默认即src通过cjpm build -V可以看到cjc实际执行的编译命令例如cjc --import-path target -p src/package1 --output-typestaticlib ...。从cjpm的默认行为可以印证src是仓颉源码根目录的默认命名源码目录中的包声明与src下的相对目录一一对应。八、小结与自查清单包声明虽然只有一行却是仓颉源码组织的基础。撰写包声明时请对照以下清单自查语法正确以package开头各级包名以.分隔包名为合法的普通标识符Windows 平台仅限 ASCII位置正确位于源文件非空非注释的首行同一包内所有源文件的包声明保持一致目录一致包名与源码相对src的目录路径完全对应文件夹名与包名一致冲突检查子包名不得与当前包的顶层声明同名避免import出现歧义可见性合适按需使用internal/protected/public修饰包声明默认public编译配套使用cjc -p 包目录或cjpm build编译整包必要时配合--module-name、--no-sub-pkg等选项。掌握以上规则你就能在仓颉项目中搭建出清晰、无冲突、可独立编译的包结构为后续的跨包导入、模块发布与大型项目维护打下坚实基础。赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉语言包声明package 声明完全指南语法、目录映射与命名约束仓颉语言包声明package 声明完全指南语法、目录映射与命名约束 在仓颉编程语言中 包package是编译的最小单元 每个包拥有独立的名字空间文档编程语言仓颉编程语言包的导入import 语法、名字冲突消解、重命名与重导出实战指南仓颉编程语言包的导入import 语法、名字冲突消解、重命名与重导出实战指南 导读本文以仓颉Cangjie编程语言开发指南中「包的导入」章节为核心系统文档编程语言仓颉编程语言包导入import机制完全指南语法、作用域规则、别名与重导出仓颉编程语言包导入import机制完全指南语法、作用域规则、别名与重导出 仓颉编程语言以 包package 为编译最小单元跨包复用代码的唯一途径就是文档编程语言上一篇【免费下载】 年会抽奖程序安装和配置指南下一篇Teo框架入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考