README.md
1clazy v1.5
2===========
3
4clazy 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.
5
6Table of contents
7=================
8
9 * [Source Code](#source-code)
10 * [](#pre-built-binaries)
11 * [Build Instructions](#build-instructions)
12 * [Linux](#linux)
13 * [Install dependencies](#install-dependencies)
14 * [Build and install clang](#build-and-install-clang)
15 * [Build clazy](#build-clazy)
16 * [Windows](#windows)
17 * [Build and install clang](#build-and-install-clang-1)
18 * [Build clazy](#build-clazy-1)
19 * [macOS with MacPorts](#macos-with-macports)
20 * [Install clang](#install-clang)
21 * [Build clazy](#build-clazy-2)
22 * [macOS with Homebrew](#macos-with-homebrew)
23 * [Install clang](#install-clang-1)
24 * [Build clazy](#build-clazy-3)
25 * [Setting up your project to build with clazy](#setting-up-your-project-to-build-with-clazy)
26 * [List of checks](#list-of-checks)
27 * [Selecting which checks to enable](#selecting-which-checks-to-enable)
28 * [Example via env variable](#example-via-env-variable)
29 * [Example via compiler argument](#example-via-compiler-argument)
30 * [clazy-standalone and JSON database support](#clazy-standalone-and-json-database-support)
31 * [Enabling Fixits](#enabling-fixits)
32 * [Troubleshooting](#troubleshooting)
33 * [Qt4 compatibility mode](#qt4-compatibility-mode)
34 * [Reducing warning noise](#reducing-warning-noise)
35 * [Reporting bugs and wishes](#reporting-bugs-and-wishes)
36 * [Authors](#authors)
37 * [Contributing patches](#contributing-patches)
38
39# Source Code
40
41You can get clazy from:
42
43- <https://github.com/KDE/clazy>
44- git@git.kde.org:clazy
45- git://anongit.kde.org/clazy
46
47# Pre-built binaries
48
49Pre-built binaries are produced by KDAB, you can get them from https://downloads.kdab.com/clazy/.
50Currently MSVC2015, MSVC2017 and Linux AppImage packages are provided. All of them are based on clang 7.0.
51
52# Build Instructions
53## Linux
54
55### Install dependencies
56- OpenSUSE tumbleweed: `zypper install cmake git-core llvm llvm-devel llvm-clang llvm-clang-devel`
57- Ubuntu: `apt install g++ cmake clang llvm-dev git-core libclang-dev`
58- Archlinux: `pacman -S make llvm clang python2 cmake git gcc`
59- Fedora: be sure to *remove* the llvm-static package and only install the one with dynamic libraries
60- Other distros: Check llvm/clang build docs.
61
62### Build and install clang
63clang and LLVM >= 4.0 are required.
64Use clazy v1.1 if you need 3.7 support, or v1.3 for 3.8 support.
65
66If your distro provides clang then you can skip this step.
67
68
69```
70 $ git clone https://github.com/llvm-mirror/llvm.git <some_directory>
71 $ cd <some_directory>/tools/ && git clone https://github.com/llvm-mirror/clang.git
72 $ cd <some_directory>/projects && git clone https://github.com/llvm-mirror/compiler-rt.git
73 $ mkdir <some_directory>/build && cd <some_directory>/build
74 $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DLLVM_TARGETS_TO_BUILD=X86 -DCMAKE_BUILD_TYPE=Release ..
75 $ make -jX && make install
76```
77
78### Build clazy
79```
80 $ cd clazy/
81 $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_BUILD_TYPE=Release
82 $ make && make install
83```
84
85See troubleshooting section if you have problems.
86
87## Windows
88
89### Build and install clang
90These instructions assume your terminal is suitable for development (msvc2015).
91jom, nmake, git, cmake and cl should be in your PATH.
92
93clang and LLVM >= 4.0 are required.
94
95Be sure to pass -DLLVM_EXPORT_SYMBOLS_FOR_PLUGINS=ON to CMake when building LLVM, otherwise clazy won't work.
96
97```
98 > git clone https://github.com/llvm-mirror/llvm.git <some_directory>
99 > cd <some_directory>\tools\ && git clone https://github.com/llvm-mirror/clang.git
100 > git checkout release_40
101 > cd clang
102 > git checkout release_40
103 > mkdir <some_directory>\build && cd <some_directory>\build
104 > cmake -DCMAKE_INSTALL_PREFIX=c:\my_install_folder\llvm\ -DLLVM_TARGETS_TO_BUILD="X86" -DLLVM_EXPORT_SYMBOLS_FOR_PLUGINS=ON -DCMAKE_BUILD_TYPE=Release -G "NMake Makefiles JOM" ..
105 > jom
106 > nmake install
107 > Add c:\my_install_folder\llvm\bin\ to PATH
108```
109
110### Build clazy
111
112Be sure to point CLANG_LIBRARY_IMPORT to clang.lib. It's probably inside your LLVM build dir since it doesn't get installed.
113
114```
115 > cd clazy\
116 > 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 "NMake Makefiles JOM"
117 > jom && nmake install
118```
119
120## macOS with MacPorts
121
122### Install clang
123```
124$ sudo port install clang-3.9 llvm-3.9
125$ sudo ln -sf /opt/local/bin/llvm-config-mp-3.9 /opt/local/bin/llvm-config
126$ sudo port select --set clang mp-clang-3.9
127```
128
129### Build clazy
130```
131 $ export CXX=clang++
132 $ cmake
133 $ make
134 $ make install
135```
136
137## macOS with Homebrew
138
139The recommended way is to build clazy yourself, but alternatively you can try user recipes, such as:
140
141```
142$ brew install kde-mac/kde/clazy
143```
144
145for stable branch, or for master:
146
147```
148$ brew install kde-mac/kde/clazy --HEAD
149```
150
151As these are not verified or tested by the clazy developers please don't report bugs to us.
152
153For building yourself, read on. You'll have to install clang and build clazy from source.
154
155### Install clang
156
157```
158$ brew install --with-clang llvm
159```
160
161### Build clazy
162```
163 $ export CXX=clang++
164 $ export LLVM_ROOT=/usr/local/opt/llvm
165 $ cmake
166 $ make
167 $ make install
168```
169
170# Setting up your project to build with clazy
171
172Note: Wherever `clazy` it mentioned, replace with `clazy-cl.bat` if you're on Windows, or replace with `Clazy-x86_64.AppImage` if you're using AppImage.
173Note: If you prefer running clazy over a JSON compilation database instead of using it as a plugin, jump to [clazy-standalone](#clazy-standalone-and-json-database-support).
174
175You should now have the clazy command available to you, in `<prefix>/bin/`.
176Compile your programs with it instead of clang++/g++.
177
178Note that this command is just a convenience wrapper which calls:
179`clang++ -Xclang -load -Xclang ClazyPlugin.so -Xclang -add-plugin -Xclang clazy`
180
181If you have multiple versions of clang installed (say clang++-3.8 and clang++-3.9)
182you can choose which one to use by setting the CLANGXX environment variable, like so:
183`export CLANGXX=clang++-3.8; clazy`
184
185To build a CMake project use:
186 `cmake . -DCMAKE_CXX_COMPILER=clazy`
187and rebuild.
188
189To make it the compiler for qmake projects, just run qmake like:
190`qmake -spec linux-clang QMAKE_CXX="clazy"`
191
192On Windows with MSVC it's simply: `qmake QMAKE_CXX="clazy-cl.bat"`
193
194Alternatively, if you want to use clang directly, without the wrapper:
195`qmake -spec linux-clang QMAKE_CXXFLAGS="-Xclang -load -Xclang ClazyPlugin.so -Xclang -add-plugin -Xclang clazy"`
196
197On Windows it's similar, just inspect the contents of `clazy-cl.bat`.
198
199
200It's recommended that you disable pre-compiled headers and don't use ccache.
201
202You're all set, clazy will now run some checks on your project, but not all of them.
203Read on if you want to enable/disable which checks are run.
204
205# List of checks
206
207There are many checks and they are divided in levels:
208- level0: Very stable checks, 99.99% safe, mostly no false-positives, very desirable
209- level1: The default level. Very similar to level 0, slightly more false-positives but very few.
210- level2: Also very few false-positives, but contains noisy checks which not everyone agree should be default.
211- level3: Contains checks with high rate of false-positives.
212- manual: Checks here need to be enabled explicitly, as they don't belong to any level. Checks here are very stable and have very few false-positives.
213
214clazy runs all checks from level1 by default.
215
216- Checks from Manual Level:
217 - [container-inside-loop](docs/checks/README-container-inside-loop.md)
218 - [ifndef-define-typo](docs/checks/README-ifndef-define-typo.md)
219 - [inefficient-qlist](docs/checks/README-inefficient-qlist.md)
220 - [isempty-vs-count](docs/checks/README-isempty-vs-count.md)
221 - [qhash-with-char-pointer-key](docs/checks/README-qhash-with-char-pointer-key.md)
222 - [qrequiredresult-candidates](docs/checks/README-qrequiredresult-candidates.md)
223 - [qstring-varargs](docs/checks/README-qstring-varargs.md)
224 - [qt-keywords](docs/checks/README-qt-keywords.md) (fix-qt-keywords)
225 - [qt4-qstring-from-array](docs/checks/README-qt4-qstring-from-array.md) (fix-qt4-qstring-from-array)
226 - [raw-environment-function](docs/checks/README-raw-environment-function.md)
227 - [tr-non-literal](docs/checks/README-tr-non-literal.md)
228
229- Checks from Level 0:
230 - [connect-by-name](docs/checks/README-connect-by-name.md)
231 - [connect-non-signal](docs/checks/README-connect-non-signal.md)
232 - [connect-not-normalized](docs/checks/README-connect-not-normalized.md)
233 - [container-anti-pattern](docs/checks/README-container-anti-pattern.md)
234 - [empty-qstringliteral](docs/checks/README-empty-qstringliteral.md)
235 - [fully-qualified-moc-types](docs/checks/README-fully-qualified-moc-types.md)
236 - [lambda-in-connect](docs/checks/README-lambda-in-connect.md)
237 - [lambda-unique-connection](docs/checks/README-lambda-unique-connection.md)
238 - [lowercase-qml-type-name](docs/checks/README-lowercase-qml-type-name.md)
239 - [mutable-container-key](docs/checks/README-mutable-container-key.md)
240 - [qcolor-from-literal](docs/checks/README-qcolor-from-literal.md)
241 - [qdatetime-utc](docs/checks/README-qdatetime-utc.md) (fix-qdatetime-utc)
242 - [qenums](docs/checks/README-qenums.md)
243 - [qfileinfo-exists](docs/checks/README-qfileinfo-exists.md)
244 - [qgetenv](docs/checks/README-qgetenv.md) (fix-qgetenv)
245 - [qmap-with-pointer-key](docs/checks/README-qmap-with-pointer-key.md)
246 - [qstring-arg](docs/checks/README-qstring-arg.md)
247 - [qstring-insensitive-allocation](docs/checks/README-qstring-insensitive-allocation.md)
248 - [qstring-ref](docs/checks/README-qstring-ref.md) (fix-missing-qstringref)
249 - [qt-macros](docs/checks/README-qt-macros.md)
250 - [qvariant-template-instantiation](docs/checks/README-qvariant-template-instantiation.md)
251 - [strict-iterators](docs/checks/README-strict-iterators.md)
252 - [temporary-iterator](docs/checks/README-temporary-iterator.md)
253 - [unused-non-trivial-variable](docs/checks/README-unused-non-trivial-variable.md)
254 - [writing-to-temporary](docs/checks/README-writing-to-temporary.md)
255 - [wrong-qevent-cast](docs/checks/README-wrong-qevent-cast.md)
256 - [wrong-qglobalstatic](docs/checks/README-wrong-qglobalstatic.md)
257
258- Checks from Level 1:
259 - [auto-unexpected-qstringbuilder](docs/checks/README-auto-unexpected-qstringbuilder.md) (fix-auto-unexpected-qstringbuilder)
260 - [child-event-qobject-cast](docs/checks/README-child-event-qobject-cast.md)
261 - [connect-3arg-lambda](docs/checks/README-connect-3arg-lambda.md)
262 - [const-signal-or-slot](docs/checks/README-const-signal-or-slot.md)
263 - [detaching-temporary](docs/checks/README-detaching-temporary.md)
264 - [foreach](docs/checks/README-foreach.md)
265 - [incorrect-emit](docs/checks/README-incorrect-emit.md)
266 - [inefficient-qlist-soft](docs/checks/README-inefficient-qlist-soft.md)
267 - [install-event-filter](docs/checks/README-install-event-filter.md)
268 - [non-pod-global-static](docs/checks/README-non-pod-global-static.md)
269 - [overridden-signal](docs/checks/README-overridden-signal.md)
270 - [post-event](docs/checks/README-post-event.md)
271 - [qdeleteall](docs/checks/README-qdeleteall.md)
272 - [qhash-namespace](docs/checks/README-qhash-namespace.md)
273 - [qlatin1string-non-ascii](docs/checks/README-qlatin1string-non-ascii.md)
274 - [qproperty-without-notify](docs/checks/README-qproperty-without-notify.md)
275 - [qstring-left](docs/checks/README-qstring-left.md)
276 - [range-loop](docs/checks/README-range-loop.md) (fix-range-loop-add-ref,fix-range-loop-add-qasconst)
277 - [returning-data-from-temporary](docs/checks/README-returning-data-from-temporary.md)
278 - [rule-of-two-soft](docs/checks/README-rule-of-two-soft.md)
279 - [skipped-base-method](docs/checks/README-skipped-base-method.md)
280 - [virtual-signal](docs/checks/README-virtual-signal.md)
281
282- Checks from Level 2:
283 - [base-class-event](docs/checks/README-base-class-event.md)
284 - [copyable-polymorphic](docs/checks/README-copyable-polymorphic.md)
285 - [ctor-missing-parent-argument](docs/checks/README-ctor-missing-parent-argument.md)
286 - [function-args-by-ref](docs/checks/README-function-args-by-ref.md) (fix-function-args-by-ref)
287 - [function-args-by-value](docs/checks/README-function-args-by-value.md)
288 - [global-const-char-pointer](docs/checks/README-global-const-char-pointer.md)
289 - [implicit-casts](docs/checks/README-implicit-casts.md)
290 - [missing-qobject-macro](docs/checks/README-missing-qobject-macro.md)
291 - [missing-typeinfo](docs/checks/README-missing-typeinfo.md)
292 - [old-style-connect](docs/checks/README-old-style-connect.md) (fix-old-style-connect)
293 - [qstring-allocations](docs/checks/README-qstring-allocations.md) (fix-qlatin1string-allocations,fix-fromLatin1_fromUtf8-allocations,fix-fromCharPtrAllocations)
294 - [returning-void-expression](docs/checks/README-returning-void-expression.md)
295 - [rule-of-three](docs/checks/README-rule-of-three.md)
296 - [static-pmf](docs/checks/README-static-pmf.md)
297 - [virtual-call-ctor](docs/checks/README-virtual-call-ctor.md)
298
299- Checks from Level 3:
300 - [assert-with-side-effects](docs/checks/README-assert-with-side-effects.md)
301 - [detaching-member](docs/checks/README-detaching-member.md)
302 - [reserve-candidates](docs/checks/README-reserve-candidates.md)
303 - [thread-with-slots](docs/checks/README-thread-with-slots.md)
304 - [unneeded-cast](docs/checks/README-unneeded-cast.md)
305
306# Selecting which checks to enable
307
308You may want to choose which checks to enable before starting to compile.
309If you don't specify anything then all checks from level0 and level1 will run.
310To specify a list of checks to run, or to choose a level, you can use the `CLAZY_CHECKS` env variable or pass arguments to the compiler.
311You can disable checks by prefixing with `no-`, in case you don't want all checks from a given level.
312
313## Example via env variable
314```
315export CLAZY_CHECKS="unneeded-cast,qmap-with-key-pointer,virtual-call-ctor" # Enables only these 3 checks
316export CLAZY_CHECKS="level0,no-qenums" # Enables all checks from level0, except for qenums
317export CLAZY_CHECKS="level0,detaching-temporary" # Enables all from level0 and also detaching-temporary
318```
319## Example via compiler argument
320`clazy -Xclang -plugin-arg-clazy -Xclang level0,detaching-temporary`
321Don't forget to re-run cmake/qmake/etc if you altered the c++ flags to specify flags.
322
323# clazy-standalone and JSON database support
324
325The `clazy-standalone` binary allows you to run clazy over a compilation database JSON file, in the same
326way you would use `clang-tidy` or other clang tooling. This way you don't need to build your application,
327only the static analysis is performed.
328
329Note: If you're using the AppImage, use `Clazy-x86_64.AppImage --standalone` instead of `clazy-standalone`.
330
331`clazy-standalone` supports the same env variables as the clazy plugin. You can also specify a list of checks via
332the `-checks` argument.
333
334
335Running on one cpp file:
336`clazy-standalone -checks=install-event-filter,qmap-with-pointer-key,level0 -p compile_commands.json my.file.cpp`
337
338Running on all cpp files:
339`find . -name "*cpp" | xargs clazy-standalone -checks=level2 -p default/compile_commands.json`
340
341See https://clang.llvm.org/docs/JSONCompilationDatabase.html for how to generate the compile_commands.json file. Basically it's generated
342by passing `-DCMAKE_EXPORT_COMPILE_COMMANDS` to CMake, or using [Bear](https://github.com/rizsotto/Bear) to intercept compiler commands, or, if you're using `qbs`:
343
344`qbs generate --generator clangdb`
345
346**Note:** Be sure the clazy-standalone binary is located in the same folder as the clang binary, otherwise it will have trouble
347finding builtin headers, like stddef.h. Alternatively, you can symlink to the folder containing the builtin headers:
348
349(Assuming clazy was built with `-DCMAKE_INSTALL_PREFIX=/myprefix/`)
350
351```
352$ touch foo.c && clang++ '-###' -c foo.c 2>&1 | tr ' ' '\n' | grep -A1 resource
353 "-resource-dir"
354 "/usr/bin/../lib/clang/4.0.1" # this is the interesting path (without the version)
355$ ln -sf /usr/bin/../lib/clang/ /myprefix/lib/clang
356$ ln -sf /usr/bin/../include/c++/ /myprefix/include/c++ # Required on macOS
357```
358
359If that doesn't work, run `clang -v` and check what's the InstalledDir. Move clazy-standalone to that folder.
360
361`clang-tidy` support will be added after <https://bugs.llvm.org//show_bug.cgi?id=32739> is fixed.
362
363# Enabling Fixits
364
365Some checks support fixits, in which clazy will re-write your source files whenever it can fix something.
366You can enable a fixit through the env variable, for example:
367`export CLAZY_FIXIT="fix-qlatin1string-allocations"`
368
369Only one fixit can be enabled each time.
370**WARNING**: Backup your code, don't blame me if a fixit is not applied correctly.
371For better results don't use parallel builds, otherwise a fixit being applied in an header file might be done twice.
372
373By default clazy will rewrite your file, but it's suggested that you set the `CLAZY_FIXIT_SUFFIX` env variable to something like
374`_clazy`. This will make clazy generate a new file with the fixes, suffixed with a string of your choice instead of overwriting the original
375one. Otherwise the build would most likely fail due to rewriting code and compiling at the same time.
376
377# Troubleshooting
378
379- clang: symbol lookup error: `/usr/lib/x86_64-linux-gnu/ClazyPlugin.so: undefined symbol: _ZNK5clang15DeclarationName11getAsStringEv`.
380 This is due to mixing ABIs. Your clang/llvm was compiled with the [new gcc c++ ABI][1] but you compiled the clazy plugin with clang (which uses [the old ABI][2]).
381
382 The solution is to build the clazy plugin with gcc or use a distro which hasn't migrated to gcc5 ABI yet, such as archlinux.
383
384[1]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html
385[2]: https://llvm.org/bugs/show_bug.cgi?id=23529
386
387- [Fedora] cmake can't find LLVM ?
388 Try building llvm/clang yourself
389 (There are reports that /usr/share/llvm/cmake/LLVM-Config.cmake is buggy).
390
391- [Fedora] CommandLine Error: `Option 'opt-bisect-limit' registered more than once!`
392 Remove the llvm-static package and use the dynamically linked libraries instead.
393 Alternatively, if you want to use llvm-static, see next item.
394
395- CommandLine Error: `Option 'foo' registered more than once!`
396 Means you're building against a static version of LLVM (*.a files instead of *.so).
397 Try passing to cmake -DLINK_CLAZY_TO_LLVM=OFF when building clazy, this was tested
398 successfully against a static LLVM 7.0, and might work with other versions.
399
400- Some checks are mysteriously not producing warnings or not applying fixits ?
401 Check if you have ccache interfering and turn it off.
402
403- fatal error: 'stddef.h' file not found, while using `clazy-standalone`
404 Be sure the clazy-standalone binary is located in the same folder as the clang binary.
405
406- Be sure to disble pch.
407
408- macOS: Be sure you're not using Apple Clang
409
410- Windows: fatal error LNK1112: module machine type ‘X86’ conflicts with target machine type ‘x64’
411 If you're building in 32-bit, open clazy-cl.bat and insert a -m32 argument.
412 Should read: %~dp0\clang\clang.exe –driver-mode=cl -m32 (...)
413
414# Qt4 compatibility mode
415
416When running on codebases that must still compile with Qt4, you can pass `--qt4compat`
417(a convenience option equivalent to passing `-Xclang -plugin-arg-clazy -Xclang qt4-compat`)
418to disable checks that only make sense with Qt5.
419
420For example, to build a CMake project with Qt4 compatibility use:
421 `CXX="clazy --qt4compat"; cmake .`
422and rebuild.
423
424# Reducing warning noise
425
426If you think you found a false-positive, file a bug report. But do make sure to test first without icecc/distcc enabled.
427
428If you want to suppress warnings from headers of Qt or 3rd party code, include them with `-isystem` instead of `-I` (gcc/clang only).
429For MSVC use `/external`, which is available since VS 15.6.
430
431Alternatively you can set the CLAZY_HEADER_FILTER env variable to a regexp matching the path where you want warnings,
432for example `CLAZY_HEADER_FILTER=.*myapplication.*`.
433
434You can also exclude paths using a regexp by setting CLAZY_IGNORE_DIRS, for example `CLAZY_IGNORE_DIRS=.*my_qt_folder.*`.
435
436You can also suppress individual warnings by file or by line by inserting comments:
437
438- To disable clazy in a specific source file, insert this comment, anywhere in the file:
439`// clazy:skip`
440
441- To disable specific checks in a source file, insert a comment such as
442`// clazy:excludeall=check1,check2`
443
444- To disable specific checks in specific source lines, insert a comment in the same line as the warning:
445`(...) // clazy:exclude=check1,check2`
446
447Don't include the `clazy-` prefix. If, for example, you want to disable qstring-allocations you would write:
448`// clazy:exclude=qstring-allocations` not `clazy-qstring-allocations`.
449
450# Reporting bugs and wishes
451
452- bug tracker: <https://bugs.kde.org/enter_bug.cgi?product=clazy>
453- IRC: #kde-clazy (freenode)
454- E-mail: <smartins at kde.org>
455
456# Authors
457
458- Sérgio Martins
459
460with contributions from:
461
462- Allen Winter
463- Kevin Funk
464- Mathias Hasselmann
465- Laurent Montel
466- Albert Astals Cid
467- Aurélien Gâteau
468- Hannah von Reth
469- Volker Krause
470- Christian Ehrlicher
471
472and thanks to:
473
474- Klarälvdalens Datakonsult AB (<http://www.kdab.com>), for letting me work on clazy as a research project
475
476
477# Contributing patches
478
479New features go to master and bug fixes go to the 1.5 branch.
480The prefered way to contributing is by using KDE's phabricator, see:
481- <https://community.kde.org/Infrastructure/Phabricator>
482- <https://phabricator.kde.org/differential/>
483
484If you rather just create a pull request in https://github.com/KDE/clazy for a drive-by change, it's also fine, but beware that
485the maintainer might forget to check on github and the KDE bot will close the PR. In that case just send a reminder to the maintainer (smartins at kde.org).
486