macOS 上使用 OpenHarmony SDK 交叉编译指导

macOS 上使用 OpenHarmony SDK 交叉编译指导

本文以 cJSON 三方库为例，详细介绍如何通过 OpenHarmony SDK 在 macOS 平台进行交叉编译。

环境准备

SDK 准备

我们可以通过 OpenHarmony SDK 官方发布渠道[1] 下载对应 macOS 版本的 SDK。当前 OpenHarmony macOS 版本的 SDK 有两种架构：

• x86_64：适用于 Intel 芯片的 Mac
• arm64：适用于 Apple Silicon（M 系列芯片）的 Mac

我们需要根据自身设备的架构信息选择对应的版本。本示例使用的 Mac 设备是 M 系列芯片，架构为 arm64，因此选择 arm64 架构的 SDK。

cd ~                        # 进入到用户目录
curl -L https://cidownload.openharmony.cn/version/Master_Version/OpenHarmony_6.0.0.37/20250819111110/20250819111110-L2-SDK-MAC-M1-FULL.tar.gz --output ohos-sdk.tar.gz

下载完 SDK 后对其进行解压：

tar -zxvf ohos-sdk.tar.gz                           # 解压 OpenHarmony SDK
cd sdk/packages/ohos-sdk/darwin/                    # 进入到 darwin 目录
unzip native-darwin-arm64-4.0.10.5-Release.zip      # 解压 native 工具（C/C++ 库编译只需要 native 工具）

注意：请根据实际下载的 SDK 版本调整文件名和路径。

CMake 工具准备

cJSON 使用 CMake 构建系统进行编译，因此在编译前需要确保编译机上 CMake 能正常使用。

安装 CMake

原则上应使用 SDK 提供的 CMake，但当前 SDK 中的 CMake 是 x86_64 架构，在 arm64 架构的编译机上无法使用，因此需要在编译机上安装系统 CMake：

brew install cmake          # 通过 Homebrew 安装 CMake

添加 OHOS 平台支持

由于 CMake 官方不支持 OHOS 平台，在编译过程中会因为无法识别 OHOS 而导致编译错误。因此需要在系统 CMake 中添加 OHOS 平台配置文件：

# 查找 SDK 中的 OHOS.cmake 文件路径
SDK_OHOS_CMAKE=$(find ~/ohosdk -name "OHOS.cmake" | head -1)

# 查找系统 CMake 的 Platform 目录
CMAKE_PLATFORM_DIR=$(find $(brew --prefix)/Cellar/cmake -type d -name "Platform" | head -1)

# 复制 OHOS.cmake 到系统 CMake 目录
cp "$SDK_OHOS_CMAKE" "$CMAKE_PLATFORM_DIR/"

提示：如果使用 Homebrew 安装的 CMake，Platform 目录通常在 /opt/homebrew/Cellar/cmake/<version>/share/cmake/Modules/Platform/ 或 /usr/local/Cellar/cmake/<version>/share/cmake/Modules/Platform/。

快捷操作

cp /Users/jianguo/Desktop/ohosdk/native/build-tools/cmake/share/cmake-3.28/Modules/Platform/OHOS.cmake /opt/homebrew/Cellar/cmake/4.0.2/share/cmake/Modules/Platform/

CMake 版本要求

重要：确保项目的 CMakeLists.txt 中要求的最低 CMake 版本至少为 3.10，以避免版本兼容性问题：

cmake_minimum_required(VERSION 3.10)

如果项目要求的是较低版本（如 3.0 或 3.5），CMake 会报错提示版本不兼容，需要更新 CMakeLists.txt 文件。

cJSON 源码准备

适配三方库时，如果没有指定版本，建议使用三方库的稳定发布版本，不建议使用 master 分支的代码。本示例下载 cJSON v1.7.19 版本的源码：

cd ~/Workspace
git clone https://github.com/DaveGamble/cJSON.git -b v1.7.19

编译与安装

1. 新建编译目录

为了不污染源码目录，推荐在源码目录下新建一个独立的编译目录。本示例在 cJSON 目录下创建 build 目录：

cd cJSON                             # 进入 cJSON 目录
mkdir build && cd build              # 创建编译目录并进入

2. 配置交叉编译参数

执行 CMake 配置命令，生成 Makefile。重要：工具链文件路径必须指向具体的 .cmake 文件，而不是目录。

编译 64 位库（arm64-v8a）

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/ohosdk/native/build/cmake/ohos.toolchain.cmake \
      -DCMAKE_INSTALL_PREFIX=/path/to/install \
      -DOHOS_ARCH=arm64-v8a .. -L

编译 32 位库（armeabi-v7a）

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/ohosdk/native/build/cmake/ohos.toolchain.cmake \
      -DCMAKE_INSTALL_PREFIX=/path/to/install \
      -DOHOS_ARCH=armeabi-v7a .. -L

参数说明：

• CMAKE_TOOLCHAIN_FILE：交叉编译工具链配置文件路径，必须指向具体的 .cmake 文件（如 ohos.toolchain.cmake），不能只指定目录。
• CMAKE_INSTALL_PREFIX：安装路径，编译后的库文件和头文件将安装到此目录。
• OHOS_ARCH：目标 CPU 架构
  • arm64-v8a：64 位 ARM 架构（推荐）
  • armeabi-v7a：32 位 ARM 架构
• -L：显示 CMake 中可配置的项目列表

示例（请根据实际路径调整）：

cmake -DCMAKE_TOOLCHAIN_FILE=/Users/jianguo/Desktop/ohosdk/native/build/cmake/ohos.toolchain.cmake \
      -DCMAKE_INSTALL_PREFIX=/Users/jianguo/OpenHarmonyTpc/cJSON \
      -DOHOS_ARCH=arm64-v8a .. -L

常见错误：如果工具链文件路径只指定到目录而不是具体文件，CMake 会报错：Could not find toolchain file。确保路径指向 ohos.toolchain.cmake 文件。

3. 执行编译

CMake 配置成功后，会在 build 目录下生成 Makefile。执行 make 命令进行编译：

make

编译过程中可能会看到一些警告信息（如 clang: warning: argument unused during compilation），这些警告通常不影响编译结果。编译成功后会看到类似输出：

[100%] Built target fuzz_main

4. 验证编译结果

编译成功后，可以通过 file 命令查看生成的文件属性，验证交叉编译是否成功：

file libcjson.so.1.7.19

成功输出示例：

libcjson.so.1.7.19: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV),
dynamically linked, BuildID[sha1]=2178eadd53795baa889d6a728ad140d28948527c,
with debug_info, not stripped

如果看到 ARM aarch64 或 ARM, version 7 等 ARM 架构信息，说明交叉编译成功。

5. 安装库文件

编译成功后，执行 make install 将编译好的二进制文件和头文件安装到 CMake 配置的安装路径：

make install

安装完成后，可以查看安装目录结构：

ls <CMAKE_INSTALL_PREFIX>/
# 输出示例：
# include  lib

ls <CMAKE_INSTALL_PREFIX>/lib/
# 输出示例：
# cmake  libcjson.so  libcjson.so.1  libcjson.so.1.7.19  pkgconfig

测试验证

交叉编译完成后，需要对三方库进行测试验证。为了保证三方库功能的完整性，建议基于原生库的测试用例进行测试验证。

OpenHarmony 提供了一套可以在 OH 环境上进行 make、cmake、ctest 等操作的工具，具体请阅读 OH 测试环境配置[2] 文档。

cJSON 使用 ctest 方式进行测试，具体步骤如下：

1. 测试环境配置

请参考 OH 测试环境配置[3] 文档进行环境配置。

2. 准备测试资源

使用原生库的测试用例进行测试。为了保证测试时不进行编译操作，需要将整个编译的源码作为测试资源包推送到开发板，且需要保证三方库在开发板的路径与编译时路径一致：

tar -zcvf cJSON.tar.gz cJSON/

打包完资源后，通过 hdc[4] 工具将资源包推送到开发板：

cd /path/to/ohos-sdk/packages/ohos-sdk/darwin
unzip toolchains-darwin-arm64-4.0.10.5-Release.zip    # 解压 toolchain，hdc 工具在 toolchain 包中
export PATH=/path/to/ohos-sdk/packages/ohos-sdk/darwin/toolchains:$PATH
cd ~/Workspace
hdc file send cJSON.tar.gz /data/                      # 推送资源到开发板，确保设备已连接到编译机
hdc shell                                               # 进入开发板系统

在开发板上设置与编译时相同的路径：

# mkdir -p /Users/ohos
# cd /Users/ohos
# ln -s Workspace /data/                                # 系统根目录空间有限，建议通过软链接配置路径
# cd Workspace
# tar -zxf cJSON.tar.gz                                 # 解压测试资源

3. 执行测试

进入 cJSON 的编译目录 build，执行 ctest 测试命令：

cd /Users/ohos/Workspace/cJSON/build
ctest

测试结果示例：

Test project /Users/ohos/Workspace/cJSON/build
     Start  1: cJSON_test
 1/19 Test  #1: cJSON_test .......................   Passed    0.02 sec
     Start  2: parse_examples
 2/19 Test  #2: parse_examples ...................   Passed    0.02 sec
     Start  3: parse_number
 3/19 Test  #3: parse_number .....................   Passed    0.02 sec
 ...
19/19 Test #19: minify_tests .....................   Passed    0.01 sec

100% tests passed, 0 tests failed out of 19

Total Test time (real) =   0.37 sec

所有测试用例通过，说明交叉编译和库功能正常。

常见问题

1. CMake 版本兼容性错误

错误信息：

CMake Error: Compatibility with CMake < 3.5 has been removed from CMake.

解决方法：更新项目的 CMakeLists.txt 文件，将最低版本要求更新为 3.10 或更高：

cmake_minimum_required(VERSION 3.10)

2. 找不到工具链文件

错误信息：

CMake Error: Could not find toolchain file: /path/to/cmake

解决方法：确保 CMAKE_TOOLCHAIN_FILE 参数指向具体的 .cmake 文件，而不是目录：

# 错误示例
-DCMAKE_TOOLCHAIN_FILE=/path/to/ohosdk/native/build/cmake

# 正确示例
-DCMAKE_TOOLCHAIN_FILE=/path/to/ohosdk/native/build/cmake/ohos.toolchain.cmake

3. CMake 无法识别 OHOS 平台

错误信息：

CMake Error: CMAKE_SYSTEM_NAME is "OHOS" but CMAKE_SYSTEM_PROCESSOR is not set.

解决方法：确保已将 SDK 中的 OHOS.cmake 文件复制到系统 CMake 的 Platform 目录。参考本文"CMake 工具准备"章节。

4. 编译警告信息

编译过程中可能出现以下警告，通常不影响编译结果：

• clang: warning: argument unused during compilation: '--gcc-toolchain=...'
• warning: 'long long' is an extension when C99 mode is not enabled

这些警告可以忽略，或者根据项目需求调整编译选项。

最佳实践

1. 使用稳定版本：优先使用三方库的稳定发布版本，避免使用 master 分支。
2. 独立编译目录：在源码目录外创建独立的 build 目录，避免污染源码。
3. 版本管理：记录使用的 SDK 版本、三方库版本和编译参数，便于后续维护。
4. 测试验证：编译完成后务必进行测试验证，确保库功能正常。
5. 路径管理：使用环境变量或配置文件管理 SDK 路径，避免硬编码。

参考资源

• OpenHarmony SDK 官方发布渠道[5]
• macOS 上使用 OpenHarmony SDK 交叉编译指导[6]
• OH 测试环境配置[7]
• hdc 使用指导[8]
• CMake 官方文档[9]

文档版本：v1.1

参考资料

[1]

官方发布渠道: https://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist

[2]

OH 测试环境配置: https://gitcode.com/openharmony-sig/tpc_c_cplusplus/blob/master/lycium/CItools/README_zh.md

[3]

OH 测试环境配置: https://gitcode.com/openharmony-sig/tpc_c_cplusplus/blob/master/lycium/CItools/README_zh.md

[4]

hdc: https://gitcode.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-toolchain-hdc-guide.md#hdc使用指导

[5]

OpenHarmony SDK 官方发布渠道: https://ci.openharmony.cn/workbench/cicd/dailybuild/dailylist

[6]

macOS 上使用 OpenHarmony SDK 交叉编译指导: https://gitcode.com/openharmony-sig/tpc_c_cplusplus/blob/master/docs/adapter_mac.md

[7]

OH 测试环境配置: https://gitcode.com/openharmony-sig/tpc_c_cplusplus/blob/master/lycium/CItools/README_zh.md

[8]

hdc 使用指导: https://gitcode.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-toolchain-hdc-guide.md#hdc使用指导

[9]

CMake 官方文档: https://cmake.org/documentation/