Building C/C++ libraries for HarmonyOS with vcpkg

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

Apr 10, 2026 byJörg Bornemann

​2026年4月10日，约尔格·博内曼

We're currently working on porting Qt to HarmonyOS. For our CI and developer machines, we need a number of third-party libraries built for HarmonyOS. Cross-compiling open-source C and C++ libraries for this platform has been a manual, error-prone process. Each library has its own build system, whether CMake, Autotools, or Meson. Each needs individual attention to produce correct binaries for the OHOS target. We have been maintaining a hand-written shell script that builds libraries one by one, with per-library workarounds for cross-compilation quirks.

​我们目前正在将Qt移植到HarmonyOS。对于我们的CI和开发人员机器，我们需要为HarmonyOS构建许多第三方库。为这个平台交叉编译开源C和C++库是一个手动的、容易出错的过程。每个库都有自己的构建系统，无论是CMake、Autotools还是Meson。每个都需要单独注意为OHOS目标生成正确的二进制文件。我们一直在维护一个手写的shell脚本，该脚本逐一构建库，并为每个库提供交叉编译怪癖的解决方法。

With our vcpkg fork, that script is now a single command.

通过我们的vcpkg分支，该脚本现在是一个命令。

Why vcpkg?

为什么选择vcpkg？

vcpkg is Microsoft's open-source C/C++ package manager. It already handles cross-compilation for Android, iOS, and other embedded targets. Adding HarmonyOS as a first-class platform means the entire vcpkg port catalog becomes available to OHOS developers without per-library build system surgery.

vcpkg是微软的开源C/C++包管理器。它已经处理了Android、iOS和其他嵌入式目标的交叉编译。将HarmonyOS添加为一流平台意味着整个vcpkg端口目录可供OHOS开发人员使用，而无需进行每个库的构建系统操作。

Qt supports building against third-party libraries provided by vcpkg since some versions, and Qt 6.11 introduces a configure option to run vcpkg in manifest mode and automatically install dependencies.

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

Unfortunately, vcpkg did not support HarmonyOS, but we addressed this shortcoming in our fork.

不幸的是，vcpkg不支持HarmonyOS，但我们在fork中解决了这个缺点。

What our fork adds

我们的fork添加了什么

The changes are small and focused. The vcpkg-tool fork (one commit) adds ohos as a recognized platform identifier. Note that for historical reasons we use OHOS as a synonym for HarmonyOS. The SDK's toolchain file does the same. The vcpkg registry fork adds:

这些变化很小，而且很集中。vcpkg工具分支（一次提交）将ohos添加为可识别的平台标识符。请注意，由于历史原因，我们将OHOS用作HarmonyOS的同义词。SDK的工具链文件也有同样的功能。vcpkg注册表分支添加了：

• An OHOS toolchain file that delegates  to the HarmonyOS SDK's native toolchain

• 委托给HarmonyOS SDK的本机工具链的OHOS工具链文件

• Three community triplets: arm64-ohos, arm-ohos, x64-ohos

• 三个社区三胞胎：arm64 ohos，arm ohos，x64 ohos

• Platform detection so that port expressions like "supports": "!uwp" can include or exclude OHOS

• 平台检测，使端口表达式如“supports”：“！uwp”可以包含或排除OHOS

• Portfile patches for libraries that need OHOS-specific adjustments (for now: libpng, fontconfig, ICU)

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

Getting started

新手入门

Prerequisites

前置条件

• HarmonyOS SDK with native toolchain (API 12+)

• 带有本机工具链的HarmonyOS SDK（API 12+）

• CMake 3.20+, Ninja

• Git

Step 1: Build vcpkg-tool from source

步骤1：从源代码构建vcpkg工具

The upstream vcpkg-tool does not yet recognize OHOS, so we build from our fork:

上游的vcpkg工具还不能识别OHOS，所以我们从我们的fork构建：

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

Step 2: Set up the vcpkg registry

步骤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

Step 3: Set the SDK path

步骤3：设置SDK路径

Depending on where you've installed the HarmonyOS command line tools:

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

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

The directory should contain native/build/cmake/ohos.toolchain.cmake.

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

Step 4: Install libraries

步骤4：安装库

To install the libraries into a common install root, we use vcpkg's "classic mode" (as opposed to "manifest mode"):

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

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

That is it. vcpkg resolves dependencies, downloads sources, cross-compiles everything with the OHOS toolchain, and installs headers, libraries, and CMake config files into $VCPKG_ROOT/installed/arm64-ohos.

就是这样。vcpkg解析依赖关系，下载源代码，使用OHOS工具链交叉编译所有内容，并将头文件、库和CMake配置文件安装到$vcpkg_ROOT/installed/arm64-OHOS中。

Step 5: Use in your project

步骤5：在项目中使用

Or use vcpkg's own CMake integration:

或者使用vcpkg自己的CMake集成：

cmake -S . -B build \

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

    -DVCPKG_TARGET_TRIPLET=arm64-ohos

To instruct Qt to use vcpkg, pass QT_USE_VCPKG=ON to configure. Qt's build system will automatically figure out where the vcpkg toolchain file is and use it.

要指示Qt使用vcpkg，请传递QT_USE_VCPKG=ON进行配置。Qt的构建系统会自动找出vcpkg工具链文件的位置并使用它。

Available triplets

可用的三元组

The following triplets are available for HarmonyOS:

HarmonyOS提供以下三元组：

Triplet	OHOS ABI
arm64-ohos	arm64-v8a
arm-ohos	armeabi-v7a
x64-ohos	x86_64

All triplets produce dynamically linked libraries with unversioned sonames.

所有三元组都会生成具有未版本化soname的动态链接库。

Upstreaming

上传

We are working to upstream these changes to the official vcpkg and vcpkg-tool repositories. The goal is to provide standard community triplets, making OHOS a first-class vcpkg target alongside Android, iOS, and the other cross-compilation platforms.

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

Once upstreamed, no forks will be needed. A standard vcpkg installation will support OHOS out of the box.

一旦上传，就不需要forks了。标准的vcpkg安装将支持OHOS开箱即用。

Conclusion

结论

Adding HarmonyOS support to vcpkg eliminates the per-library cross-compilation burden that every OHOS C/C++ developer faces today. Instead of maintaining custom build scripts for each dependency, the build recipes live in a community-maintained repository.

在vcpkg中添加HarmonyOS支持消除了每个OHOS C/C++开发人员今天面临的每个库的交叉编译负担。构建配方位于社区维护的存储库中，而不是为每个依赖项维护自定义构建脚本。

If you are building native libraries for HarmonyOS, give our vcpkg fork a try and let us know how it works for you.

如果正在为HarmonyOS构建原生库，请尝试我们的vcpkg fork，并让我们知道它是如何工作的。