📚 课程目录第1章搭建OpenHarmony开发环境

1. 搭建OpenHarmony开发环境

任务说明

本案例目标是在 Ubuntu 22.04 系统上完成 OpenHarmony 标准系统（mini/small 系统）编译环境的搭建，安装必要的编译工具链与 hb 构建工具，并成功编译出一个最小系统镜像（以 qemu_mini 目标为例）。最终验证方式为：hb 命令可正常执行，编译产物镜像文件生成且文件大小非空。

环境准备与依赖安装

首先更新软件源并安装基础依赖包。OpenHarmony 编译需要 Python 3.8+、Node.js 14+、以及一系列系统库。以下命令在 Ubuntu 22.04 终端中执行：

sudo apt update
sudo apt install -y git curl wget unzip zip python3 python3-pip \
    build-essential gcc g++ make cmake ninja-build \
    libssl-dev libffi-dev libncurses5-dev libncursesw5-dev \
    file rsync bc mtd-utils dosfstools mtools \
    default-jre default-jdk

安装完成后，确认 Python 版本不低于 3.8：

python3 --version

安装 hb 工具

hb 是 OpenHarmony 的构建命令行工具，通过 pip 安装。为避免权限问题，建议使用 --user 方式安装：

python3 -m pip install --user build/hb

如果上述命令因网络原因失败，可先下载 hb 源码包再本地安装。安装完成后，需要将 hb 所在路径加入 PATH 环境变量。hb 通常安装在 ~/.local/bin 下：

export PATH=~/.local/bin:$PATH
echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

验证 hb 是否安装成功：

hb --version

若输出版本号（如 0.4.4），则说明 hb 工具已就绪。

获取 OpenHarmony 源码

本案例以 OpenHarmony 3.2 Release 版本为例。使用 repo 工具拉取源码（需先安装 repo）：

curl -s https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > /usr/local/bin/repo
chmod +x /usr/local/bin/repo
mkdir -p ~/ohos && cd ~/ohos
repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-3.2-Release --no-repo-verify
repo sync -c -j8

源码同步完成后，进入源码根目录，后续所有编译操作均在此目录下进行。

配置编译环境并编译最小系统

OpenHarmony 提供了一键式环境配置脚本。在源码根目录执行：

cd ~/ohos
bash build/prebuilts_download.sh

该脚本会自动下载编译所需的预编译工具链（包括 clang、llvm、sysroot 等），下载完成后设置环境变量：

source build/envsetup.sh

选择编译目标。本案例编译 qemu_mini 最小系统镜像（基于 ARM 架构的 QEMU 模拟器目标）：

hb set

在交互界面中选择 qemu_mini 对应的产品（通常位于 mini 分类下），然后执行编译：

hb build -f

首次编译需要较长时间（取决于机器性能，通常 20~60 分钟）。编译过程中终端会输出编译日志，最终生成镜像文件。

验证编译产物

编译完成后，检查镜像文件是否生成且大小非空。对于 qemu_mini 目标，产物路径通常为：

ls -lh out/qemu_mini/packages/phone/images/

预期应看到类似 system.img、vendor.img、userdata.img 等镜像文件。以 system.img 为例，验证其存在且大小大于 0：

test -s out/qemu_mini/packages/phone/images/system.img && echo "PASS: system.img exists and non-empty"

若输出 PASS，则说明最小系统镜像编译成功。

验证判定标准

hb 工具可用：hb --version 能输出版本号。
编译流程完整：hb build -f 命令执行完毕且无致命错误（exit code 为 0）。
镜像产物存在：上述 test -s 命令返回 PASS，证明镜像文件已生成且非空。

满足以上三点，即可判定本案例目标达成。

常见问题排查

hb 命令找不到：确认 ~/.local/bin 已加入 PATH，或使用 python3 -m hb 调用。
编译报错缺少 Python 模块：执行 python3 -m pip install --user setuptools kconfiglib pycryptodome 补装。
repo sync 失败：检查网络连通性，可尝试 repo sync -c --no-tags -j4 降低并发。
磁盘空间不足：OpenHarmony 源码加编译产物约需 30GB 可用空间，使用 df -h 确认。