MacOS下Qt 5开发环境安装与配置

news2025/6/21 23:23:41

最近笔者在MacOS中使用Qt Creator开发Qt程序时遇到了一些问题，在网上查了不少资料，都没有找到解决方案，只有自己进行研究摸索了，今天晚上终于将目前遇到的问题全部解决了，特记录下来分享给大家。

笔者使用的是MacOS 10.13.6和MacOS 10.15.7，前者为MBP笔记本，后者为虚拟机。笔者之前在虚拟机中安装过Qt5.14.2，在使用过程中并没出现最近遇到的问题，但最近在MBP笔记本中安装Qt5.14.2却出现了以下问题：

Qt Creator界面设计器中的菜单不显示
Qt菜单在MacOS中不显示
使用CMake构建系统时，智能提示有问题，Qt Creator中不能跳转打开Qt的头文件，报警告：
Warning: The code model could not parse an included file, which might lead to incorrect code completion and highlighting, for example.

在这里插入图片描述
点“Show Details”按钮可以看到一些错误，比如：

error: 'QtWidgets/qtwidgetsglobal.h' file not found

在这里插入图片描述
下面笔者就从MacOS下的Qt 5开发环境的安装与配置开始介绍，然后再介绍如何解决上述问题。

一、下载Qt安装包

MacOS版本下载 qt-opensource-mac-x64-5.14.2.dmg
在这里插入图片描述

二、安装

1. 安装Xcode

在安装Qt之前，需要先安装Xcode，如果已经安装好了Xcode.app，则使用下面命令选择Xcode：

$ sudo xcode-select --switch /Applications/Xcode.app

可以使用下面命令查看选择的Xcode

$ xcode-select -print-path
/Applications/Xcode.app/Contents/Developer

如果没有安装过Xcode.app，则可以使用下面的命令安装Xcode命令行工具

xcode-select --install

2. 安装Qt

安装时需要登录Qt账号，如果不想登录，可以在安装前断开网络链接，则安装程序会自动跳过登录进行安装。

在这里插入图片描述
默认会安装在用户目录下的Qt5.14.2中，也可以更改目录。

在选择安装组件的时候，可以根据需要进行选择：

在这里插入图片描述

笔者的MBP笔记本磁盘空间不大，所以仅选择了如下几项，需要1.44G的空间。

在这里插入图片描述

安装好后就可以运行Qt Creator了

在这里插入图片描述

三、创建项目

1.选择`Qt Widgets Application`

在这里插入图片描述

2. 选择CMake构建系统

在这里插入图片描述

3. 选择类信息

在这里插入图片描述

4. 选择翻译文件及语言

注意：这步非常重要，默认的情况下是没有语言，如果想要编写中文界面一定要选择中文，否则就会遇到中文菜单不能显示的问题

在这里插入图片描述

5. 选择Qt包

在这里插入图片描述

6. 选择版本控制系统

在Summary页可以选择版本控制系统，也可以保持默认，不选择

在这里插入图片描述

四、出现问题、解决问题

前面创建好项目后，就可以进行项目开发，不过笔者遇到了前述问题，下面一个一个来解决：

1. Qt Creator界面设计器中的菜单不显示

在这里插入图片描述

菜单中应该是文件的，但是在界面设计器中显示不出来，而且菜单设计栏最右边出现了一个双箭头按钮，这是因为菜单的默认字体太大了，笔者的默认为14号字体。

在这里插入图片描述

在属性中将menubar的字体设置小点，比如12号，就可以正常显示了：

在这里插入图片描述

2. Qt菜单在MacOS中不显示

前面我们在界面设计器中将菜单的字号设置成12号后，界面设计器中可以正常显示了，但是运行后，看不到菜单：

在这里插入图片描述

这是因为菜单项的文本是英文，也没有响应事件。需要将菜单项设置成中文（前面创建项目时需要选择翻译文件及语言为中文）

在这里插入图片描述

再将退出的响应事件添加上：

在这里插入图片描述

再次运行就要以看到菜单了：

在这里插入图片描述

关于此问题，网上很多资料都是说将menubar的nativeMenuBar开关关掉：

在这里插入图片描述

虽然可以，但是并非MacOS的习惯。运行效果如下：

在这里插入图片描述

3. Warning: The code model could not parse an included file

报警告：
Warning: The code model could not parse an included file, which might lead to incorrect code completion and highlighting, for example.

智能提示不能正常工作，Qt Creator中不能跳转打开Qt头文件，Code Model在解析源码时报：
Lexical or Preprocessor Issue：
error: 'QtCore/QVariant' file not found
error: 'QtWidgets/QAction' file not found
error: 'QtWidgets/QApplication' file not found
error: 'QtWidgets/QMainWindow' file not found
error: 'QtWidgets/QMenu' file not found
error: 'QtWidgets/QMenuBar' file not found

在这里插入图片描述

笔者在虚拟的MacOS 10.15.7中是没有出现，但在MBP中却出现了，笔者查过一些资料，网上很多的解决方案是不加载ClangCodeModel插件：

在这里插入图片描述

这就是一种掩耳盗铃的做法，让Qt Creator不再报警告，但是智能提示也不能正常工作，严重影响编码。

笔者想过编译器版本的问题，MacOS 10.13是Clang 9

$ clang -v
Apple LLVM version 9.0.0 (clang-900.0.39.2)
Target: x86_64-apple-darwin17.7.0
Thread model: posix

而MacOS 10.15是clang 12:

$ clang -v
Apple clang version 12.0.0 (clang-1200.0.32.29)
Target: x86_64-apple-darwin19.6.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin

但是编译运行都没问题，只是智能提示有问题。智能提示是使用的libclang或者clangd，都是基于clang的，肯定就是ClangCodeModel未能正确使用编译器在编译时的配置导致的。

对比查看Code Model相关信息：

在这里插入图片描述

没问题的Code Mode信息如下所示：

在这里插入图片描述

有问题的Code Mode如下所示：

在这里插入图片描述

通过对比，可以看到没问题的有多个FrameworkPath项，其中有指向Qt安装路径的（~/Qt5.14.2/5.14.2/clang_64/lib），而有问题的却没有，所以QT的头文件都会找不到：在这里插入图片描述

在MacOS中，Qt安装后的是以framework的形式存在的：

在这里插入图片描述

其中的头文件路径中并没有QtCore，QtWidgets这样的目录：

在这里插入图片描述

所以在MacOS中需要向编译器指定参数-iframework，这样编译器就可以自动搜索头文件路径了：

在这里插入图片描述

Qt Creator中Code Model信息是无法手动修改的，只能查看。它是通过Qmake或者CMake构建系统生成的信息来解析的。qmake没问题，那就很有可能是CMake的问题了。

再次对比CMake的版本，发现没问题的是CMake 3.25.1，而有问题的则是新版本3.28.1，我回退CMake版本到3.25.1版本，问题解决！更新到目前最新的3.29.1，依旧有问题。所以在新版本未解决之前，还是继续使用老版本吧！

当然这也许不是CMake的问题，而是CMake由于版本的升级，可能一些输出发生了变化，而Qt Creator版本比较老了，不支持新版本了。感兴趣的读者可以继续深究！

目前MacOS 10.15.7版本使用Qt 5.14.2开发就只有下面这个问题了:

Unable to create basic Accelerated OpenGL renderer.
Unable to create basic Accelerated OpenGL renderer.
Core Image is now using the software OpenGL renderer. This will be slow.

在这里插入图片描述