欢迎加入【开源鸿蒙PC社区】，一起共建鸿蒙化C/C++三方库生态。
前言
bat（一款增强版的cat命令行工具）的源代码仓库，核心定位是 “带翅膀的cat克隆工具”，用 Rust 编写，主打语法高亮、Git 集成等特性，是传统cat命令的现代化替代方案。
前置条件
| 环境/工具 | 描述 |
|---|---|
| 适配库 | bat |
| 开源协议 | "MIT" "Apache-2.0" |
| 源码版本 | 0.26.1 |
| 目标平台 | 鸿蒙PC |
| 依赖项 | oniguruma |
| 操作系统平台 | macOS |
| 原仓库地址 | https://github.com/sharkdp/bat |
| 鸿蒙化适配仓库地址 | https://atomgit.com/OpenHarmonyPCDeveloper/ohos-bat |
在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 |
| 支持Rust三方库适配的扩展lycium框架 | https://atomgit.com/CodexBai/lycium_plusplus.git |
| 鸿蒙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 集成 |
| 第五篇 | 流程图与角色职责 | 完整流程图、各角色职责、协作时序 |
| 第六篇 | 关键注意事项与最佳实践 | 依赖管理、架构超集、日志调试、外部适配仓 |
| 第七篇 | 快速参考与模板 | 入门步骤、模板、完整案例、检查清单 |
| 第八篇「番外」 | 扩展lycium框架使其满足rust三方库适配 | 不改变框架原有设计，增加Rust三方库适配能力 |
一、环境配置
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.gzWindows 请使用资源管理器或 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 目录unzipnative-darwin-arm64-6.0.0.46-Beta1.zipunziptoolchains-darwin-arm64-6.0.0.46-Beta1.zipWindows 可对两个 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 路径exportOHOS_SDK=~/ohos-sdk# 添加到 PATHexportPATH="$OHOS_SDK/native/llvm/bin:$PATH"exportPATH="$OHOS_SDK/native/build-tools/cmake/bin:$PATH"exportPATH="$OHOS_SDK/toolchains/bin:$PATH"# 验证source~/.zshrc# 或 source ~/.bash_profile1.4 验证 SDK 配置
# 检查 SDK 路径echo$OHOS_SDK# 检查工具是否在 PATH 中whichclangwhichcmakewhichhnpcli# 检查 SDK 工具目录ls$OHOS_SDK/native/llvm/bin/ls$OHOS_SDK/native/build-tools/cmake/bin/ls$OHOS_SDK/toolchains/# 验证工具版本clang--versioncmake--versionhnpcli--version2 Rust 工具链安装
2.1 安装 Rust
# 安装 Rust（如果未安装）curl--proto'=https'--tlsv1.2-sSfhttps://sh.rustup.rs|shsource~/.cargo/env# 验证安装rustc--versioncargo--version2.2 配置 Rust 环境变量
编辑~/.zshrc（如果使用 zsh）或~/.bash_profile（如果使用 bash）：
# Rust 环境变量（通常由 rustup 自动添加）source~/.cargo/env# 验证source~/.zshrc# 或 source ~/.bash_profilerustc--versioncargo--version二、适配步骤
1. 分析bat构建特性
bat由Rust语言编写，使用Cargo作为构建系统。
核心特性
- 语法高亮：支持海量编程语言、标记语言的语法高亮（如 Rust、Python、JSON、Markdown 等），让代码 / 文本在终端中更易读。
- Git 集成：能与 Git 交互，在输出内容旁标注文件相对于 Git 索引的修改（如新增 / 删除行），方便开发者查看代码变更。
- 显示不可打印字符：通过
-A/--show-all选项可高亮显示空白符、制表符、换行符等不可打印字符，排查格式问题更高效。 - 自动分页：若输出内容超过一屏，会自动通过分页器（如
less）展示；也可通过--paging=never禁用，完全兼容cat的无分页行为。 - 完全兼容 cat：可作为
cat的无缝替代品：支持文件拼接、从标准输入读取、重定向输出等，非交互式场景下（如管道 / 重定向）会自动降级为纯文本输出。
2. 创建适配项目
参考前置条件列表完成lycium_plusplus交叉框架编译环境搭建，以及lycium_plusplus交叉框架代码克隆，在lycium_plusplus/RustAdapt创建目标库bat适配目录为ohos-bat。
为什么是
ohos-bat？为了和源库名称做区分，表示该库用于ohos设备。
ohos-bat创建可以借助编辑器工具（如VSCode）或者使用文件夹在lycium_plusplus/RustAdapt目录下创建目标库适配目录ohos-bat，也可以执行以下命令进行创建。
# 我将交叉编译框架克隆在根目录，此处可改为正确的目录地址cd~/lycium_plusplus/RustAdaptmkdirohos-bat3. 编写HPKBUILD
然后将lycium/template/HPKBUILD.cargo拷贝到RustAdapt/ohos_bat目录下，并重命名为HPKBUILD，HPKBUILD是lycium交叉编译框架完成编译构建的核心配置文件，定义包的元信息、依赖、构建和打包逻辑。需要根据模板在HPKBUILD开头声明bat的基本信息，这些字段被lycium用于下载、组织和记录：
# lycium_plusplus/RustAdapt/ohos-bat/HPKBUILDpkgname=bat# 库名pkgver=0.26.1# 库版本pkgrel=0# 发布号pkgdesc="A cat(1) clone with wings - syntax highlighting"# 库描述url="https://github.com/sharkdp/bat"# 官网链接archs=("arm64-v8a")# cpu 架构license=("MIT""Apache-2.0")depends=("oniguruma")# 依赖库的目录名 必须保证被依赖的库的archs是当前库的archs的超集makedepends=("cargo""rustc")# 构建库时的依赖工具->需要用户安装的工具source="https://github.com/sharkdp/bat/archive/refs/tags/v${pkgver}.tar.gz"# 库源码下载链接downloadpackage=true# 是否自动下载压缩包，如若不写默认 true. (应对一些特殊情况，代码只能 git clone (项目中依赖 submoudle ))autounpack=true# 是否自动解压，如若不写默认 true, 如果为 false 则需要用户在 prepare 函数中自行解压buildtools=cargo# 编译方法: cmake(默认) | configure | cargo | 其它则不在此注入 buildargs，由 build() 自行处理builddir=bat-${pkgver}# 源码压缩包解压后目录名 编译目录名packagename=${builddir}.tar.gz# 压缩包名| 字段 | 配置值 | 用途 |
|---|---|---|
pkgname | bat | pkgname=bat：包名，用于在LYCIUM_ROOT/usr/下创建安装目录、标识依赖关系。 |
pkgver | 0.26.1 | pkgver=0.26.1：上游版本号，与https://github.com/sharkdp/bat仓库最新发行版本保持一致。 |
pkgrel | 0 | pkgrel=0：包发布号，当同一上游版本需要重新打包时递增，首次适配为 0。 |
pkgdesc | - | 包的简短描述，取自bat官方README。 |
url | - | 上游项目主页URL。 |
archs | ("arm64-v8a") | archs=("arm64-v8a")：声明支持的架构数组。此处仅列出arm64-v8a，但代码内部实际也处理了armeabi-v7a和x86_64，此处是声明"主要支持"而非"仅支持"。当前鸿蒙 PC 设备为arm64架构，因此必须配置arm64-v8a。 |
license | ("MIT" "Apache-2.0") | bat采用双重许可（MIT或Apache-2.0），用户可任选其一。 |
depends | ("oniguruma") | depends=("oniguruma")：运行时依赖。 |
makedepends | ("cargo" "rustc") | makedepends=("cargo" "rustc")：编译时依赖。Rust工具链是构建前提。 |
source | refs/tags/${pkgver}.tar.gz | 源码包下载地址。使用${pkgver}变量拼接，下载bat 0.26.1的release tarball。 |
downloadpackage | true | downloadpackage=true：告诉lycium构建系统自动下载source指定的源码包。如果设置为false需要在目标库目录下手动下载源码包。 |
autounpack | true | autounpack=true：下载后自动解压，无需手动解压步骤。如果设置为false需要手动解压。 |
buildtools | cargo | buildtools=cargo：声明构建工具类型。lycium据此选择Cargo构建流程（而非make/cmake等）。 |
builddir | ${pkgname}-${pkgver} | builddir=${pkgname}-${pkgver}：解压后的源码目录名。prepare()/build()/package()均通过cd $builddir进入此目录。 |
packagename | ${builddir}.tar.gz | packagename=${builddir}.tar.gz：源码包文件名，用于校验/定位。 |
还需要修改package函数中编译完成后的二进制文件名称，bat项目编译完成后，会产出一个名为bat的二进制文件，此处需要将cp target/${OHOS_RUST_TARGET}/release/xxx改为cp target/${OHOS_RUST_TARGET}/release/bat并复制到安装目录。
# 打包安装package(){# 进入 Rust 项目目录（和编译时同一个目录）cd$builddir# 定义安装路径：鸿蒙库的安装目录DEST="$LYCIUM_ROOT/usr/$pkgname/$ARCH"# 创建安装目录bin 文件夹mkdir-p$DEST/bin/# 【关键】把编译好的 Rust 程序 → 复制到目标目录的 bin 文件夹cptarget/${OHOS_RUST_TARGET}/release/bat"$DEST/bin/"cd$OLDPWD}4 HNP 打包配置
在lycium_plusplus/RustAdapt/ohos-bat目录下创建hnp.json文件，因为在HPKBUILD中存在archive函数，用于将产物打包为output/<arch>/<pkgname>_<ver>.tar.gz，或执行 HNP 打包，详细介绍可参考系列索引-构建执行与产物获取。
{"type":"hnp-config","name":"bat","version":"0.26.1","install":{}}5 交叉编译并解决可能存在的问题
HPKBUILD中函数不做改变，在lycium_plusplus/lycium目录下打开终端工具，输入./build.sh ohos-bat进行第一次交叉编译。bat依赖oniguruma库，第一次编译会因为没有在thirdparty、RustAdapt、community、external_deps文件中找到，因此需要开发者自行完成适配，可以参考已完成适配的ohos-oniguruma。
如果提示ALL JOBS DONE!!!表示当前交叉编译没有问题，编译后的产物，可以在lycium/usr/目录和out/arm64-v8目录下查看。
三、 在鸿蒙PC上验证交叉编译后的rg命令是否可用
将lycium_plusplus/lycium/usr/bat/arm64-v8a/bin/bat二进制文件传到鸿蒙PC上，方式有多种，可以通过聊天软件。macos设备可以在App Store下载【鸿蒙星河互联】，通过分享方式将bat二进制文件发送到鸿蒙PC设备上，这种方式需要鸿蒙PC开启华为分享为所有人可见。在鸿蒙PC右下角会弹出接受弹窗，选择“接受”或者“另存为”，接受bat二进制文件。接受后的二进制文件是不可以直接运行的，哪怕使用chmod +x bat这种方式授权也是无法运行的。需要给二进制文件进行签名后才可以，在鸿蒙 PC 侧执行前涉及二进制签名流程，可参考《鸿蒙PC端二进制文件签名命令行使用指南》。打开鸿蒙PC终端，输入以下命令为bat签名授权。
# 进入rg所在目录cdDesktop# 执行签名binary-sign-tool sign-inFilebat-outFilebat-selfSign"1"# 授予权限chmod+x bat# 查看bat版本./bat--version四、 FAQ
执行签名命令出现“zsh: command not found: binary-sign-tool”提示。
需要在应用市场搜索DevBox并安装，DevBox提供了一些开发者常用命令，主要包含文件和目录操作命令、网络命令、构建命令、签名工具等。
