HarmonyOS PC 命令行工具构建框架

欢迎大家一起共建 HarmonyOS PC 生态欢迎加入开源鸿蒙PC社区https://harmonypc.csdn.net/目录概述环境准备Windows 环境WSLLinux 环境Ubuntu 22.04macOS 环境快速开始详细步骤步骤 1环境配置步骤 2SDK 准备步骤 3下载构建框架步骤 4添加组件源码步骤 5创建构建脚本步骤 6源码适配步骤 7执行构建项目结构贡献指南常见问题相关资源概述本仓库是 HarmonyOS PC 命令行工具构建框架用于将 Linux/Unix 命令行工具适配并构建为 HarmonyOS Native Package (HNP) 格式。主要功能 自动化交叉编译环境配置 生成 HNP 格式安装包 支持批量构建多个组件️ 统一的构建流程和规范适用场景将开源命令行工具移植到 HarmonyOS PC为 HarmonyOS PC 生态贡献工具学习和研究 HarmonyOS 原生应用构建编译运行实际效果图最终测试效果·成功多层级测试真机环境环境准备Windows 环境WSL1. 安装 WSL Ubuntu 22.04下载并安装 WSL Ubuntu 22.04下载地址https://wslstorestorage.blob.core.windows.net/wslblob/Ubuntu2204-221101.AppxBundle安装步骤下载.AppxBundle文件双击安装安装完成后在开始菜单中启动 Ubuntu 22.04首次启动会提示创建用户账户2. 进入 WSL 环境安装完成后可以通过以下方式进入 WSL# 方式 1在开始菜单中启动 Ubuntu 22.04# 方式 2在 PowerShell 或 CMD 中执行wslLinux 环境Ubuntu 22.04如果您的系统是 Ubuntu 22.04可以直接使用。其他 Linux 发行版需要安装相应的依赖。macOS 环境macOS 环境可以直接使用但需要确保已安装必要的工具。快速开始前置要求Ubuntu 22.04WSL 或原生系统Python 3.xGitHarmonyOS SDK一键安装脚本# 1. 克隆仓库gitclone https://gitcode.com/OpenHarmonyPCDeveloper/buildcdbuild# 2. 配置 SDK 路径替换为您的 SDK 路径exportOHOS_SDK/path/to/ohos-sdk/linux# 3. 执行构建以 tree 工具为例./build.sh--sdk$OHOS_SDK详细步骤步骤 1环境配置1.1 修改镜像源可选推荐为了提高下载速度建议将 Ubuntu 源改为国内镜像# 备份原始源文件sudocp/etc/apt/sources.list /etc/apt/sources.list.bak# 编辑源文件sudovim/etc/apt/sources.list阿里云镜像源配置Ubuntu 22.04 Jammydeb https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse deb https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse# deb https://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiverse# deb-src https://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiversedeb https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse deb-src https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse更新软件包列表sudoapt-getupdatesudoapt-getupgrade1.2 安装 Python# 安装 Python 3 和 pipsudoaptinstallpython3 python3-pip# 设置 python 命令指向 python3可选sudoupdate-alternatives--install/usr/bin/python python /usr/bin/python31# 验证安装python--version1.3 安装其他必要工具# 安装 Git如果未安装sudoaptinstallgit# 安装构建工具sudoaptinstallbuild-essential步骤 2SDK 准备2.1 下载 HarmonyOS SDK# 进入用户目录cd~# 下载 SDK请替换为最新版本的下载链接wgethttps://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-full_ohos/20250819_020817/version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz# 解压 SDKtar-zvxfversion-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz2.2 解压工具链# 进入 SDK 目录cd~/ohos-sdk/linux# 解压 native 工具链unzipnative-linux-x64-6.0.0.46-Beta1.zip# 解压工具链unziptoolchains-linux-x64-6.0.0.46-Beta1.zip注意native-linux-x64-6.0.0.46-Beta1.zip解压所在的父目录的全路径即为后续构建所需的 SDK 路径。示例 SDK 路径/home/goblinrs/ohos-sdk/linux2.3 验证 SDK# 检查 SDK 目录结构ls-la~/ohos-sdk/linux/# 应该包含以下目录# - native/# - toolchains/步骤 3下载构建框架# 克隆构建框架仓库cd~gitclone gitgitcode.com:OpenHarmonyPCDeveloper/build.git# 进入构建目录cdbuild步骤 4添加组件源码以tree工具为例# 创建代码目录如果不存在mkdir-pcode# 进入代码目录cdcode# 克隆组件源码gitclone gitgitcode.com:OpenHarmonyPCDeveloper/cmdtree.git-bmaster# 返回构建根目录cd..步骤 5创建构建脚本5.1 创建 build_ohos.sh在组件源码目录下创建build_ohos.sh文件文件位置code/cmdtree/build_ohos.sh文件内容#!/bin/bash# 设置 HNP 安装路径# 路径规则${HNP_PUBLIC_PATH}/部件名称.org/部件名称_版本号exportTREE_INSTALL_HNP_PATH${HNP_PUBLIC_PATH}/tree.org/tree_2.2.1# 保存并临时修改 PREFIXsys_prefix${PREFIX}exportPREFIX${TREE_INSTALL_HNP_PATH}echo${PREFIX}# 清理构建makeclean# 编译注意这里不需要传递 prefix 参数makeVERBOSE1# 安装makeinstall# 复制 HNP 配置文件cphnp.json${TREE_INSTALL_HNP_PATH}/# 打包pushd${TREE_INSTALL_HNP_PATH}/../${HNP_TOOL}pack-i${TREE_INSTALL_HNP_PATH}-o${ARCHIVE_PATH}/tar-zvcf${ARCHIVE_PATH}/ohos_tree_2.2.1.tar.gz tree_2.2.1/popd# 恢复 PREFIXexportPREFIX${sys_prefix}重要说明HNP 路径必须遵循规范${HNP_PUBLIC_PATH}/组件名.org/组件名_版本号示例${HNP_PUBLIC_PATH}/tree.org/tree_2.2.1make命令不需要传递prefix参数因为已经通过环境变量PREFIX设置5.2 创建 hnp.json在组件源码目录下创建hnp.json文件文件位置code/cmdtree/hnp.json文件内容{type:hnp-config,name:tree,version:2.2.1,install:{}}字段说明type: 固定为hnp-configname: 组件名称必须与目录名一致version: 组件版本号install: 安装配置可选5.3 组件源码结构示例以tree工具为例完整的源码结构如下cmdtree/ ├── CHANGES ├── INSTALL ├── LICENSE ├── Makefile ├── README ├── TODO ├── build_ohos.sh # 新增构建脚本 ├── hnp.json # 新增HNP 配置文件 ├── color.c ├── doc/ │ ├── global_info │ ├── tree.1 │ └── xml.dtd ├── file.c ├── filter.c ├── hash.c ├── html.c ├── info.c ├── json.c ├── list.c ├── strverscmp.c ├── tree.c ├── tree.h ├── unix.c └── xml.c步骤 6源码适配根据具体工具的特点可能需要进行 HarmonyOS 平台适配系统调用适配HarmonyOS 使用 musl libc某些系统调用可能需要调整平台宏定义使用#ifdef __OHOS__进行平台特定代码路径处理确保路径分隔符和路径处理逻辑正确参考示例tree 工具适配提交 1tree 工具适配提交 2步骤 7执行构建7.1 设置安装目录# 创建 HNP 安装目录sudomkdir-p/data/service/hnp# 设置权限根据实际情况调整sudochmod777-R/data/service/hnp注意如果使用 WSL可能需要先创建/data目录sudomkdir-p/data/service/hnpsudochmod777-R/data/service/hnp7.2 执行构建# 进入构建目录cd~/build# 执行构建替换为您的 SDK 路径./build.sh--sdk/home/goblinrs/ohos-sdk/linux构建参数说明--sdk 路径指定 HarmonyOS SDK 路径必需7.3 查看构建产物构建成功后产物位于output/目录ls-lhoutput/# 输出示例# -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产物说明tree.hnpHarmonyOS Native Package 格式可直接在 HarmonyOS PC 上安装ohos_tree_2.2.1.tar.gz传统压缩包格式便于手动部署项目结构构建完成后的项目结构build/ ├── build.sh # 主构建脚本 ├── build_dependency.py # 依赖构建脚本 ├── dependency.json # 依赖配置文件 ├── README.md # 本文档 ├── LICENSE # 许可证 ├── 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. 准备组件源码# 在 code 目录下克隆组件源码cdcodegitclone组件仓库地址组件名2. 创建构建脚本参考 步骤 5创建构建脚本创建build_ohos.sh和hnp.json。3. 进行源码适配参考 步骤 6源码适配进行 HarmonyOS 平台适配。4. 测试构建# 修改 build.sh 中的 SPECIFIC_DIRSPECIFIC_DIR组件名# 执行构建./build.sh--sdkSDK路径5. 提交代码5.1 提交组件代码将适配后的组件代码提交到组件仓库cdcode/组件名gitadd.gitcommit-m适配 HarmonyOS PC 平台gitpush5.2 添加到 dependency.json在dependency.json中添加组件信息{dependency:[{name:tree,branch:2.2.1_ohos,url:gitgitcode.com:OpenHarmonyPCDeveloper/cmdtree.git},{name:新组件名,branch:分支名,url:仓库地址}]}5.3 提交到构建框架仓库cd~/buildgitadddependency.jsongitcommit-m添加 组件名 组件gitpush贡献流程Fork 本仓库创建特性分支git checkout -b feature/组件名提交更改git commit -m 添加 组件名 组件推送到分支git push origin feature/组件名提交 Pull Request常见问题Q1: SDK 路径错误问题Error: SDK path is not exist or no permossion: [/path/to/sdk]解决检查 SDK 路径是否正确确认路径有读取权限验证 SDK 目录结构是否完整Q2: 权限不足问题无法创建/data/service/hnp目录解决# 使用 sudo 创建目录sudomkdir-p/data/service/hnpsudochmod777-R/data/service/hnpQ3: Python 未安装问题You need install python in your system解决sudoaptinstallpython3 python3-pipsudoupdate-alternatives--install/usr/bin/python python /usr/bin/python31Q4: Git 克隆失败问题git clone失败提示权限错误解决配置 SSH 密钥ssh-keygen-trsa-b4096-Cyour_emailexample.comcat~/.ssh/id_rsa.pub将公钥添加到 GitCode 账户或使用 HTTPS 方式克隆gitclone https://gitcode.com/OpenHarmonyPCDeveloper/build.gitQ5: 构建失败问题编译过程中出现错误排查步骤检查环境变量是否正确设置确认源码已进行 HarmonyOS 适配查看详细编译日志make VERBOSE1检查依赖库是否完整Q6: WSL 中无法访问 Windows 文件问题在 WSL 中无法访问 Windows 文件系统解决WSL 可以通过/mnt/访问 Windows 文件系统# 访问 C 盘cd/mnt/c/# 访问 D 盘cd/mnt/d/相关资源适配鸿蒙PC命令行指南 - 详细的适配文档HarmonyOS 开发者文档 - 官方开发文档社区讨论 - 加入社区讨论