[鸿蒙PC命令行移植适配] 移植 oniguruma 到鸿蒙PC的完整实践

本文介绍了如何将正则表达式库 oniguruma 适配到鸿蒙PC平台。主要内容包括环境配置、SDK安装、交叉编译流程，以及生成静态库、头文件等产物的方法。文章提供了详细的前置条件、系列索引和操作步骤，帮助开发者完成鸿蒙PC生态的三方库移植，支持HNP打包和验证。适用于macOS/Windows/Linux平台的开发者参考。

Alex

8人浏览 · 2026-06-05 00:04:34

Alex · 2026-06-05 00:04:34 发布

欢迎加入【开源鸿蒙PC社区】，一起共建鸿蒙化C/C++三方库生态。

前言

在为开源鸿蒙PC（OpenHarmony PC）适配 Linux 命令行工具与基础库时，正则表达式库是许多上层应用（如rust三方库bat）的基础依赖。oniguruma 是一个高性能、功能丰富的正则表达式库，使用 Autotools 构建，通过 configure/make 即可完成交叉编译。本文将介绍如何将 oniguruma 适配到鸿蒙PC平台，提供可复用的静态库、头文件、pkg-config 及验证程序，并支持 HNP 打包。

前置条件

环境/工具	描述
适配库	`oniguruma`
开源协议	`BSD-2-Clause`
源码版本	`6.9.10`
目标平台	鸿蒙PC
操作系统平台	`macOS`
原仓库地址	https://github.com/kkos/oniguruma
鸿蒙化适配仓库地址	https://atomgit.com/OpenHarmonyPCDeveloper/ohos-oniguruma
鸿蒙应用集成oniguruma三方库源代码仓库地址	https://atomgit.com/unisources/OnigurumaDemo
在`Ubuntu`中搭建鸿蒙PC 三方库交叉编译构建开发环境	https://blog.csdn.net/zl392321162/article/details/159284760
在 `macOS` 中搭建鸿蒙 PC 三方库交叉编译开发环境	https://blog.csdn.net/zl392321162/article/details/159284830
`Windows 10` 上安装和使用 `WSL 2`、安装 `Ubuntu 24` 详细指南	https://blog.csdn.net/yyz_1987/article/details/148545443
鸿蒙 PC 命令行适配指南（Mac 版）	https://blog.csdn.net/qq_39132095/article/details/154796658
鸿蒙 PC 生态三方软件移植：开发环境搭建及三方库移植指南	https://blog.csdn.net/yyz_1987/article/details/154794871
OpenHarmony Linux 命令行工具适配实战：基于 `Cursor × WSL` 的 `tree 2.2.1` 交叉编译与 `HNP` 打包全流程指南	https://weishuo.blog.csdn.net/article/details/155140843
社区维护的鸿蒙 PC 生态命令行工具构建框架 `lycium_plusplus`	https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus
鸿蒙PC端二进制文件签名命令行使用指南	https://blog.csdn.net/jianguo888888/article/details/156644386
`hnp`包验证环境	https://bxming.blog.csdn.net/article/details/155073889

系列索引

篇章	标题	内容
第一篇	概述与环境配置	Lycium 概念、构建机要求、OHOS SDK 配置
第二篇	项目结构与适配目录创建	目录结构、community vs thirdparty、创建适配目录
第三篇	HPKBUILD 编写详解	元数据字段、过程函数、三种构建系统写法
第四篇	构建执行与产物获取	构建流程、日志分析、多库递归、HAP 集成
第五篇	流程图与角色职责	完整流程图、各角色职责、协作时序
第六篇	关键注意事项与最佳实践	依赖管理、架构超集、日志调试、外部适配仓
第七篇	快速参考与模板	入门步骤、模板、完整案例、检查清单

一、环境配置

1 OpenHarmony SDK 安装

1.1 下载 SDK（环境搭建）

在浏览器中打开 DCP 每日构建列表：https://dcp.openharmony.cn/workbench/cicd/dailybuild/dailylist
在列表中按本机操作系统选择对应产物（名称随版本变化，以页面为准）：

开发机系统	选择产物（关键词）
Windows / Linux	`ohos-sdk-full`（OHOS 全量 SDK，用于交叉编译）
macOS	`mac-sdk-full`（Mac 版 SDK 包）

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

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

Windows 请使用资源管理器或 7-Zip 等工具解压对应 .zip / .tar.gz 包。

说明：每日构建会更新版本与文件名，不要固定使用旧文档中的直链；以 DCP 页面上当前可下载的 SDK 包为准。解压后若顶层目录名不是 ohos-sdk，可将该目录移动或软链为 ~/ohos-sdk（或 Windows 下放到固定路径），与下文 OHOS-SDK 配置一致。

再进入 ohos-sdk 根目录解压（文件名以 darwin 目录下为准，下例版本号仅作演示）：

cd ~/ohos-sdk   # Linux / macOS；Windows 请先 cd 到 OHOS_SDK 目录
unzip native-darwin-arm64-6.0.0.46-Beta1.zip
unzip toolchains-darwin-arm64-6.0.0.46-Beta1.zip

Windows 可对两个 zip 右键解压到当前文件夹，或使用 tar/Expand-Archive 等工具解压到 ohos-sdk 根目录。

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

1.2 SDK 目录结构

ohos-sdk/
├── native/
│   ├── llvm/bin/          # 编译器工具链
│   ├── sysroot/           # 系统根目录（头文件和库）
│   └── build-tools/       # 构建工具
└── toolchains/
    └── hnpcli            # HNP打包工具

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"
export PATH="$OHOS_SDK/toolchains/bin:$PATH"

# 验证
source ~/.zshrc  # 或 source ~/.bash_profile

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

二、适配步骤

1. 分析`oniguruma`构建特性

Oniguruma 是一个功能丰富的正则表达式库，由 kkos 维护，主打多字符编码支持（UTF-8/16/32、EUC-JP、Shift_JIS 等），兼容 POSIX 正则语法，同时支持 Ruby、Perl 等风格的扩展语法，广泛用于 Ruby、PHP 等语言及各类工具中。

核心优势：

原生支持多种字符编码，无需额外转码；
支持多种正则语法风格（POSIX Basic/Extended、Ruby、Perl、Java 等）；
轻量级、可嵌入，提供 C 语言 API，易于集成到其他项目；
支持正则表达式的实时编译、匹配、替换、分割等核心操作。

2. 创建适配项目

参考前置条件列表完成lycium_plusplus交叉框架编译环境搭建，以及lycium_plusplus交叉框架代码克隆，在lycium_plusplus/thirdparty创建目标库oniguruma适配目录为ohos_oniguruma。

为什么是ohos_oniguruma？为了和源库名称做区分，表示该库用于ohos设备。

ohos_oniguruma创建可以借助编辑器工具（如VSCode）或者使用文件夹在lycium_plusplus/thirdparty目录下创建目标库适配目录ohos_oniguruma，也可以执行以下命令进行创建。

# 我将交叉编译框架克隆在根目录，此处可改为正确的目录地址
cd ~/lycium_plusplus/thirdparty
mkdir ohos_oniguruma

3. 编写`HPKBUILD`

然后将lycium/template/HPKBUILD拷贝到thirdparty/ohos_oniguruma目录下，HPKBUILD是lycium交叉编译框架完成编译构建的核心配置文件，定义包的元信息、依赖、构建和打包逻辑。需要根据模板在HPKBUILD开头声明oniguruma的基本信息，这些字段被lycium用于下载、组织和记录：

# lycium_plusplus/thirdparty/ohos-oniguruma/HPKBUILD
pkgname=oniguruma # 库名
pkgver=6.9.10 # 库版本
pkgrel=0 # 发布号
pkgdesc="A regular expressions library" # 库描述
url="https://github.com/kkos/oniguruma" # 官网链接
archs=("arm64-v8a") # cpu 架构
license=("BSD-2-Clause")
depends=() # 依赖库的目录名 必须保证被依赖的库的archs是当前库的archs的超集
makedepends=() # 构建库时的依赖工具->需要用户安装的工具
source="https://github.com/kkos/oniguruma/archive/refs/tags/v${pkgver}.tar.gz" # 库源码下载链接

downloadpackage=true # 是否自动下载压缩包，如若不写默认 true. (应对一些特殊情况，代码只能 git clone (项目中依赖 submoudle ))
autounpack=true # 是否自动解压，如若不写默认 true, 如果为 false 则需要用户在 prepare 函数中自行解压
buildtools=cmake # 编译方法, 暂时支持cmake, configure, make等, 是什么就填写什么. 如若不写默认为cmake.

builddir=oniguruma-${pkgver} # 源码压缩包解压后目录名 编译目录名
packagename=${builddir}.tar.gz # 压缩包名

字段	配置值	用途
`pkgname`	`oniguruma`	`pkgname=oniguruma`：包名，用于在 `LYCIUM_ROOT/usr/` 下创建安装目录、标识依赖关系。
`pkgver`	`6.9.10`	`pkgver=6.9.10`：上游版本号，与 `https://github.com/kkos/oniguruma` 仓库最新发行版本保持一致。
`pkgrel`	`0`	`pkgrel=0`：包发布号，当同一上游版本需要重新打包时递增，首次适配为 0。
`pkgdesc`	-	包的简短描述，取自 `oniguruma` 官方 `README`。
`url`	-	上游项目主页 `URL`。
`archs`	`("arm64-v8a")`	`archs=("arm64-v8a")`：声明支持的架构数组。此处仅列出 `arm64-v8a`，但代码内部实际也处理了 `armeabi-v7a` 和 `x86_64`，此处是声明"主要支持"而非"仅支持"。当前鸿蒙 PC 设备为 `arm64` 架构，因此必须配置`arm64-v8a`。
`license`	`("BSD-2-Clause")`	`oniguruma` 采用 `BSD-2-Clause`协议。
`depends`	`()`	无其他依赖库。
`makedepends`	`()`	无编译时依赖。
`source`	`refs/tags/${pkgver}.tar.gz`	源码包下载地址。使用 `${pkgver}` 变量拼接，下载 `oniguruma 6.9.10` 的 `release tarball`。
`downloadpackage`	`true`	`downloadpackage=true`：告诉 `lycium` 构建系统自动下载 `source` 指定的源码包。如果设置为`false`需要在目标库目录下手动下载源码包。
`autounpack`	`true`	`autounpack=true`：下载后自动解压，无需手动解压步骤。如果设置为`false`需要手动解压。
`buildtools`	`cargo`	`buildtools=make`：声明构建工具类型。
`builddir`	`${pkgname}-${pkgver}`	`builddir=${pkgname}-${pkgver}`：解压后的源码目录名。`prepare()`/`build()`/`package()` 均通过 `cd $builddir` 进入此目录。
`packagename`	`${builddir}.tar.gz`	`packagename=${builddir}.tar.gz`：源码包文件名，用于校验/定位。

4 HNP 打包配置

在lycium_plusplus/thirdparty/ohos-oniguruma目录下创建hnp.json文件，因为在HPKBUILD中存在archive函数，用于将产物打包为 output/<arch>/<pkgname>_<ver>.tar.gz，或执行 HNP 打包，详细介绍可参考系列索引-构建执行与产物获取。

{
    "type": "hnp-config",
    "name": "oniguruma",
    "version": "6.9.10",
    "install": {}
}

5 交叉编译并解决可能存在的问题

HPKBUILD中函数不做改变，在lycium_plusplus/lycium目录下打开终端工具，输入./build.sh ohos-oniguruma进行第一次交叉编译。

如果提示ALL JOBS DONE!!!表示当前交叉编译没有问题，编译后的产物，可以在lycium/usr/目录和out/arm64-v8目录下查看。

三、使用AtomCode快速完成鸿蒙应用集成oniguruma

oniguruma是一个三方库，对于三方库，我们可以通过将三方库集成到鸿蒙应用中来验证，接下来使用AtomCode来完成在鸿蒙应用中集成oniguruma三方库，可以参考手把手教你在鸿蒙应用中集成鸿蒙化abseil-cpp三方库，Demo已开源博文创建鸿蒙应用程序，并将交叉编译后的lycium/usr/oniguruma拷贝到/OnigurumaDemo/entry/src/main/cpp/thirdparty目录下。然后在OnigurumaDemo目录下打开终端工具，执行atomcode启动工具，并输入集成指令（当然这个指令不是固定的，可以按照自己的喜欢来写）已经完成oniguruma三方库交叉编译，现在需要在当前应用中集成该三方库，并完成对应的功能验证，交叉编译产物已经放在entry/src/main/cpp/thirdparty目录下。先梳理oniguruma提供的能力，然后完成编码。。

使用AtomCode完成示例项目代码编写后，在DevEco Studio工具中为项目进行签名，然后将鸿蒙PC与开发机连接，使用DevEco Studio安装运用应用，项目源代码OnigurumaDemo。

四. FAQ

问题：将lycium/usr/oniguruma/bin/onig-config文件发送到鸿蒙PC，签名执行后提示不是有效的elf文件。

原因：oniguruma是一个三方库，并没有生成可执行的二进制文件，即使你把bin/onig-config发送到鸿蒙PC也是不行的，会提示不是有效的elf文件，因为onig-config是一个shell 脚本，类似 pkg-config，输出编译/链接 oniguruma 需要的 -I / -L / -l 等；部分构建系统会调用它。

解决方法：可以参考手把手教你在鸿蒙应用中集成鸿蒙化abseil-cpp三方库，Demo已开源博文在鸿蒙应用中集成oniguruma三方库。