Qt6.2下qmake如何为旧项目配置ATL实现无硬编码跨机构建

问题背景 #

在将依赖ATL与COM服务器通信的遗留Qt项目迁移到Qt 6.2时，目标是实现跨机器可移植构建。目前通过在.pro文件中添加硬编码路径配置，已经可以在本机完成构建：

INCLUDEPATH += "C:/Program Files/Microsoft Visual Studio/2022/Professional/VC/Tools/MSVC/14.32.31326/atlmfc/include/"
win32:LIBS += "C:/Program Files/Microsoft Visual Studio/2022/Professional/VC/Tools/MSVC/14.32.31326/atlmfc/lib/x64/atls.lib"

上述配置的作用：

• INCLUDEPATH 配置解决编译阶段无法打开ATLComTime.h头文件的报错
• win32:LIBS 配置用于引入项目依赖的必要ATL库文件

当前存在的问题：硬编码了绑定本机VS安装路径、MSVC版本号的绝对路径，更换开发机、升级VS版本、切换构建架构时都会出现构建失败。已知同一项目在VS 2022中无需手动添加上述配置即可正常构建，VS内部存在自动配置ATL路径的逻辑，需要找到qmake下的机器无关配置方案，同时确认是否存在专门标识ATL项目的qmake配置项。

可行方案 #

方案1：使用qmake内置ATL配置（推荐） #

qmake针对MSVC编译器预置了ATL相关的配置规则，不需要手动编写任何路径或链接规则，只需要在.pro文件中添加一行配置即可：

win32-msvc*: CONFIG += atl

添加该配置后，qmake会自动完成以下操作，逻辑和VS内部的自动配置完全一致：

• 自动匹配当前使用的MSVC工具链版本，添加对应版本的ATL头文件搜索路径
• 自动匹配当前构建的目标架构（x86/x64/arm64），添加对应架构的ATL库搜索路径
• 自动添加ATL所需的预处理器定义、默认链接atls.lib等必要依赖
• 自动适配不同VS版本（2017/2019/2022）、不同安装盘符、不同MSVC小版本号的路径差异

如果项目同时依赖MFC，同理添加CONFIG += mfc即可自动完成MFC相关配置。

方案2：通过MSVC内置环境变量拼接路径 #

如果需要自定义ATL相关配置，也不要硬编码绝对路径，直接使用MSVC工具链自带的环境变量拼接路径即可，同样可以实现跨机器兼容：

win32-msvc* {
    # VCToolsInstallDir是VS注册的系统环境变量，指向当前激活的MSVC工具链根目录
    ATL_ROOT = $$(VCToolsInstallDir)atlmfc
    INCLUDEPATH += $$ATL_ROOT/include
    # QMAKE_TARGET.arch是qmake内置变量，自动填充当前目标架构对应的目录名
    LIBS += -L$$ATL_ROOT/lib/$$QMAKE_TARGET.arch
    LIBS += atls.lib
}

注意写法中读取系统环境变量需要用$$(变量名)格式，和读取qmake内置变量的$$变量名格式做区分。

排查注意事项 #

如果配置后仍然提示找不到ATL头文件或库，优先打开Visual Studio Installer检查，确认对应MSVC版本的「C++ ATL生成工具」组件已经安装，未安装该组件时任何路径配置都无法生效。

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