从零编译OpenHarmony：我在Ubuntu 22.04物理机上踩过的那些‘坑’与填坑实录-平芜编程栈

从零编译OpenHarmony：Ubuntu 22.04物理机上的实战排坑指南

当我在Ubuntu 22.04物理机上第一次尝试编译OpenHarmony时，本以为按照官方文档就能顺利完成，没想到却遭遇了一系列意想不到的"坑"。这篇文章记录了我从环境准备到最终编译成功的完整过程，重点分享那些官方文档没有提及的疑难问题及其解决方案。不同于标准教程的平铺直叙，这里将还原一个真实的、充满挑战的搭建过程，希望能为后来者节省宝贵的时间。

1. 环境准备：那些容易被忽视的基础配置

在开始编译OpenHarmony之前，Ubuntu 22.04的基础环境配置就有几个关键点需要注意。这些细节看似简单，却可能成为后续编译失败的罪魁祸首。

1.1 解释器切换：dash与bash的抉择

Ubuntu默认使用dash作为/bin/sh的链接，而OpenHarmony的编译脚本需要bash特性支持。执行以下命令检查并切换：

ls -l /bin/sh # 查看当前链接 sudo dpkg-reconfigure dash # 选择"No"切换为bash

这个步骤经常被忽略，但如果不做，后续运行编译脚本时可能会出现奇怪的语法错误。

1.2 依赖库安装：一个都不能少

OpenHarmony编译依赖大量开发库，官方文档的列表可能不完整。以下是经过验证的完整依赖安装命令：

sudo apt-get update && sudo apt-get install -y \ binutils binutils-dev git git-lfs gnupg flex bison gperf \ build-essential zip curl zlib1g-dev gcc-multilib g++-multilib \ gcc-arm-linux-gnueabi libc6-dev-i386 libc6-dev-amd64 \ lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z1-dev \ ccache libgl1-mesa-dev libxml2-utils xsltproc unzip m4 bc \ gnutls-bin python3.10 python3-pip ruby genext2fs \ device-tree-compiler make libffi-dev e2fsprogs pkg-config perl \ openssl libssl-dev libelf-dev libdwarf-dev u-boot-tools \ mtd-utils cpio doxygen liblz4-tool openjdk-8-jre gcc g++ \ texinfo dosfstools mtools default-jre default-jdk libncurses5 \ apt-utils wget scons python3.10-distutils tar rsync git-core \ libxml2-dev lib32z-dev grsync xxd libglib2.0-dev libpixman-1-dev \ kmod jfsutils reiserfsprogs xfsprogs squashfs-tools pcmciautils \ quota ppp libtinfo-dev libtinfo5 libncurses5-dev libncursesw5 \ libstdc++6 gcc-arm-none-eabi vim ssh locales libxinerama-dev \ libxcursor-dev libxrandr-dev libxi-dev

安装过程中可能会遇到某些包无法找到的情况，这时可以尝试添加universe仓库：

sudo add-apt-repository universe sudo apt-get update

2. Python环境配置：版本兼容性陷阱

Ubuntu 22.04默认使用Python 3.10，这带来了一些特殊的兼容性问题，是本次编译过程中最大的"坑"之一。

2.1 设置Python 3.10为默认版本

虽然系统已安装Python 3.10，但需要确保python和python3命令都指向它：

which python3.10 # 记下路径，例如/usr/bin/python3.10 sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1 sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1

注意：不要随意更改系统默认Python版本，特别是Python 2.x和3.x之间的切换，这可能导致系统工具链失效。

2.2 prompt_toolkit的Mapping错误解决方案

在运行hb命令时，我遇到了如下错误：

ImportError: cannot import name 'Mapping' from 'collections' (/usr/lib/python3.10/collections/__init__.py)

这是因为Python 3.10中collections.Mapping已被移至collections.abc。解决方法如下：

定位问题文件：

find ~/.local/lib/python3.10 -name "from_dict.py" | grep prompt_toolkit

修改文件（路径可能不同）：

sudo nano /home/your_user/.local/lib/python3.10/site-packages/prompt_toolkit/styles/from_dict.py

将第9行左右的：

from collections import Mapping

修改为：

from collections.abc import Mapping

这个修改虽然简单，但如果不了解Python 3.10的变化，可能会花费大量时间排查。

3. 源码获取与工具链配置

3.1 获取repo工具

OpenHarmony使用repo管理多仓库代码，需要先获取适配的repo工具：

curl https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 -o repo chmod a+x repo sudo mv repo /usr/bin/ pip3 install -i https://repo.huaweicloud.com/repository/pypi/simple requests

提示：如果遇到网络问题，可以尝试设置HTTP代理环境变量。

3.2 同步OpenHarmony源码

初始化并同步代码仓库（这可能需要较长时间）：

repo init -u https://gitee.com/openharmony/manifest.git -b master --no-repo-verify repo sync -c repo forall -c 'git lfs pull'

常见问题及解决方案：

同步中断：执行repo sync -c继续
速度慢：尝试更换镜像源或夜间同步
存储空间不足：至少需要50GB可用空间

3.3 预编译二进制下载

执行预编译工具下载脚本：

bash build/prebuilts_download.sh

这个步骤可能会因为网络问题失败多次，需要耐心重试。如果某些文件始终无法下载，可以尝试手动下载后放到指定目录。

4. 编译工具安装与配置

4.1 安装hb工具

hb是OpenHarmony的编译构建工具，需要从源码安装：

python3 -m pip install --user build/hb

添加hb到PATH环境变量：

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

验证安装成功：

hb help

4.2 选择编译目标

设置编译目标（以qemu小型系统为例）：

hb set

在交互界面中选择：

small qemu_small_system_demo

4.3 开始编译

执行编译命令：

hb build

编译成功的关键指标：

控制台输出[OHOS INFO] qemu_small_system_demo build success
编译时间根据机器性能从几分钟到几小时不等
最终生成的镜像位于out/ohos-arm-release/packages/phone/images/

5. 常见问题速查表

为了便于参考，我将遇到的主要问题及解决方案整理如下：

问题现象	可能原因	解决方案
`/bin/sh: Syntax error`	使用dash而非bash作为sh	`sudo dpkg-reconfigure dash`选择No
`ImportError: cannot import name 'Mapping'`	Python 3.10兼容性问题	修改prompt_toolkit的from_dict.py文件
`hb命令未找到`	PATH环境变量未配置	添加`~/.local/bin`到PATH
编译过程中断	内存不足	增加swap空间或关闭其他内存消耗程序
下载失败	网络连接问题	检查网络或使用代理

6. 性能优化建议

经过多次尝试，我总结出一些可以显著提升编译效率的技巧：

使用ccache加速：

echo "export USE_CCACHE=1" >> ~/.bashrc echo "export CCACHE_DIR=/path/to/ccache" >> ~/.bashrc source ~/.bashrc ccache -M 50G # 设置缓存大小

并行编译：在hb build命令后添加-jN参数，N为CPU核心数的1-2倍：
```
hb build -j8
```

内存优化：如果内存不足（小于8GB），可以增加swap空间：

sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

选择性编译：只编译特定组件而非完整系统，可以节省大量时间。例如：
```
hb build --build-target your_component
```

在物理机上直接编译OpenHarmony确实比使用虚拟机或容器方案更具挑战性，但也更灵活高效。经过这些"坑"的磨练，不��成功完成了编译，对OpenHarmony的构建系统也有了更深理解。建议每次编译前先执行repo sync更新代码，并定期清理out目录以避免奇怪的构建错误。

从零编译OpenHarmony：我在Ubuntu 22.04物理机上踩过的那些‘坑’与填坑实录