为QGC开发铺路：在Jetson Orin Nano上部署Qt 5.15.3私有库的完整避坑指南

mjchen404

为QGC开发铺路：在Jetson Orin Nano上部署Qt 5.15.3私有库的完整避坑指南

在无人机和机器人开发领域，QGroundControl（QGC）作为一款功能强大的开源地面站软件，已经成为许多开发者的首选工具。然而，当我们需要在嵌入式平台上进行QGC的二次开发或定制时，往往会遇到一个关键的技术门槛——Qt私有库的部署问题。Jetson Orin Nano作为NVIDIA推出的高性能边缘计算平台，其强大的AI算力和紧凑的尺寸使其成为无人机和机器人应用的理想选择。但在这类ARM架构的嵌入式平台上部署完整的Qt开发环境，特别是确保私有模块的正确安装，却是一个充满挑战的过程。

本文将从一个实际应用场景出发，详细解析如何在Jetson Orin Nano上为QGC开发准备完善的Qt 5.15.3环境。不同于普通的Qt安装教程，我们将重点关注那些容易被忽略却至关重要的技术细节，特别是私有库的配置问题。这些私有模块虽然不包含在标准的Qt安装中，却是编译QGC等大型Qt项目的必备组件。通过本指南，您将掌握从源码编译Qt到解决各种常见报错的完整流程，最终搭建一个稳定可靠的开发环境。

1. 理解Qt私有库对QGC开发的重要性

在开始技术实践之前，我们需要先理解为什么QGC开发如此依赖Qt的私有库。Qt框架的设计哲学是将核心功能公开为公共API，而将实现细节和特定功能模块标记为"私有"。这种设计既保证了框架的稳定性，又为开发者提供了必要的灵活性。

对于QGC这样的复杂应用程序，它需要访问Qt框架中一些未公开但至关重要的功能。例如：

QtLocation私有模块：提供地图渲染和地理空间数据处理的核心功能
QtQuick私有组件：实现高级UI效果和性能优化的底层支持
QtWebEngine内部接口：支持嵌入式浏览器功能的扩展

这些私有模块通常以_p.h（私有头文件）和private子目录的形式存在，它们不是标准Qt安装的一部分，但却是许多大型项目（包括QGC）编译和运行的必备条件。当这些私有头文件缺失时，您会遇到类似fatal error: QtLocation/private/qgeomaptype_p.h: No such file or directory的编译错误。

在Jetson Orin Nano这样的ARM平台上，问题会变得更加复杂，因为：

预编译的Qt二进制包通常不包含私有模块
交叉编译环境下的依赖关系更难处理
系统库路径与x86平台有所不同
硬件加速相关的优化需要特殊配置

理解这些背景知识后，我们就可以着手准备Qt的源码编译环境了。与直接安装二进制包相比，从源码编译虽然过程更复杂，但能确保所有必要的私有模块都被正确包含和安装，为后续的QGC开发打下坚实基础。

2. Jetson Orin Nano开发环境准备

在开始编译Qt之前，我们需要为Jetson Orin Nano准备一个完善的开发环境。由于这是一个ARM架构的平台，与常见的x86开发机存在一些差异，需要特别注意依赖项的安装和配置。

2.1 系统基础配置

首先，确保您的Jetson Orin Nano运行的是最新版本的JetPack SDK。可以通过以下命令更新系统：

bash复制sudo apt update
sudo apt full-upgrade -y
sudo reboot

接下来，安装编译Qt所需的基础开发工具和库：

bash复制sudo apt install -y build-essential git cmake python3 python3-pip \
    libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev libxcb-xinerama0-dev \
    libfontconfig1-dev libfreetype6-dev libx11-dev libxext-dev libxfixes-dev \
    libxi-dev libxrender-dev libxcb1-dev libx11-xcb-dev libxcb-glx0-dev \
    libxkbcommon-dev libxkbcommon-x11-dev libssl-dev libpng-dev libjpeg-dev \
    libdbus-1-dev libicu-dev libpcre2-dev zlib1g-dev libbz2-dev \
    libsqlite3-dev libharfbuzz-dev libdouble-conversion-dev

2.2 Qt编译专用依赖项

除了基础开发工具外，Qt编译还需要一些特定的依赖库。这些库在标准系统安装中可能不存在，需要单独处理：

OpenGL ES开发库：Jetson平台的图形加速支持
EGL开发文件：用于窗口系统集成
Vulkan开发工具：可选，用于高级图形功能

安装命令如下：

bash复制sudo apt install -y libgles2-mesa-dev libegl1-mesa-dev vulkan-tools

2.3 磁盘空间与交换空间配置

Qt源码编译是一个资源密集型过程，特别是在Jetson Orin Nano这样的嵌入式平台上。建议：

确保至少有20GB的可用磁盘空间
配置足够的交换空间以避免内存不足错误

检查磁盘空间：

bash复制df -h

如果空间不足，可以考虑使用外接存储或清理不必要的文件。增加交换空间的步骤：

bash复制sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

要将交换空间设置为永久生效，编辑/etc/fstab文件并添加：

code复制/swapfile none swap sw 0 0

2.4 环境变量配置

为了优化编译过程，建议设置以下环境变量。编辑~/.bashrc文件，在末尾添加：

bash复制export MAKEFLAGS="-j$(nproc)"
export QT_HOST_PATH=/usr/local/Qt-5.15.3
export PATH=$QT_HOST_PATH/bin:$PATH

然后应用更改：

bash复制source ~/.bashrc

这些准备工作完成后，您的Jetson Orin Nano就已经具备了编译Qt源码所需的所有条件。接下来，我们可以开始下载和配置Qt源码了。

3. 获取与配置Qt 5.15.3源码

选择合适的Qt源码获取方式并正确配置编译选项，是确保私有模块被包含的关键步骤。对于国内开发者，推荐使用清华大学的镜像源以加速下载过程。

3.1 从清华源下载Qt源码

打开终端，执行以下命令下载Qt 5.15.3源码包：

bash复制wget https://mirrors.tuna.tsinghua.edu.cn/qt/official_releases/qt/5.15/5.15.3/single/qt-everywhere-opensource-src-5.15.3.tar.xz

下载完成后，验证文件的完整性：

bash复制md5sum qt-everywhere-opensource-src-5.15.3.tar.xz

对比官方MD5校验值（可在Qt官网找到），确保文件下载完整无误。

解压源码包并进入目录：

bash复制tar -xvf qt-everywhere-opensource-src-5.15.3.tar.xz
cd qt-everywhere-src-5.15.3

3.2 配置编译选项

创建一个构建目录并进入：

bash复制mkdir build && cd build

现在，我们需要准备configure命令。对于QGC开发，以下配置选项特别重要：

bash复制../configure -prefix /usr/local/Qt-5.15.3 \
    -opensource \
    -confirm-license \
    -release \
    -optimize-size \
    -c++std c++17 \
    -qt-zlib \
    -qt-libpng \
    -qt-libjpeg \
    -qt-freetype \
    -qt-pcre \
    -qt-harfbuzz \
    -no-opengl \
    -opengl es2 \
    -eglfs \
    -xcb \
    -qt-xcb \
    -no-gtk \
    -nomake examples \
    -nomake tests \
    -skip qtandroidextras \
    -skip qtmacextras \
    -skip qtwinextras \
    -skip qtwebengine \
    -feature-qtlocation \
    -qt-sqlite \
    -plugin-sql-sqlite \
    -no-sql-odbc \
    -no-sql-psql \
    -no-sql-mysql \
    -no-sql-oci

这个配置特别针对Jetson Orin Nano平台进行了优化：

-opengl es2：使用OpenGL ES 2.0，适合Jetson的GPU架构
-eglfs：启用EGLFS平台插件，适合无X11的嵌入式环境
-xcb和-qt-xcb：保留XCB支持，方便桌面环境调试
-feature-qtlocation：确保QtLocation模块被包含
优化选项：-optimize-size减小生成代码体积，-c++std c++17使用现代C++标准

3.3 解决常见配置错误

在配置过程中，可能会遇到几个典型错误：

错误1：Project ERROR: Library 'assimp' is not defined

这个错误发生在qtquick3d模块的配置阶段。解决方法：

定位到qtquick3d/src/plugins/assetimporters/assimp/assimp.pro文件
修改文件内容，替换或添加以下行：

makefile复制CONFIG += link_pkgconfig
PKGCONFIG += assimp

错误2：缺少limits头文件

某些Qt头文件可能缺少#include <limits>声明。需要手动添加的文件包括：

qtbase/src/corelib/text/qbytearraymatcher.h
qtbase/src/corelib/global/qendian.h
qtbase/src/corelib/global/qfloat16.h
qtdeclarative/src/qmldebug/qqmlprofilerevent_p.h

在每个文件的顶部添加：

cpp复制#include <limits>

完成这些修改后，重新运行configure命令。当看到"Qt is now configured..."消息时，表示配置成功，可以开始编译了。

4. 编译与安装Qt 5.15.3

配置完成后，我们就可以开始编译Qt源码了。在Jetson Orin Nano上，这个过程可能需要数小时，因此建议在稳定的网络环境下进行，并确保设备有可靠的电源供应。

4.1 启动编译过程

在build目录下，执行以下命令开始编译：

bash复制make -j$(nproc)

这里的-j$(nproc)选项会使用所有可用的CPU核心进行并行编译，显著加快编译速度。对于Jetson Orin Nano，这通常是6或8个核心。

编译过程中可能会遇到一些警告，但只要不出现致命错误(fatal error)，通常可以继续。如果编译因内存不足而终止，可以尝试：

减少并行任务数：make -j4
增加交换空间（如前面所述）
关闭不必要的应用程序释放内存

4.2 解决编译中的问题

在编译过程中，有几个常见问题需要特别注意：

问题1：模块依赖缺失

某些模块可能因为缺少依赖而编译失败。例如，如果遇到与SQL驱动相关的错误，可以：

bash复制sudo apt install -y libsqlite3-dev

然后重新运行make命令。

问题2：链接器错误

如果出现未定义的引用错误，可能是库路径问题。确保：

所有必要的开发包已安装
环境变量LD_LIBRARY_PATH包含正确的路径
运行sudo ldconfig更新库缓存

问题3：特定模块编译失败

如果某个非关键模块（如示例或测试）编译失败，可以尝试跳过它：

bash复制make module-qtbase # 仅编译qtbase模块

或者完全禁用问题模块后重新配置。

4.3 安装Qt到系统目录

编译成功后，执行安装命令：

bash复制sudo make install

这将把Qt安装到配置时指定的前缀目录（本例中为/usr/local/Qt-5.15.3）。安装完成后，建议更新系统库缓存：

bash复制sudo ldconfig

4.4 验证安装

检查Qt是否安装成功：

bash复制/usr/local/Qt-5.15.3/bin/qmake --version

应该能看到类似输出：

code复制QMake version 3.1
Using Qt version 5.15.3 in /usr/local/Qt-5.15.3/lib

4.5 部署私有库到系统路径

为了让QGC等应用程序能够找到Qt的私有库，我们需要将相关文件部署到系统目录。创建以下目录结构：

bash复制sudo mkdir -p /usr/local/include/Qt5/private

然后复制私有头文件：

bash复制sudo cp -r /usr/local/Qt-5.15.3/include/QtCore/private /usr/local/include/Qt5/private/QtCore
sudo cp -r /usr/local/Qt-5.15.3/include/QtGui/private /usr/local/include/Qt5/private/QtGui
sudo cp -r /usr/local/Qt-5.15.3/include/QtLocation/private /usr/local/include/Qt5/private/QtLocation
# 复制其他需要的私有模块

更新库文件链接：

bash复制sudo cp /usr/local/Qt-5.15.3/lib/*.so* /usr/local/lib/
sudo ldconfig

这样设置后，QGC在编译时就能找到所需的私有头文件和库了。

5. 配置QGC开发环境

完成Qt的安装和配置后，我们现在可以准备QGC的开发环境了。这一部分将指导您如何设置QGC项目，确保它能够正确识别和使用我们刚刚安装的Qt私有库。

5.1 获取QGC源码

首先，克隆QGC的官方仓库：

bash复制git clone https://github.com/mavlink/qgroundcontrol.git --recursive
cd qgroundcontrol

建议检查最新的稳定版本：

bash复制git checkout stable
git submodule update --recursive

5.2 配置Qt Creator

虽然可以直接使用命令行构建QGC，但使用Qt Creator作为IDE会大大提高开发效率。按照以下步骤配置：

启动Qt Creator
选择"文件"→"打开文件或项目"
导航到QGC目录，选择qgroundcontrol.pro文件
在"Configure Project"页面，确保选择了正确的Kit（应使用我们编译的Qt 5.15.3）

5.3 解决QGC编译中的私有库问题

即使正确安装了Qt私有库，QGC编译时仍可能遇到找不到私有头文件的问题。这是因为QGC的CMake配置默认不包含私有头文件路径。解决方法：

编辑CMakeLists.txt文件，在适当位置添加：

cmake复制include_directories(
    /usr/local/include/Qt5
    /usr/local/include/Qt5/private
    /usr/local/include/Qt5/private/QtLocation
    # 添加其他需要的私有路径
)

5.4 构建QGC

在Qt Creator中点击"构建"按钮，或者使用命令行：

bash复制mkdir build && cd build
cmake .. -DQt5_DIR=/usr/local/Qt-5.15.3/lib/cmake/Qt5
make -j$(nproc)

5.5 常见QGC编译错误及解决

错误1：缺少qgeomaptype_p.h等私有头文件

这通常是因为私有头文件路径没有正确包含。确保：

私有头文件已复制到/usr/local/include/Qt5/private目录
QGC的CMake配置包含了这些路径
清理构建目录后重新构建

错误2：QtLocation私有库链接失败

检查是否所有必要的QtLocation库文件都已安装：

bash复制ls /usr/local/Qt-5.15.3/lib/libQt5Location*

如果缺少，可能需要重新编译Qt并确保QtLocation模块被包含。

错误3：插件加载失败

运行时如果出现插件加载错误，确保插件路径正确：

bash复制export QT_PLUGIN_PATH=/usr/local/Qt-5.15.3/plugins

5.6 优化QGC性能

在Jetson Orin Nano上运行QGC时，可以通过以下设置优化性能：

在"设置"→"常规"中降低地图质量
禁用不必要的插件
使用EGLFS平台插件以获得更好的图形性能：

bash复制./qgroundcontrol-start.sh -platform eglfs

6. 高级调试与性能优化

成功编译和运行QGC后，我们还需要关注一些高级主题，确保开发环境在生产场景中稳定可靠。这一部分将介绍如何调试Qt应用程序、优化性能以及处理特定于Jetson平台的问题。

6.1 调试Qt应用程序技巧

在嵌入式平台上调试Qt应用程序有其特殊性。以下是一些实用技巧：

使用Qt的日志系统

Qt提供了强大的日志机制，可以通过以下方式启用：

cpp复制#include <QLoggingCategory>
Q_LOGGING_CATEGORY(myCategory, "my.category")
qCDebug(myCategory) << "Debug message";

运行时控制日志级别：

bash复制export QT_LOGGING_RULES="my.category.debug=true"
./qgroundcontrol

GDB调试配置

为Jetson Orin Nano配置GDB调试：

安装调试工具：

bash复制sudo apt install -y gdb-multiarch

在Qt Creator中配置设备调试：
- 进入"工具"→"选项"→"设备"
- 添加Generic Linux设备，填写Jetson的SSH连接信息
- 在Kit设置中选择该设备

核心转储分析

配置系统生成核心转储文件：

bash复制ulimit -c unlimited
echo "core.%e.%p" | sudo tee /proc/sys/kernel/core_pattern

当程序崩溃时，使用GDB分析：

bash复制gdb-multiarch qgroundcontrol core.1234

6.2 Jetson平台特定优化

GPU加速配置

确保Qt使用Jetson的GPU进行渲染：

检查OpenGL ES版本：

bash复制glxinfo | grep "OpenGL ES"

在QGC的main.cpp中添加：

cpp复制QCoreApplication::setAttribute(Qt::AA_UseOpenGLES);

内存管理

Jetson Orin Nano的内存有限，需要特别注意：

监控内存使用：

bash复制tegrastats

在Qt中启用内存优化：

cpp复制QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
QCoreApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);

温度管理

长时间运行可能导致过热，添加温度监控：

bash复制watch -n 1 cat /sys/class/thermal/thermal_zone*/temp

在代码中实现动态降频：

cpp复制// 读取温度
QFile tempFile("/sys/class/thermal/thermal_zone0/temp");
if (tempFile.open(QIODevice::ReadOnly)) {
    QString temp = tempFile.readAll();
    double tempC = temp.toDouble() / 1000;
    if (tempC > 80) {
        // 降低更新频率或简化渲染
    }
}

6.3 QGC特定问题解决

地图渲染性能

如果地图渲染卡顿，可以：

降低地图瓦片分辨率
使用离线地图
优化地图提供者设置

MAVLink通信延迟

改善通信延迟的方法：

优化串口或网络设置
调整MAVLink消息频率
使用更高效的编解码器

UI响应优化

对于复杂的UI界面：

使用Qt Quick Controls 2
启用硬件加速合成
避免过度使用动画效果

7. 持续集成与自动化部署

对于专业的QGC开发团队，建立自动化的构建和测试流程至关重要。这一部分将介绍如何在Jetson Orin Nano上设置持续集成环境，确保代码变更不会引入回归问题。

7.1 交叉编译环境配置

虽然我们主要在Jetson上开发，但某些情况下可能需要从x86主机交叉编译：

安装交叉编译工具链

bash复制sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

配置Qt for交叉编译

在x86主机上配置Qt时添加：

bash复制-device linux-jetson-orin-g++ \
-device-option CROSS_COMPILE=aarch64-linux-gnu- \
-sysroot /path/to/jetson/sysroot

创建sysroot

在Jetson上：

bash复制sudo apt install -y rsync
rsync -avz --relative /lib /usr/include /usr/lib /usr/local/Qt-5.15.3 /path/to/sysroot

7.2 Jenkins自动化构建

设置Jenkins服务器进行自动化构建：

安装Jenkins：

bash复制sudo apt install -y jenkins

创建构建任务，添加以下构建步骤：

bash复制git clone https://github.com/your-qgc-fork.git
cd qgc
mkdir build && cd build
cmake -DQt5_DIR=/usr/local/Qt-5.15.3/lib/cmake/Qt5 ..
make -j$(nproc)

添加自动化测试步骤

7.3 容器化部署

使用Docker简化环境配置：

Dockerfile示例

dockerfile复制FROM nvcr.io/nvidia/l4t-base:r35.1.0

RUN apt update && apt install -y build-essential cmake git ...

COPY qt-everywhere-opensource-src-5.15.3.tar.xz /tmp
RUN tar -xvf /tmp/qt-everywhere-opensource-src-5.15.3.tar.xz -C /tmp && \
    cd /tmp/qt-everywhere-src-5.15.3 && \
    ./configure -prefix /usr/local/Qt-5.15.3 ... && \
    make -j$(nproc) && \
    make install

WORKDIR /qgc
CMD ["bash"]

构建和运行：

bash复制docker build -t qgc-builder .
docker run -it --rm --runtime nvidia qgc-builder

7.4 性能基准测试

建立性能基准，监控代码变更的影响：

帧率测试

cpp复制QElapsedTimer timer;
timer.start();
// 渲染代码
qDebug() << "Frame time:" << timer.elapsed() << "ms";

内存使用监控

bash复制valgrind --tool=massif ./qgroundcontrol
ms_print massif.out.* > memory_report.txt

自动化测试脚本

创建测试脚本，定期运行并记录性能指标。

已经到底了哦

精选内容

1 从谷歌论文到落地实战：我的Copy-Paste数据增强踩坑与调优记录 2 单片机串口通信入门：手把手教你配置SCON、SBUF和PCON寄存器（附代码）3 锁相环PLL在调频通信里到底有多香？对比传统LC振荡，实测稳定度与抗干扰性能 4 从ISO 21448到工程实践：构建自动驾驶预期功能安全的“场景-验证”闭环 5 Arduino + L298N 驱动 12V 电磁铁：打造线性振动效果全解析 6 从配置文件看算法设计：EGO-Planner的advanced_param.xml隐藏了哪些运动规划黑科技？7 uniapp中tki-tree树形选择器的实战应用与优化技巧 8 Altium Designer封装库管理实战：从Unknown Pin错误谈如何维护可靠的元件库 9 从linspace到logspace：Matlab新手必须掌握的两种‘等分’向量生成技巧与避坑指南 10 剪映视频转 Live Photo 的隐藏技巧：与原生的差异对比

为QGC开发铺路：在Jetson Orin Nano上部署Qt 5.15.3私有库的完整避坑指南

为QGC开发铺路：在Jetson Orin Nano上部署Qt 5.15.3私有库的完整避坑指南

1. 理解Qt私有库对QGC开发的重要性

2. Jetson Orin Nano开发环境准备

2.1 系统基础配置

2.2 Qt编译专用依赖项

2.3 磁盘空间与交换空间配置

2.4 环境变量配置

3. 获取与配置Qt 5.15.3源码

3.1 从清华源下载Qt源码

3.2 配置编译选项

3.3 解决常见配置错误

4. 编译与安装Qt 5.15.3

4.1 启动编译过程

4.2 解决编译中的问题

4.3 安装Qt到系统目录

4.4 验证安装

4.5 部署私有库到系统路径

5. 配置QGC开发环境

5.1 获取QGC源码

5.2 配置Qt Creator

5.3 解决QGC编译中的私有库问题

5.4 构建QGC

5.5 常见QGC编译错误及解决

5.6 优化QGC性能

6. 高级调试与性能优化

6.1 调试Qt应用程序技巧

6.2 Jetson平台特定优化

6.3 QGC特定问题解决

7. 持续集成与自动化部署

7.1 交叉编译环境配置

7.2 Jenkins自动化构建

7.3 容器化部署

7.4 性能基准测试

内容推荐