Building C/C++ libraries for HarmonyOS with vcpkg

Liang Qi

https://www.qt.io/blog/building-libraries-for-harmonyos-with-vcpkg

Building C/C++ libraries for HarmonyOS with vcpkg

Summarize

Jörg Bornemann
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.

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

Why 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.

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.

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

What our fork adds

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:

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

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

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

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

Getting started

Prerequisites

HarmonyOS SDK with native toolchain (API 12+)

CMake 3.20+, Ninja

Git

Step 1: Build vcpkg-tool from source

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

git clone https://git.qt.io/jobor/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

git clone https://git.qt.io/jobor/vcpkg.git -b ohos ~/vcpkg
cd ~/vcpkg
cp ~/vcpkg-tool/build/vcpkg ./
export VCPKG_ROOT=~/vcpkg

Step 3: Set the SDK path

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

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

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

Step 4: Install libraries

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

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.

Step 5: Use in your project

Or use vcpkg's own CMake integration:

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.

Available triplets

The following triplets are available for 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.

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.

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

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.

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

For Chinese version, you can read this in Huawei Developer Forum.

Liang Qi

Jörg Bornemann(Qt for HarmonyOS team) has created an issue for vcpkg to upstream our OHOS changes: https://github.com/microsoft/vcpkg/issues/51302 .

Liang Qi

Found a fork, https://gitcode.com/OpenHarmonyPCDeveloper/ohos_vcpkg/ and a blog about it, https://blog.csdn.net/qq8864/article/details/160148325 .