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

2. 开发环境搭建：OpenHarmony源码获取、编译环境配置、hdc工具使用

说实话，很多初学者在HDF驱动开发上栽跟头，不是因为框架多难，而是环境没搭好。我见过太多人花了一周时间折腾编译，结果发现是repo同步时网络断了。所以这一章，咱们把地基打牢。

2.1 环境总览：你需要准备什么

先列个清单，心里有个数。我个人习惯把环境分成三层：主机工具链、源码管理、烧录与调测。

层级	组件	说明
主机工具链	Ubuntu 20.04/22.04、Python 3.8+、gn、ninja	编译环境核心，建议用虚拟机或WSL2
源码管理	repo、git、curl	用于拉取OpenHarmony多仓代码
烧录与调测	hdc、HiBurn、USB驱动	设备侧交互，hdc是主力

注意：不要用Windows直接编译OpenHarmony。我曾经试过在Cygwin上跑，折腾了两天，最后还是切回了Ubuntu。老老实实用Linux，省心。

2.2 获取OpenHarmony源码

源码获取分两步：安装repo工具，然后同步代码。这里有个坑——网络。OpenHarmony的仓库在gitee，国内访问还行，但如果你在海外或者用某些小众运营商，可能会断断续续。

2.2.1 安装repo

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

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

# 验证安装
repo --version

嗯，这里要注意：repo脚本会调用git，所以确保git已经配置好用户名和邮箱。

2.2.2 同步源码

以OpenHarmony 4.0 Release为例，我个人建议用每日构建标签，而不是master分支。为什么？因为master可能正在修bug，你拉下来编译不过，心态容易崩。

# 创建工作目录
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

# 同步代码（这步最耗时）
repo sync -c -j4

小技巧：如果同步中断，不要重新repo init。直接再跑一次repo sync -c -j4就行。repo会断点续传，只拉取未完成的部分。

同步完成后，源码目录大概长这样：

ohos_4.0/
├── applications/
├── base/
├── build/
├── device/
├── drivers/          # HDF驱动框架核心代码
├── foundation/
├── kernel/
├── third_party/
└── vendor/

咱们做HDF开发，重点关注drivers/目录。里面分了framework、peripheral、interface等子目录，后面章节会细讲。

2.3 编译环境配置

环境配置说白了就是装一堆依赖。我整理了一个清单，你照着敲就行。

2.3.1 安装编译依赖

# 更新包管理器
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y git curl wget tar unzip

# 安装编译工具链
sudo apt install -y gcc g++ make cmake

# 安装Python环境
sudo apt install -y python3 python3-pip python3-setuptools

# 安装gn和ninja（OpenHarmony用它们构建）
sudo apt install -y gn ninja-build

# 安装其他依赖
sudo apt install -y libssl-dev libffi-dev libncurses5-dev

这里有个细节：Python版本。OpenHarmony 4.0要求Python 3.8以上。你可以用python3 --version检查。如果版本太低，我建议用pyenv管理多版本，别直接升级系统Python，容易把apt搞坏。

2.3.2 配置编译环境变量

我个人习惯把环境变量写进~/.bashrc，这样每次打开终端自动生效。

# 编辑bashrc
vim ~/.bashrc

# 添加以下内容
export PATH=~/bin:$PATH
export OHOS_ROOT=~/ohos_4.0
export OHOS_ARCH=arm64

# 生效
source ~/.bashrc

2.3.3 首次编译验证

环境配好之后，跑一次全量编译，验证工具链是否正常。以Hi3516DV300开发板为例：

# 进入源码根目录
cd $OHOS_ROOT

# 设置产品
hb set -root .
hb set -p hi3516dv300

# 开始编译
hb build -f

第一次编译大概需要30-60分钟，取决于机器性能。如果编译成功，你会看到类似这样的输出：

[1/1] build OHOS image done
out/hi3516dv300/packages/OHOS_image.tar.gz

    关键路径：编译产物在out/目录下。HDF驱动编译后的.ko文件在out/<product>/lib/modules/里。后面调测时，我们需要把这些模块推到开发板上。

2.4 hdc工具使用

hdc（HarmonyOS Device Connector）是咱们和开发板打交道的核心工具。说白了，它就是Android的adb在鸿蒙上的对应物。但用法上有些差异，我踩过不少坑。

2.4.1 安装hdc

hdc工具在源码的developtools/hdc_standard/目录下。你可以直接编译出来，也可以下载预编译版本。

# 编译hdc
cd $OHOS_ROOT/developtools/hdc_standard
python3 build.py

# 编译产物在
out/hdc_standard/hdc

编译完成后，把hdc放到PATH里：

sudo cp out/hdc_standard/hdc /usr/local/bin/
sudo chmod +x /usr/local/bin/hdc

2.4.2 连接开发板

连接方式有两种：USB和网络。我建议初学者先用USB，稳定。

# 查看设备列表
hdc list targets

# 如果显示[empty]，检查USB驱动和线缆
# 正常情况会显示设备序列号
[10086]

避坑指南：我曾经遇到hdc连不上设备，折腾了半天，最后发现是USB线的问题。有些线只能充电，不能传数据。换一根带数据传输的线就好了。

2.4.3 常用hdc命令

这里列几个我日常调测HDF驱动时最常用的命令：

命令	用途	示例
`hdc shell`	进入设备shell	`hdc shell`
`hdc file send`	推送文件到设备	`hdc file send ./hdf_test.ko /data/`
`hdc file recv`	从设备拉取文件	`hdc file recv /data/log.txt ./`
`hdc reboot`	重启设备	`hdc reboot`
`hdc hilog`	查看设备日志	`hdc hilog \| grep HDF`

举个例子，调测HDF驱动时，我经常这样操作：

# 1. 编译驱动模块
hb build -T hdf_test_driver

# 2. 推送模块到设备
hdc file send out/hi3516dv300/lib/modules/hdf_test.ko /data/

# 3. 加载模块
hdc shell "cd /data && insmod hdf_test.ko"

# 4. 查看日志确认加载状态
hdc hilog | grep "HDF_TEST"

2.4.4 hdc hilog的妙用

调HDF驱动，日志是命根子。hdc hilog比dmesg更强大，它支持过滤、格式化、实时输出。

# 实时查看HDF相关日志
hdc hilog -b D -t HDF -T 100

# 参数说明：
# -b D   : 只显示Debug级别以上
# -t HDF : 只显示HDF标签
# -T 100 : 显示最近100条

个人经验：我习惯开两个终端。一个跑hdc hilog | grep HDF实时看日志，另一个用来执行insmod/rmmod操作。这样驱动加载的每一行输出都能抓到，定位问题快很多。

2.5 环境验证：跑一个Hello World驱动

环境搭好了，咱们跑个最简单的驱动验证一下。这个驱动不干别的，就打印一行"Hello HDF"。

// hello_hdf.c
#include "hdf_device_desc.h"
#include "hdf_log.h"

#define HDF_LOG_TAG hello_hdf

static int32_t HelloDriverBind(struct HdfDeviceObject *deviceObject)
{
    HDF_LOGI("Hello HDF: Bind");
    return HDF_SUCCESS;
}

static int32_t HelloDriverInit(struct HdfDeviceObject *deviceObject)
{
    HDF_LOGI("Hello HDF: Init");
    return HDF_SUCCESS;
}

static void HelloDriverRelease(struct HdfDeviceObject *deviceObject)
{
    HDF_LOGI("Hello HDF: Release");
}

struct HdfDriverEntry g_helloDriverEntry = {
    .moduleVersion = 1,
    .moduleName = "hello_hdf",
    .Bind = HelloDriverBind,
    .Init = HelloDriverInit,
    .Release = HelloDriverRelease,
};

HDF_INIT(g_helloDriverEntry);

编译、推送、加载，三步走：

# 编译
hb build -T hello_hdf

# 推送
hdc file send out/.../hello_hdf.ko /data/

# 加载
hdc shell "cd /data && insmod hello_hdf.ko"

# 看日志
hdc hilog | grep "Hello HDF"

如果看到"Hello HDF: Init"和"Hello HDF: Bind"，恭喜你，环境全部打通了。

2.6 本章知识图谱

下面这张图总结了开发环境搭建的完整流程和关键节点，你可以对照着检查自己的环境。