适用读者：需在 macOS 上为 OpenHarmony 准备 C/C++ 交叉编译 SDK，并希望通过官方 tpc_c_cplusplus 仓库的 lycium 完成编译与设备测试的开发者。

本文说明 OpenHarmony SDK 的获取、解压与环境变量；可与更大文档中的「第 2 章」编号（2.1.x）对照使用。

范围说明：完成本文 SDK 部分后，宿主机已具备 clang、cmake、ohos、hnpcli 等命令。若脱离 lycium 自行用 CMake 交叉编译，通常还需显式指定 CMAKE_TOOLCHAIN_FILE、OHOS_ARCH 等（见文末）。

目录

• 前置条件
• OpenHarmony SDK 安装
• 交叉编译示例：以 cJSON 为例
• 常见问题（FAQ）

---

前置条件

• 架构与产物：SDK 的 native-*、toolchains-* 压缩包名中的 darwin-arm64 对应 Apple Silicon（M 系列），darwin-x86_64（或页面所示 Intel/amd64 命名）对应 Intel Mac。须与当前机器一致，避免错下包导致无法运行。
• 磁盘：SDK 解压后体积较大，建议预留 ≥ 10 GB 可用空间（以实际包为准）。
• 下载访问：DCP 页面 每日构建列表 若需 登录、内网或 VPN，请按所在组织要求访问。

---

OpenHarmony SDK 安装

2.1.1 下载 SDK（环境搭建）

1. 在浏览器中打开 DCP 每日构建列表：https://dcp.openharmony.cn/workbench/cicd/dailybuild/dailylist
   

2. 在列表中按本机操作系统选择对应产物：

开发机系统	选择产物（关键词）
macOS	mac-sdk-full（Mac 版 SDK 包）

3. 版本与目标一致：尽量选择与目标 OpenHarmony 设备/镜像/工程匹配的 SDK 版本（或同一主版本线），减少头文件、API 或工具行为不一致问题。

4. 下载到本机后解压外层包（请将文件名替换为你实际下载的包名）：

cd ~
# macOS 示例（包名以 DCP 页面为准）
tar -zxvf <你下载的-sdk-xxx>.tar.gz

解压后若得到的是带版本号的一层目录（例如 ohos-sdk-xxx/），请先 cd 到该目录或将其重命名为你计划使用的根路径（例如 ~/ohos-sdk），保证后续步骤里的 OHOS_SDK 指向层内已包含「待解压的 native-*.zip / toolchains-*.zip」或与 DCP 说明一致的根目录。

5. 再进入 ohos-sdk 根目录解压 darwin-* 对应的 zip（文件名以你本机包内列表为准；下例版本号与架构仅作演示；Intel Mac 请改用 darwin-x86_64 等页面上的命名）：

cd ~/ohos-sdk   # 按你实际上一步得到的 SDK 根目录修改
tar -zxvf native-darwin-arm64-6.0.0.46-Beta1.zip   # 以实际包名为准
tar -zxvf toolchains-darwin-arm64-6.0.0.46-Beta1.zip   # 以实际包名为准

解压完成后，应得到 native/、toolchains/ 等目录（含 llvm、sysroot、hnpcli 等），再配置环境变量。

2.1.2 SDK 目录结构

ohos-sdk/
├── native/
│   ├── llvm/bin/          # 编译器工具链
│   ├── sysroot/           # 系统根目录（头文件和库）
│   └── build-tools/       # 构建工具（含 cmake 等，布局随版本可能略有差异）
└── toolchains/
    └── hnpcli             # HNP 打包工具（部分版本可能在 toolchains/bin 下）

2.1.3 环境变量配置

编辑 ~/.zshrc（如果使用 zsh）或 ~/.bash_profile（如果使用 bash）：

# OpenHarmony SDK 路径（与解压后的根目录一致）
export OHOS_SDK=~/ohos-sdk

# 添加到 PATH
export PATH="$OHOS_SDK/native/llvm/bin:$PATH"
export PATH="$OHOS_SDK/native/build-tools/cmake/bin:$PATH"
# hnpcli 可能在 toolchains 根目录或 toolchains/bin，两处均加入可避免版本差异
export PATH="$OHOS_SDK/toolchains/bin:$PATH"
export PATH="$OHOS_SDK/toolchains:$PATH"

# 验证（修改配置后执行其一）
source ~/.zshrc

使用 fish 等其他 shell 时，请用对应语法设置 OHOS_SDK 与 PATH。

2.1.4 验证 SDK 配置

# 检查 SDK 路径
echo $OHOS_SDK

# 检查工具是否在 PATH 中
which clang
which cmake
which hnpcli

# 检查 SDK 工具目录
ls "$OHOS_SDK/native/llvm/bin/"
ls "$OHOS_SDK/native/build-tools/cmake/bin/"
ls "$OHOS_SDK/toolchains/"

# 验证工具版本
clang --version
cmake --version
hnpcli --version

若 which hnpcli 仍为空，请在该 SDK 的 toolchains 下查找 hnpcli 实际位置，并把其所在目录追加到 PATH。

---

交叉编译示例：以 cJSON 为例（tpc_c_cplusplus）

以下按 流程 说明：克隆 openharmony-sig/tpc_c_cplusplus 后，使用已有目录 thirdparty/cJSON/ 中的适配脚本，在 Mac 上交叉编译并在设备上跑测试。仓库内 HPKBUILD / HPKCHECK 为完整版，此处只摘 与流程相关的核心片段。

说明：build.sh 的参数是 thirdparty 下的目录名，本例为 cJSON（大小写与文件夹一致）。测试在 OpenHarmony 设备上执行，不能在 macOS 上直接跑交叉编译出的测试二进制。

本机额外依赖（Mac）

brew install cmake make autoconf automake libtool pkg-config ninja curl wget

详见仓库 lycium/README.md、lycium/Buildtools。

流程概览

步骤	做什么
1	克隆仓库
2	看 thirdparty/cJSON/ 里 HPKBUILD / HPKCHECK（一般无需改即可试编）
3	设置 OHOS_SDK，在 lycium/ 执行 ./build.sh cJSON
4	设备准备 CItools，整仓路径对齐后执行 ./test.sh cJSON

步骤一：克隆官方框架

cd ~/work   # 换成你的工作目录
git clone https://atomgit.com/openharmony-sig/tpc_c_cplusplus.git
cd tpc_c_cplusplus

• lycium/build.sh、lycium/test.sh：编译与测试入口
• thirdparty/cJSON/：本例适配目录（HPKBUILD、HPKCHECK、README 等）

步骤二：适配文件在做什么（cJSON）

源码由 HPKBUILD 的 source 在首次构建时下载到 thirdparty/cJSON/ 下；builddir 解压后为 cJSON-1.7.19（与 pkgver=v1.7.19 对应，去掉 tag 前缀 v）。

HPKBUILD 要点（变量名 + prepare / build / package 主干）：

pkgname=cJSON
pkgver=v1.7.19
archs=("armeabi-v7a" "arm64-v8a")
source="https://github.com/DaveGamble/$pkgname/archive/refs/tags/$pkgver.tar.gz"
buildtools="cmake"
builddir=$pkgname-${pkgver:1}    # cJSON-1.7.19

prepare() {
    mkdir -p $builddir/$ARCH-build
}

build() {
    cd $builddir
    PKG_CONFIG_LIBDIR="${pkgconfigpath}" ${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" \
        -DOHOS_ARCH=$ARCH -B$ARCH-build -S./ -L > $buildlog 2>&1
    $MAKE VERBOSE=1 -C $ARCH-build >> $buildlog 2>&1
    cd $OLDPWD
}

package() {
    cd $builddir
    $MAKE VERBOSE=1 -C $ARCH-build install >> $buildlog 2>&1
    cd $OLDPWD
}

cleanbuild() {
    rm -rf ${PWD}/$builddir
}

HPKCHECK 要点（与仓库 thirdparty/cJSON/HPKCHECK 一致）：用 LYCIUM_THIRDPARTY_ROOT 拼出构建目录绝对路径，保证设备上工作目录无关；为 musl 运行时把 ${ARCH}-build 置于 LD_LIBRARY_PATH 首位；若存在 /usr/CIusr/bin 则优先加入 PATH（cmake/ctest 常见位置）；最后 ctest 写入 logfile。

source HPKBUILD > /dev/null 2>&1
logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log

openharmonycheck() {
    res=0
    build_abs="${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${builddir}/${ARCH}-build"
    cd "$build_abs" || return 1
    [ -d /usr/CIusr/bin ] && export PATH="/usr/CIusr/bin:${PATH}"
    export LD_LIBRARY_PATH="${build_abs}:${LYCIUM_ROOT}/usr/${pkgname}/${ARCH}/lib:${LD_LIBRARY_PATH}"
    ctest --timeout 40000 >> ${logfile} 2>&1
    res=$?
    cd $OLDPWD
    return $res
}

（完整脚本还会在失败时备份 Testing/Temporary/LastTest.log 到 LYCIUM_FAULT_PATH/${pkgname}/。）

新建其它库时：在 thirdparty/<目录名>/ 从 lycium/template/ 拷贝模板，按上游改 source、builddir、build() 等；HPKCHECK 里 cd 的构建目录必须与 HPKBUILD 一致；文件换行保持 LF。

步骤三：交叉编译

export OHOS_SDK=~/ohos-sdk   # 与本文 2.1.3 一致，按实际路径修改
cd /path/to/tpc_c_cplusplus/lycium
./build.sh cJSON

• 多库时：./build.sh cJSON 其他库名；若 A 依赖 B，参数里要带上 B。
• 产物示例：lycium/usr/cJSON/arm64-v8a/（lib/、include/ 等，以实际 install 为准）。
• macOS：构建阶段一般不在宿主机执行 check()；验证走 步骤四。
• 

步骤四：测试

说明：lycium/test.sh 需在 OpenHarmony 设备上运行（仓库内注释已写明）。Mac 上生成的 armeabi-v7a-build / arm64-v8a-build 内为 ELF + musl 测试程序，不能当 macOS 本地程序执行。

1. 按 lycium/CItools 在设备上准备 cmake / ctest / perl 等。
2. 将 tpc_c_cplusplus 同步到设备（含 thirdparty/、lycium/usr/、各库 …/<ARCH>-build/），路径尽量与编译机一致。
3. 在设备上 cd 到 lycium（使 LYCIUM_ROOT=pwd 与 test.sh 一致），执行 ./test.sh cJSON。PATH / LD_LIBRARY_PATH 由 test.sh 与 HPKCHECK 协同处理。
4. 仅手搓 cJSON 单库验证：在设备上进入 thirdparty/cJSON/cJSON-1.7.19/<ARCH>-build（<ARCH> 与你要测的架构一致），musl 不会默认加载当前目录的 .so，须先：

export LD_LIBRARY_PATH="$PWD:${LD_LIBRARY_PATH}"
ctest --timeout 40000 --output-on-failure

预期结果：19 条用例全部通过时输出 100% tests passed, 0 tests failed out of 19。异常时执行 ls -la libcjson.so* 检查 .so 实体与符号链接 是否随目录同步。

更多排错见下文 常见问题（FAQ）。

---

常见问题（FAQ）

SDK 与 macOS

Q：build.sh 提示 OHOS_SDK 未设置？
A：未导出 OHOS_SDK。写入 ~/.zshrc / ~/.bash_profile 后 source，或每次执行 export OHOS_SDK=/你的/sdk/根；根目录下须存在 native/llvm/bin。

Q：Apple Silicon 与 Intel Mac 怎么选 zip？
A：darwin-arm64 对应 M 系列，darwin-x86_64（或页面所述 amd64） 对应 Intel，与「关于本机」一致即可。

Q：which cmake / which hnpcli 为空？
A：核对 PATH 是否包含 $OHOS_SDK/native/build-tools/cmake/bin、$OHOS_SDK/toolchains（及 toolchains/bin）；hnpcli 有时在 toolchains 根目录。

Q：DCP 页面打不开？
A：按环境使用 VPN/内网；或改用组织允许的其他 SDK 获取方式（如 AtomGit 发布说明目录 等）。

lycium

Q：./build.sh 写 cjson 还是 cJSON？
A：与 thirdparty/ 下文件夹名一致，示例为 ./build.sh cJSON。

Q：多库编译报依赖错误？
A：./build.sh 的参数里需包含被依赖库，详见 lycium/README.md — 快速编译。

Q：source HPKBUILD 语法错、command not found？
A：多为 CRLF。sed 's/\r$//' HPKBUILD > HPKBUILD.lf && mv HPKBUILD.lf HPKBUILD，HPKCHECK 同理。

设备测试与 cJSON

Q：Mac 上对 *-build 跑 ctest 全挂？
A：那是 交叉编译的 ELF，不是 macOS 可执行文件。请在 OpenHarmony 设备上测，或另建 本机原生 build 目录。

Q：libcjson.so.1: No such file or directory？
A：musl 需 LD_LIBRARY_PATH 包含 $PWD（构建目录） 或 lycium/usr/cJSON/<ARCH>/lib。用 ./test.sh 时 HPKCHECK 已处理；手工测见 步骤四 第 4 步。

Q：./test.sh 找 arm64-v8a-build，设备上只有 armeabi-v7a-build？
A：test.sh 根据 getconf LONG_BIT 定 ARCH（64 → arm64-v8a）。64 位板需 同步 arm64-v8a-build，或在 Mac 上编出双架构后整仓同步。

Q：./tests 不能执行？
A：tests 是目录。用 ctest 或 ./cJSON_test。

Q：测试日志文件名里的 SDK 版本字符串不对？
A：lycium/test.sh 内 OHOS_SDK_VER 为示例值（如 OpenHarmony_4.0.8.1），需按你当前系统/SDK 改为一致，否则仅影响 log 文件名与展示，不挡 ctest 本身。

---

🎉 至此，完成了从零到一的通用三方库快速交叉编译构建工作。