2. 开发环境搭建：源码获取、编译配置与工具链验证

说实话，HDF 驱动开发的第一步，往往就把不少人卡住了。我见过太多人花了一整天，就为了把环境跑通。其实没那么玄乎，关键是把几个环节理清楚。

这一章，我带你一步步把环境搭起来。咱们的目标很明确：能拉代码、能编译、能验证 HDF 工具链好不好使。

2.1 环境概览：我们需要什么？

先看看整体需要哪些东西。我习惯把环境分成三层：

层级	组件	说明
宿主系统	Ubuntu 20.04 / 22.04	推荐 22.04，包更全
容器环境	Docker + 官方镜像	隔离编译依赖，避免污染宿主机
源码管理	repo + git	OpenHarmony 多仓管理工具
编译框架	hb + gn + ninja	HDF 驱动编译的核心工具链
验证工具	hdf_devmgr / hdf_test	验证 HDF 框架是否正常

这张表你收好，后面每一步都会用到。

2.2 获取 OpenHarmony 源码

源码获取，说白了就是两件事：装 repo、拉代码。

2.2.1 安装 repo 工具

repo 是 Google 为多 Git 仓管理写的工具。OpenHarmony 有上千个仓库，没有 repo 你根本搞不定。

# 创建 bin 目录并加入 PATH
mkdir -p ~/bin
export PATH=~/bin:$PATH

# 下载 repo 工具
curl -s https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > ~/bin/repo
chmod a+x ~/bin/repo

# 验证安装
repo --version

嗯，这里要注意：如果你在墙内，建议用 Gitee 的镜像源，速度会快很多。我刚开始用 GitHub 源，拉了一下午没拉完，换了 Gitee 十几分钟搞定。

2.2.2 初始化并同步代码

以 OpenHarmony 4.0 Release 为例：

# 创建工作目录
mkdir ohos_4.0 && cd ohos_4.0

# 初始化 repo
repo init -u https://gitee.com/openharmony/manifest.git -b OpenHarmony-4.0-Release --no-repo-verify

# 同步代码（-j4 表示 4 个并行任务）
repo sync -c -j4

同步时间取决于你的网速。我建议用 -j4 而不是 -j8，虽然慢一点，但不容易因为网络波动中断。曾经有一次我贪快用 -j16，结果断了三次，反而更慢。

2.3 编译环境配置：Ubuntu + Docker

我个人强烈建议用 Docker。为什么？因为 OpenHarmony 的编译依赖非常复杂，Python、Node.js、Clang 版本都有严格限制。用 Docker 可以一键搞定，省心。

2.3.1 安装 Docker

# 更新包索引
sudo apt update

# 安装依赖
sudo apt install -y ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 设置稳定版仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# 将当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
newgrp docker

# 验证
docker --version

2.3.2 拉取官方编译镜像

OpenHarmony 官方提供了标准编译镜像，省去了自己配环境的麻烦。

# 拉取标准编译镜像
docker pull swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0

# 验证镜像
docker images | grep openharmony

2.3.3 启动容器并挂载源码

这里有个关键点：要把源码目录挂载到容器里，这样在容器里编译，在宿主机上编辑代码。

# 启动容器，挂载源码目录
docker run -it --name ohos_build \
  -v $(pwd)/ohos_4.0:/home/openharmony \
  -w /home/openharmony \
  swr.cn-south-1.myhuaweicloud.com/openharmony-docker/openharmony-docker:1.0.0 \
  /bin/bash

进入容器后，你就有了一个干净的编译环境。所有工具链都已经预装好了。

2.4 HDF 开发工具链安装与验证

工具链包括三部分：编译工具（hb）、HDF 框架工具、验证脚本。官方镜像里其实已经带了大部分，但我们需要确认一下。

2.4.1 检查 hb 工具

hb 是 OpenHarmony 的编译命令行工具，负责调用 gn 和 ninja。

# 检查 hb 是否可用
which hb
hb --help

# 如果找不到，手动安装
pip3 install --user build/hb

# 设置环境变量
export PATH=~/.local/bin:$PATH

我遇到过一种情况：hb 装上了但报错说找不到 gn。这是因为环境变量没配全。解决办法是 source 一下编译环境的脚本：

source build/envsetup.sh

2.4.2 验证 HDF 框架编译

我们编译一个小目标——HDF 的 sample 驱动，来验证整个链路通不通。

# 选择产品（以 rk3568 为例）
hb set -p rk3568

# 编译 HDF 相关模块
hb build -T //drivers/hdf_core/adapter/khdf/linux/platform:khdf_platform

# 查看编译产物
ls out/rk3568/packages/phone/images/

如果编译成功，你会看到 khdf_platform.ko 之类的内核模块文件。这说明 HDF 框架已经能正常编译了。

2.4.3 验证 HDF 设备管理服务

编译完成后，我们可以在开发板上验证 HDF 服务是否正常启动。

# 进入开发板系统后
# 查看 HDF 设备管理器状态
hdf_devmgr list

# 查看已注册的 HDF 设备
hdf_devmgr dump

正常输出应该能看到类似这样的信息：

DeviceManager: HDF_DEV_MGR
  Device: platform_driver
    Service: HDF_PLATFORM_SERVICE
    State: RUNNING

看到 RUNNING 状态，说明 HDF 框架已经跑起来了。

2.5 环境搭建流程图

下面这张图把整个流程串起来了。你照着这个顺序走，基本不会出错。

2.6 避坑指南

最后，分享几个我踩过的坑，你遇到了可以直接跳过。

• repo 同步卡住：我曾经在同步到 80% 的时候卡了半小时。后来发现是网络问题。解决办法：用 repo sync -c -j1 --fail-fast 单线程重试，虽然慢但稳定。
• Docker 权限问题：如果你每次运行 docker 都要加 sudo，说明没把用户加到 docker 组。执行 sudo usermod -aG docker $USER 后重新登录即可。
• hb 编译报错找不到 Python 模块：这通常是因为容器里默认 Python 版本不对。检查一下 python3 --version，OpenHarmony 4.0 要求 Python 3.8+。
• hdf_devmgr 命令不存在：说明编译时没把 HDF 测试工具编进去。在 hb build 时加上 -T //drivers/hdf_core/adapter/khdf/linux:khdf_test 重新编译。