使用 Clazy 检查将 C++ 应用程序移植到 Qt 6

我们在 Clazy 框架中实现了一些检查和修复功能，以帮助您将应用程序从 Qt 5 移植到 Qt 6。用他们自己的话来说：“Clazy 是一个编译器插件，它使 clang 能够理解 Qt 的语义”。 请获取 Clazy（https://invent.kde.org/sdk/clazy），并继续阅读以下内容，让您的 Qt 6 移植过程更加顺畅。

Clazy 检查可在编译期间作为插件运行，或通过clazy-standalone 基于 JSON 编译数据库进行运行。后续可通过clang-apply-replacements 应用修复。

专用于 Qt 6 移植的 Clazy 检查

以下检查专用于简化从 Qt 5 到 Qt 6 的移植过程。

• qt6-deprecated-api-fixes
• qt6-header-fixes
• qt6-qhash-signature
• qt6-fwd-fixes
• missing-qobject-macro

这些检查必须针对 Qt 5 运行。修复后的代码仅能针对 Qt 6 编译通过。因此，上述检查必须一次性运行完毕。Clazy 建议每次只运行一项测试，以避免应用修复时发生冲突，但在将这些检查作为插件运行时，这种做法不可行。

如何应用 Clazy 检查

关于如何配置项目以配合 Clazy 运行，以及如何选择和应用检查，请参阅此处详细说明：https://invent.kde.org/sdk/clazy#setting-up-your-project-to-build-with-clazy。

如果您不想以插件形式运行检查，而是希望通过 JSON 编译数据库进行检查，则需要使用clazy-standalone 。具体操作指南请参阅https://invent.kde.org/sdk/clazy#clazy-standalone-and-json-database-support。

简而言之，假设您已安装了最新版本的 Clazy，下面将说明如何将其作为插件运行检查。

配置项目以支持 Clazy 运行。

如果使用 qmake

请根据您的操作系统，在 qmake 命令中添加以下行：

-spec linux-clang QMAKE_CXX="clazy"
-spec macx-clang QMAKE_CXX="clazy"

对于使用 MSVC 的 Windows 系统，请添加 `QMAKE_CXX="clazy-cl.bat"`。

运行 qmake。

如果使用 CMake

在 cmake 命令中添加：-DCMAKE_CXX_COMPILER=clazy 。

运行 cmake。

选择检查项：

export CLAZY_CHECKS="qt6-deprecated-api-fixes,qt6-header-fixes,
qt6-qhash-signature,qt6-qlatin1stringchar-to-u,qt6-fwd-fixes,missing-qobject-macro"

启用 fixits：

export CLAZY_EXPORT_FIXES=ON

设置 Clazy 需忽略的目录：

export CLAZY_IGNORE_DIRS=.*lib_dir.*

这将防止 Clazy 对库文件进行检查。如果库的路径是通过-I 和-F 包含的，而不是通过-isystem 和-framework 包含的，则必须进行此设置。此外，如果触发检查的头文件包含在所引用的库文件中，为避免qt-header-fixes 检查产生的警告，也必须进行此设置。

编译您的代码。

编译过程中，会在源文件旁边生成.yaml 文件。

要应用这些修正，请运行：

clang-apply-replacements <path_to_yaml_files>

这将修改源文件，请考虑备份您的代码。

如果修复项之间存在冲突，系统会发出通知，且不会修改任何文件。

并非所有移植工作都能通过自动修正程序完成。请仔细查看编译过程中的警告，以确定哪些代码需要手动修改。

如何在Qt Creator

您可以在Qt Creator 中通过选择“Tools ” > “Options ” > “Analyzer ”（或 Qt Creator >Preferences >Analyzer ）。

您必须创建自己的配置，并选择专用于移植的 Clazy 检查项——这些检查项可在Qt Creator 4.14.1 版或更高版本的“Level 2”和“Manual Level”部分中找到。您可以使用qt6过滤器来定位大部分检查项。请务必仅选择上述列表中列出的检查项。

要运行检查，请选择Analyze > “Clang-Tidy and Clazy ”。

有关配置和运行 Clazy 检查的更多信息，请参阅Qt Creator: Clang Tools。

注意事项

在Qt Creator 中，系统不会对修复项之间的冲突发出警告。如果同一行存在多个修复项，请在应用修复项时格外小心。

一旦应用了某个 fixit，再次运行检查将会失败，因为新代码只能针对 Qt 6 进行编译。