通用 Qt 交叉编译环境搭建攻略

lcyzxc

已于 2025-02-26 10:19:13 修改

阅读量1.6k

点赞数 42

文章标签： qt 开发语言

于 2025-02-26 10:18:45 首次发布

本文链接：https://blog.youkuaiyun.com/lcyzxc/article/details/145870505

版权

通用 Qt 交叉编译环境搭建攻略

前言

本攻略将指导如何在任意 ARM 平台开发板上搭建 Qt 交叉编译环境。目标是使用 Qt 在 ARM 开发板上运行应用程序，但无论是选择哪个开发板（如 i.MX6U 或其他），都可以参考本攻略进行环境搭建，重要的是学习方法，注意：不要原搬照抄，根据自己的实际情况作相应的替换。

环境要求

操作系统：Windows 7/8/10（64 位）或 Ubuntu 16.04（推荐）。
开发工具：FileZilla、WinSCP、Windows Git（用于文件传输）。

第一章安装交叉编译器

交叉编译器是将代码从主机系统（如 x86 Ubuntu）编译为目标开发板（如 ARM）的可执行文件的工具。我们将以 Linaro 或其他 ARM 编译工具链为例说明。

获取交叉编译工具
- 可以使用 Linaro Toolchain 或其他适用于 ARM 的交叉编译工具链。选择适合目标开发板架构（如 Cortex-A7）的工具链。
- 下载适合开发板架构的交叉编译工具链包（如：gcc-linaro-arm-linux-gnueabihf-<version>.tar.xz）。

安装交叉编译工具

解压并移动交叉编译工具链：

tar -xvf gcc-linaro-arm-linux-gnueabihf-<version>-x86_64_arm-linux-gnueabihf.tar.xz
sudo mv gcc-linaro-arm-linux-gnueabihf-<version> /opt/

配置交叉编译环境变量

编辑

文件，将交叉编译器路径添加到环境变量中：

~/.bashrc

export CROSS_COMPILE=/opt/gcc-linaro-arm-linux-gnueabihf-<version>/bin/arm-linux-gnueabihf-
export ARCH=arm
export CROSS_COMPILER_PATH=/opt/gcc-linaro-arm-linux-gnueabihf-<version>/bin
export PATH=$CROSS_COMPILER_PATH:$PATH

更新环境变量：
```
source ~/.bashrc
```

验证交叉编译器安装
- 使用以下命令检查交叉编译器是否配置成功：
```
arm-linux-gnueabihf-gcc --version
```

第二章安装 Qt Creator 和配置交叉编译环境

下载 Qt Creator
- 访问 Qt 官方下载页面下载 Qt 5.12.9 安装包。
- 使用以下命令下载 Qt Creator 安装包：
```
wget http://download.qt.io/archive/qt/5.12/5.12.9/qt-opensource-linux-x64-5.12.9.run
```

安装 Qt Creator

赋予安装包执行权限并安装：

chmod u+x qt-opensource-linux-x64-5.12.9.run
sudo ./qt-opensource-linux-x64-5.12.9.run

配置 Qt Creator
- 打开qtcreator.sh
  
  配置文件：
```
sudo vi /opt/Qt5.12.9/Tools/QtCreator/bin/qtcreator.sh
```
- 在文件第一行插入以下指令（不要原搬照抄，根据自己的实际情况作相应的替换），配置交叉编译环境变量：
```
source /opt/gcc-linaro-arm-linux-gnueabihf-<version>/bin/arm-linux-gnueabihf-gcc
```
- 通过以下命令后台运行 Qt Creator：
```
/opt/Qt5.12.9/Tools/QtCreator/bin/qtcreator.sh &
```

第三章配置交叉编译 Kits

在 Qt Creator 中，配置交叉编译环境（Kits）是将 Qt 应用程序从的主机编译为适用于目标开发板（如 ARM 开发板）上运行的过程。本章将详细介绍如何在 Qt Creator 中配置交叉编译 Kits，并确保的应用程序能够成功编译并在目标设备上运行。
- 配置 Qt Versions
  
  Qt Creator 需要识别目标平台的 Qt 版本，并且使用适当的 qmake 工具生成正确的构建文件。为了配置 Qt 版本，我们需要指向交叉编译器所使用的 Qt 版本。
  - 打开 Qt Creator。
  - 进入 Tools -> Options。
  - 在 Options 窗口中，选择 Qt Versions 选项卡。
  - 点击右侧的Add按钮，选择交叉编译工具链中的qmake路径。例如：
```
/opt/Qt5.12.9/5.12.9/gcc_64/bin/qmake
```
  - 设置 Qt 版本名称为 Custom-ARM Qt 5.12.9，并点击 Apply。
  注意：确保选择的是与交叉编译工具链匹配的 Qt 版本。此步骤是确保交叉编译器能正确生成针对目标设备的构建文件。
- 配置 C++ 编译器
  
  在 Qt Creator 中，需要配置交叉编译器的 C++ 编译器（如 g++）。此编译器将用于编译 Qt 应用程序，使其能够在目标开发板上运行。
  - 进入 Tools -> Options -> Compilers。
  - 在此窗口中，点击Add按钮，并选择适合目标开发板的 C++ 编译器。路径通常位于交叉编译工具链的bin目录下，如：
```
/opt/gcc-linaro-arm-linux-gnueabihf-<version>/bin/arm-linux-gnueabihf-g++
```
  - 设置编译器名称为 Custom-ARM-GCC。
  - 点击 Apply 保存设置。
  注意：确保选择的编译器与交叉编译工具链相匹配。编译器需要能够在 ARM 架构上编译 Qt 应用程序。
- 配置 Kits
  
  Kits 是 Qt Creator 中配置不同平台（如桌面平台或交叉编译平台）进行编译和运行的工具。在本节中，我们将配置一个针对 ARM 目标开发板的交叉编译 Kit。这样，就可以选择该 Kit 来为目标设备编译应用程序。
  - 进入 Tools -> Options -> Kits。
  - 点击 Add 按钮创建一个新的 Kit，命名为 Custom-ARM。
  - 配置 Kit 的相关设置：
    - Device Type：选择 Generic Linux Device。
    - Device：点击右侧的 Add 按钮，选择或创建的目标开发板设备。
    - Sysroot：为交叉编译器指定正确的 sysroot 路径。这个路径通常是开发板的根文件系统目录（它包含目标设备的所有系统头文件和库文件）。
    - Qt version：选择之前配置的 Custom-ARM Qt 5.12.9 版本。
    - Compiler：选择之前配置的 Custom-ARM-GCC 编译器。
    - CMake（如果需要）：选择适当的 CMake 路径，或者使用 Qt Creator 自带的版本。
    - Debugger：选择适合目标平台的调试器（通常是 GDB）。
  - 完成后，点击 Apply 保存设置。
  注意：Sysroot 是交叉编译时非常重要的一部分，它告诉 Qt Creator 在编译时从哪里获取目标设备的头文件和库文件。如果没有正确配置 sysroot，交叉编译将无法找到目标平台所需的资源。
- 配置其他参数
  
  除了上述基本的配置之外，还可以在 Kits 配置中调整其他细节，比如设置环境变量、修改构建选项等。通常，这些配置用于在特定环境下进行优化或调试。
  - 环境变量：可以在 Kits 配置中设置自定义的环境变量，这些变量会在编译和调试过程中使用。例如，可以设置目标设备的特定路径，或者启用一些优化选项。
  - 构建选项：可以根据需要调整构建选项，如启用特定的编译器标志或者调整生成的 Makefile。
- 选择 Kit 并进行编译
  
  配置完 Kit 后，就可以在 Qt Creator 中选择该 Kit 来编译的应用程序：
  - 打开 Qt Creator 并加载的项目。
  - 在左侧的“项目”面板中，选择“构建和运行”设置。
  - 在“构建套件”部分，选择 Custom-ARM Kit。
  - 点击 应用 保存设置。
  之后，可以点击 构建 按钮开始编译，Qt Creator 会自动使用配置的交叉编译工具链为目标开发板生成应用程序。
- 验证配置
  
  为确保配置成功，可以创建一个简单的 Qt 项目，选择适当的 Kit 编译，并在目标设备上运行它。如果应用程序能够正常在目标设备上运行并与硬件交互，说明交叉编译环境配置成功。
  - 编译过程：在 Qt Creator 中点击 构建 按钮，查看是否有错误或警告。如果构建成功，会看到生成的可执行文件。
  - 文件传输
    
    ：将生成的应用程序拷贝到目标开发板的文件系统，并通过终端执行：
```
./your_application
```

第四章验证搭建的交叉编译 Kits

创建新项目
- 打开 Qt Creator，选择 Application -> Qt Widgets Application，命名为 test，选择合适的保存位置。
选择 Kit 和编译目标
- 在 Qt Creator 中选择 Custom-ARM Kit 进行编译，并确认项目使用交叉编译工具进行构建。
编译并拷贝可执行文件
- 编译完成后，会在 build-test-Custom_ARM-Debug 文件夹中找到可执行文件。
- 将该文件拷贝到目标开发板的文件系统目录，并通过串口终端执行：
```
./test
```

第五章 Ubuntu 本机 Kits 编译 Qt 应用程序

使用 Ubuntu 编译 Qt 应用
- 如果希望直接在 Ubuntu 上编译并运行 Qt 应用程序而不涉及目标开发板，可以选择使用 Qt Creator 自带的桌面 Kits 进行本地编译。
- 选择合适的 Kit：在 Qt Creator 中，可以选择 Desktop Qt5.12.9 GCC 64bit Kit（这是默认的桌面环境）。这个 Kit 是基于本机的编译器和工具链进行编译的，因此适用于在 Ubuntu 上直接构建和运行应用程序。
  - 打开 Qt Creator，创建一个新项目或者选择一个现有的项目。
  - 在“项目设置”中选择 Desktop Qt5.12.9 GCC 64bit Kit 作为编译目标。
- 编译和运行应用程序：
  - 配置好 Kit 后，点击 Qt Creator 的“构建”按钮（通常是一个绿色的锤子图标），开始编译应用程序。
  - 编译完成后，点击“运行”按钮，Qt Creator 会直接在 Ubuntu 上启动并运行的应用程序。
- 调试应用程序：
  - 在本地调试时，可以使用 Qt Creator 的调试工具进行逐步调试。点击“调试”按钮（通常是一个带虫子的绿色按钮），开始调试的应用程序。
  - 可以设置断点，查看变量，或者进行栈跟踪，帮助定位程序中的问题。
注意事项：
- 使用 Ubuntu 进行本地编译时，程序的最终运行效果可能与目标开发板上的行为有所不同，特别是在硬件加速、外设支持等方面。确保在开发时测试所有功能，最终将应用程序移植到目标开发板上进行验证。
- 如果使用 Ubuntu 来编译和调试程序，确保安装了适当版本的 Qt 和开发工具链，以便最大限度地减少可能的版本差异导致的错误。

附录

A. 常见问题与解决方法

交叉编译器路径未正确配置
- 如果在尝试编译时遇到“找不到编译器”的错误，通常是因为交叉编译器的路径未正确配置。
- 解决方法：检查的.bashrc配置文件，确保CROSS_COMPILE和CROSS_COMPILER_PATH
  
  环境变量设置正确。执行以下命令来查看当前路径设置：
```
echo $CROSS_COMPILE
echo $CROSS_COMPILER_PATH
```
Qt Creator 提示找不到目标平台的支持
- 如果 Qt Creator 报告无法识别交叉编译的目标平台（例如，显示为 Unknown platform），可能是由于未正确配置 Qt Creator 中的 Kits 和 Qt Versions。
- 解决方法：检查 Qt Creator 配置：
  - 在 Tools -> Options -> Kits 中确保已选择正确的交叉编译工具链和目标平台。
  - 在 Tools -> Options -> Qt Versions 中，检查是否正确配置了交叉编译的 Qt 版本。
编译器报错 “找不到头文件”
- 如果在编译过程中出现找不到头文件的错误，通常是由于交叉编译器的 sysroot 没有配置正确。
- 解决方法：确保交叉编译器的 sysroot 路径已设置正确，并且所有必需的头文件和库文件已被正确包含。在 Qt Creator 的 Kits 配置中，设置 sysroot 路径。
程序无法在目标开发板上运行
- 如果程序在目标开发板上无法运行（例如启动后没有任何反应，或者报错退出），可能是由于运行时依赖项缺失，或者程序无法找到必要的库文件。
- 解决方法：
  - 确保将所有运行时依赖项（如 Qt 库、共享库）拷贝到目标开发板的适当目录。
  - 使用命令 ldd your_program 来检查程序是否缺少某些共享库。
编译时 qmake 配置失败
- 如果在 Qt Creator 中遇到 qmake 配置失败的错误，可能是因为 qmake 路径没有正确配置，或者 qmake 没有正确识别交叉编译环境。
- 解决方法：在 Qt Creator 中，确保 qmake 路径指向交叉编译工具链的正确 qmake 版本，并且 Qt Versions 中的配置正确。

B. 常见调试技巧

使用 gdb 进行调试
- 如果程序在目标开发板上运行时出现崩溃，可以使用 gdb 调试器进行分析。
- 在目标开发板上安装gdb并通过以下命令启动调试：
```
gdb ./your_program
```
- 在调试器中，设置断点并逐步跟踪程序执行，检查崩溃的原因。
日志记录
- 使用 qDebug() 和 qWarning() 进行日志记录，可以帮助在开发过程中追踪程序的行为。
- 在调试过程中，还可以将日志输出到远程设备的文件中，以便调试时查看详细信息。
调试启动时的环境问题
- 如果程序无法正常启动，或者在启动时卡住，可以通过检查启动时的环境变量来调试。
- 在目标开发板的终端中，使用以下命令查看环境变量：printenv
优化交叉编译配置
- 在交叉编译时，可以使用-v选项来查看详细的编译信息，帮助诊断编译错误。例如：
```
arm-linux-gnueabihf-gcc -v your_program.c -o your_program
```