425 lines
7.7 KiB
Markdown
425 lines
7.7 KiB
Markdown
# AGV 路径跟踪系统 - 编译说明
|
||
|
||
本文档提供完整的编译说明，包括 Qt6 GUI 应用程序和 CAN 通信模块。
|
||
|
||
## 📋 目录
|
||
- [系统要求](#系统要求)
|
||
- [Qt6 GUI 编译（推荐）](#qt6-gui-编译推荐)
|
||
- [命令行程序编译](#命令行程序编译)
|
||
- [常见问题](#常见问题)
|
||
- [验证安装](#验证安装)
|
||
|
||
---
|
||
|
||
## 系统要求
|
||
|
||
### 必需组件
|
||
- **编译器**:
|
||
- Windows: MinGW-w64 13.1+ 或 MSVC 2019+
|
||
- Linux: GCC 9.0+ 或 Clang 10.0+
|
||
- **CMake**: 3.10 或更高版本
|
||
- **C++ 标准**: C++17
|
||
|
||
### Qt6 GUI 所需
|
||
- **Qt6**: 6.x 或更高版本
|
||
- 必需组件: Qt6::Widgets
|
||
- 推荐版本: Qt 6.10.1
|
||
- **编译器匹配**:
|
||
- Qt6 MinGW 版本 → MinGW 编译器
|
||
- Qt6 MSVC 版本 → MSVC 编译器
|
||
|
||
### CAN 通信所需
|
||
- **ControlCAN 库**: lib/ControlCAN.lib
|
||
- **支持的设备**: USBCAN-2A, USBCAN-2C
|
||
|
||
---
|
||
|
||
## Qt6 GUI 编译（推荐）
|
||
|
||
### Windows (MinGW)
|
||
|
||
#### 步骤 1: 安装 Qt6
|
||
|
||
从 [Qt 官网](https://www.qt.io/download) 下载并安装 Qt6：
|
||
- 安装路径示例: `C:\Qt\6.10.1`
|
||
- 选择组件: MinGW 64-bit, Qt6 Widgets
|
||
|
||
#### 步骤 2: 清理构建目录
|
||
|
||
```bash
|
||
cd build
|
||
rm -rf *
|
||
cd ..
|
||
```
|
||
|
||
#### 步骤 3: 配置 CMake
|
||
|
||
**方法 1: 使用完整路径（推荐）**
|
||
```bash
|
||
cd build
|
||
cmake -G "MinGW Makefiles" \
|
||
-DCMAKE_PREFIX_PATH=C:/Qt/6.10.1/mingw_64 \
|
||
-DCMAKE_C_COMPILER=C:/Qt/Tools/mingw1310_64/bin/gcc.exe \
|
||
-DCMAKE_CXX_COMPILER=C:/Qt/Tools/mingw1310_64/bin/g++.exe \
|
||
-DCMAKE_MAKE_PROGRAM=C:/Qt/Tools/mingw1310_64/bin/mingw32-make.exe ..
|
||
```
|
||
|
||
**方法 2: 设置环境变量**
|
||
```bash
|
||
# 设置 Qt 路径
|
||
export CMAKE_PREFIX_PATH=/c/Qt/6.10.1/mingw_64
|
||
export PATH=/c/Qt/Tools/mingw1310_64/bin:$PATH
|
||
|
||
# 配置
|
||
cd build
|
||
cmake -G "MinGW Makefiles" ..
|
||
```
|
||
|
||
#### 步骤 4: 编译
|
||
|
||
```bash
|
||
# 使用多线程编译（-j4 表示 4 个线程）
|
||
cmake --build . -j4
|
||
|
||
# 或者指定 Release 模式
|
||
cmake --build . --config Release -j4
|
||
```
|
||
|
||
#### 步骤 5: 验证
|
||
|
||
检查生成的可执行文件：
|
||
```bash
|
||
ls -lh agv_qt_gui.exe
|
||
# 应该显示类似: -rwxr-xr-x 1 user group 558K Nov 27 13:33 agv_qt_gui.exe
|
||
```
|
||
|
||
#### 步骤 6: 运行
|
||
|
||
```bash
|
||
# 直接运行（需要 Qt DLL 在 PATH 中）
|
||
./agv_qt_gui.exe
|
||
|
||
# 或者添加 Qt bin 目录到 PATH
|
||
export PATH=/c/Qt/6.10.1/mingw_64/bin:$PATH
|
||
./agv_qt_gui.exe
|
||
```
|
||
|
||
---
|
||
|
||
### Windows (MSVC)
|
||
|
||
#### 前提条件
|
||
- 安装 Visual Studio 2019 或 2022
|
||
- 安装 Qt6 MSVC 版本（例如 msvc2019_64）
|
||
|
||
#### 配置和编译
|
||
|
||
```bash
|
||
cd build
|
||
cmake -G "Visual Studio 17 2022" -A x64 \
|
||
-DCMAKE_PREFIX_PATH=C:/Qt/6.10.1/msvc2019_64 ..
|
||
|
||
cmake --build . --config Release -j4
|
||
```
|
||
|
||
#### 运行
|
||
|
||
```bash
|
||
# 添加 Qt DLL 路径
|
||
set PATH=C:\Qt\6.10.1\msvc2019_64\bin;%PATH%
|
||
|
||
# 运行
|
||
Release\agv_qt_gui.exe
|
||
```
|
||
|
||
---
|
||
|
||
### Linux
|
||
|
||
#### 步骤 1: 安装依赖
|
||
|
||
**Ubuntu/Debian:**
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install build-essential cmake qt6-base-dev
|
||
```
|
||
|
||
**Fedora:**
|
||
```bash
|
||
sudo dnf install gcc-c++ cmake qt6-qtbase-devel
|
||
```
|
||
|
||
**Arch Linux:**
|
||
```bash
|
||
sudo pacman -S base-devel cmake qt6-base
|
||
```
|
||
|
||
#### 步骤 2: 编译
|
||
|
||
```bash
|
||
mkdir -p build && cd build
|
||
cmake ..
|
||
make -j$(nproc)
|
||
```
|
||
|
||
#### 步骤 3: 运行
|
||
|
||
```bash
|
||
./agv_qt_gui
|
||
```
|
||
|
||
---
|
||
|
||
## 命令行程序编译
|
||
|
||
如果只需要编译命令行程序（不含 Qt GUI），可以使用更简单的方法：
|
||
|
||
### 基本编译
|
||
|
||
```bash
|
||
cd build
|
||
cmake ..
|
||
cmake --build .
|
||
```
|
||
|
||
### 生成的可执行文件
|
||
|
||
编译完成后，在 `build/` 目录下会生成以下程序：
|
||
|
||
| 程序名称 | 功能描述 |
|
||
|---------|---------|
|
||
| `agv_demo.exe` | 基本路径跟踪演示 |
|
||
| `generate_data.exe` | 生成测试数据 |
|
||
| `generate_smooth_path.exe` | 平滑路径生成器 |
|
||
| `agv_gui.exe` | 控制台 GUI 演示 |
|
||
| `curtis_demo.exe` | Curtis 电机控制器键盘演示 |
|
||
| `curtis_path_tracking_demo.exe` | Curtis 路径跟踪演示 |
|
||
| `agv_qt_gui.exe` | Qt6 图形界面（需要 Qt6） |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 问题 1: CMake 找不到 Qt6
|
||
|
||
**错误信息:**
|
||
```
|
||
CMake Error at CMakeLists.txt:65 (find_package):
|
||
By not providing "FindQt6.cmake" in CMAKE_MODULE_PATH this project has
|
||
asked CMake to find a package configuration file provided by "Qt6", but
|
||
CMake did not find one.
|
||
```
|
||
|
||
**解决方案:**
|
||
|
||
**方法 1:** 设置 `CMAKE_PREFIX_PATH`
|
||
```bash
|
||
cmake -DCMAKE_PREFIX_PATH=C:/Qt/6.10.1/mingw_64 ..
|
||
```
|
||
|
||
**方法 2:** 设置环境变量
|
||
```bash
|
||
# Windows (Git Bash)
|
||
export CMAKE_PREFIX_PATH=/c/Qt/6.10.1/mingw_64
|
||
|
||
# Windows (CMD)
|
||
set CMAKE_PREFIX_PATH=C:\Qt\6.10.1\mingw_64
|
||
|
||
# Linux
|
||
export CMAKE_PREFIX_PATH=/opt/Qt/6.10.1/gcc_64
|
||
```
|
||
|
||
---
|
||
|
||
### 问题 2: 编译器不匹配
|
||
|
||
**错误信息:**
|
||
```
|
||
error: undefined reference to `__imp__ZN7QWidget...'
|
||
```
|
||
|
||
**原因:** Qt6 MinGW 版本与 MSVC 编译器不兼容。
|
||
|
||
**解决方案:**
|
||
- 使用 MinGW 编译 MinGW 版 Qt6
|
||
- 或安装 MSVC 版 Qt6 并使用 MSVC 编译
|
||
|
||
---
|
||
|
||
### 问题 3: 程序运行时缺少 DLL
|
||
|
||
**错误信息:**
|
||
```
|
||
The code execution cannot proceed because Qt6Core.dll was not found.
|
||
```
|
||
|
||
**解决方案 1:** 添加 Qt bin 目录到 PATH
|
||
```bash
|
||
# Windows (Git Bash)
|
||
export PATH=/c/Qt/6.10.1/mingw_64/bin:$PATH
|
||
|
||
# Windows (CMD)
|
||
set PATH=C:\Qt\6.10.1\mingw_64\bin;%PATH%
|
||
```
|
||
|
||
**解决方案 2:** 部署应用程序（推荐用于发布）
|
||
参见 [Qt6 部署指南](QT6_DEPLOYMENT_GUIDE.md)
|
||
|
||
---
|
||
|
||
### 问题 4: 编译时提示程序正在运行
|
||
|
||
**错误信息:**
|
||
```
|
||
cannot create agv_qt_gui.exe: Permission denied
|
||
```
|
||
|
||
**解决方案:**
|
||
关闭正在运行的 `agv_qt_gui.exe` 进程：
|
||
|
||
**Windows 任务管理器:**
|
||
1. 按 `Ctrl + Shift + Esc`
|
||
2. 找到 `agv_qt_gui.exe`
|
||
3. 右键 → 结束任务
|
||
|
||
**命令行:**
|
||
```bash
|
||
# Windows
|
||
taskkill /F /IM agv_qt_gui.exe
|
||
|
||
# Linux
|
||
pkill -9 agv_qt_gui
|
||
```
|
||
|
||
---
|
||
|
||
### 问题 5: CMake 版本过低
|
||
|
||
**错误信息:**
|
||
```
|
||
CMake 3.5 or higher is required. You are running version 2.8.12
|
||
```
|
||
|
||
**解决方案:**
|
||
更新 CMake：
|
||
|
||
**Windows:**
|
||
从 [CMake 官网](https://cmake.org/download/) 下载最新版本
|
||
|
||
**Linux:**
|
||
```bash
|
||
# Ubuntu (添加官方 PPA)
|
||
sudo apt-get remove cmake
|
||
sudo snap install cmake --classic
|
||
|
||
# 或从源码编译
|
||
wget https://github.com/Kitware/CMake/releases/download/v3.28.0/cmake-3.28.0.tar.gz
|
||
tar -xzvf cmake-3.28.0.tar.gz
|
||
cd cmake-3.28.0
|
||
./bootstrap && make && sudo make install
|
||
```
|
||
|
||
---
|
||
|
||
## 验证安装
|
||
|
||
### 检查 Qt6 安装
|
||
|
||
```bash
|
||
# 检查 qmake
|
||
qmake --version
|
||
# 应输出: QMake version 3.1, Using Qt version 6.x.x
|
||
|
||
# 检查 Qt6Config.cmake
|
||
ls C:/Qt/6.10.1/mingw_64/lib/cmake/Qt6/Qt6Config.cmake
|
||
# 应显示文件存在
|
||
```
|
||
|
||
### 检查编译器
|
||
|
||
```bash
|
||
# MinGW
|
||
gcc --version
|
||
g++ --version
|
||
# 应输出: gcc/g++ (MinGW-W64) 13.1.0 或更高
|
||
|
||
# MSVC (Visual Studio Developer Command Prompt)
|
||
cl
|
||
# 应输出: Microsoft (R) C/C++ Optimizing Compiler Version 19.xx
|
||
```
|
||
|
||
### 检查 CMake
|
||
|
||
```bash
|
||
cmake --version
|
||
# 应输出: cmake version 3.10 或更高
|
||
```
|
||
|
||
---
|
||
|
||
## 清理构建
|
||
|
||
如果需要重新开始：
|
||
|
||
```bash
|
||
# 清理构建目录
|
||
cd build
|
||
rm -rf *
|
||
|
||
# 或者删除并重建
|
||
cd ..
|
||
rm -rf build
|
||
mkdir build
|
||
cd build
|
||
```
|
||
|
||
---
|
||
|
||
## 构建配置选项
|
||
|
||
### 调试模式 vs 发布模式
|
||
|
||
```bash
|
||
# Debug 模式（包含调试符号，未优化）
|
||
cmake -DCMAKE_BUILD_TYPE=Debug ..
|
||
cmake --build .
|
||
|
||
# Release 模式（优化，无调试符号）
|
||
cmake -DCMAKE_BUILD_TYPE=Release ..
|
||
cmake --build .
|
||
```
|
||
|
||
### 指定安装路径
|
||
|
||
```bash
|
||
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
|
||
cmake --build .
|
||
sudo cmake --install .
|
||
```
|
||
|
||
### 只构建特定目标
|
||
|
||
```bash
|
||
# 只构建 Qt GUI
|
||
cmake --build . --target agv_qt_gui
|
||
|
||
# 只构建 Curtis 演示
|
||
cmake --build . --target curtis_demo
|
||
```
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
- 📖 运行程序: [QUICK_START.md](QUICK_START.md)
|
||
- 🚀 部署应用: [QT6_DEPLOYMENT_GUIDE.md](QT6_DEPLOYMENT_GUIDE.md)
|
||
- 🔧 CAN 通信: [../can/CAN_README.md](../can/CAN_README.md)
|
||
- 🎨 自定义路径: [../custom_path/README.md](../custom_path/README.md)
|
||
|
||
---
|
||
|
||
**最后更新:** 2025-11-27
|
||
**Qt 版本:** 6.10.1
|
||
**CMake 版本:** 3.10+
|
||
**编译器:** MinGW 13.1.0, GCC 9.0+, MSVC 2019+
|