使用 vcpkg 为 HarmonyOS 构建 C/C++ 库

作者：Jörg Bornemann | May 19, 2026 6:21:43 AM

我们目前正在将 Qt 移植到HarmonyOS。我们的持续集成 (CI) 和开发机器需要一些专为 HarmonyOS 构建的第三方库。为该平台交叉编译开源 C 和 C++ 库一直是一个手动且容易出错的过程。每个库都有自己的构建系统，如 CMake、Autotools 或 Meson。每个库都需要单独处理才能生成适用于 OHOS 目标的正确二进制文件。我们一直在维护一个手写的 shell 脚本，该脚本逐个构建库，并针对每个库的交叉编译问题进行相应的变通处理。

有了我们修改后的 vcpkg，现在只需一条命令即可完成该脚本的构建。

为什么选择 vcpkg？

vcpkg 是微软的开源 C/C++ 包管理器。它已经可以处理 Android、iOS 和其他嵌入式目标的交叉编译。将 HarmonyOS 添加为一流平台意味着 OHOS 开发者无需对每个库的构建系统进行修改，即可使用整个 vcpkg 移植目录。

Qt 从某些版本开始就支持根据 vcpkg 提供的第三方库进行构建，并且Qt 6.11 引入了一个配置选项，允许以清单模式运行 vcpkg 并自动安装依赖项。

遗憾的是，vcpkg 之前不支持 HarmonyOS，但我们在我们的分叉中解决了这一缺陷。

我们的分叉新增功能

这些更改很小且重点突出。vcpkg-tool 分叉（仅提交一次）将 ohos 添加为可识别的平台标识符。请注意，出于历史原因，我们使用 OHOS 作为 HarmonyOS 的同义词。SDK 的工具链文件也采用了相同的做法。 vcpkg 注册表分叉新增了以下内容：

  • 一个 OHOS 工具链文件，用于委托给 HarmonyOS SDK 的原生工具链

  • 三个社区三元组：arm64-ohos、arm-ohos、x64-ohos

  • 平台检测功能，使得类似“supports”:“!uwp”这样的端口表达式可以包含或排除 OHOS

  • 针对需要 OHOS 特定调整的库的端口文件补丁（目前包括：libpng、fontconfig 和 ICU）

     

入门指南

前提条件

  • 带有原生工具链的 HarmonyOS SDK（API 12+）

  • CMake 3.20+, Ninja

  • Git

     

第 1 步：从源代码构建 vcpkg-tool

 

上游 vcpkg-tool 尚不支持 OHOS，因此我们从自己的分叉构建：

git clone https://git.qt.io/qtbuildsystem/vcpkg-tool.git -b ohos ~/vcpkg-tool
cd ~/vcpkg-tool
cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF
ninja build

第 2 步：设置 vcpkg 注册表

git clone https://git.qt.io/qtbuildsystem/vcpkg.git -b ohos ~/vcpkg

cd ~/vcpkg

cp ~/vcpkg-tool/build/vcpkg ./

export VCPKG_ROOT=~/vcpkg

第 3 步：设置 SDK 路径

根据 HarmonyOS 命令行工具的安装位置：

 export OHOS_SDK_ROOT=~/.local/opt/ohos/command-line-tools/sdk/default/openharmony 

该目录应包含native/build/cmake/ohos.toolchain.cmake。

第 4 步：安装库

要将库安装到通用安装根目录，我们使用 vcpkg 的“经典模式”（而非“清单模式”）：

 vcpkg install --triplet arm64-ohos libpng libjpeg-turbo ... 

完成！vcpkg 会解析依赖关系，下载源代码，使用 OHOS 工具链交叉编译所有内容，并将头文件、库文件和 CMake 配置文件安装到 $VCPKG_ROOT/installed/arm64-ohos 目录。

第 5 步：在项目中使用

或使用 vcpkg 自带的 CMake 集成：

cmake -S . -B build \

-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \

-DVCPKG_TARGET_TRIPLET=arm64-ohos

要指示 Qt 使用 vcpkg，请将 QT_USE_VCPKG=ON 传递给 configure。Qt 的构建系统将自动查找 vcpkg 工具链文件的位置并使用它。

可用的三元组

以下三元组适用于 HarmonyOS：

三进制 OHOS ABI
arm64-ohos arm64-v8a
arm-ohos armeabi-v7a
x64-ohos x86_64

 

所有三元组都会生成动态链接库，其 soname 不带版本号。

向上游提交

我们正在努力将这些更改提交到官方的 vcpkg 和 vcpkg-tool 代码库。我们的目标是提供标准的社区三元组，使 OHOS 与 Android、iOS 和其他交叉编译平台一起成为 vcpkg 的一流目标平台。

一旦合并到上游，就不需要任何分叉。标准的 vcpkg 安装将开箱即用地支持 OHOS。

结论

将 HarmonyOS 支持添加到 vcpkg 可以消除目前每个 OHOS C/C++ 开发人员面临的每个库单独进行交叉编译的负担。无需为每个依赖项维护自定义构建脚本，构建配方都位于一个由社区维护的仓库中。

如果您正在为 HarmonyOS 构建原生库，请尝试我们的 vcpkg 分叉，并告诉我们它的使用体验。
查看完整帖子