企业官网建设流程全解析

• 文档
• 教程
• 构建工具

本文基于 cangjie_build 仓库中的 macOS 构建指导书（中文版见 docs/macos.md），面向希望在 macOS（以 14 Sonoma 为例）上搭建完整构建环境、源码级集成构建包含全部组件的mac仓颉 SDK 的开发者。按照本文从系统要求、依赖安装、环境变量、四个源码仓库的获取与编译，到最终打包和验证逐步执行，你可以独立完成一次从零到可运行的 SDK 构建，并理解每个组件的产物去向与相互依赖关系。

1 构建流程全景

macOS 原生构建的目标产物是两个安装包：cangjie-sdk-${SDK_NAME}-${CANGJIE_VERSION}.tar.gz（SDK 主体，SDK_NAME为mac-aarch64或mac-x64）和cangjie-stdx-${SDK_NAME}-${CANGJIE_VERSION}.${STDX_VERSION}.zip（STDX 扩展库）。整个流程可以分为五个阶段：

从源码组织结构看，整个构建依赖 4 个上游仓库：cangjie_compiler（编译器cjc与调试器cjdb，其output/目录是所有组件的汇聚中心）、cangjie_runtime（运行时runtime与标准库stdlib）、cangjie_tools（9 个配套工具）和cangjie_stdx（STDX 扩展库）。除 stdx 外，所有组件的产物最终都汇聚到$WORKSPACE/cangjie_compiler/output，因此构建顺序上编译器和运行时、标准库必须先于工具集完成。

需要特别说明构建前提：本指导书基于较高版本操作系统（macOS 14 Sonoma）简化步骤，如 README_zh.md 所述，构建出的 SDK 只能在对应系统上运行；若目标系统版本更低，需要在低版本系统上构建，且更多依赖工具需要从源码编译，复杂度会显著提升。

2 环境准备

2.1 系统要求

芯片架构决定了后续ARCH、SDK_NAME及产物目录名（darwin_${ARCH}_cjnative）的取值，是贯穿全流程的关键变量，务必在最开始就确认正确。

2.2 各组件的构建依赖版本要求

构建依赖工具矩阵 中给出了 macOS 版本各组件所需的构建工具与版本要求，与本指导书直接相关的部分如下（✅ 表示该组件需要此工具）：

可以看出 macOS 与 Linux 构建的一个重要差异：编译器侧要求LLVM 16（Linux 为 LLVM 15.x），这也是指导书要求通过 Homebrew 安装llvm@16的原因。另外矩阵中的objc interop组件依赖 Xcode >=15，属于交叉/互操作构建范畴，不在本篇原生 macOS 构建的流程内。

2.3 安装 cmake（要求 >=3.17, <4）

cmake 需要手动安装 dmg 或 tar.gz 包，官方下载渠道为 CMake 官网。两种安装方式：

方式一：dmg 安装。下载后拖入 Applications，并执行（二选一）：

# 安装至 /usr/local/bin sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install # 自定义安装位置（/path/to/cmake 请替换为你的安装目录） sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install=/path/to/cmake # 使用前将 cmake/bin 加入环境变量 PATH="/Applications/CMake.app/Contents/bin:$PATH"

方式二：tar.gz 安装。

# 解压 tar 包 tar -zxvf cmake-3.x.x-macos-universal.tar.gz /path/to/cmake # 使用前将 cmake/bin 加入环境变量，或将配置写入 ~/.zshrc export PATH="/path/to/cmake/bin:$PATH"

2.4 使用 Homebrew 安装其他构建工具

除 cmake 外，其余依赖推荐使用 Homebrew 一键安装：

brew install python3 ninja llvm@16 openssl@3 bison googletest gnu-tar swig

这几个工具与依赖矩阵的对应关系：llvm@16满足 LLVM >=16.0.0 且 <17；openssl@3供 stdlib 与 stdx 链接使用；googletest供 cjc 与 lsp 的测试编译；swig供 cjdb 的接口绑定；gnu-tar则直接用于第 5 章的gtar打包命令；bison、ninja、python3是各组件build.py的通用依赖。

2.5 设置环境变量

请在构建前务必设置以下变量：

export ARCH=aarch64 # 或x86_64 export CANGJIE_VERSION=1.0.0 # Cangjie SDK 版本 export STDX_VERSION=1 # Stdx 版本 export SDK_NAME=mac-aarch64 # 或mac-x64

各变量的作用：

• ARCH：芯片架构，取值aarch64（Apple Silicon）或x86_64（Intel）。它决定运行时/标准库的产物目录darwin_release_${ARCH}、stdx 目标目录darwin_${ARCH}_cjnative，以及 cjpm 的 rpath 路径；
• CANGJIE_VERSION：SDK 版本号，会出现在编译参数-v和最终安装包文件名中；
• STDX_VERSION：STDX 扩展库版本，仅用于 stdx 安装包文件名；
• SDK_NAME：SDK 命名标识，取mac-aarch64或mac-x64，与ARCH保持一致，用于最终打包文件名。

接着设置工具链路径。请注意：以下示例中 16.x、3.x 等版本号必须替换为你实际安装的版本：

export CELLAR_PATH=/path/to/Cellar # 可使用 brew --cellar 命令查看 # 对于 arm 芯片，Cellar 通常位于：/opt/homebrew/Cellar # 对于 intel 芯片，Cellar 通常位于：/usr/local/Cellar # 如何找到版本号： # 使用 brew list --versions 查看已安装的软件包及其版本号，例如： # brew list --versions llvm@16 export PATH=$CELLAR_PATH/llvm@16/16.x/bin:$PATH export OPENSSL_PATH=$CELLAR_PATH/openssl@3/3.x/lib export LD_LIBRARY_PATH=$OPENSSL_PATH:$LD_LIBRARY_PATH export DYLD_LIBRARY_PATH=$OPENSSL_PATH:$DYLD_LIBRARY_PATH

这里有两处 macOS 特有的细节值得注意：

1. Homebrew 的包体位于Cellar下按“包名/版本号”组织的目录中，Apple Silicon 与 Intel 的默认前缀不同（/opt/homebrew与/usr/local），因此CELLAR_PATH必须按芯片区分；
2. OPENSSL_PATH同时导出到LD_LIBRARY_PATH和DYLD_LIBRARY_PATH，前者服务于构建期链接，后者是 macOS 上动态库加载的实际路径变量，后续标准库（--target-lib=$OPENSSL_PATH）和 STDX 构建都会直接引用它。

3 源码准备

3.1 创建工作区

/path/to/workspace请替换为你构建仓颉 SDK 的工作目录：

export WORKSPACE=/path/to/workspace mkdir -p $WORKSPACE; cd $WORKSPACE;

3.2 获取仓颉源码

依次克隆 4 个仓库的main分支到工作区：

git clone https://gitcode.com/Cangjie/cangjie_compiler.git -b main; git clone https://gitcode.com/Cangjie/cangjie_runtime.git -b main; git clone https://gitcode.com/Cangjie/cangjie_tools.git -b main; git clone https://gitcode.com/Cangjie/cangjie_stdx.git -b main;

这 4 个目录之后会反复出现在所有编译命令中，可先建立对照关系：cangjie_compiler是产物汇聚地（output/），cangjie_runtime/runtime与cangjie_runtime/stdlib分别对应运行时与标准库，cangjie_tools下是各工具各自的独立子工程，cangjie_stdx独立产出扩展库。

4 编译流程

各组件统一采用build.py驱动的三段式流程：clean清理历史产物 →build -t release以 Release 模式编译 →install安装到约定位置。以下按依赖顺序逐组件展开。

4.1 编译仓颉编译器和调试器

cd $WORKSPACE/cangjie_compiler; python3 build.py clean; python3 build.py build -t release -v ${CANGJIE_VERSION} --no-tests --build-cjdb; python3 build.py install;

关键参数说明：

• -t release：Release 构建模式，SDK 交付必须使用 Release；
• -v ${CANGJIE_VERSION}：将版本号注入编译器，使cjc -v输出与 SDK 版本一致；
• --no-tests：跳过测试编译，缩短构建时间（googletest 依赖因此只在测试构建时才被用到）；
• --build-cjdb：一并构建调试器 cjdb，该选项需要 swig 工具支持接口绑定。

安装完成后立即验证：

source output/envsetup.sh; cjc -v;

output/envsetup.sh是编译器产出的环境脚本，source 之后cjc等命令即可直接使用，cjc -v输出版本号即说明编译器安装成功。

4.2 编译仓颉运行时

cd $WORKSPACE/cangjie_runtime/runtime; python3 build.py clean; python3 build.py build -t release -v ${CANGJIE_VERSION}; python3 build.py install; cp -R output/common/darwin_release_${ARCH}/{lib,runtime} $WORKSPACE/cangjie_compiler/output;

注意最后一条cp：运行时产物先落在自己的output/common/darwin_release_${ARCH}目录下，需要把lib和runtime两个子目录复制到cangjie_compiler/output，这是产物汇聚到编译器输出目录的第一步——后续envsetup.sh与最终 SDK 包都从这个目录取运行时。

4.3 编译仓颉标准库

cd $WORKSPACE/cangjie_runtime/stdlib; python3 build.py clean; python3 build.py build -t release \ --target-lib=$WORKSPACE/cangjie_runtime/runtime/output \ --target-lib=$OPENSSL_PATH; python3 build.py install; cp -R output/* $WORKSPACE/cangjie_compiler/output/;

标准库构建有两次--target-lib指定：一次指向运行时输出目录（标准库需链接运行时），一次指向OPENSSL_PATH（依赖矩阵中 std 组件的 openssl: >3 依赖在此生效）。构建完成后用cp -R output/*将全部产物并入编译器输出目录。

4.4 编译 Stdx 扩展库

cd $WORKSPACE/cangjie_stdx; python3 build.py clean; python3 build.py build -t release \ --include=${WORKSPACE}/cangjie_compiler/include \ --target-lib=$OPENSSL_PATH; python3 build.py install; export CANGJIE_STDX_PATH=$WORKSPACE/cangjie_stdx/target/darwin_${ARCH}_cjnative/static/stdx;

• --include指向编译器仓库的include头文件目录，说明 STDX 静态库是在编译器头文件环境下编译的，二者版本必须匹配；
• --target-lib=$OPENSSL_PATH与标准库类似，用于链接 OpenSSL；
• 产物位于target/darwin_${ARCH}_cjnative/static/stdx，这里导出CANGJIE_STDX_PATH便于后续引用；
• STDX 是独立交付物，不并入cangjie_compiler/output，而是与 SDK 分开打包（见 5.2 节）。

4.5 编译仓颉工具集

工具集共 9 个组件，均位于cangjie_tools下的独立子工程中，每个都有独立的build/build.py。统一模式是：在子工程内执行clean/build/install后，把产物手动拷贝或移动到cangjie_compiler/output/tools/的对应子目录（bin、lib、config）。

(1) cjpm

cd $WORKSPACE/cangjie_tools/cjpm/build; python3 build.py clean; python3 build.py build -t release --set-rpath @loader_path/../../runtime/lib/darwin_${ARCH}_cjnative; python3 build.py install; mkdir -p ${WORKSPACE}/cangjie_compiler/output/tools/config; cp ${WORKSPACE}/cangjie_tools/cjpm/dist/cjpm ${WORKSPACE}/cangjie_compiler/output/tools/bin; mv ${WORKSPACE}/cangjie_tools/cjpm/dist/*.toml ${WORKSPACE}/cangjie_compiler/output/tools/config;

cjpm 是全部工具中唯一带--set-rpath参数的：@loader_path/../../runtime/lib/darwin_${ARCH}_cjnative是 macOS 的动态库定位语法（@loader_path相对可执行文件自身定位），它让 cjpm 在脱离构建环境的任意安装位置都能找到运行时库，这正是 macOS 平台上打包可独立分发的工具时的典型做法。

(2) cjfmt

cd ${WORKSPACE}/cangjie_tools/cjfmt/build; python3 build.py clean; python3 build.py build -t release; python3 build.py install; mv ${WORKSPACE}/cangjie_tools/cjfmt/build/build/bin/cjfmt ${WORKSPACE}/cangjie_compiler/output/tools/bin; mv ${WORKSPACE}/cangjie_tools/cjfmt/config/*.toml ${WORKSPACE}/cangjie_compiler/output/tools/config;

除可执行文件外，还要把config/*.toml格式配置一并放入tools/config，保证 SDK 内的 cjfmt 开箱即用。

(3) cjlint

cd ${WORKSPACE}/cangjie_tools/cjlint/build; python3 build.py clean; python3 build.py build -t release; python3 build.py install; mv ${WORKSPACE}/cangjie_tools/cjlint/dist/bin/cjlint ${WORKSPACE}/cangjie_compiler/output/tools/bin mv ${WORKSPACE}/cangjie_tools/cjlint/dist/lib/* ${WORKSPACE}/cangjie_compiler/output/tools/lib mv ${WORKSPACE}/cangjie_tools/cjlint/dist/config/* ${WORKSPACE}/cangjie_compiler/output/tools/config

cjlint 是三层产物结构最完整的示例：二进制进bin，动态库进lib，规则配置进config。

(4) cjcov

cd ${WORKSPACE}/cangjie_tools/cjcov/build; python3 build.py clean; python3 build.py build -t release; python3 build.py install; mv ${WORKSPACE}/cangjie_tools/cjcov/dist/cjcov ${WORKSPACE}/cangjie_compiler/output/tools/bin;

(5) cjtrace-recover

cd ${WORKSPACE}/cangjie_tools/cjtrace-recover/build; python3 build.py clean; python3 build.py build -t release; python3 build.py install; python3 build.py install --prefix ${WORKSPACE}/cangjie_compiler/output/tools;

与其他工具不同，cjtrace-recover 通过install --prefix直接把安装前缀指定为 SDK 工具目录，无需再手动cp。

(6) HyperLangExtension（hle）

cd $WORKSPACE/cangjie_tools/hyperlangExtension/build; python3 build.py clean; python3 build.py build -t release; python3 build.py install; cp ${WORKSPACE}/cangjie_tools/hyperlangExtension/target/bin/main ${WORKSPACE}/cangjie_compiler/output/tools/bin/hle; cp -R ${WORKSPACE}/cangjie_tools/hyperlangExtension/src/dtsparser ${WORKSPACE}/cangjie_compiler/output/tools; rm -rf ${WORKSPACE}/cangjie_compiler/output/tools/dtsparser/*.cj;

该工具主程序名为main，交付时需重命名为hle；dtsparser子目录随工具一并分发，并删除其中的.cj源码，只保留编译产物。

(7) LSP Server

cd $WORKSPACE/cangjie_tools/cangjie-language-server/build; python3 build.py clean; python3 build.py build -t release; python3 build.py install; cp ${WORKSPACE}/cangjie_tools/cangjie-language-server/output/bin/LSPServer ${WORKSPACE}/cangjie_compiler/output/tools/bin

(8) cjprof

cd ${WORKSPACE}/cangjie_tools/cjprof/build; python3 build.py build -t release; python3 build.py install; cp $WORKSPACE/cangjie_tools/cjprof/dist/bin/cjprof ${WORKSPACE}/cangjie_compiler/output/tools/bin cp $WORKSPACE/cangjie_tools/cjprof/dist/lib/* ${WORKSPACE}/cangjie_compiler/output/tools/lib; if [[ -d "$WORKSPACE/cangjie_tools/cjprof/static" ]]; then cp -Rf $WORKSPACE/cangjie_tools/cjprof/static cangjie/tools/config; fi

注意static目录为可选项：指令书用if [[ -d ... ]]做了存在性判断，若源码仓库中不存在该目录则跳过拷贝。

(9) cjcompat

cd ${WORKSPACE}/cangjie_tools/cjcompat/build; python3 build.py build -t release; python3 build.py install; cp $WORKSPACE/cangjie_tools/cjcompat/dist/bin/cjcompat ${WORKSPACE}/cangjie_compiler/output/tools/bin

完成以上 9 个工具后，cangjie_compiler/output/tools下即形成完整的 SDK 工具集：bin/中是各工具可执行文件，lib/中是 cjlint、cjprof 的动态库，config/中是各工具的*.toml与规则配置。

5 组织并打包文件

5.1 组织并打包 SDK

# 清空历史构建 mkdir -p $WORKSPACE/software; rm -rf $WORKSPACE/software/*; cd $WORKSPACE/software; # 拷贝cangjie目录 cp -R $WORKSPACE/cangjie_compiler/output cangjie; cp $WORKSPACE/cangjie_compiler/LICENSE cangjie; cp $WORKSPACE/cangjie_compiler/Open_Source_Software_Notice.docx cangjie; # 打包和设置权限 chmod -R 750 cangjie gtar --format=gnu -zcvf cangjie-sdk-${SDK_NAME}-${CANGJIE_VERSION}.tar.gz cangjie; chmod 550 cangjie-sdk-${SDK_NAME}-${CANGJIE_VERSION}.tar.gz;

打包要点：

• SDK 主体就是cangjie_compiler/output目录整体，此前各组件汇入的编译器、运行时、标准库与工具集在这里一次性交付；
• 附带LICENSE与Open_Source_Software_Notice.docx满足开源合规要求；
• 使用 Homebrew 安装的gnu-tar（gtar），并显式指定--format=gnu，保证压缩包在不同平台间归档格式一致；
• 命名规则为cangjie-sdk-${SDK_NAME}-${CANGJIE_VERSION}.tar.gz，例如cangjie-sdk-mac-aarch64-1.0.0.tar.gz。

5.2 组织并打包 Stdx

cd $WORKSPACE/software; # 拷贝stdx目录 cp -r $WORKSPACE/cangjie_stdx/target/darwin_${ARCH}_cjnative ./; cp $WORKSPACE/cangjie_stdx/LICENSE darwin_${ARCH}_cjnative; cp $WORKSPACE/cangjie_stdx/Open_Source_Software_Notice.docx darwin_${ARCH}_cjnative; chmod -R 750 darwin_${ARCH}_cjnative; zip -qr cangjie-stdx-${SDK_NAME}-${CANGJIE_VERSION}.${STDX_VERSION}.zip darwin_${ARCH}_cjnative; chmod 550 cangjie-stdx-${SDK_NAME}-${CANGJIE_VERSION}.${STDX_VERSION}.zip;

STDX 以整个darwin_${ARCH}_cjnative目标目录交付，命名中额外包含${STDX_VERSION}，与 SDK 包形成独立的版本维度。

6 验证：编译并运行 Hello, Cangjie

先确认两个产物都已生成：

ls -lh $WORKSPACE/software # 应包含： # - cangjie-sdk-${SDK_NAME}-${CANGJIE_VERSION}.tar.gz # - cangjie-stdx-${SDK_NAME}-${CANGJIE_VERSION}.${STDX_VERSION}.zip

然后做端到端验证——加载 SDK 环境、编写并编译运行一段最小仓颉程序：

cd $WORKSPACE; source $WORKSPACE/software/cangjie/envsetup.sh; echo "main() { println(\"Hello, Cangjie\") }" > hello.cj cjc hello.cj -o hello && ./hello # 您将在控制台看到以下输出： # Hello, Cangjie

这一验证覆盖了构建链路中最关键的两段：source envsetup.sh证明 SDK 的环境脚本可用，cjc hello.cj -o hello验证了编译器，./hello则验证了运行时与标准库在目标架构上的实际可执行性。三步全部通过，即说明本次 macOS 原生构建完整成功。

7 延伸：与其他构建指导的关系

本指导书产出的是mac（macOS 原生）SDK。cangjie_build 仓库还覆盖了同一构建体系下的其他目标：MacOS -> Android 交叉构建、MacOS -> iOS 交叉构建、MacOS -> OHOS 交叉构建，以及 Linux Native 构建 等；各环境入口索引见 README_zh.md。需要说明的是，交叉构建指导（如 mac-android 的SDK_NAME为mac-android）在准备阶段会额外引入 NDK 等目标平台工具链，并在工具集阶段增加互操作库编译步骤；本篇原生 macOS 流程是理解这些交叉构建指导的共同基础。

• 文档
• 教程
• 构建工具