1. 交叉编译配置在嵌入式 Linux 开发中交叉编译工具链是连接宿主机与目标板的关键桥梁。arm-2014.05-29 是 CodeSourcery 推出的基于 ARM 架构的交叉编译工具链版本广泛用于早期 ARM 平台如 ARM926EJ-S、Cortex-A8 等的内核与驱动开发。本章详细介绍该工具链的下载、配置、安装与环境变量设置帮助读者快速搭建可用的交叉编译环境。1.1 工具链简介arm-2014.05-29 全称为 Sourcery CodeBench Lite for ARM EABI采用 GCC 4.8.3 编译器支持 ARM EABI 与 GNU/Linux 两种目标格式。该版本于 2014 年发布适合配合较老的内核源码如 Linux 3.x 系列进行编译。其主要特点包括支持 ARMv4T 至 ARMv7-A 架构。内置 GDB 调试器便于远程调试。提供 glibc 与 uclibc 两种 C 库支持。安装包为自解压格式无需复杂依赖。1.2 下载与解压首先从官方或镜像站点获取安装包文件名为 arm-2014.05-29-arm-none-linux-gnueabi-i686-pc-linux-gnu.tar.bz2。下载完成后将其放置到 /opt 目录下并执行解压cd /opt sudo tar -xjf arm-2014.05-29-arm-none-linux-gnueabi-i686-pc-linux-gnu.tar.bz2解压完成后会在 /opt 下生成目录 arm-2014.05该目录即为工具链的根目录。1.3 环境变量配置为了让系统能够识别交叉编译工具需要将工具链的 bin 目录添加到 PATH 环境变量中。编辑当前用户的环境配置文件vim ~/.bashrc在文件末尾追加以下内容export PATH/opt/arm-2014.05/bin:$PATH保存退出后执行以下命令使配置立即生效source ~/.bashrc1.4 验证安装配置完成后通过以下命令验证工具链是否正常工作arm-none-linux-gnueabi-gcc --version若输出 GCC 版本信息如 gcc version 4.8.3则说明安装成功。此外还可以查看编译器路径确认环境变量生效which arm-none-linux-gnueabi-gcc1.5 常见问题在安装和使用过程中可能会遇到以下问题32 位库缺失该工具链为 32 位程序在 64 位系统上运行需要安装 32 位兼容库可通过 apt 安装 lib32z1、lib32ncurses5 等。权限问题解压和编译时建议使用普通用户操作避免因权限导致文件属性异常。路径冲突若系统中已存在其他 ARM 工具链注意 PATH 顺序确保优先使用本工具链。2. Qt 5.9.1 源码交叉编译在完成交叉编译工具链的配置后接下来需要将 Qt 源码交叉编译为可在 ARM 目标板上运行的库。本章以 qt-everywhere-opensource-src-5.9.1 为例详细介绍源码获取、解压、qmake.conf 配置修改、编译选项设置、编译安装以及打包移植的完整流程。2.1 获取 Qt 源码Qt 5.9.1 是 Qt 5.9 LTS 系列的一个重要补丁版本修复了大量稳定性问题适合嵌入式项目长期使用。获取源码有以下几种途径官网下载访问 Qt 官方下载页面选择 qt-everywhere-opensource-src-5.9.1.tar.xz 进行下载。镜像服务器国内用户可优先使用清华、中科大等开源镜像站下载速度更快且稳定。云盘分享部分嵌入式社区或论坛会提供该版本的云盘备份下载后注意校验文件完整性。无论通过哪种方式获取建议下载后先校验文件校验和确保源码包完整无损。2.2 解压源码将下载好的源码包放置到工作目录例如 /home/user/qt 下然后执行解压cd /home/user/qt tar -xvf qt-everywhere-opensource-src-5.9.1.tar.xz解压完成后进入源码根目录cd qt-everywhere-opensource-src-5.9.1后续所有配置和编译操作都在该目录下进行。2.3 修改配置文件Qt 的交叉编译依赖于 mkspecs 目录下的平台配置文件。针对 ARM 平台需要修改 qtbase/mkspecs/linux-arm-gnueabi-g/qmake.conf 文件使其适配我们使用的 arm-2014.05-29 工具链。首先打开配置文件vi qtbase/mkspecs/linux-arm-gnueabi-g/qmake.conf文件中默认定义了编译器名称需要将其修改为实际使用的交叉编译器。原文件中涉及编译器名称的配置项共有 8 处全部由 arm-linux-gnueabi-gcc 改为 arm-none-linux-gnueabi-gcc具体包括# 修改前 QMAKE_CC arm-linux-gnueabi-gcc QMAKE_CXX arm-linux-gnueabi-g QMAKE_LINK arm-linux-gnueabi-g QMAKE_LINK_SHLIB arm-linux-gnueabi-g QMAKE_AR arm-linux-gnueabi-ar QMAKE_OBJCOPY arm-linux-gnueabi-objcopy QMAKE_STRIP arm-linux-gnueabi-strip QMAKE_RANLIB arm-linux-gnueabi-ranlib 修改后 QMAKE_CC arm-none-linux-gnueabi-gcc QMAKE_CXX arm-none-linux-gnueabi-g QMAKE_LINK arm-none-linux-gnueabi-g QMAKE_LINK_SHLIB arm-none-linux-gnueabi-g QMAKE_AR arm-none-linux-gnueabi-ar QMAKE_OBJCOPY arm-none-linux-gnueabi-objcopy QMAKE_STRIP arm-none-linux-gnueabi-strip QMAKE_RANLIB arm-none-linux-gnueabi-ranlib修改完成后保存退出。注意如果工具链的 bin 目录已正确加入 PATH则无需填写编译器绝对路径否则建议填写完整路径以确保能找到编译器。2.4 添加 ARM 指令集支持为了让编译出的 Qt 库充分发挥 ARM 处理器的性能需要在 qmake.conf 中追加针对 ARMv7-A 架构的编译优化选项。在配置文件的合适位置添加以下两行QMAKE_CFLAGS_RELEASE -O2 -marcharmv7-a QMAKE_CXXFLAGS_RELEASE -O2 -marcharmv7-a其中 -O2 表示二级优化-marcharmv7-a 指定目标处理器架构为 ARMv7-A适用于 Cortex-A8、Cortex-A9 等主流处理器。如果目标板是 Cortex-A7 或 Cortex-A15同样属于 ARMv7-A 架构该配置同样适用。2.5 配置编译选项在源码根目录下执行 configure 脚本生成 Makefile 并配置编译选项。以下是一个常用的嵌入式配置示例./configure \ -prefix /usr/local/qt5.9.1-arm \ -opensource \ -confirm-license \ -release \ -shared \ -xplatform linux-arm-gnueabi-g \ -no-opengl \ -no-cups \ -no-xcb \ -no-gtk \ -no-nis \ -no-accessibility \ -no-sql-sqlite \ -no-sql-mysql \ -no-sql-psql \ -no-sql-odbc \ -no-sql-ibase \ -no-sql-sqlite2 \ -no-sql-tds \ -no-sql-db2 \ -no-sql-oci下面对上述配置中涉及的主要编译选项逐一进行解释帮助读者理解每个参数的作用以便根据实际项目需求灵活调整。-prefix /usr/local/qt5.9.1-arm指定 Qt 的安装路径。编译完成后所有头文件、库文件、可执行程序以及 mkspecs 等都会安装到该目录下。建议使用独立目录便于后续打包移植和版本管理。-opensource选择开源版本许可。Qt 提供开源版LGPL/GPL和商业版两种许可使用开源版时需配合 -confirm-license 确认接受许可协议。-confirm-license自动确认并接受许可协议避免 configure 过程中出现交互式询问适合脚本化自动化编译场景。-release以 Release 模式编译即启用编译优化并去除调试信息生成的库体积更小、运行效率更高适合最终发布到目标板使用。与之对应的是 -debug 模式用于开发调试阶段。-shared编译生成动态链接库.so 文件而非静态库.a 文件。动态库可显著减小应用程序体积并支持多个程序共享同一份库便于后续单独升级 Qt 库。-xplatform linux-arm-gnueabi-g指定交叉编译的目标平台。该参数告诉 configure 使用 qtbase/mkspecs/linux-arm-gnueabi-g 目录下的 qmake.conf 配置从而调用我们前面修改好的 arm-linux-gcc 交叉编译器进行编译。这是整个交叉编译流程中最关键的参数。-no-opengl禁用 OpenGL 支持。嵌入式目标板通常没有 GPU 或缺少 OpenGL 驱动禁用后可以避免编译 OpenGL 相关模块带来的依赖问题同时减小库体积。-no-cups禁用 CUPS 打印系统支持。嵌入式设备一般不需要打印功能禁用后可以减少不必要的依赖。-no-xcb禁用 XCB 平台插件。XCB 是 X11 窗口系统在 Linux 下的接口库嵌入式设备通常直接运行在 framebuffer 上而不使用 X11因此需要禁用。-no-gtk禁用 GTK 主题集成。Qt 默认可以集成 GTK 主题风格但在嵌入式环境中没有 GTK 运行环境禁用后避免编译错误。-no-nis禁用 NIS网络信息服务支持。NIS 主要用于大型网络环境下的用户认证嵌入式单机设备不需要该功能。-no-accessibility禁用无障碍辅助功能支持。该功能主要用于屏幕阅读器等辅助工具嵌入式设备通常不需要禁用后可以减小体积。-no-sql-sqlite、-no-sql-mysql、-no-sql-psql、-no-sql-odbc、-no-sql-ibase、-no-sql-sqlite2、-no-sql-tds、-no-sql-db2、-no-sql-oci这一组参数用于禁用各类数据库驱动插件包括 SQLite、MySQL、PostgreSQL、ODBC、InterBase、SQLite2、TDS、DB2 和 Oracle。嵌入式项目如果不需要数据库功能全部禁用可以显著减少编译时间和库体积。如果目标应用确实需要某种数据库则去掉对应的 -no-sql-xxx 参数即可。配置完成后执行 make 命令开始编译编译过程耗时较长建议使用 make -j4 或 make -j8 利用多核加速。编译完成后执行 make install 将产物安装到 -prefix 指定的目录。2.6 编译configure 配置完成后会在源码根目录下生成 Makefile。接下来执行 make 命令开始编译 Qt 源码编译过程耗时较长建议使用多核并行编译以加快速度make -j4如果宿主机 CPU 核心数较多可以使用 make -j8 或更高并行度。编译过程中会输出大量日志如果出现错误可先查看错误信息定位问题常见错误包括编译器路径未找到、依赖库缺失等可参考第一章的常见问题部分排查。编译完成后可以继续编译 Qt 自带的示例程序用于后续在目标板上验证 Qt 环境是否正常make examples2.7 安装编译成功后执行 make install 将编译产物安装到 configure 时通过 -prefix 指定的目录即 /usr/local/qt5.9.1-armsudo make install安装完成后检查安装目录是否生成了完整的 Qt 运行环境主要包括以下子目录bin包含 qmake、moc、uic 等 Qt 开发工具。lib包含 Qt 核心库、插件以及 cmake 配置文件。include包含 Qt 头文件供交叉编译应用程序时引用。mkspecs包含平台配置文件即我们前面修改过的 qmake.conf 所在目录。plugins包含平台插件、图像格式插件等运行时组件。可以通过以下命令确认安装是否成功ls /usr/local/qt5.9.1-arm /usr/local/qt5.9.1-arm/bin/qmake -v若 qmake 能正常输出版本信息则说明 Qt 已成功安装到宿主机。2.8 打包移植Qt 交叉编译完成后需要将编译产物移植到 ARM 目标板上运行。由于目标板通常存储空间有限建议只拷贝运行所需的库和插件而不是整个安装目录。下面介绍两种常用的移植方式。方式一整体拷贝如果目标板存储空间充足可以直接将整个安装目录拷贝到目标板。将 /usr/local/qt5.9.1-arm 目录打包后传输到目标板再解压到相同路径# 在宿主机上打包 cd /usr/local tar -czf qt5.9.1-arm.tar.gz qt5.9.1-arm 将压缩包拷贝到目标板后在目标板上解压 tar -xzf qt5.9.1-arm.tar.gz -C /usr/local方式二精简拷贝如果目标板存储空间有限可以只拷贝运行所需的库和插件。首先在宿主机上查看 Qt 库的依赖关系确定需要哪些动态库# 查看 Qt 库依赖的共享库 arm-none-linux-gnueabi-readelf -d /usr/local/qt5.9.1-arm/lib/libQt5Core.so.5 | grep NEEDED然后根据目标应用实际使用的模块将对应的 lib 目录下的 .so 文件、plugins 目录下的平台插件如 libqlinuxfb.so以及目标板系统所需的依赖库一并拷贝到目标板。拷贝完成后在目标板上设置环境变量使 Qt 能找到库和插件环境变量作用示例值LD_LIBRARY_PATH指定 Qt 动态库的搜索路径使目标板运行时能找到 Qt 的 .so 库文件/usr/local/qt5.9.1-arm/libQT_QPA_PLATFORM指定 Qt 使用的平台插件嵌入式设备通常使用 Linux framebuffer 平台linuxfbQT_QPA_FONTDIR指定 Qt 的字体目录避免中文等文字显示为方块/usr/share/fontsexport LD_LIBRARY_PATH/usr/local/qt5.9.1-arm/lib:$LD_LIBRARY_PATH export QT_QPA_PLATFORMlinuxfb export QT_QPA_FONTDIR/usr/share/fonts其中 QT_QPA_PLATFORMlinuxfb 指定 Qt 使用 Linux framebuffer 平台插件适用于无显示服务器的嵌入式设备QT_QPA_FONTDIR 指定字体目录避免中文等文字显示为方块。最后将交叉编译好的应用程序及其依赖的 Qt 库一起拷贝到目标板即可运行验证。建议先在目标板上运行 Qt 自带的示例程序如 ./examples/widgets/analogclock确认环境正常再运行自己的应用程序。3. 编译常见错误与排查在 Qt 5.9.1 交叉编译过程中由于工具链、系统环境或配置参数等原因经常会遇到各类编译错误。本节汇总了几种典型错误给出错误现象、原因分析及解决步骤帮助读者快速定位并解决问题。3.1 qmake.conf 路径错误错误现象执行 configure 时提示找不到平台配置文件例如ERROR: Cannot find mkspecs/linux-arm-gnueabi-g/qmake.conf Project ERROR: Unknown module(s) in QT: core原因分析-xplatform 参数指定的平台名称与 mkspecs 目录下的实际目录名不一致或者源码解压不完整导致 mkspecs 目录缺失。解决步骤确认源码根目录下存在 qtbase/mkspecs/linux-arm-gnueabi-g 目录ls qtbase/mkspecs/ | grep linux-arm检查 configure 命令中的 -xplatform 参数是否与目录名完全一致注意大小写和连字符./configure -xplatform linux-arm-gnueabi-g ...若目录确实缺失重新解压源码包并校验完整性tar -xvf qt-everywhere-opensource-src-5.9.1.tar.xz3.2 缺少 32 位库错误现象运行 arm-none-linux-gnueabi-gcc 或执行 configure 时提示无法加载共享库例如arm-none-linux-gnueabi-gcc: error while loading shared libraries: libstdc.so.6: cannot open shared object file: No such file or directory原因分析arm-2014.05-29 工具链是 32 位程序在 64 位 Linux 系统上运行需要 32 位兼容库支持。解决步骤在 Ubuntu/Debian 系统上安装 32 位兼容库sudo apt-get update sudo apt-get install lib32z1 lib32ncurses5 lib32stdc6安装完成后重新验证工具链是否可运行arm-none-linux-gnueabi-gcc --version若仍提示缺少其他库可使用 ldd 查看具体依赖ldd /opt/arm-2014.05/bin/arm-none-linux-gnueabi-gcc3.3 编译器版本不匹配错误现象编译过程中出现大量语法错误或头文件找不到例如error: nullptr was not declared in this scope error: std::unique_ptr has not been declared原因分析Qt 5.9.1 要求编译器支持 C11 标准而工具链版本过旧或 qmake.conf 中未正确启用 C11 支持。解决步骤确认工具链版本支持 C11arm-2014.05-29 自带的 GCC 4.8.3 已支持arm-none-linux-gnueabi-g --version在 qmake.conf 中显式添加 C11 支持标志QMAKE_CXXFLAGS -stdc11若使用其他版本工具链建议升级到 GCC 4.8 及以上版本或改用与 Qt 5.9.1 匹配的交叉编译工具链。3.4 configure 失败错误现象执行 configure 时中途退出提示缺少依赖或配置项错误例如ERROR: Feature opengl was enabled, but the pre-condition libs.opengl failed. ERROR: The test for linking against libxcb failed.原因分析configure 会检测宿主机上的各类开发库若缺少某些依赖库或配置参数冲突会导致检测失败。解决步骤根据错误提示在 configure 命令中禁用对应模块例如./configure \ -no-opengl \ -no-xcb \ -no-gtk \ -no-cups \ -no-nis \ -no-accessibility \ -no-sql-sqlite \ -no-sql-mysql \ -no-sql-psql \ -no-sql-odbc \ -no-sql-ibase \ -no-sql-sqlite2 \ -no-sql-tds \ -no-sql-db2 \ -no-sql-oci若提示缺少宿主机开发库可通过 apt 安装后重新 configuresudo apt-get install libx11-dev libxext-dev libxrender-dev libxcb1-dev libxcb-glx0-dev libxcb-util0-dev查看 configure 日志定位具体失败原因./configure ... 21 | tee configure.log grep -i error configure.log3.5 编译过程中找不到头文件错误现象make 编译时提示找不到 Qt 头文件例如fatal error: QWidget: No such file or directory fatal error: qglobal.h: No such file or directory原因分析编译应用程序时未正确设置 Qt 的头文件搜索路径或 Qt 库尚未安装完成。解决步骤确认 Qt 已安装到指定目录且 include 目录存在ls /usr/local/qt5.9.1-arm/include编译应用程序时使用 qmake 生成 Makefile 并指定正确的交叉编译环境/usr/local/qt5.9.1-arm/bin/qmake your_app.pro make若仍找不到头文件检查 qmake.conf 中的 QMAKE_INCDIR 是否指向正确的 include 目录。3.6 链接错误找不到 Qt 库错误现象链接阶段提示找不到 Qt 库文件例如/opt/arm-2014.05/bin/../lib/gcc/arm-none-linux-gnueabi/4.8.3/../../../../arm-none-linux-gnueabi/bin/ld: cannot find -lQt5Core collect2: error: ld returned 1 exit status原因分析链接器未找到 Qt 库文件可能是库路径未正确设置或 Qt 库尚未编译安装完成。解决步骤确认 Qt 库文件已生成ls /usr/local/qt5.9.1-arm/lib/libQt5Core.so*在 qmake 生成的 Makefile 中检查 LIBS 变量是否包含正确的库路径grep LIBS Makefile若路径缺失可在 .pro 文件中手动指定LIBS -L/usr/local/qt5.9.1-arm/lib -lQt5Core -lQt5Gui -lQt5Widgets3.7 编译速度过慢或内存不足错误现象make 编译过程中系统卡顿严重或提示内存不足g: internal compiler error: Killed (program cc1plus) make: *** [Makefile:123: xxx.o] Error 1原因分析并行编译任务过多导致内存耗尽或编译单元过大。解决步骤降低并行编译的核数例如从 -j8 改为 -j2make -j2关闭其他占用内存较大的程序释放系统资源。若宿主机内存确实不足可增加 swap 空间sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile3.8 常见错误速查表错误现象可能原因解决方向Cannot find mkspecs/linux-arm-gnueabi-g/qmake.conf-xplatform 参数与目录名不匹配核对平台名称重新解压源码error while loading shared libraries缺少 32 位兼容库安装 lib32z1、lib32ncurses5 等nullptr was not declared in this scope编译器不支持 C11添加 -stdc11升级工具链Feature opengl was enabled, but pre-condition failed依赖库缺失或配置冲突禁用对应模块或安装依赖库fatal error: QWidget: No such file or directory头文件搜索路径未设置使用 qmake 生成 Makefile检查 QMAKE_INCDIRcannot find -lQt5Core库路径未设置或库未安装检查 LIBS 变量确认库文件存在internal compiler error: Killed内存不足降低并行度增加 swap4. 总结本文围绕 ARM 嵌入式开发中的交叉编译环境搭建与 Qt 5.9.1 源码交叉编译系统梳理了从工具链配置到应用移植的完整流程。下面从整体流程、关键要点和后续建议三个角度进行总结。4.1 整体流程回顾整个交叉编译过程可以划分为三个阶段工具链准备下载并解压 arm-2014.05-29 交叉编译工具链配置 PATH 环境变量并验证安装为后续编译提供基础。Qt 源码编译获取 qt-everywhere-opensource-src-5.9.1 源码修改 qmake.conf 中的编译器名称并添加 ARMv7-A 指令集支持通过 configure 配置编译选项再执行 make 与 make install 完成编译安装。打包移植根据目标板存储空间选择整体拷贝或精简拷贝设置 LD_LIBRARY_PATH、QT_QPA_PLATFORM、QT_QPA_FONTDIR 等环境变量最后将应用程序与依赖库一并部署到目标板运行验证。4.2 关键要点在实际操作中以下几个要点对成败影响较大工具链与平台匹配qmake.conf 中 8 处编译器名称必须全部由 arm-linux-gnueabi-gcc 改为 arm-linux-gcc且 -xplatform 参数要与 mkspecs 目录名完全一致。架构优化在 qmake.conf 中追加 -O2 -marcharmv7-a 编译选项可让生成的 Qt 库充分发挥 ARMv7-A 处理器性能。裁剪编译选项嵌入式场景下通过 -no-opengl、-no-xcb、-no-sql-xxx 等参数禁用不需要的模块可显著缩短编译时间并减小库体积。环境变量配置目标板运行时需正确设置动态库搜索路径、平台插件和字体目录否则程序无法启动或中文显示异常。4.3 后续建议完成本文流程后建议读者从以下方向继续深入在目标板上运行 Qt 自带示例程序如 analogclock验证环境再逐步移植自己的业务应用。结合具体项目需求按需调整 configure 参数例如启用需要的数据库驱动或图形模块。若遇到编译问题可对照第三章的常见错误速查表快速定位并结合 configure.log 日志深入排查。通过以上步骤即可在 ARM 嵌入式平台上搭建起完整的 Qt 运行环境为后续应用开发与部署打下坚实基础。