VS2022编译安装Qt6.4

前言

事情的起因是想在Win11装个Qt。打算装Qt6，然后查了一下发现Qt6不提供离线安装包了，只能用在线安装包安装预编译文件。下载在线安装程序看了一下，随即想起先前在Win10装Qt5.12时痛苦的环境配置经历，只怕一不小心选错哪个组件就用不了，可怜的一点下载流量只能付诸东流。随后得知Qt是可以编译安装的，且所有源代码只有700MB，心想没尝试过编译安装的CSer不是合格的CSer，于是查阅各种文献然后实战，就有了本文。

我使用的系统是Windows 11 22H2，VS版本是2022 17.4.4，打算编译的Qt版本是6.4.3。

获取源码

要编译一个程序，首先要获得它的源码。有三种办法获取Qt6的源码：

• 通过Qt Online Installer安装”Sources“这个组件
• 从Qt的Git仓库获取
• 从https://download.qt.io/下载打包的源码。你也可以到国内的各大开源镜像站（如mirrors.tsinghua.edu.cn）下载。

我使用第三种方法。我使用的下载链接是 https://mirrors.tuna.tsinghua.edu.cn/qt/archive/qt/6.4/6.4.3/single/qt-everywhere-src-6.4.3.tar.xz

源码包的选择：Qt提供两种源码包，所有组件全打在一个包里的，和各种组件分开打包的。根据这篇文章的说法，只安装分开打包的qtbase包就可以写大多数Qt程序了。而且后续其他组件也可以增量安装，见本文。但是我仍然下载了所有组件全在一起的包。

源码包会提供.tar.xz和.zip两种格式的，内容应该是完全一致的。.tar.xz格式的压缩率会高一些，可以省下一些流量和下载时间。你可以使用7-Zip来解压.tar.xz文件。

编译前的准备工作

为了编译Qt6.4，你应该具备至少15GB的硬盘空间。源代码大概4GB，编译过程中产生的中间文件可以达到8GB，安装后的文件应该不到1GB。

构建环境准备

你应该预先安装如下工具，且确保它们都在PATH环境变量中：

• 一个完整支持C++17标准的编译器。在本文中，使用的是VS2022带的msvc143版本。mingw应该也能用，但估计会有疑难杂症。
  • 如果你使用Visual Studio，那么需要在Installer应用中勾选“使用C++的桌面开发”工作负载，其中必装的组件是MSVC生成工具和Windows SDK，均选择最新即可。“实时调试器”和IntelliCode也建议安装，其他的都可以不装。“用于Windows的C++ CMake工具”组件不是必要的，但注意下面的独立CMake是必要的。
• CMake 3.16 或更新的版本 (为了使用-debug-and-release选项，需要3.17或更新版本；为了使用-static选项，需要3.21或更新版本). https://cmake.org/
• Ninja，不是必须的，但是建议安装，应该是用来加速构建的。本身也不大。 https://ninja-build.org/
• Perl，必须。流行的Windows包是ActiveState Perl和Strawberry Perl。前者需要注册账号（可用GitHub登录），因此我选的后者。另外安装Windows Git时会自带perl，但是我玩不明白那个git bash，就只好再装一个。
  • 注意：Strawberry Perl会自带一个完整的mingw编译器，而且它的安装程序会在系统的PATH环境变量添加三条变量，其中一条路径下包含了这个自带的mingw。如果你已经安装有mingw，安装Strawberry Perl后请使用where.exe gcc来检查gcc.exe的位置，如果自带的mingw和你系统原先的mingw产生了冲突，建议删除...\Strawberry\perl\c\bin这条环境变量。
• Python 3，必须。python.org。我的系统没有装Python的默认环境，但有一个miniconda的base环境，所以简单粗暴地将C:\Users\Eslzzyl\miniconda3加进了环境变量。这似乎不太好，建议编译完之后把这个环境变量删了。
  • 如果没装python的话，Windows可能会推荐你去Microsoft Store装，但我不推荐。很难说会不会有什么莫名其妙的问题。使用最多人使用的方法是最稳妥的。
  • 看某个官方文档说Python 2也可以，但是还是装3吧。2已经过时很久了。也许是文档的bug。
• 另：Qt源码包中的README.md说还需要Ruby，实测：没装也可以正常编译。

附：根据官方文档，Windows平台的下列编译器能够支持Qt6.4的编译：

Operating System	Architecture	Compiler
Windows 11 21H2 (1809 or later)	x86_64	MSVC 2022, MSVC 2019, MinGW 11.2
Windows 10 21H2 (1809 or later)	x86_64	MSVC 2022, MSVC 2019, MinGW 11.2
Windows on ARM	arm64	MSVC 2019/2022	Technology Preview

解压源码、组织文件夹

把源码解压到一个不带空格、不带特殊字符的路径下面。路径应该尽可能短，以防出现乱七八糟的问题。我使用的路径是D:\Library\Qt\。

源码解压后，压缩文件先不要删除，或者备份到别的地方。因为可能一次编译不过，保留源码还可以从头再来。

关于目录的组织问题，官方文档给的方案会把源码和生成的各种文件混在一起，很难受。因此我们选择分离存放的方式，这也是这篇官方文档推荐的方式：

• D:\Library\Qt\src放源代码
• D:\Library\Qt\build放构建生成的东西
• D:\Library\Qt\install放安装文件

因此，你应该把刚刚解压出来的一大堆源码放在src文件夹中。注意是直接放在src文件夹中，而不是在里面再套一个形如qt-everywhere-src-6.4.3的文件夹。为此你可以简单地将解压出来的qt-everywhere-src-6.4.3文件夹重命名为src。

开始编译

提示：编译中出现任何问题，都可以直接删除build文件夹，然后重新开始configure流程。只要你的源码没变，一切都可以从头再来。

VS安装时应该会生成一个x64 Native Tools Command Prompt fo VS 2022工具，在开始菜单中搜索它并启动。接下来的命令行操作全部在这个定制过的CMD环境中进行。（吐槽：这玩意居然不是PowerShell）

进入上一节所述的...\Qt\build目录。注意是build目录，不是src目录。

然后执行

..\src\qtbase\configure -prefix ..\install -debug

来使CMake检查你的构建环境并生成构建脚本。-prefix选项指定输出的安装文件应该存放在..\install目录。

耐心等待configure完成。

注：检查configure的输出，你会发现如下的内容：

Build options:
  Mode ................................... debug
  Fully optimize release builds (-O3) .... no

这表示Qt将在Debug模式下被构建。Qt的Debug模式和Release模式分别对应了MSVC的Debug和Release模式，二者的区别主要是产生的.lib文件有所不同，如Release模式下有Qt6Widgets.lib，而Debug模式对应的文件则是Qt6Widgetsd.lib，注意多出来的d字母。

你希望在哪个模式下使用Qt，就要以哪个模式作为目标进行编译。当然你也可以使用选项debug-and-release来同时产生Debug和Release模式的库文件，这样就可以同时支持MSVC的Debug和Release模式了。这篇文档在configure时指定了-debug-and-release选项而这篇文档没有。这个帖子讨论了这个问题。应该可以确定的是，通过Qt在线安装程序下载的预编译版本是使用了-debug-and-release的。

另外，我在第一次编译时使用了-debug-and-release，但在后续安装时发现只拷贝了Release的.lib文件，因此我又以Debug模式重新编译了一次，然后执行安装。如果你遇到了同样的问题，可以通过分别指定-debug和-release并编译两遍来简单地解决这个问题。在-debug-and-release选项还没有诞生之前，社区都是这么干的。

最后输出的内容应该形如：

Qt is now configured for building. Just run 'cmake --build . --parallel'

Once everything is built, you must run 'ninja install'
Qt will be installed into 'D:/Library/Qt/install'

To configure and build other Qt modules, you can use the following convenience script:
        D:/Library/Qt/install/bin/qt-configure-module.bat

If reconfiguration fails for some reason, try removing 'CMakeCache.txt' from the build directory

-- Configuring done
-- Generating done
-- Build files have been written to: D:/Library/Qt/build

然后保持当前文件夹不变，执行

cmake --build . --parallel

来启动编译。编译时间依CPU性能差距，可能从5分钟到半小时不等。如果你使用移动设备，建议连接电源来获得最佳的性能释放。在我的Ryzen 6800HS机器上，编译大约花费了8分钟。

附一张编译时的盛况：

然后执行

cmake --install .

就会把文件拷贝到install目录了。

此时不忙着删build和src，建议先配一下VS环境，确定没问题之后再删。

使用

在Visual Studio 2022中选择”扩展 - 管理扩展“，搜索并安装”Qt Visual Studio Tools“扩展，安装后就可以创建Qt项目了。首次进入项目时会提示你配置Qt环境，选择../install/bin/qmake.exe即可。"Version"的名字可以随便起。

随后你可以在”扩展 - Qt VS Tools“菜单来管理Qt的各项设置。

新建一个Qt Widget项目，使用自动生成的代码模板，在你期望的模式（Debug/Release）下运行程序，查看是否正常弹出了窗口。

窗口正常弹出，成功了！

至此，你可以删除build和src文件夹了。

后记

编译安装Qt这个事情没有我想象得那么困难。实际上和之前做硬件系统课程设计的时候编译Linux下的RISC-V GCC工具链相比，可以说是小巫见大巫了。编译好的目标文件（Debug+Release）居然只有不到700MB，属实令人吃惊。毕竟之前对Qt5离线安装的印象是动辄4-6G。而且熟练的话，编译安装应该是要比在线下载安装更快的。

总之还是要勇于尝试。大不了删build重来嘛，源码又不会跑掉。

另外我没有做太多调查就开始操作了，因此可能会犯一些错误，有些错误可能在之后较深入地使用Qt时才能发现。如果我发现有错误，我会及时更新本文。