广东省网站建设_网站建设公司_数据统计_seo优化

OpenHarmony Linux 命令行开源软件适配与构建：基于 Cursor × WSL 的全流程实战指南

前言

随着 OpenHarmony PC 生态不断完善，Linux 命令行工具适配成为生态拓展的关键环节，本文以经典目录可视化工具 tree 2.2.1 为案例，基于 Cursor/VS Code + WSL Ubuntu 24.04 技术栈，提供从环境搭建、SDK 配置到交叉编译、HNP 打包的完整可复现实操方案，帮助开发者快速掌握 Windows 侧鸿蒙交叉编译环境搭建核心流程，规避各类适配痛点，助力更多 Linux 开源软件高效融入 OpenHarmony PC 生态，为生态丰富与功能拓展提供实用技术支撑。

前提准备

通过 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 -Name "wslhost" -Force -ErrorAction SilentlyContinue
# 强制终止wslservice进程，遇到错误时静默处理（不报错）
Stop-Process -Name "wslservice" -Force -ErrorAction SilentlyContinue
# 等待30秒，确保相关进程完全停止
Start-Sleep -Seconds 30
# 列出所有已安装的WSL分发版，并显示其运行状态（名称、状态、WSL版本）
wsl -l -v

2、使用.tar格式备份系统

# 创建WSL备份目录（已存在则忽略）
New-Item -Path "D:\WSL" -ItemType Directory -Force
# 导出Ubuntu-24.04到指定备份文件
wsl --export Ubuntu-24.04 D:\WSL\Ubuntu2404_backup.tar

3、注销原系统释放C盘空间

# 彻底注销/删除 Ubuntu-24.04 WSL 发行版（所有数据会丢失）
wsl --unregister Ubuntu-24.04

4、导入系统到D盘

# 从备份文件导入并创建 Ubuntu-24.04 WSL 发行版（安装路径：D:\WSL\Ubuntu2404）
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu2404 D:\WSL\Ubuntu2404_backup.tar

5、恢复默认用户

# 设置 Ubuntu-24.04 WSL 的默认登录用户为 weishuo
ubuntu2404.exe config --default-user weishuo

6、验证迁移结果

# 列出所有已安装的 WSL 发行版及运行状态
wsl -l -v
# 启动并进入 Ubuntu-24.04 WSL 发行版
wsl -d Ubuntu-24.04

Linux 开发环境初始化与依赖配置

1、更换APT软件源

# 备份 Ubuntu 官方软件源配置文件（避免修改出错后无法恢复）
sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.backup
# 使用 vim 编辑器修改软件源配置文件（用于替换为国内源等操作）
sudo vim /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.gpg

2、更新软件包

# 更新软件源索引（获取最新的软件包版本信息）
sudo apt update
# 自动升级所有可更新的软件包（-y 自动确认所有提示，无需手动输入y）
sudo apt upgrade -y

3、安装Python环境

# 安装 Python3 及 pip 包管理工具（-y 自动确认安装）
sudo apt install python3 python3-pip -y
# 配置 python 命令默认指向 python3（优先级 1，若有其他版本可调整优先级）
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1

OpenHarmony SDK 获取、安装与环境配置指南

1、下载OpenHarmony SDK

# 下载 OpenHarmony Master 版本完整 SDK（20250819 构建版本）
wget https://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

2、解压SDK包

# 解压 OpenHarmony 完整 SDK 压缩包（z=gz格式，v=显示进度，x=解压，f=指定文件）
tar -zvxf version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz

3、解压核心组件

# 解压 native 工具包（Linux x64 架构，6.0.0.46 Beta1 版本）
unzip native-linux-x64-6.0.0.46-Beta1.zip
# 解压 toolchains 工具链包（Linux x64 架构，6.0.0.46 Beta1 版本）
unzip toolchains-linux-x64-6.0.0.46-Beta1.zip

4、创建鸿蒙软件包安装目录

# 递归创建 /data/service/hnp 目录（-p 自动创建父目录，不存在则新建）
sudo mkdir -p /data/service/hnp
# 递归设置该目录及所有子内容权限为 777（所有用户可读可写可执行，-R 递归应用）
sudo chmod 777 -R /data/service/hnp

5、获取构建工具，下载鸿蒙构建脚手架

# 切换到当前用户主目录（~ 等价于 /home/用户名）
cd ~
# 从 GitCode 克隆 OpenHarmony PC 开发版构建配置仓库
git clone https://gitcode.com/OpenHarmonyPCDeveloper/build.git

6、源码准备与适配，下载tree命令鸿蒙适配版源码

# 切换到 build 仓库的 code 子目录（需确保该目录已存在）
cd ~/build/code/
# 从 GitCode 克隆 cmdtree 仓库，指定拉取 master 分支
git clone https://gitcode.com/OpenHarmonyPCDeveloper/cmdtree.git -b master

7、创建适配配置文件，进入源码目录，添加两个关键适配文件

• hnp.json 配置文件（）

{
"name": "tree",
"version": "2.2.1",
"description": "递归目录列表显示工具",
"license": "GPL-2.0",
"arch": "aarch64",
"target": "ohos-pc"
}

• build_ohos.sh 编译脚本

#!/bin/bash
# 定义 tree 的安装路径
export TREE_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/tree.org/tree_2.2.1
# 保存原始 PREFIX，编译后恢复
sys_perfix=${PREFIX}
export PREFIX=${TREE_INSTALL_HNP_PATH}
echo "安装路径：${PREFIX}"
# 清理旧编译产物，重新编译
make clean
make VERBOSE=1 prefix=${TREE_INSTALL_HNP_PATH}
make install prefix=${TREE_INSTALL_HNP_PATH}
# 复制配置文件到安装目录
cp hnp.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
# 恢复原始 PREFIX
export PREFIX=${sys_perfix}

8、赋予脚本执行权限，这样就是完整的基于windows的wsl适配鸿蒙pc的linux命令行环境配置流程

chmod +x build_ohos.sh

OpenHarmony 工具链验证与编译测试

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 --version

2、编译环境测试，创建测试程序验证交叉编译环境

• hello_ohos.c

#include <stdio.h>int main() {#ifdef __OHOS__printf("✅ 鸿蒙编译环境正常！已识别 __OHOS__ 系统宏\n");#elseprintf("❌ 未识别鸿蒙系统宏，编译环境异常\n");#endifreturn 0;}

3、使用鸿蒙工具链编译（用 OpenHarmony SDK 的 clang 交叉编译 hello_ohos.c，指定 aarch64-OHOS 目标平台、SDK sysroot 路径及 OHOS 宏，生成适配 OpenHarmony 的可执行文件）

/home/weishuo/ohos-sdk/linux/native/llvm/bin/clang -o hello_ohos hello_ohos.c --target=aarch64-linux-ohos --sysroot=/home/weishuo/ohos-sdk/linux/native/sysroot -D__OHOS__

4、验证生成文件

# 查看 hello_ohos 可执行文件的类型、架构、目标系统等详细信息
file hello_ohos

5、环境验证成功：输出显示为 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 终端进行开发

OpenHarmony PC 适配：tree 2.2.1 交叉编译与 HNP 打包

1、修改 build.sh 需要构建的命令行组件名称

SPECIFIC_DIR="tree"

2、code/cmdtree/hnp.json 鸿蒙原生包配置

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

3、code/cmdtree/build_ohos.sh 构建与打包脚本

export TREE_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/tree.org/tree_2.2.1
sys_prefix=${PREFIX}
export PREFIX=${TREE_INSTALL_HNP_PATH}
echo "${PREFIX}"
make clean
make VERBOSE=1
make install
cp hnp.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
export PREFIX=${sys_prefix}

4、请确保本地完成了 Git 的全局配置

git config --global user.name weixin_62765017
git config --global user.email weixin_62765017@noreply.gitcode.com

5、配置 dependency.json 依赖配置文件

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

6、成功在鸿蒙 OpenHarmony 环境中交叉编译并打包了 tree 工具 版本 2.2.1 ，整个流程从编译、安装到 HNP 打包完全顺畅，没有报错 ret=0 表示执行成功

cd ~/build
./build.sh --sdk ~/ohos-sdk/linux

7、检查构建产物

ls -lh output/

总结

本次实践不仅为 tree 工具融入 OpenHarmony PC 生态提供了完整方案，更提炼出一套通用的 Linux 开源软件鸿蒙适配方法论，从环境迁移、依赖配置到打包发布的标准化流程，可为后续更多命令行工具的生态适配提供参考，助力 OpenHarmony PC 端工具链的丰富与完善，进一步降低开源软件融入鸿蒙生态的技术门槛，推动生态功能多元化拓展。