前段时间给手头的Cubietruck重新整理一套Qt开发环境顺手把x64、x86、armhf三个版本的Qt 5.8.0全部编译安装了一遍。这个做法听起来有点折腾但实际需求很实在日常在x64主机上写界面、调逻辑需要一套桌面版的Qt要兼容老依赖或32位中间件时又得用x86版最终部署到Cubietruck上跑的则是armhf版本。三个版本共用一份源码只是configure参数和工具链不同。这篇文章把整套流程按实际操作顺序记录下来重点放在armhf交叉编译上因为这是Cubietruck项目里最容易被卡住的一环同时给出x64和x86的完整编译步骤方便你在PC端做同版本联调。内容适合正在给A20开发板做Qt移植、或者想在同一套环境中同时维护多架构SDK的嵌入式Linux开发者参考。编译过程中常见的问题和排查方法放在最后都是我自己踩过的坑直接照着做能省不少时间。1. 编译前的整体认知与方案选型1.1 为什么要在同一套环境编译三个版本先说说为什么要一次性编译x64、x86、armhf三个版本。Qt是以目标平台为导向的同一个版本的Qt源码可以编译出不同架构下的库文件但这些库文件不能互相替代。x64是PC上64位Linux系统用的x86则是32位Linux或旧系统环境需要armhf是目前Debian系嵌入式Linux上最常见的ARM硬浮点架构Cubietruck这类全志A20板子跑的系统基本都属于armhf。在实际开发流程里x64版本解决的是开发效率问题Cubietruck性能有限直接在板上编译写界面代码非常痛苦在x64主机上先用同一版本Qt把代码逻辑跑通再交叉编译到armhf版本部署这是嵌入式开发最常见的节奏。x86版本解决的是兼容验证问题有些第三方32位库或者老驱动只提供x86版本程序最终要跟这些库混编时桌面端就得有一份x86 Qt来提前验证接口。很多人在Cubietruck上做Qt开发时只关心armhf版本等到代码在板上频繁编译、频繁崩溃才知道痛苦。正因为我一开始就把三个版本都准备好后续调试Qt程序时逻辑问题在PC端几分钟就能定位真正放到板上跑的每次都是编译好的产物整个迭代速度快了不止一倍。1.2 Cubietruck平台对Qt构建的约束Cubietruck的主控是全志A20双核Cortex-A7大部分版本带1GB DDR3内存GPU是Mali400 MP2。这个配置放到今天看确实比较基础但对于Qt 5.8.0来说完全够用前提是编译方式要选对。Cubietruck的板载存储通常是nand/flash跑的系统可以是Lubuntu、Debian或者Cubian。如果直接在板子上运行Qt源码的configure和make会遇到两个问题一是CPU性能低编译整个Qt 5.8.0完整版可能需要四五个小时以上二是内存紧张1GB内存跑编译很容易触发OOM哪怕加了swap也不一定稳定。所以我的建议是armhf版本必须在PC上用交叉编译工具链完成生成armhf二进制之后拷到Cubietruck上运行。另一个约束是系统架构。Cubietruck跑的系统虽然是ARMv7指令集但A20的浮点单元是VFPv4和NEON编译器必须用hard-float模式也就是我们常说的armhf。如果编译时误用了armel软浮点程序在板上会运行得非常慢甚至直接报非法指令错误。这个细节会在后面的qmake.conf配置中体现。在方案选型上Qt 5.8.0本身支持在同一个源码树里分别构建多个平台只需要给每个平台一个独立的build目录和独立的prefix安装路径即可。这样三个版本互不干扰源码不重复下载磁盘占用也最省。我这里选择的是Qt 5.8.0因为它对armhf平台的改动相对稳定qmake配置清晰而且不需要像Qt 6那样引入额外的cmake依赖对于Cubietruck这种性能有限的目标平台反而更顺手。2. 编译环境与依赖准备2.1 基础工具链安装交叉编译Qt 5.8.0需要一套完整的Linux构建环境。我的主机是Ubuntu 16.04 x86_64这套步骤在Ubuntu 18.04上同样适用只是个别依赖包名略有出入。先安装基础编译工具和常用依赖库sudo apt update sudo apt install build-essential perl python git sudo apt install libgl1-mesa-dev libfontconfig1-dev libfreetype6-dev sudo apt install libx11-dev libxkbcommon-dev libxcb1-dev sudo apt install libxcb-xinerama0-dev libxcb-icccm4-dev sudo apt install libxcb-image0-dev libxcb-keysyms1-dev sudo apt install libxcb-render-util0-dev libxcb-xkb-dev sudo apt install libglib2.0-dev libssl-dev libicu-dev sudo apt install libts-dev libudev-dev这里面的依赖各有各的用途。libxcb系列是为Qt的xcb平台插件服务的这个插件能让Qt程序在Linux桌面环境下正常显示窗口libfontconfig和libfreetype是字体渲染的基础缺少它们Qt编译出来的程序即使能跑界面上也全是方块字libgl1-mesa-dev提供OpenGL开发头文件虽然Cubietruck上最终用不到桌面OpenGL但configure阶段会检测OpenGL相关功能提前装好可以避免不必要的检测失败。如果你是直接复制上面的命令请注意Ubuntu 18.04里libts-dev可能叫libts-devUbuntu 20.04及之后系统需要额外确认缺失的话configure会显示tslib相关警告但不影响非触摸屏场景使用。想要在编译时省去这些依赖检查的麻烦也可以稍后统一加-no-feature-xxx参数但我建议尽量把依赖装齐这样Qt编译出来的功能模块更完整。2.2 依赖库清单与作用Qt 5.8.0的configure阶段会自动探测很多库如果探测不到它并不会立刻报错而是自动关闭相应功能。这种方式虽然提供了兼容性但也容易让人忽略一些实际需要的能力。比如没有libsslQt的网络模块就编不出SSL支持没有libicuQt的文本处理和日期模块功能会退化没有libudevQt在Linux下的设备热插拔检测会失效。下面这个表格是把关键依赖和它对应的Qt功能模块对应起来方便你裁剪或者排查依赖库Qt模块缺失后的影响libxcb系列Qt Xcb平台插件程序无法以GUI方式运行libfontconfig/freetypeQt Gui字体渲染界面汉字显示异常libglib2.0Qt EventDispatcher事件循环集成能力下降libsslQt Network SSL无法使用Https链接libicuQt Core文本处理Unicode处理能力受限libtsQt LinuxFB触摸输入触摸屏不可用libudevQt Core设备管理外部设备检测异常对于Cubietruck的armhf交叉编译还有一类特殊的依赖目标板上运行的库版本必须跟交叉编译时sysroot里的头文件版本一致。比如板上系统是Debian 9那sysroot最好也用Debian 9的根文件系统否则编译出来的Qt库在板上可能因为glibc版本不匹配而无法启动。2.3 交叉工具链与sysroot准备armhf版本编译的核心是arm-linux-gnueabihf工具链。在Ubuntu上可以直接装sudo apt install gcc-arm-linux-gnueabihf g-arm-linux-gnueabihf装完之后验证一下编译器版本arm-linux-gnueabihf-gcc --version输出正常说明基础工具链没问题。但光有编译器还不够交叉编译Qt时configure会去检查目标平台上的头文件和库文件。这些文件来自armhf的根文件系统也就是sysroot。最省事的方式是用debootstrap制作一个armhf的最小Ubuntu/Debian根文件系统sudo apt install debootstrap sudo mkdir /opt/armhf-rootfs sudo debootstrap --archarmhf bionic /opt/armhf-rootfs http://ports.ubuntu.com/ubuntu-ports/这里以Ubuntu 18.04的bionic为例如果你板子跑的是Debian可以把发行版名称和源换成对应的debian源。debootstrap执行时间取决于网速一般几分钟到二三十分钟。根文件系统准备好之后进入chroot环境安装依赖sudo chroot /opt/armhf-rootfs apt-get update sudo chroot /opt/armhf-rootfs apt-get install libfontconfig1-dev libfreetype6-dev libx11-dev libxcb1-dev libxkbcommon-dev libglib2.0-dev libts-dev libudev-dev libssl-dev libicu-dev这些dev包会把armhf架构下的头文件和.a静态库放进sysroot的/usr目录里。最后设置两个环境变量方便后续任何交叉编译任务使用export SYSROOT/opt/armhf-rootfs export PATH/usr/bin:$PATH3. 三个版本的完整编译流程3.1 x64版本编译步骤先下载Qt 5.8.0源码包。源码包有很多渠道这里用官方archive地址如果下载慢可以使用国内镜像站wget https://download.qt.io/archive/qt/5.8/5.8.0/qt-everywhere-opensource-src-5.8.0.tar.xz tar -xf qt-everywhere-opensource-src-5.8.0.tar.xz cd qt-everywhere-opensource-src-5.8.0x64版本编译最简单因为主机就是x86_64架构不需要交叉工具链所有依赖库都在系统里。先创建独立目录避免在源码目录里直接构建产生污染mkdir build-x64 cd build-x64 ../configure -prefix /opt/Qt5.8.0-x64 \ -opensource -confirm-license \ -release -shared \ -xcb -qt-xcb \ -nomake tests -nomake examples参数说明一下-prefix指定安装路径这样后续make install会把所有文件安装到独立目录不会污染系统-opensource和-confirm-license组合用于跳过交互确认-release表示编译发布版本去掉调试符号体积和运行速度都有优势-shared表示动态链接-xcb启用xcb平台插件配合-qt-xcb让Qt使用自带的libxcb避免跟系统xcb版本冲突-nomake tests和-nomake examples是为了减少编译时间。然后开始编译make -j$(nproc) 21 | tee build.log sudo make install如果机器内存足够-j参数可以用逻辑核心数。编译时间取决于CPU性能一般半小时到一小时。编译完成后验证/opt/Qt5.8.0-x64/bin/qmake --version能正常输出版本信息x64版本就成功了。后续写Qt程序时用这个qmake来生成Makefile即可。3.2 x86版本编译步骤x86版本的目标是32位Intel架构。这一步容易让人犯迷糊的地方在于我是在64位主机上编译32位版本的Qt。如果你手头正好是32位系统的老机器那可以直接照搬x64的步骤把-prefix改成x86路径即可。但绝大多数人手上都是64位系统所以要处理多架构编译的问题。首先是安装32位编译支持sudo apt install gcc-multilib g-multilibgcc-multilib让64位系统的gcc具备编译-m32程序的能力也就是能生成32位代码。光有编译器还不够32位程序需要32位版本的C运行库和依赖库所以还得启用dpkg的多架构支持并安装32位基础库sudo dpkg --add-architecture i386 sudo apt update sudo apt install libc6-dev:i386 libx11-dev:i386 libxcb1-dev:i386 libfontconfig1-dev:i386 libfreetype6-dev:i386 libssl-dev:i386 libglib2.0-dev:i386这里有很多依赖包如果configure阶段提示缺少某个库就再用apt-get install 包名:i386补上。安装32位库时要注意部分:i386包依赖的多媒体库比较大如果只是做基础Qt应用可以只装核心库configure不会全部强制要求。configure时指定32位平台mkdir build-x86 cd build-x86 linux32 ../configure -prefix /opt/Qt5.8.0-x86 \ -opensource -confirm-license \ -release -shared \ -platform linux-g-32 \ -xcb -qt-xcb \ -nomake tests -nomake exampleslinux32命令的作用是把当前环境伪装成32位系统有些configure脚本会自动检测host系统位数不加这个可能检测出64位导致配置错误。核心参数是-platform linux-g-32这个mkspec明确告诉构建系统用-m32编译标志。编译安装跟x64一样make -j$(nproc) 21 | tee build.log sudo make install这里有一个非常常见的坑没有安装32位依赖时configure会报“Basic XLib functionality test failed”。很多人以为是xcb没装好其实通常是x11相关库缺失。比较好的排查方式是看config.log搜索test failed附近的错误信息几乎都会明确指出是哪个头文件或库找不到直接用apt装对应的:i386版本即可。3.3 armhf版本交叉编译步骤armhf版本是整个流程里最核心也最容易出问题的一步。先准备armhf专用的mkspec。Qt 5.8.0源码里默认有linux-arm-gnueabi-g配置但针对armhf需要微调浮点参数。我习惯复制一份然后定制cp -r qtbase/mkspecs/linux-arm-gnueabi-g qtbase/mkspecs/linux-arm-gnueabihf-g cd qtbase/mkspecs/linux-arm-gnueabihf-g然后编辑qmake.conf改成下面这样# # qmake configuration for building with arm-linux-gnueabihf-g # MAKEFILE_GENERATOR UNIX CONFIG incremental QMAKE_INCREMENTAL_STYLE sublib include(../common/linux.conf) include(../common/gcc-base-unix.conf) include(../common/g-unix.conf) QMAKE_CC arm-linux-gnueabihf-gcc QMAKE_CXX arm-linux-gnueabihf-g QMAKE_LINK arm-linux-gnueabihf-g QMAKE_LINK_SHLIB arm-linux-gnueabihf-g QMAKE_CFLAGS -marm -marcharmv7-a -mfpuneon-vfpv4 -mfloat-abihard QMAKE_CXXFLAGS -marm -marcharmv7-a -mfpuneon-vfpv4 -mfloat-abihard QMAKE_INCDIR $$[QT_SYSROOT]/usr/include/arm-linux-gnueabihf QMAKE_LIBDIR $$[QT_SYSROOT]/usr/lib/arm-linux-gnueabihf load(qt_config)这些编译参数是针对Cubietruck的A20芯片特别选择的。-marcharmv7-a告诉编译器按ARMv7指令集生成代码-mfpuneon-vfpv4启用NEON和VFPv4浮点单元A20是Cortex-A7支持这个指令集向量运算和浮点性能会明显提升-mfloat-abihard则确保使用硬件浮点ABI也就是armhf的意义所在。sysroot环境变量在这里很关键configure时通过-sysroot参数指定它的作用是让编译器在交叉编译时优先查找sysroot下的头文件和库而不是主机系统的x86_64版本。创建armhf的build目录并执行configurecd qt-everywhere-opensource-src-5.8.0 mkdir build-armhf cd build-armhf export SYSROOT/opt/armhf-rootfs export PKG_CONFIG_PATH$SYSROOT/usr/lib/arm-linux-gnueabihf/pkgconfig export PKG_CONFIG_SYSROOT_DIR$SYSROOT ../configure -prefix /opt/Qt5.8.0-armhf \ -opensource -confirm-license \ -release -shared \ -xplatform linux-arm-gnueabihf-g \ -sysroot $SYSROOT \ -no-xcb -linuxfb -tslib \ -no-eglfs \ -nomake tests -nomake examples这里的-xplatform和x64版本里的-platform不同-platform用于本机编译-xplatform用于交叉编译。sysroot指向我们的armhf根文件系统。没有用-xcb因为Cubietruck不是跑完整桌面系统不需要xcb插件真正依赖的是linuxfb平台插件它直接把Qt窗口输出到framebuffer设备/dev/fb0。-tslib则启用触摸屏支持Cubietruck如果接的是电阻屏或者带tslib驱动的触摸屏这个选项必不可少。有个容易被忽略的点如果sysroot里的pkgconfig路径不在PKG_CONFIG_PATH里configure可能在探测fontconfig等库时失败。所以开头设置的两个环境变量一定要先export否则后续会报各种检测不到库的诡异错误。编译make -j$(nproc) 21 | tee build.log sudo make install交叉编译比x64版本编译耗时更长一般在1到2小时之间。编译期间可以留意日志里是否有error中断如果有特定模块编译失败比如qtmultimedia库缺ALSA依赖可以单独进入对应模块目录重新make。编译完成之后把安装目录打包拷到板子上cd /opt sudo tar -czf qt5.8.0-armhf.tar.gz Qt5.8.0-armhf scp qt5.8.0-armhf.tar.gz cubie板子IP:/home/cubie/在Cubietruck上解压到目标目录sudo tar -xzf qt5.8.0-armhf.tar.gz -C /opt/3.4 关于Qt模块裁剪交叉编译完完整版Qt之后建议检查一下实际安装体积。完整版Qt 5.8.0 armhf大概有几百MB如果Cubietruck的存储空间比较小可以通过configure阶段禁用不需要的模块来节省空间。比如明确不用Qt Multimedia和Qt WebEngine的话可以加-skip qtwebengine -skip qtmultimedia -skip qtwayland-skip参数在Qt 5.8里是支持的每指定一个模块就跳过对应目录的构建。对于纯界面业务通常保留qtbase、qtdeclarative、qtquickcontrols即可。裁剪模块时要注意依赖关系跳过qtwebengine对编译时间影响最大因为那个模块编译量非常大跳过之后整个构建时间能缩短一半以上。我当时第一次编译没裁剪等了相当久才完成后来重编时果断跳过webengine体验完全不同。4. 常见问题与排查技巧实录4.1 configure阶段问题Configure阶段是报错最密集的地方排查思路其实很统一无论报什么错第一件事是查看config.log搜索最后的error关键字看错误上下文。下面几个是我遇到的典型情况。第一个问题报“Basic XLib functionality test failed!”。这个错误在x64和x86编译时经常出现。原因基本就是找不到libX11头文件或者xcb相关库。解决办法是检查libx11-dev和libxcb1-dev是否安装完整如果是在64位主机上编x86版则要安装:i386版本。如果确定依赖没问题但还报错可以打开config.log看具体是哪个test executable编译失败错误信息里会直接显示缺少哪个头文件或函数。第二个问题报“Could not find qmake spec linux-arm-gnueabihf-g”这是mkspec没放对位置。确认一下是否在qtbase/mkspecs目录下创建了对应的文件夹而且名称要和-xplatform参数完全一致包括大小写。第三个问题configure时提示“The QT_ARCH is not supported by the toolchain”或者类似的架构不匹配错误。这种情况通常是sysroot路径没设置好或者工具链前缀不对。在armhf配置里务必确认arm-linux-gnueabihf-gcc命令能正常执行并且qmake.conf里的QMAKE_CC和QMAKE_CXX指向正确的编译器。4.2 make阶段问题Make阶段最常见的是内存不足导致的编译器崩溃。症状是编译某个大文件时突然报“internal compiler error: Killed”这是因为gcc进程被系统OOM杀掉。解决办法有几种一是降低-j并发数比如从-j8降到-j4甚至-j2二是临时增加swap分区尤其对于内存较少的构建机三是拆分编译先单独编译qtbase再编译其他模块这样可以把峰值内存摊开。另一个make阶段的经典问题是“c: fatal error: Killed signal terminated program cc1plus”本质上还是内存不足。如果你用交叉编译同时主机的内存又比较小这样的情况很容易反复出现。我建议在make之前先执行free -h swapon --show如果swap没有开启或者只有几百MB就先加一个swap文件sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile加上4GB swap之后编译稳定性会好很多。还有一种情况是make过程中某个子模块链接失败报一堆未定义的引用。这种基本都是交叉编译时依赖库顺序或者库路径不对。排查方法是找到报错的链接命令手动复制到终端执行然后在末尾加上-ldl之类的库参数确认能否链接通过。如果是因为sysroot目录下的库符号不兼容最好重新debootstrap一个和板子系统版本一致的根文件系统别指望直接在原sdk上打补丁。4.3 板子运行阶段问题编译好的Qt库拷到Cubietruck后运行程序可能遇到的问题比编译期要多得多。第一个高发问题是“error while loading shared libraries: libQt5Core.so.5: cannot open shared object file”。原因很简单动态库路径没设置。解决方法是把Qt库路径加入LD_LIBRARY_PATH或者把路径写入/etc/ld.so.conf.d/qt5.conf然后ldconfig。第二个高发问题是程序启动时报“Could not load the Qt platform plugin linuxfb”。这个问题的根源是Qt运行时找不到plugins/platforms目录下的libqlinuxfb.so。Qt通过编译时的QLibraryInfo来确定插件路径如果整个安装目录是从PC搬到板子的路径不对就会出问题。解决方法是使用设置环境变量QT_QPA_PLATFORM_PLUGIN_PATH或者在程序里用QApplication::addLibraryPath显式指定。最稳妥的做法是进入Qt安装目录检查目录结构ls /opt/Qt5.8.0-armhf/plugins/platforms/里面有libqlinuxfb.so就说明插件编译进去了接下来把环境变量设置好即可。第三个问题是触摸屏没反应。Qt 5.8的linuxfb插件默认会读取libinput或者tslib库。如果sysroot里装了tslibconfigure时也开了-tslib那运行前还要设置对应的触摸屏设备参数。常见做法export QT_QPA_PLATFORMlinuxfb:/dev/fb0 export TSLIB_TSDEVICE/dev/input/event0 export TSLIB_CALIBFILE/etc/pointercal export QT_QPA_FB_TSLIB1具体event编号要根据板子的实际设备节点确定有时候是event1有时候是event2在板上执行一下cat /proc/bus/input/devices就能看到触摸屏对应的设备节点。字体问题也得提醒一下。Qt在armhf板子上默认找不到中文字体界面里的中文会显示成方块。解决方法是把PC上的中文字体拷贝到板子Qt目录下scp /usr/share/fonts/truetype/wqy/wqy-microhei.ttc cubie板子IP:/opt/Qt5.8.0-armhf/lib/fonts/然后设置QT_QPA_FONTDIR指向这个目录。如果你的Qt程序完全不涉及中文这一步可以跳过但绝大多数GUI项目都躲不开汉字显示。4.4 问题排查速查表问题现象直接原因排查/解决办法configure报Basic XLib test failed缺少xcb/x11开发包安装libx11-dev和libxcb1-devx86版需要安装:i386包qmake spec not foundmkspec目录不存在检查qtbase/mkspecs下是否创建了对应配置目录make时gcc被Killed内存不足降低-j并发数增加swap空间链接阶段大量未定义引用sysroot库路径或顺序不对查看具体链接命令核查sysroot下依赖库板子上报libQt5Core.so找不到动态库路径未配置export LD_LIBRARY_PATH/opt/Qt5.8.0-armhf/lib找不到linuxfb平台插件plugins目录未拷贝或路径不对设置QT_QPA_PLATFORM_PLUGIN_PATH触摸屏无响应tslib设备参数未配置设置TSLIB_TSDEVICE和QT_QPA_FB_TSLIB界面中文显示方块缺少字体拷贝中文字体到Qt fonts目录设置QT_QPA_FONTDIR5. 部署到Cubietruck后的运行环境配置Qt装到板子上只是第一步实际运行程序时还需要配全环境变量。Cubietruck的系统环境相对精简很多默认路径跟PC不同我在板子上反复试过几套配置最终稳定生效的是这一个export QTDIR/opt/Qt5.8.0-armhf export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_QPA_PLATFORMlinuxfb:/dev/fb0 export QT_QPA_FONTDIR$QTDIR/lib/fonts export QT_QPA_PLATFORM_PLUGIN_PATH$QTDIR/plugins/platforms把这些写进板子上用户的~/.bashrc避免每次开终端都手工设置。然后写一个最简单的Qt测试程序编译后放到板子上验证整条链路#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Cubietruck Qt OK); label.resize(320, 240); label.show(); return app.exec(); }编译时用armhf的qmake/opt/Qt5.8.0-x64/bin/qmake # 这是PC端x64版本用来生成Makefile make # 这里需要确保交叉工具链已被调用严格来说PC上直接用x64 qmake编译出来的产物不能给armhf板子用。正确操作是使用交叉编译好的qmake/opt/Qt5.8.0-armhf/bin/qmake或者在PC上直接用armhf SDK里的qmake交叉编译/opt/Qt5.8.0-armhf/bin/qmake test.pro make再把生成的test二进制拷贝到板子上运行。如果能在Cubietruck的屏幕上看到“Cubietruck Qt OK”标签说明整个工具链已经跑通了。关于linuxfb和eglfs的选择我个人的体会是Cubietruck虽然支持Mali400 GPU但GPU驱动在Linux板端往往没有桌面级那么稳定如果只是做普通界面应用linuxfb的软件渲染反而更省心兼容性也更好。如果要做动画较多的QML应用再考虑折腾eglfs不过驱动和qmake参数都得重新调不是一蹴而就的事。最后再分享一个小技巧。交叉编译Qt时建议把config.log和build.log都保留下来。下次升级Qt版本或者换板子时很多问题可以在旧日志里直接找到对应答案比自己重新排查一遍快得多。编译这套三个版本的Qt流程我最大的感受是真正容易翻车的地方从来不是configure那些参数而是qmake.conf里的编译器前缀、sysroot路径、浮点参数这些细节。只要这些基础设定不出错整个构建流程其实可以一路顺畅跑完。