树莓派环境下Qt开发提示无法找到QSerialPort模块问题咨询

问题核心原因 #

Project MESSAGE: Warning: unknown QT: serialport报错本质是qmake无法识别serialport模块，和头文件路径无关，你注释的INCLUDEPATH配置不解决根本问题，即使强制加了头文件路径后续也会出现链接错误。

排查解决步骤 #

• 第一步：核对Qt Creator的套件配置
  打开Qt Creator -> 工具 -> 选项 -> 构建和运行 -> 套件，检查当前使用的套件对应的qmake路径是否为/usr/bin/qmake（即apt安装的系统Qt对应的qmake）。如果配置的是自行安装的其他版本Qt的qmake，apt安装的libqt5serialport5-dev仅适配系统源的Qt 5.11.3，和其他版本Qt不兼容，自然无法识别serialport模块。
• 第二步：适配不同Qt版本的处理
  • 若要使用系统自带的Qt 5.11.3：将套件的qmake路径切换为/usr/bin/qmake，清理项目的构建目录后重新qmake、构建即可。
  • 若要使用自行安装的其他版本Qt：打开对应版本的Qt Maintenance Tool，勾选安装对应版本的Serial Port组件即可，无需使用apt安装的serialport相关包。
• 第三步：终端验证配置是否生效
  新建空目录，创建test.pro写入以下内容：

  QT += core serialport
  

  在该目录下执行/usr/bin/qmake test.pro，如果没有出现unknown QT报错，说明系统Qt的serialport模块配置正常，问题确定为Qt Creator套件配置错误；如果仍报错，执行以下命令重装依赖：

  sudo apt reinstall qtbase5-dev qtchooser libqt5serialport5 libqt5serialport5-dev
  

其他疑问解答 #

• 不存在apt安装的Qt包仅对特定用户生效的情况，你朋友设备上的单用户正常现象，本质是不同用户的Qt Creator套件配置不一致，部分用户配置了正确的系统Qt qmake路径，部分用户配置了其他版本Qt的qmake导致的。
• 头文件引入无需加QtSerialPort/前缀，pro中正确添加QT += serialport后直接写#include <QSerialPort>即可。

内容的提问来源于stack exchange，提问作者Hugo