目录

• 概述
• 准备工作
• 项目结构
• 适配步骤
  • 步骤 1：创建 build_ohos.sh 脚本
  • 步骤 2：创建 hnp.json 配置文件
  • 步骤 3：源码鸿蒙化适配
• 构建脚本详解
  • build_ohos.sh - 组件构建脚本
  • build.sh - 主构建脚本
• 构建流程
• 常见问题
• 贡献指南

---

概述

本文档介绍如何将 Linux/Unix 命令行工具适配到 HarmonyOS PC 平台。适配后的工具可以打包为 HNP（HarmonyOS Native Package）格式，在 HarmonyOS PC 设备上安装和使用。

适配目标

• 将开源命令行工具移植到 HarmonyOS PC 平台
• 使用 HarmonyOS SDK 进行交叉编译
• 生成 HNP 格式的安装包
• 确保工具在 HarmonyOS PC 上正常运行

前置要求

• HarmonyOS SDK（包含 native 工具链）
• Python 3.x
• Bash shell
• Git（用于克隆源码）

---

准备工作

1. 环境准备

确保已安装以下工具：

# 检查 Python
python --version

# 检查 Git
git --version

# 检查 Bash
bash --version

2. SDK 准备

下载并解压 HarmonyOS SDK：

# 下载 SDK（示例）
cd ~
wget https://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-full_ohos/xxx/ohos-sdk-full_ohos.tar.gz
tar -xzf ohos-sdk-full_ohos.tar.gz

# SDK 路径示例：/home/user/ohos-sdk/linux

3. 克隆构建框架

git clone git@gitcode.com:OpenHarmonyPCDeveloper/build.git
cd build

---

项目结构

适配完成后，项目目录结构如下：

build/
├── build.sh                    # 主构建脚本
├── build_dependency.py         # 依赖构建脚本
├── dependency.json             # 依赖配置文件
├── README.md                   # 说明文档
├── code/                       # 源代码目录
│   └── cmdtree/                # tree 工具源码
│       ├── build_ohos.sh       # 组件构建脚本（需创建）
│       ├── hnp.json            # HNP 配置文件（需创建）
│       ├── Makefile            # 构建配置
│       ├── *.c                 # 源代码文件
│       └── ...
├── data/                       # 数据目录
│   └── service/
│       └── hnp/
│           └── tree.org/
│               └── tree_2.2.1/  # 安装目录
│                   ├── bin/
│                   │   └── tree
│                   ├── man/
│                   │   └── man1/
│                   │       └── tree.1
│                   └── hnp.json
└── output/                     # 输出目录
    ├── tree.hnp                # HNP 格式包
    └── ohos_tree_2.2.1.tar.gz  # tar.gz 压缩包

---

适配步骤

步骤 1：创建 build_ohos.sh 脚本

在组件源码目录下创建 build_ohos.sh 文件，这是组件的构建脚本。

文件位置：code/<组件名>/build_ohos.sh

示例内容（以 tree 工具为例）：

#!/bin/bash
# ============================================================================
# build_ohos.sh - Tree 工具 HarmonyOS 构建脚本
# ============================================================================
# 功能说明：
#   本脚本用于将 tree 命令行工具编译并打包为 HarmonyOS HNP 格式
#   主要步骤包括：
#   1. 设置 HNP 安装路径
#   2. 编译 tree 工具
#   3. 安装到指定目录
#   4. 打包为 HNP 格式和 tar.gz 压缩包
#
# 环境变量依赖：
#   - HNP_PUBLIC_PATH: HNP 公共路径，由主构建脚本 build.sh 设置
#   - HNP_TOOL: HNP 打包工具路径，用于生成 .hnp 文件
#   - ARCHIVE_PATH: 输出归档路径，通常为 ${WORK_ROOT}/output
#   - PREFIX: 系统默认安装前缀（会被临时覆盖）
#
# 使用方法：
#   本脚本由主构建脚本 build.sh 调用，不应直接执行
# ============================================================================

# ----------------------------------------------------------------------------
# 步骤 1: 设置 HNP 安装路径
# ----------------------------------------------------------------------------
# HNP 路径规则：${HNP_PUBLIC_PATH}/<部件名称>.org/<部件名称>_<版本号>
# 例如：/data/service/hnp/tree.org/tree_2.2.1
export TREE_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/tree.org/tree_2.2.1

# ----------------------------------------------------------------------------
# 步骤 2: 保存并临时修改 PREFIX 环境变量
# ----------------------------------------------------------------------------
sys_prefix=${PREFIX}
export PREFIX=${TREE_INSTALL_HNP_PATH}
echo "${PREFIX}"

# ----------------------------------------------------------------------------
# 步骤 3: 清理之前的构建产物
# ----------------------------------------------------------------------------
make clean

# ----------------------------------------------------------------------------
# 步骤 4: 编译 tree 工具
# ----------------------------------------------------------------------------
# VERBOSE=1: 启用详细输出模式，便于调试
make VERBOSE=1

# ----------------------------------------------------------------------------
# 步骤 5: 安装 tree 工具
# ----------------------------------------------------------------------------
# 安装结构：
#   ${PREFIX}/bin/tree          - 可执行文件
#   ${PREFIX}/man/man1/tree.1   - 手册页
make install

# ----------------------------------------------------------------------------
# 步骤 6: 复制 HNP 配置文件
# ----------------------------------------------------------------------------
cp hnp.json ${TREE_INSTALL_HNP_PATH}/

# ----------------------------------------------------------------------------
# 步骤 7: 打包为 HNP 格式和 tar.gz 压缩包
# ----------------------------------------------------------------------------
pushd ${TREE_INSTALL_HNP_PATH}/../
    # 生成 HNP 格式包
    ${HNP_TOOL} pack -i ${TREE_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/
    
    # 生成 tar.gz 压缩包
    tar -zvcf ${ARCHIVE_PATH}/ohos_tree_2.2.1.tar.gz tree_2.2.1/
popd

# ----------------------------------------------------------------------------
# 步骤 8: 恢复原始 PREFIX 环境变量
# ----------------------------------------------------------------------------
export PREFIX=${sys_prefix}

# ============================================================================
# 构建完成
# 输出文件：
#   - ${ARCHIVE_PATH}/tree.hnp              (HNP 格式包)
#   - ${ARCHIVE_PATH}/ohos_tree_2.2.1.tar.gz (tar.gz 压缩包)
# ============================================================================

关键点说明：

1. HNP 路径规范：必须遵循 ${HNP_PUBLIC_PATH}/<组件名>.org/<组件名>_<版本号> 格式
2. PREFIX 管理：临时修改 PREFIX 后必须恢复，避免影响其他构建
3. 构建步骤：清理 → 编译 → 安装 → 打包
4. 双重打包：同时生成 HNP 和 tar.gz 两种格式

步骤 2：创建 hnp.json 配置文件

在组件源码目录下创建 hnp.json 文件，这是 HNP 包的元数据配置文件。

文件位置：code/<组件名>/hnp.json

示例内容：

{
    "type": "hnp-config",
    "name": "tree",
    "version": "2.2.1",
    "install": {}
}

字段说明：

• type: 固定为 "hnp-config"
• name: 组件名称，必须与目录名一致
• version: 组件版本号
• install: 安装配置（可选，目前为空对象）

步骤 3：源码鸿蒙化适配

根据具体工具的特点，可能需要进行以下适配：

1. 系统调用适配：HarmonyOS 使用 musl libc，某些系统调用可能需要调整
2. 平台宏定义：使用 #ifdef __OHOS__ 进行平台特定代码
3. 路径处理：确保路径分隔符和路径处理逻辑正确
4. 依赖库：检查并适配依赖的系统库

参考示例：

• tree 工具适配提交 1
• tree 工具适配提交 2

---

构建脚本详解

build_ohos.sh - 组件构建脚本

build_ohos.sh 是每个组件的独立构建脚本，负责：

• 设置组件特定的安装路径
• 执行编译和安装
• 生成 HNP 包和 tar.gz 压缩包

执行流程：

设置路径 → 清理 → 编译 → 安装 → 复制配置 → 打包 → 恢复环境

build.sh - 主构建脚本

build.sh 是构建系统的入口脚本，负责：

1. 环境检测：检测操作系统类型和工具链
2. 工具链配置：设置交叉编译工具链（LLVM/Clang）
3. 环境变量设置：配置 CFLAGS、LDFLAGS 等编译参数
4. 调用组件脚本：执行组件的 build_ohos.sh

使用方法：

./build.sh --sdk <HarmonyOS SDK 路径>

示例：

./build.sh --sdk /home/user/ohos-sdk/linux

关键环境变量（由 build.sh 设置）：

变量	说明	示例
OHOS_SDK	SDK 路径	/home/user/ohos-sdk/linux
COMPILER_TOOLCHAIN	工具链路径	${OHOS_SDK}/native/llvm/bin/
SYSROOT	系统根目录	${OHOS_SDK}/native/sysroot
TARGET_PLATFORM	目标平台	aarch64-linux-ohos
HNP_PUBLIC_PATH	HNP 公共路径	/data/service/hnp
ARCHIVE_PATH	输出路径	${WORK_ROOT}/output
HNP_TOOL	HNP 打包工具	${OHOS_SDK}/toolchains/hnpcli

build.sh 核心代码片段：

#!/bin/bash

# 解析命令行参数
SDK_PATH=""
while [[ $# -gt 0 ]]; do
    case "$1" in
        --sdk)
            SDK_PATH="$2"
            shift 2
            ;;
        *)
            echo "Error: unknow param $1"
            echo "Usage: $0 --sdk <SDK path>"
            exit 1
            ;;
    esac
done

# 验证 SDK 路径
if [ -z "$SDK_PATH" ]; then
    echo "Error: SDK path must be specified with the \"--sdk\" option"
    exit 1
fi

if [ ! -d "$SDK_PATH" ]; then
    echo "Error: SDK path is not exist or no permossion: [$SDK_PATH]"
    exit 2
fi

# 设置 SDK 路径
export OHOS_SDK="$SDK_PATH"

# 检测操作系统并选择工具链
BUILD_OS=$(uname)
case $BUILD_OS in
    'OpenHarmony')
        export COMPILER_TOOLCHAIN=${OHOS_TOOL_CHAIN_PATH}
        ;;
    'HarmonyOS')
        export COMPILER_TOOLCHAIN=${HMOS_TOOL_CHAIN_PATH}
        export HNP_PERFIX=${PWD}/hnp
        ;;
    *)
        # 交叉编译模式（最常见）
        export COMPILER_TOOLCHAIN=${OHOS_SDK}/native/llvm/bin/
        ;;
esac

# 配置工具链环境变量
export CC=${COMPILER_TOOLCHAIN}clang
export CXX=${COMPILER_TOOLCHAIN}clang++
export LD=${COMPILER_TOOLCHAIN}ld.lld
# ... 其他工具

# 设置系统根目录
export SYSROOT=${OHOS_SDK}/native/sysroot

# 设置编译标志
export TARGET_PLATFORM=aarch64-linux-ohos
export CFLAGS="-fPIC -D__MUSL__=1 -D__OHOS__ -fstack-protector-strong \
    --target=${TARGET_PLATFORM} -fuse-ld=${LD} --sysroot=${SYSROOT}"

# 设置路径
export WORK_ROOT=${PWD}
export ARCHIVE_PATH=${WORK_ROOT}/output
export HNP_PUBLIC_PATH=${HNP_PERFIX}${WORK_ROOT}/data/service/hnp

# 创建目录
mkdir -p ${HNP_PUBLIC_PATH}
mkdir -p ${ARCHIVE_PATH}
mkdir -p code

# 执行构建
BUILD_BY_DEPENDENCY="false"
SPECIFIC_DIR="cmdtree"

if [[ "${BUILD_BY_DEPENDENCY}" == "true" ]]; then
    python build_dependency.py
else
    pushd code/${SPECIFIC_DIR}
        chmod +x build_ohos.sh && source build_ohos.sh
    popd
fi

---

构建流程

完整构建流程

执行示例

# 1. 进入构建目录
cd ~/build

# 2. 确保源码已克隆
cd code
git clone git@gitcode.com:OpenHarmonyPCDeveloper/cmdtree.git
cd ..

# 3. 执行构建
./build.sh --sdk /home/user/ohos-sdk/linux

# 4. 查看构建产物
ls -lh output/
# 输出：
# -rw-r--r-- 1 user user 123K Dec 1 10:00 tree.hnp
# -rw-r--r-- 1 user user 456K Dec 1 10:00 ohos_tree_2.2.1.tar.gz

构建输出

构建成功后，在 output/ 目录下会生成：

• tree.hnp：HarmonyOS Native Package 格式，可直接在 HarmonyOS PC 上安装
• ohos_tree_2.2.1.tar.gz：传统压缩包格式，便于手动部署

---

常见问题

Q1: SDK 路径错误

问题：

Error: SDK path is not exist or no permossion: [/path/to/sdk]

解决：

1. 检查 SDK 路径是否正确
2. 确认路径有读取权限
3. 验证 SDK 目录结构是否完整（应包含 native/llvm/bin/ 目录）

Q2: 工具链找不到

问题：

CC      : /path/to/sdk/native/llvm/bin/clang
bash: /path/to/sdk/native/llvm/bin/clang: No such file or directory

解决：

1. 确认 SDK 版本包含 native 工具链
2. 检查 SDK 是否完整解压
3. 验证工具链文件权限

Q3: Python 未安装

问题：

You need install python in your system

解决：
根据操作系统安装 Python：

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip

# macOS
brew install python

# 或从官网下载
# https://www.python.org/downloads/

Q4: 编译错误

问题：编译过程中出现错误

排查步骤：

1. 检查环境变量是否正确设置：

   echo $CC
   echo $CFLAGS
   echo $SYSROOT
   

2. 确认源码已进行 HarmonyOS 适配
3. 查看详细编译日志（make VERBOSE=1）
4. 检查依赖库是否完整

Q5: HNP 路径错误

问题：HNP 路径不符合规范

解决：
确保路径遵循格式：${HNP_PUBLIC_PATH}/<组件名>.org/<组件名>_<版本号>

例如：

• ✅ 正确：/data/service/hnp/tree.org/tree_2.2.1
• ❌ 错误：/data/service/hnp/tree_2.2.1

Q6: 权限问题

问题：无法创建目录或写入文件

解决：

# 检查目录权限
ls -ld ${HNP_PUBLIC_PATH}
ls -ld ${ARCHIVE_PATH}

# 创建目录（如果需要）
mkdir -p ${HNP_PUBLIC_PATH}
mkdir -p ${ARCHIVE_PATH}

---

贡献指南

添加新组件

1. 克隆源码：

   cd code
   git clone <组件仓库地址> <组件名>
   

2. 创建构建脚本：
   在组件目录下创建 build_ohos.sh，参考 tree 工具的示例

3. 创建配置文件：
   在组件目录下创建 hnp.json

4. 源码适配：
   根据需要进行 HarmonyOS 平台适配

5. 测试构建：

   # 修改 build.sh 中的 SPECIFIC_DIR
   SPECIFIC_DIR="<组件名>"
   
   # 执行构建
   ./build.sh --sdk <SDK路径>
   

6. 提交代码：

   • 将组件添加到 dependency.json
   • 提交 Pull Request

dependency.json 格式

{
    "dependency": [
        {
            "name": "tree",
            "branch": "2.2.1_ohos",
            "url": "git@gitcode.com:OpenHarmonyPCDeveloper/cmdtree.git"
        }
    ]
}

代码规范

• 使用有意义的变量名
• 添加必要的注释
• 遵循 HNP 路径规范
• 确保脚本可重复执行（幂等性）

---

总结

通过本文档，您可以：

1. ✅ 了解 HarmonyOS PC 命令行工具适配流程
2. ✅ 掌握构建脚本的编写方法
3. ✅ 学会使用构建系统进行编译和打包
4. ✅ 解决常见的构建问题

下一步

• 查看 tree 工具源码 作为参考
• 阅读 HarmonyOS 开发者文档
• 加入社区讨论分享适配经验