📚 课程目录第3章开发环境搭建（下）

3. 开发环境搭建（下）：获取 OpenHarmony 源码、配置编译环境、首次编译与烧录

上一节我们把开发工具链装好了，但光有工具没有源码，就像有了菜刀没有菜。这一节我们真正开始「下锅」——拉取 OpenHarmony 源码、配置编译环境、然后完成第一次编译和烧录。

说实话，源码拉取这一步，很多新手会卡在 repo 同步上。别急，我带你一步步走通。

3.1 获取 OpenHarmony 源码

OpenHarmony 的源码托管在 Gitee 上，使用 Google 的 repo 工具来管理多仓库。我个人习惯把源码放在 ~/openharmony 目录下，方便管理。

提示： 确保你的网络环境能正常访问 Gitee。如果在内网开发，可以考虑先下载镜像包再离线同步。

3.1.1 配置 Git 与 repo

先确认 Git 已经安装，并且配置好用户名和邮箱：

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

然后初始化 repo 工具。如果你按照上一节安装了 Python 和 Git，repo 脚本应该已经就绪：

mkdir ~/openharmony
cd ~/openharmony
repo init -u https://gitee.com/openharmony/manifest.git -b master --no-repo-verify

-b master 指定主干分支。如果你想针对某个具体版本（比如 3.2 Release），可以把 master 换成对应的标签名。

3.1.2 同步源码

初始化完成后，执行同步命令：

repo sync -c -j4

-j4 表示用 4 个线程并行下载。如果你的机器性能好、网速快，可以改成 -j8 甚至 -j16。我曾经在只有 4GB 内存的旧笔记本上跑 -j16，结果直接 OOM 了……嗯，量力而行。

注意： 首次同步时间较长，取决于网络状况，通常需要 30 分钟到 2 小时。如果中途断网，重新执行 repo sync 会断点续传，不用从头再来。

3.1.3 切换指定版本（可选）

如果你需要固定某个发布版本，比如 OpenHarmony 3.2 Release，可以这样操作：

repo init -u https://gitee.com/openharmony/manifest.git -b refs/tags/OpenHarmony-v3.2-Release --no-repo-verify
repo sync -c -j4

版本号可以在 OpenHarmony 官方 Release 页面查到。我个人建议初学者直接用 master 分支，因为社区修复快、文档更新也及时。

3.2 配置编译环境

源码拉下来了，下一步是配置编译环境。OpenHarmony 使用 hb 作为编译构建工具，它本质上是对 GN + Ninja 的封装。

3.2.1 安装 hb 工具

进入源码根目录，执行：

cd ~/openharmony
pip3 install --user build/lite/hb

安装完成后，验证一下：

hb --version

如果能正常输出版本号，说明安装成功。如果提示 command not found，检查一下 ~/.local/bin 是否在 PATH 中。

3.2.2 设置编译环境变量

每次编译前，需要导入环境变量。我习惯写一个脚本，省得每次都敲：

cat > ~/openharmony/env_setup.sh << 'EOF'
#!/bin/bash
export PATH=~/.local/bin:$PATH
export DEVICE_NAME=hisilicon
export PRODUCT_NAME=hi3861v100
EOF

chmod +x ~/openharmony/env_setup.sh

然后每次打开新终端，执行 source ~/openharmony/env_setup.sh 就行。

  关键点： 不同的开发板对应不同的 PRODUCT_NAME。我们课程以 Hi3861 为例，它的 product 就是 hi3861v100。如果你用其他板子，记得换成对应的名称。

3.3 首次编译

环境配好，终于可以编译了。说实话，第一次编译我也有点紧张，生怕报一堆红错。但只要你前面的步骤没漏，一般都能一次过。

3.3.1 选择编译目标

在源码根目录下，执行：

hb set

会弹出一个图形化菜单，让你选择产品。用方向键选择 hi3861v100，然后回车确认。

你也可以直接命令行指定，跳过菜单：

hb set -root . -p hi3861v100

3.3.2 执行编译

选择好目标后，直接运行：

hb build -f

-f 表示全量编译。第一次编译建议用全量，后面增量编译可以不加 -f。

编译过程会输出大量日志。看到类似下面的信息，说明编译成功：

[1/1] STAMP obj/build/lite/ohos.stamp
OHOS build success!
@Generated by /home/user/openharmony/out/hi3861v100/wifiiot_hispark_pegasus/OHOS_Image.bin

整个编译过程，在我的 i7 机器上大约 3-5 分钟。如果你的机器比较老，可能得 10 分钟以上。

小技巧： 编译过程中如果报错，先看错误日志的前几行，大部分问题都是缺少依赖或者路径不对。我曾经遇到一个坑——Python 版本不对，hb 工具跑不起来，换了 Python 3.8 就好了。

3.4 烧录到开发板

编译出 OHOS_Image.bin 之后，下一步就是烧录到 Hi3861 开发板上。

3.4.1 连接开发板

用 USB 线把 Hi3861 开发板连接到电脑。在 Linux 下，通常会被识别为 /dev/ttyUSB0 或 /dev/ttyACM0。可以用 ls /dev/ttyUSB* 查看。

注意： 如果看不到设备节点，检查一下 USB 驱动是否安装，或者换一根数据线。有些劣质线只能充电，不能传数据。

3.4.2 使用烧录工具

OpenHarmony 为 Hi3861 提供了烧录脚本，位于源码目录下：

cd ~/openharmony
python3 build/lite/hb/flash.py -p hi3861v100 -b out/hi3861v100/wifiiot_hispark_pegasus/OHOS_Image.bin

执行后，脚本会提示你按下开发板上的复位键（或者某些板子需要按住 BOOT 键再上电）。按照提示操作，烧录就开始了。

烧录成功后会显示：

Flashing completed successfully.

3.4.3 验证烧录结果

烧录完成后，用串口工具连接开发板，波特率设置为 115200。我习惯用 screen：

screen /dev/ttyUSB0 115200

按下开发板复位键，你应该能看到 OpenHarmony 的启动日志，最后出现 OHOS # 提示符，说明系统已经跑起来了。

  验证要点： 看到 OHOS # 提示符，说明内核启动成功，文件系统挂载正常。如果卡在某个驱动加载阶段，通常是设备树配置问题。

3.5 本章知识结构

下面这张图帮你梳理了从源码获取到烧录运行的完整流程：

3.6 常见问题与避坑

问题现象	可能原因	解决办法
`repo sync` 卡住不动	网络不稳定或 Gitee 限流	加 `--no-tags` 参数，或换时间段重试
`hb build` 报 Python 错误	Python 版本不匹配	确认使用 Python 3.7-3.9，推荐 3.8
烧录时找不到串口	USB 驱动未安装或权限不足	安装 CH340 驱动，或 `sudo chmod 666 /dev/ttyUSB0`
启动日志卡在某个驱动	设备树配置与板子不匹配	检查 `device/hisilicon` 下的 dts 文件

避坑提醒： 我曾经在烧录时忘记按复位键，结果脚本一直等待，我还以为是死机了。后来才发现提示信息里写着「Please press reset button」……所以，仔细看终端输出，别着急。

好了，到这里你已经完成了 OpenHarmony 源码的获取、编译环境的配置、首次编译和烧录。整个过程走通之后，后面的事情就顺了。开发板上的 OHOS # 提示符，就是你进入 OpenHarmony 南向开发世界的第一道门。