从零编译OpenHarmonyUbuntu 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 \ libstdc6 gcc-arm-none-eabi vim ssh locales libxinerama-dev \ libxcursor-dev libxrandr-dev libxi-dev安装过程中可能会遇到某些包无法找到的情况这时可以尝试添加universe仓库sudo add-apt-repository universe sudo apt-get update2. 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 ax 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 help4.2 选择编译目标设置编译目标以qemu小型系统为例hb set在交互界面中选择small qemu_small_system_demo4.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作为shsudo dpkg-reconfigure dash选择NoImportError: cannot import name MappingPython 3.10兼容性问题修改prompt_toolkit的from_dict.py文件hb命令未找到PATH环境变量未配置添加~/.local/bin到PATH编译过程中断内存不足增加swap空间或关闭其他内存消耗程序下载失败网络连接问题检查网络或使用代理6. 性能优化建议经过多次尝试我总结出一些可以显著提升编译效率的技巧使用ccache加速echo export USE_CCACHE1 ~/.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物理机上踩过的那些‘坑’与填坑实录
从零编译OpenHarmonyUbuntu 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 \ libstdc6 gcc-arm-none-eabi vim ssh locales libxinerama-dev \ libxcursor-dev libxrandr-dev libxi-dev安装过程中可能会遇到某些包无法找到的情况这时可以尝试添加universe仓库sudo add-apt-repository universe sudo apt-get update2. 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 ax 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 help4.2 选择编译目标设置编译目标以qemu小型系统为例hb set在交互界面中选择small qemu_small_system_demo4.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作为shsudo dpkg-reconfigure dash选择NoImportError: cannot import name MappingPython 3.10兼容性问题修改prompt_toolkit的from_dict.py文件hb命令未找到PATH环境变量未配置添加~/.local/bin到PATH编译过程中断内存不足增加swap空间或关闭其他内存消耗程序下载失败网络连接问题检查网络或使用代理6. 性能优化建议经过多次尝试我总结出一些可以显著提升编译效率的技巧使用ccache加速echo export USE_CCACHE1 ~/.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目录以避免奇怪的构建错误。
