OpenHarmony Linux 命令行工具适配实战：基于 Cursor × WSL 的 tree 2.2.1 交叉编译与 HNP 打包全流程指南

OpenHarmony Linux 命令行工具适配实战基于 Cursor × WSL 的 tree 2.2.1 交叉编译与 HNP 打包全流程指南前言随着鸿蒙PC生态不断完善Linux 命令行工具适配成为生态拓展的关键环节本文以经典目录可视化工具 tree 2.2.1 为案例基于 Cursor/VS Code WSL Ubuntu 24.04 技术栈提供从环境搭建、SDK 配置到交叉编译、HNP 打包的完整可复现实操方案帮助开发者快速掌握 Windows 侧鸿蒙交叉编译环境搭建核心流程规避各类适配痛点助力更多 Linux 开源软件高效融入鸿蒙PC生态为生态丰富与功能拓展提供实用技术支撑。项目信息适配对象完成 Linux 命令行工具 tree 2.2.1 向 OpenHarmony PCaarch64 架构的全流程适配技术栈基于 OpenHarmony SDK 的 clang 交叉编译工具链、hnpcli 打包工具通过标准化脚本配置完成产物打包环境基础WSL Ubuntu 24.04 开发环境输出可直接部署的 HNP 包和 tar.gz 产物项目名称tree目录可视化工具开源协议GPL-2.0源码版本2.2.1目标平台OpenHarmony PCaarch64-linux-ohos依赖项OpenHarmony SDK、Python3、hnpcli 工具操作系统平台开发WSL Ubuntu 24.04前提准备通过 Microsoft Store 安装 WSL Ubuntu 24.04打开微软应用商店搜索 Ubuntu 并选择最新长期支持版本安装完成后从开始菜单启动对应终端即可WSL Ubuntu 24.04 系统迁移与重构全流程指南1、管理员身份运行 Windows PowerShell 后先通过 wsl --shutdown 关闭所有 WSL 实例再强制终止 wslhost 和 wslservice 相关进程忽略终止失败的错误等待 30 秒确保进程完全停止最后用 wsl -l -v 查看当前 WSL 分发版的列表及运行状态# 以管理员身份运行Windows PowerShell执行以下命令# 关闭所有正在运行的WSL实例wsl--shutdown# 强制终止wslhost进程遇到错误时静默处理不报错Stop-Process-Namewslhost-Force-ErrorActionSilentlyContinue# 强制终止wslservice进程遇到错误时静默处理不报错Stop-Process-Namewslservice-Force-ErrorActionSilentlyContinue# 等待30秒确保相关进程完全停止Start-Sleep-Seconds30# 列出所有已安装的WSL分发版并显示其运行状态名称、状态、WSL版本wsl-l-v2、使用.tar格式备份系统# 创建WSL备份目录已存在则忽略New-Item-PathD:\WSL-ItemTypeDirectory-Force# 导出Ubuntu-24.04到指定备份文件wsl--exportUbuntu-24.04 D:\WSL\Ubuntu2404_backup.tar3、注销原系统释放C盘空间# 彻底注销/删除 Ubuntu-24.04 WSL 发行版所有数据会丢失wsl--unregisterUbuntu-24.044、导入系统到D盘# 从备份文件导入并创建 Ubuntu-24.04 WSL 发行版安装路径D:\WSL\Ubuntu2404wsl--importUbuntu-24.04 D:\WSL\Ubuntu2404 D:\WSL\Ubuntu2404_backup.tar5、恢复默认用户# 设置 Ubuntu-24.04 WSL 的默认登录用户为 weishuoubuntu2404.exe config --default-user weishuo6、验证迁移结果# 列出所有已安装的 WSL 发行版及运行状态wsl-l-v# 启动并进入 Ubuntu-24.04 WSL 发行版wsl-dUbuntu-24.04Linux 开发环境初始化与依赖配置1、更换APT软件源# 备份 Ubuntu 官方软件源配置文件避免修改出错后无法恢复sudocp/etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.backup# 使用 vim 编辑器修改软件源配置文件用于替换为国内源等操作sudovim/etc/apt/sources.list.d/ubuntu.sources清华源Types: deb URIs: https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ Suites: noble noble-updates noble-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg2、更新软件包# 更新软件源索引获取最新的软件包版本信息sudoaptupdate# 自动升级所有可更新的软件包-y 自动确认所有提示无需手动输入ysudoaptupgrade-y3、安装Python环境# 安装 Python3 及 pip 包管理工具-y 自动确认安装sudoaptinstallpython3 python3-pip-y# 配置 python 命令默认指向 python3优先级 1若有其他版本可调整优先级sudoupdate-alternatives--install/usr/bin/python python /usr/bin/python31OpenHarmony SDK 获取、安装与环境配置指南1、下载OpenHarmony SDK# 下载 OpenHarmony Master 版本完整 SDK20250819 构建版本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.gz2、解压SDK包# 解压 OpenHarmony 完整 SDK 压缩包zgz格式v显示进度x解压f指定文件tar-zvxfversion-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz3、解压核心组件# 解压 native 工具包Linux x64 架构6.0.0.46 Beta1 版本unzipnative-linux-x64-6.0.0.46-Beta1.zip# 解压 toolchains 工具链包Linux x64 架构6.0.0.46 Beta1 版本unziptoolchains-linux-x64-6.0.0.46-Beta1.zip4、创建鸿蒙软件包安装目录# 递归创建 /data/service/hnp 目录-p 自动创建父目录不存在则新建sudomkdir-p/data/service/hnp# 递归设置该目录及所有子内容权限为 777所有用户可读可写可执行-R 递归应用sudochmod777-R/data/service/hnp5、获取构建工具下载鸿蒙构建脚手架# 切换到当前用户主目录~ 等价于 /home/用户名cd~# 克隆鸿蒙PC开发版构建配置仓库gitclone https://atomgit.com/OpenHarmonyPCDeveloper/build6、源码准备与适配下载tree命令鸿蒙适配版源码# 切换到 build 仓库的 code 子目录需确保该目录已存在cd~/build/code/# 克隆远程仓库到本地gitclone https://github.com/Old-Man-Programmer/tree /home/weishuo/build/cmdtree7、创建适配配置文件进入源码目录添加两个关键适配文件hnp.json 配置文件{name:tree,version:2.2.1,description:递归目录列表显示工具,license:GPL-2.0,arch:aarch64,target:ohos-pc}build_ohos.sh 编译脚本#!/bin/bash# 定义 tree 的安装路径exportTREE_INSTALL_HNP_PATH${HNP_PUBLIC_PATH}/tree.org/tree_2.2.1# 保存原始 PREFIX编译后恢复sys_perfix${PREFIX}exportPREFIX${TREE_INSTALL_HNP_PATH}echo安装路径${PREFIX}# 清理旧编译产物重新编译makecleanmakeVERBOSE1prefix${TREE_INSTALL_HNP_PATH}makeinstallprefix${TREE_INSTALL_HNP_PATH}# 复制配置文件到安装目录cphnp.json${TREE_INSTALL_HNP_PATH}/# 切换到上级目录用 hnpcli 工具打包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_perfix}8、赋予脚本执行权限这样就是完整的基于windows的wsl适配鸿蒙pc的linux命令行环境配置流程chmodx build_ohos.shOpenHarmony 工具链验证与编译测试1、环境验证在开始编译前需要验证鸿蒙工具链的完整性# 1. 验证 clang 编译器/home/weishuo/ohos-sdk/linux/native/llvm/bin/clang--version# 2. 验证 hnpcli 打包工具/home/weishuo/ohos-sdk/linux/toolchains/hnpcli--help# 3. 验证 ld.lld 链接器/home/weishuo/ohos-sdk/linux/native/llvm/bin/ld.lld--version2、编译环境测试创建测试程序验证交叉编译环境hello_ohos.c#include stdio.hintmain(){#ifdef __OHOS__printf(✅ 鸿蒙编译环境正常已识别 __OHOS__ 系统宏\n);#elseprintf(❌ 未识别鸿蒙系统宏编译环境异常\n);#endifreturn0;}3、使用鸿蒙工具链编译用 OpenHarmony SDK 的 clang 交叉编译 hello_ohos.c指定 aarch64-OHOS 目标平台、SDK sysroot 路径及 OHOS 宏生成适配 OpenHarmony 的可执行文件/home/weishuo/ohos-sdk/linux/native/llvm/bin/clang-ohello_ohos hello_ohos.c--targetaarch64-linux-ohos--sysroot/home/weishuo/ohos-sdk/linux/native/sysroot-D__OHOS__4、验证生成文件# 查看 hello_ohos 可执行文件的类型、架构、目标系统等详细信息filehello_ohos5、环境验证成功输出显示为 ARM aarch64 架构的鸿蒙可执行文件证明交叉编译环境已正确配置开始编译回到 build 根目录执行编译命令# 切换到 build 构建目录cd~/build# 执行构建脚本指定 OpenHarmony SDK 的 Linux 平台路径用于编译依赖 SDK 工具链/头文件./build.sh--sdk/home/weishuo/ohos-sdk/linux基于 Cursor / VS Code 的鸿蒙适配开发实践1、在 WSL 终端中快速在 Windows 中打开 build 文件夹# 在 WSL 中调用 Windows 资源管理器打开当前目录. 表示当前工作目录explorer.exe.2、Cusor集成开发环境配置在 VS Code 中打开脚手架文件夹选择终端为 WSL: Ubuntu-24.04切换到 WSL 终端进行开发鸿蒙PC 适配tree 2.2.1 交叉编译与 HNP 打包1、修改 build.sh 需要构建的命令行组件名称OpenHarmony 组件构建初始化脚本需通过 --sdk 指定 SDK 路径并校验有效性根据运行系统配置编译工具链与 HNP 相关目录检查 Python 环境并提供安装指引导出编译工具、编译选项及构建相关路径等环境变量创建必要目录后默认执行 code/cmdtree 目录下的 build_ohos.sh 构建组件也可通过 BUILD_BY_DEPENDENCYtrue 按 dependency.json 构建依赖组件#!/bin/bashSDK_PATHwhile[[$#-gt0]];docase$1in--sdk)SDK_PATH$2shift2;;*)echoError: unknow param$1echoUsage:$0--sdk SDK pathexit1;;esacdoneif[-z$SDK_PATH];thenechoError: SDK path must be specified with the\--sdk\optionechoUsage:$0--sdk SDK pathexit1fiif[!-d$SDK_PATH];thenechoError: SDK path is not exist or no permossion: [$SDK_PATH]exit2fiexportOHOS_SDK$SDK_PATHexportHNP_PERFIXBUILD_OS$(uname)case$BUILD_OSinOpenHarmony)echoBuild in: $(uname-a) by local tool chains.exportCOMPILER_TOOLCHAIN${OHOS_TOOL_CHAIN_PATH};;HarmonyOS)echoBuild in: $(uname-a) by local tool chains.exportCOMPILER_TOOLCHAIN${HMOS_TOOL_CHAIN_PATH}exportHNP_PERFIX${PWD}/hnp;;*)echoBuild in: $(uname-a) by cross tool chains.exportCOMPILER_TOOLCHAIN${OHOS_SDK}/native/llvm/bin/;;esacif[-z${HNP_PERFIX}];thenexportHNP_PERFIX${PWD}/hnpfiif[-n${HNP_PERFIX}];thenmkdir-p${HNP_PERFIX}fiPYTHON$(python--version)echopython :$PYTHONif[-z$PYTHON];thenechoYou need install python in your systemcase$BUILD_OSinOpenHarmony|HarmonyOS)echo${BUILD_OS}install by url://www.xxx.xxx.com;;Linux*)ifcommand-vapt-get/dev/null;thenecho1. sudo apt updateecho2. sudo apt install python3 python3-pipelifcommand-vyum/dev/null;thenecho1. sudo yum install python3 python3-pipelseechoPlease install python3 and pip using your systems package manager.fi;;Darwin*)echo1. Use Homebrew: brew install pythonechoorecho2. Download by python org: https://www.python.org/downloads/macos/;;CYGWIN*|MINGW32*|MSYS*|MINGW*)echo1. Download by python org: https://www.python.org/downloads/windows/echo2. Check the\Add Python to PATH\option during installation.;;*)echoUnable to determine the appropriate Python installation method for your system.;;esacexit1fiexportCC${COMPILER_TOOLCHAIN}clangechoCC :${CC}exportCXX${COMPILER_TOOLCHAIN}clangechoCXX :${CXX}exportHOSTCC${CC}echoHOSTCC :${HOSTCC}exportHOSTCXX${CXX}echoHOSTCXX :${HOSTCXX}exportCPP${CXX}echoCPP :${CPP}exportAS${COMPILER_TOOLCHAIN}llvm-asechoAS :${AS}exportLD${COMPILER_TOOLCHAIN}ld.lldechoLD :${LD}exportSTRIP${COMPILER_TOOLCHAIN}llvm-stripechoSTRIP :${STRIP}exportRANLIB${COMPILER_TOOLCHAIN}llvm-ranlibechoRANLIB :${RANLIB}exportOBJDUMP${COMPILER_TOOLCHAIN}llvm-objdumpechoOBJDUMP :${OBJDUMP}exportOBJCOPY${COMPILER_TOOLCHAIN}llvm-objcopyechoOBJCOPY :${OBJCOPY}exportNM${COMPILER_TOOLCHAIN}llvm-nmechoNM :${NM}exportAR${COMPILER_TOOLCHAIN}llvm-arechoAR :${AR}exportSYSROOT${OHOS_SDK}/native/sysrootexportPKG_CONFIG_SYSROOT_DIR${SYSROOT}/usr/lib/aarch64-linux-ohosexportPKG_CONFIG_PATH${PKG_CONFIG_SYSROOT_DIR}exportPKG_CONFIG_EXECUTABLE${PKG_CONFIG_SYSROOT_DIR}exportHNP_TOOL${OHOS_SDK}/toolchains/hnpcliexportCMAKE${OHOS_SDK}/native/build-tools/cmake/bin/cmakeexportTOOLCHAIN_FILE${OHOS_SDK}/native/build/cmake/ohos.toolchain.cmakeexportWORK_ROOT${PWD}exportARCHIVE_PATH${WORK_ROOT}/outputexportCOMM_DEP_PATH${WORK_ROOT}/deps_installexportHNP_PUBLIC_PATH${HNP_PERFIX}/data/service/hnp/exportMAKE_QUITE_PARAM -s exportCONFIGURE_QUITE_PARAM --quiet exportTARGET_PLATFORMaarch64-linux-ohosexportCFLAGS-fPIC -D__MUSL__1 -D__OHOS__ -fstack-protector-strong --target${TARGET_PLATFORM}-fuse-ld${LD}--sysroot${SYSROOT}exportCXXFLAGS${CFLAGS}exportLD_LIBRARY_PATH${SYSROOT}/usr/lib:${LD_LIBRARY_PATH}exportLDFLAGS${LDFLAGS}-fuse-ld${LD}--target${TARGET_PLATFORM}--sysroot${SYSROOT}exportHOST_TYPE--hostaarch64-linux --buildaarch64-linuxmkdir-p${HNP_PUBLIC_PATH}mkdir-p${ARCHIVE_PATH}mkdir-pcode# 默认直接构建指定目录除非显式要求按 dependency.json 走BUILD_BY_DEPENDENCY${BUILD_BY_DEPENDENCY:-false}# 需要构建的组件名称SPECIFIC_DIR${SPECIFIC_DIR:-cmdtree}if[[${BUILD_BY_DEPENDENCY}true]];thenpython build_dependency.pyelsepushdcode/${SPECIFIC_DIR}chmodx build_ohos.sh ./build_ohos.shpopdfi2、code/cmdtree/hnp.json 鸿蒙原生包配置tree 组件的 HNP 配置文件指定配置类型为 hnp-config组件名称为 tree、版本 2.2.1安装配置留空{type:hnp-config,name:tree,version:2.2.1,install:{}}3、code/cmdtree/build_ohos.sh 构建与打包脚本脚本定义 tree 组件相关参数清理旧构建、编译安装组件拷贝文档与 hnp.json通过 HNP 工具打包并生成对应版本的 tar.gz 压缩包#!/bin/bashset-euopipefailcomponent_nametreecomponent_version2.2.1install_prefix/usrexportTREE_INSTALL_HNP_PATH${HNP_PUBLIC_PATH}/${component_name}.org/${component_name}_${component_version}echoInstall root:${TREE_INSTALL_HNP_PATH}mkdir-p${TREE_INSTALL_HNP_PATH}makecleanmakeVERBOSE1PREFIX${install_prefix}MANDIR${install_prefix}/share/manmakeinstallPREFIX${install_prefix}DESTDIR${TREE_INSTALL_HNP_PATH}MANDIR${install_prefix}/share/mandoc_dir${TREE_INSTALL_HNP_PATH}/usr/share/doc/${component_name}mkdir-p${doc_dir}install-m644README README.md CHANGES LICENSE INSTALL TODO${doc_dir}/install-m644hnp.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_${component_name}_${component_version}.tar.gz${component_name}_${component_version}/popd4、配置 dependency.json 依赖配置文件配置文件定义项目依赖组件明确指定需引入 tree 工具其源码来源{dependency:[{name:tree,branch:2.2.1_ohos,url:gitgitcode.com:OpenHarmonyPCDeveloper/cmdtree.git}]}5、成功在鸿蒙 OpenHarmony 环境中交叉编译并打包了 tree 工具 版本 2.2.1 整个流程从编译、安装到 HNP 打包完全顺畅没有报错 ret0 表示执行成功成功执行两次构建命令完成 zoxide 和 tree 的 HNP 打包重新编译 tree 并输出对应产物忽略无关编译警告确保产物包含必要目录与文件cd~/build ./build.sh--sdk~/ohos-sdk/linux6、检查构建产物ls-lhoutput/总结本次实践不仅为 tree 工具融入鸿蒙PC生态提供了完整方案更提炼出一套通用的 Linux 开源软件鸿蒙适配方法论从环境迁移、依赖配置到打包发布的标准化流程可为后续更多命令行工具的生态适配提供参考助力鸿蒙PC端工具链的丰富与完善进一步降低开源软件融入鸿蒙生态的技术门槛推动生态功能多元化拓展。欢迎加入开源鸿蒙PC社区https://harmonypc.csdn.net/GitCode代码仓库https://gitcode.com/weixin_62765017/cmdtree常见问题FAQQ1编译提示 clang: command not found 怎么办原因SDK 路径错误或工具链缺失。解决检查 --sdk 路径是否正确确认 SDK 完整解压。Q2hnpcli 打包失败提示 invalid hnp.json原因JSON 格式错误或关键字段缺失。解决检查引号、逗号确保包含 type、name、version 字段。Q3鸿蒙设备上运行提示 exec format error原因架构不匹配未编译为 aarch64。解决确认 --targetaarch64-linux-ohos用 file 验证架构。