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

Table of contents

• Source Code
• Build Instructions
  • Linux
    • Install dependencies
    • Build and install clang
    • Build clazy
  • Windows
    • Build and install clang
    • Build clazy
  • macOS with MacPorts
    • Install clang
    • Build clazy
  • macOS with Homebrew
    • Install clang
    • Build clazy
• Setting up your project to build with clazy
• List of checks
• Selecting which checks to enable
  • Example via env variable
  • Example via compiler argument
• clazy-standalone and JSON database support
• Enabling Fixits
• Troubleshooting
• Reducing warning noise
• Reporting bugs and wishes
• Authors
• Contributing patches

Source Code

You can get clazy from:

• https://github.com/KDE/clazy
• https://invent.kde.org/sdk/clazy

Supported platforms

Clazy has been tested on Linux, macOS and Windows/MSVC. Other platforms are not supported but we'll gladly accept patches.

Build Instructions

Linux

Install dependencies

• OpenSUSE tumbleweed: zypper install cmake git-core llvm llvm-devel llvm-clang llvm-clang-devel
• Ubuntu: apt install g++ cmake clang llvm-dev git-core libclang-dev
• Archlinux: pacman -S make llvm clang python2 cmake git gcc
• Fedora: be sure to remove the llvm-static package and only install the one with dynamic libraries
• Other distros: Check llvm/clang build docs.

Build and install clang

clang and LLVM >= 11.0 are required.

If your distro provides clang then you can skip this step.

  $ git clone https://github.com/llvm-mirror/llvm.git <some_directory>
  $ cd <some_directory>/tools/ && git clone https://github.com/llvm-mirror/clang.git
  $ cd <some_directory>/projects && git clone https://github.com/llvm-mirror/compiler-rt.git
  $ mkdir <some_directory>/build && cd <some_directory>/build
  $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DLLVM_TARGETS_TO_BUILD=X86 -DCMAKE_BUILD_TYPE=Release -G Ninja ..
  $ cmake --build .
  $ cmake --build . --target install

Build clazy

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

See troubleshooting section if you have problems.

Windows

Build and install clang

These instructions assume your terminal is suitable for development. Ninja (or equivalent), git, cmake, and cl (msvc2022) should be in your PATH.

Be sure to pass -DLLVM_EXPORT_SYMBOLS_FOR_PLUGINS=ON to CMake when building LLVM, otherwise clazy won't work.

  > git clone https://github.com/llvm/llvm-project.git -b llvmorg-11.0.0 <some_directory>
  > mkdir build # Important that this is outside of the source directory
  > cd build
  > cmake -DCMAKE_INSTALL_PREFIX=c:\my_install_folder\llvm\ -DLLVM_EXPORT_SYMBOLS_FOR_PLUGINS=ON -DLLVM_INCLUDE_EXAMPLES=OFF -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -DCMAKE_BUILD_TYPE=Release -G "Ninja" ../<some_directory>/llvm
  > cmake --build .
  > cmake --build . --target install
  > Add c:\my_install_folder\llvm\bin\ to PATH

Also be sure to copy the generated C:\path\to\llvm-build\lib\clang.lib to your installation folder somewhere. It contains the exported symbols of clang.exe, which the plugins need. Unfortunately LLVM doesn't install it. You can put it anywhere, just save it so you can delete the build directory.

Build clazy

Be sure to point CLANG_LIBRARY_IMPORT to clang.lib. It's probably inside your LLVM build dir since it doesn't get installed.

  > cd clazy\
  > cmake -DCMAKE_INSTALL_PREFIX=c:\my_install_folder\llvm\ -DCLANG_LIBRARY_IMPORT=C:\path\to\llvm-build\lib\clang.lib -DCMAKE_BUILD_TYPE=Release -G "Ninja"
  > cmake --build .
  > cmake --build . --target install

macOS with MacPorts

Install clang

$ sudo port install llvm-11 clang-11 cmake ninja coreutils
$ sudo ln -sf /opt/local/bin/llvm-config-mp-11 /opt/local/bin/llvm-config
$ sudo port select --set clang mp-clang-11

Build clazy

  $ export CXX=clang++
  $ cmake -G Ninja
  $ cmake --build .
  $ cmake --build . --target install

macOS with Homebrew

The recommended way is to build clazy yourself, but alternatively you can try user recipes, such as:

$ brew install kde-mac/kde/clazy

for stable branch, or for master:

$ brew install kde-mac/kde/clazy --HEAD

As these are not verified or tested by the clazy developers please don't report bugs to us.

For building yourself, read on. You'll have to install clang and build clazy from source.

Install clang

$ brew install --with-clang llvm

Build clazy

  $ export CXX=clang++
  $ export LLVM_ROOT=/usr/local/opt/llvm
  $ cmake -G Ninja
  $ cmake --build .
  $ cmake --build . --target install

Setting up your project to build with clazy

Note: Wherever clazy is mentioned, replace with clazy-cl.bat if you're on Windows, or replace with Clazy-x86_64.AppImage if you're using AppImage. Note: If you prefer running clazy over a JSON compilation database instead of using it as a plugin, jump to clazy-standalone.

You should now have the clazy command available to you, in <prefix>/bin/. Compile your programs with it instead of clang++/g++.

Note that this command is just a convenience wrapper which calls: clang++ -Xclang -load -Xclang ClazyPlugin.so -Xclang -add-plugin -Xclang clazy

If you have multiple versions of clang installed (say clang++-10 and clang++-11) you can choose which one to use by setting the CLANGXX environment variable, like so: export CLANGXX=clang++-11; clazy

To build a CMake project use: cmake . -DCMAKE_CXX_COMPILER=clazy and rebuild.

To make it the compiler for qmake projects, just run qmake like: qmake -spec linux-clang QMAKE_CXX="clazy"

On Windows with MSVC it's simply: qmake QMAKE_CXX="clazy-cl.bat"

Alternatively, if you want to use clang directly, without the wrapper: qmake -spec linux-clang QMAKE_CXXFLAGS="-Xclang -load -Xclang ClazyPlugin.so -Xclang -add-plugin -Xclang clazy"

On Windows it's similar, just inspect the contents of clazy-cl.bat.

To use clazy from a preset in CMakePresets.json or CMakeUserPresets.json:

"cacheVariables": {
    "CMAKE_CXX_FLAGS": "-Xclang -plugin-arg-clazy -Xclang export-fixes -Xclang -plugin-arg-clazy -Xclang  level0,detaching-temporary",
    "CMAKE_CXX_COMPILER": "clazy"
}

It's recommended that you disable pre-compiled headers and don't use ccache.

You're all set, clazy will now run some checks on your project, but not all of them. Read on if you want to enable/disable which checks are run.

List of checks

There are many checks and they are divided in levels:

• level0: Very stable checks, 99.99% safe, mostly no false-positives, very desirable
• level1: The default level. Very similar to level 0, slightly more false-positives but very few.
• level2: Also very few false-positives, but contains noisy checks which not everyone agree should be default.
• manual: Checks here need to be enabled explicitly, as they don't belong to any level. They can be very stable or very unstable.

clazy runs all checks from level1 by default.

• Checks from Manual Level:

  • assert-with-side-effects
  • compare-member-check
  • container-inside-loop
  • detaching-member
  • heap-allocated-small-trivial-type
  • ifndef-define-typo
  • isempty-vs-count
  • jni-signatures
  • qbytearray-conversion-to-c-style (fix-qbytearray-conversion-to-c-style)
  • qhash-with-char-pointer-key
  • qproperty-type-mismatch
  • qrequiredresult-candidates
  • qstring-ref (fix-missing-qstringref)
  • qstring-varargs
  • qt-keyword-emit (fix-qt-keyword-emit)
  • qt-keywords (fix-qt-keywords)
  • qvariant-template-instantiation
  • raw-environment-function
  • reserve-candidates
  • sanitize-inline-keyword (fix-sanitize-inline-keyword)
  • signal-with-return-value
  • thread-with-slots
  • tr-non-literal
  • unexpected-flag-enumerator-value
  • [unneeded-cast](docs/checks/R