配置Qt 6.2.4时因缺失libclang无法配置QDoc求解决方案

问题描述 #

构建Qt 6.2.4源码时出现以下警告：

WARNING: QDoc will not be compiled, probably because libclang could not be located. This means that you cannot build the Qt documentation.
Either set CMAKE_PREFIX_PATH or LLVM_INSTALL_DIR to the location of your llvm installation.
On Linux systems, you may be able to install libclang by installing the libclang-dev or libclang-devel package, depending on your distribution.
On macOS, you can use Homebrew's llvm package.
You will also need to set the FEATURE_clang CMake variable to ON to re-evaluate this check.
WARNING: Clang-based lupdate parser will not be available. LLVM and Clang C++ libraries have not been found.
You will need to set the FEATURE_clangcpp CMake variable to ON to re-evaluate this check.

已将LLVM_INSTALL_DIR设置为Qt官网下载的Windows版16.0.2预构建libclang顶层目录，删除构建目录后重新配置，警告仍存在。

解决步骤 #

• 确认libclang目录结构
  解压后的预构建包顶层目录必须包含include、lib核心子目录，且include下要有clang文件夹，lib下要有libclang.lib等文件。如果解压后还有一层嵌套子目录（比如外层是libclang-16.0.2，内层才是包含include的目录），需将LLVM_INSTALL_DIR指向内层的实际顶层目录。

• 强制开启clang相关特性
  配置CMake时必须显式开启FEATURE_clang和FEATURE_clangcpp：

  • 若用cmake-gui：点击"Add Entry"，分别添加两个布尔型变量：
    • 变量名FEATURE_clang，值设为ON
    • 变量名FEATURE_clangcpp，值设为ON
  • 若用命令行，在配置命令中追加参数：

    cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_BUILD_TYPE=Release -DLLVM_INSTALL_DIR=C:/path/to/correct/libclang-dir -DFEATURE_clang=ON -DFEATURE_clangcpp=ON ../qt6.2.4-source
    

    注意替换路径为你的实际libclang目录，生成器根据你的VS版本选择。

• 检查路径格式与环境干扰

  • Windows路径使用正斜杠/或双反斜杠\\，避免单斜杠导致的转义错误；
  • 若系统中存在其他LLVM/libclang版本，需将指定的libclang目录加入CMAKE_PREFIX_PATH并置于最前，避免CMake优先识别旧版本：

    -DCMAKE_PREFIX_PATH=C:/path/to/correct/libclang-dir
    

• 验证版本兼容性
  虽然16.0.2属于Qt 6.2.x兼容的版本范围，但可尝试Qt官网提供的与6.2.x版本匹配的libclang预构建包，版本匹配度更高可能解决识别问题。

• 彻底清理构建缓存
  确保完全删除构建目录（包括隐藏文件），避免残留的CMake缓存干扰新配置，之后再重新执行CMake配置命令。

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