clazy, a Clang plugin that teaches the compiler about Qt

What the plugin does and why a compiler plugin

clazy is a compiler plugin which allows clang to understand Qt semantics, and the README says you get more than 50 Qt related compiler warnings, ranging from unneeded memory allocations to misusage of API, including fix-its for automatic refactoring.

The approach is what makes this different from a linter. A linter reads source code and applies rules to what it can parse. A compiler plugin runs inside the compiler, so it sees the full typed program after the front end has resolved overloads, built the class hierarchy and worked out the ownership of every pointer. For a language with implicit conversions, implicit sharing and expression templates, that difference is the whole point, because a Qt mistake is often only visible once the types are known.

The warnings themselves cover the categories that Qt programmers actually get wrong. An unnecessary memory allocation is the canonical one, and it is a case where a plain text linter cannot help, because whether a copy is made depends on the type of the expression and the semantics of the container.

The fix-its are the second half of the value. A warning you have to fix by hand is work, and a fix-it the editor can apply is a suggestion the developer accepts or rejects in one keystroke. For the mechanical cases, that is the difference between a warning people turn off and one people act on.

The project is on invent.kde.org under the KDE SDK, with a mirror on GitHub, and the last push was on 2026-10-17. It has been tested on Linux, macOS and Windows with MSVC, and the README says other platforms are not supported but patches are welcome.

Building it, and the dependency on building Clang

The build instructions are the part of the README that tells you how much work this is, and the honest answer is that on most distributions you can skip the first stage.

Clang and LLVM 11.0 or newer are required. If your distribution provides clang, the README says you can skip building it, and the per-distribution dependency lists are given: zypper for openSUSE Tumbleweed, apt for Ubuntu with clang, llvm-dev and libclang-dev, pacman for Arch, and a note for Fedora to remove the llvm-static package and install the one with dynamic libraries instead.

The Windows instructions carry a detail that is easy to miss and impossible to work around later. When building LLVM there you must pass -DLLVM_EXPORT_SYMBOLS_FOR_PLUGINS=ON, otherwise clazy will not work, because the plugin needs the exported symbols from clang.exe. The README also asks you to copy the generated clang.lib from the build directory to your installation folder, because LLVM does not install it, and the comment on that step is practical: save it somewhere so you can delete the build directory.

The macOS section is split into MacPorts and Homebrew variants, each with its own clang install step, which reflects that the two package managers handle the LLVM dependency differently and neither gives you a plugin-enabled build out of the box.

The clazy build itself is ordinary CMake in both cases, with an install prefix and a Release build type, generated with Ninja. On Windows there is one extra flag, CLANG_LIBRARY_IMPORT pointing at clang.lib, and the README notes it is probably in the LLVM build directory since LLVM does not install it.

The overall shape is: build a Clang with plugin support, then build clazy against it. The first step is the expensive one, and it is why the tool is a developer and CI concern rather than something a desktop user installs.

The plugin build itself is the last step, and it is the same on every platform:

  $ cd clazy/
  $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_BUILD_TYPE=Release -G Ninja
  $ cmake --build .
  $ cmake --build . --target install

Two flags matter here. The install prefix has to match the Clang you built earlier, because the plugin is loaded by that Clang and a mismatch is a load failure at compile time rather than a clear error. The build type of Release is for the plugin itself, and the generated Clang plugin runs inside every compilation, so a debug build of it is noticeably slower.

The README closes this section by pointing at the troubleshooting section, which is the sensible order of reading when something does not work. The usual cause is the prefix mismatch, and the second most common is a Clang that was not built with plugin symbol export enabled, which on Windows is the -DLLVM_EXPORT_SYMBOLS_FOR_PLUGINS=ON flag.

Wiring it into a build and choosing checks

Once it is built, the question is how to get it into a build you already have, and the README has a section on setting up your project to build with clazy, a section on the list of checks, a section on selecting which checks to enable, and a troubleshooting section.

The selection of checks is the part worth thinking about, because a plugin that emits warnings nobody reads is a plugin that gets disabled wholesale. The README gives two ways to select checks, one via an environment variable and one via a compiler argument, and the existence of a section on reducing warning noise says the same thing: a tool with fifty checks will be noisy until it is tuned, and the tuning has to be per project rather than global.

The environment variable route is the one that suits a developer trying it out, because it does not require touching the build files, and the compiler argument route is the one that belongs in the committed configuration once you have decided which checks you want.

The troubleshooting section and the reducing warning noise section are the ones to read before rolling it out to a team. A new set of fifty warnings on an existing codebase is a large diff, and a team that receives all of them at once will either spend a week fixing things or disable the tool. The usual approach is to enable a handful of high-confidence checks, fix those, and then widen.

There is also a clazy-standalone mode and JSON database support, which is a different way of running the analysis. The standalone tool lets you run the checks over a codebase without going through a full compiler invocation, and the JSON database is the mechanism for getting results somewhere a tool can consume them. The README's separate section for both suggests they matter for integration into a larger analysis setup, and they are what you would use to run clazy in a pipeline rather than in an IDE.

Enabling fix-its has its own section, which is worth noting because fix-its are usually off by default in compiler plugins for performance reasons, and turning them on changes what the compiler does with the code it is analysing.

How it fits against the alternatives

The alternative that gets compared most often is clang-tidy, because it is the same engine and the same warnings infrastructure, and clazy is in effect a set of Clang checks that understand Qt.

The difference in approach is semantic depth. clang-tidy has its own Qt-related checks, and they work, but they operate on the AST in a way that does not always have the full picture of what an expression means in Qt terms. clazy is built to be driven by the compiler with the Qt-aware analysis it needs, and the README's claim of more than 50 Qt related warnings with fix-its reflects a deeper analysis than a general-purpose checker provides.

The second alternative is doing nothing and relying on review. The failure modes clazy catches, an unnecessary allocation or a misused API, are the kind that survive review and turn into performance problems later, so a tool that finds them has clear value on a large Qt codebase.

The third alternative is a different kind of tool entirely. Static analysis that is not compiler-based, such as a custom script over the source or a code quality platform, can be easier to run across a mixed stack, and a commercial code quality service may already cover some of the same rules with no build changes at all.

The practical cost of clazy is the build. It needs a Clang built with plugin support, which is a nontrivial dependency for a project that currently builds with GCC or with a distribution's Clang, because a normal Clang build does not export the plugin symbols. That is the single biggest reason teams look at it and then do not adopt it, and the README is upfront about the requirement.

There is a middle path that many projects take. Keep the normal build as it is, add a CI job that builds Clang once with plugin support and then runs clazy over the code as a separate analysis step. The build cost is paid once, and the analysis becomes a check rather than a change to how everything compiles. That is slower than a compiler plugin in the inner loop, but it keeps the everyday build untouched and it is the arrangement that survives contact with a team that does not want to change its toolchain.

Given that the project is a KDE SDK project with a long history and an active commit record, and that the warnings are Qt-specific rather than generic, the case for it is strongest on a large Qt codebase that has never had a Qt-aware static analysis pass over it.

Editorial conclusion

Adopt clazy if you maintain a Qt codebase and want the compiler to catch Qt-specific mistakes rather than finding them in review. Skip it if your Qt usage is trivial, since the plugin is an addition to your build. Verify first by pointing the plugin at one existing target with a single check enabled, and by reading the warnings it reports on code you already believe is correct, since the point of the tool is to find things you did not know were wrong.

Frequently asked questions

Official sources

1. Issues
2. KDE/clazy on GitHub
3. Project website
4. README