README.md 22.5 KB
Newer Older
Sergio Martins's avatar
Sergio Martins committed
1
clazy v1.7
2 3 4 5 6 7 8 9
===========

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](#source-code)
10
   * [Pre-built binaries](#pre-built-binaries)
Sergio Martins's avatar
Sergio Martins committed
11 12 13 14 15 16 17 18 19 20 21 22 23 24
   * [Build Instructions](#build-instructions)
      * [Linux](#linux)
         * [Install dependencies](#install-dependencies)
         * [Build and install clang](#build-and-install-clang)
         * [Build clazy](#build-clazy)
      * [Windows](#windows)
         * [Build and install clang](#build-and-install-clang-1)
         * [Build clazy](#build-clazy-1)
      * [macOS with MacPorts](#macos-with-macports)
         * [Install clang](#install-clang)
         * [Build clazy](#build-clazy-2)
      * [macOS with Homebrew](#macos-with-homebrew)
         * [Install clang](#install-clang-1)
         * [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 28 29
   * [Selecting which checks to enable](#selecting-which-checks-to-enable)
      * [Example via env variable](#example-via-env-variable)
      * [Example via compiler argument](#example-via-compiler-argument)
30
   * [clazy-standalone and JSON database support](#clazy-standalone-and-json-database-support)
31 32
   * [Enabling Fixits](#enabling-fixits)
   * [Troubleshooting](#troubleshooting)
Sergio Martins's avatar
Sergio Martins committed
33
   * [Qt4 compatibility mode](#qt4-compatibility-mode)
34 35
   * [Reducing warning noise](#reducing-warning-noise)
   * [Reporting bugs and wishes](#reporting-bugs-and-wishes)
36
   * [Authors](#authors)
37 38
   * [Contributing patches](#contributing-patches)

39
# Source Code
Sergio Martins's avatar
Sergio Martins committed
40 41 42

You can get clazy from:

Aurélien Gâteau's avatar
Aurélien Gâteau committed
43
- <https://github.com/KDE/clazy>
44
- <https://invent.kde.org/sdk/clazy>
45

46 47 48
# Pre-built binaries

Pre-built binaries are produced by KDAB, you can get them from https://downloads.kdab.com/clazy/.
49
Currently MSVC2015, MSVC2017 (based on clang-7.0) and Linux AppImage packages (based on clang-8.0) are provided.
50

Sergio Martins's avatar
Sergio Martins committed
51 52
# Build Instructions
## Linux
Sergio Martins's avatar
Sergio Martins committed
53

Sergio Martins's avatar
Sergio Martins committed
54
### Install dependencies
Aurélien Gâteau's avatar
Aurélien Gâteau committed
55
- OpenSUSE tumbleweed: `zypper install cmake git-core llvm llvm-devel llvm-clang llvm-clang-devel`
56 57
- Ubuntu: `apt install g++ cmake clang llvm-dev git-core libclang-dev`
- Archlinux: `pacman -S make llvm clang python2 cmake git gcc`
58
- Fedora: be sure to *remove* the llvm-static package and only install the one with dynamic libraries
59
- Other distros: Check llvm/clang build docs.
Sergio Martins's avatar
Sergio Martins committed
60

Sergio Martins's avatar
Sergio Martins committed
61
### Build and install clang
Sergio Martins's avatar
Sergio Martins committed
62
clang and LLVM >= 5.0 are required.
Sergio Martins's avatar
Sergio Martins committed
63 64 65 66

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


67
```
68
  $ git clone https://github.com/llvm-mirror/llvm.git <some_directory>
Sergio Martins's avatar
Sergio Martins committed
69 70
  $ 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
71
  $ mkdir <some_directory>/build && cd <some_directory>/build
Sergio Martins's avatar
Sergio Martins committed
72 73
  $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DLLVM_TARGETS_TO_BUILD=X86 -DCMAKE_BUILD_TYPE=Release ..
  $ make -jX && make install
74
```
Sergio Martins's avatar
Sergio Martins committed
75

Sergio Martins's avatar
Sergio Martins committed
76
### Build clazy
77
```
78
  $ cd clazy/
79 80
  $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_BUILD_TYPE=Release
  $ make && make install
81
```
82

83
See troubleshooting section if you have problems.
84

Sergio Martins's avatar
Sergio Martins committed
85
## Windows
86

Sergio Martins's avatar
Sergio Martins committed
87
### Build and install clang
88 89
These instructions assume your terminal is suitable for development.
jom and nmake (or ninja), git, cmake, and cl (msvc2015 or later) should be in your PATH.
90

Sergio Martins's avatar
Sergio Martins committed
91
clang and LLVM >= 5.0 are required.
Sergio Martins's avatar
Sergio Martins committed
92 93

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

95
```
96 97
  > git clone https://github.com/llvm-mirror/llvm.git <some_directory>
  > cd <some_directory>\tools\ && git clone https://github.com/llvm-mirror/clang.git
98
  > git checkout release_90
99
  > cd clang
100
  > git checkout release_90
101
  > mkdir <some_directory>\build && cd <some_directory>\build
Sergio Martins's avatar
Sergio Martins committed
102
  > 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" ..
103 104
  > jom
  > nmake install
105
  > Add c:\my_install_folder\llvm\bin\ to PATH
106
```
107

Sergio Martins's avatar
Sergio Martins committed
108
### Build clazy
Sergio Martins's avatar
Sergio Martins committed
109 110 111

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

112
```
113
  > cd clazy\
Sergio Martins's avatar
Sergio Martins committed
114
  > 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"
115
  > jom && nmake install
116
```
117

Sergio Martins's avatar
Sergio Martins committed
118
## macOS with MacPorts
119

120 121
Note: clazy-standalone isn't parsing arguments correctly on LLVM > 8.0. Feel free to use LLVM 10 if you don't need clazy-standalone.

Sergio Martins's avatar
Sergio Martins committed
122
### Install clang
123
```
124 125 126
$ sudo port install llvm-8.0 clang-8.0 cmake ninja coreutils
$ sudo ln -sf /opt/local/bin/llvm-config-mp-8.0 /opt/local/bin/llvm-config
$ sudo port select --set clang mp-clang-8.0
127
```
128

Sergio Martins's avatar
Sergio Martins committed
129
### Build clazy
130 131
```
  $ export CXX=clang++
132 133 134 135 136
  $ cmake
  $ make
  $ make install
```

Sergio Martins's avatar
Sergio Martins committed
137
## macOS with Homebrew
138

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

```
Yurii Kolesnykov's avatar
Yurii Kolesnykov committed
142
$ brew install kde-mac/kde/clazy
143 144 145 146 147
```

for stable branch, or for master:

```
Yurii Kolesnykov's avatar
Yurii Kolesnykov committed
148
$ brew install kde-mac/kde/clazy --HEAD
149 150 151 152
```

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

Sergio Martins's avatar
Sergio Martins committed
153 154
For building yourself, read on. You'll have to install clang and build clazy from source.

Sergio Martins's avatar
Sergio Martins committed
155
### Install clang
156 157 158

```
$ brew install --with-clang llvm
159
```
160

Sergio Martins's avatar
Sergio Martins committed
161
### Build clazy
162
```
Sergio Martins's avatar
Sergio Martins committed
163
  $ export CXX=clang++
164 165
  $ export LLVM_ROOT=/usr/local/opt/llvm
  $ cmake
166 167 168 169
  $ make
  $ make install
```

170
# Setting up your project to build with clazy
171

Martin Delille's avatar
Martin Delille committed
172
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.
173
Note: 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

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

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

Sergio Martins's avatar
Sergio Martins committed
181
If you have multiple versions of clang installed (say clang++-3.8 and clang++-3.9)
182
you can choose which one to use by setting the CLANGXX environment variable, like so:
183
`export CLANGXX=clang++-3.8; clazy`
184

185 186
To build a CMake project use:
 `cmake . -DCMAKE_CXX_COMPILER=clazy`
187 188
and rebuild.

189
To make it the compiler for qmake projects, just run qmake like:
190
`qmake -spec linux-clang QMAKE_CXX="clazy"`
Sergio Martins's avatar
Sergio Martins committed
191

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

Sergio Martins's avatar
Sergio Martins committed
194
Alternatively, 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

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

Sergio Martins's avatar
Sergio Martins committed
199

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

Sergio Martins's avatar
Sergio Martins committed
202 203 204
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.

205
# List of checks
Sergio Martins's avatar
Sergio Martins committed
206 207

There are many checks and they are divided in levels:
208 209 210
- 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.
211
- manual: Checks here need to be enabled explicitly, as they don't belong to any level. They can be very stable or very unstable.
212

213
clazy runs all checks from level1 by default.
214

215
- Checks from Manual Level:
216
    - [assert-with-side-effects](docs/checks/README-assert-with-side-effects.md)
217
    - [container-inside-loop](docs/checks/README-container-inside-loop.md)
218
    - [detaching-member](docs/checks/README-detaching-member.md)
219
    - [heap-allocated-small-trivial-type](docs/checks/README-heap-allocated-small-trivial-type.md)
Sergio Martins's avatar
Sergio Martins committed
220
    - [ifndef-define-typo](docs/checks/README-ifndef-define-typo.md)
221 222
    - [inefficient-qlist](docs/checks/README-inefficient-qlist.md)
    - [isempty-vs-count](docs/checks/README-isempty-vs-count.md)
223
    - [jni-signatures](docs/checks/README-jni-signatures.md)
224
    - [qhash-with-char-pointer-key](docs/checks/README-qhash-with-char-pointer-key.md)
225
    - [qproperty-type-mismatch](docs/checks/README-qproperty-type-mismatch.md)
226
    - [qrequiredresult-candidates](docs/checks/README-qrequiredresult-candidates.md)
227 228 229
    - [qstring-varargs](docs/checks/README-qstring-varargs.md)
    - [qt-keywords](docs/checks/README-qt-keywords.md)    (fix-qt-keywords)
    - [qt4-qstring-from-array](docs/checks/README-qt4-qstring-from-array.md)    (fix-qt4-qstring-from-array)
230
    - [qt6-qlatin1string-to-u](docs/checks/README-qt6-qlatin1string-to-u.md)    (fix-qt6-qlatin1string-to-u)
231
    - [qvariant-template-instantiation](docs/checks/README-qvariant-template-instantiation.md)
232
    - [raw-environment-function](docs/checks/README-raw-environment-function.md)
233
    - [reserve-candidates](docs/checks/README-reserve-candidates.md)
234
    - [signal-with-return-value](docs/checks/README-signal-with-return-value.md)
235
    - [thread-with-slots](docs/checks/README-thread-with-slots.md)
236
    - [tr-non-literal](docs/checks/README-tr-non-literal.md)
237
    - [unneeded-cast](docs/checks/README-unneeded-cast.md)
238 239

- Checks from Level 0:
240 241 242 243
    - [connect-by-name](docs/checks/README-connect-by-name.md)
    - [connect-non-signal](docs/checks/README-connect-non-signal.md)
    - [connect-not-normalized](docs/checks/README-connect-not-normalized.md)
    - [container-anti-pattern](docs/checks/README-container-anti-pattern.md)
244
    - [empty-qstringliteral](docs/checks/README-empty-qstringliteral.md)
245 246 247
    - [fully-qualified-moc-types](docs/checks/README-fully-qualified-moc-types.md)
    - [lambda-in-connect](docs/checks/README-lambda-in-connect.md)
    - [lambda-unique-connection](docs/checks/README-lambda-unique-connection.md)
248
    - [lowercase-qml-type-name](docs/checks/README-lowercase-qml-type-name.md)
249
    - [mutable-container-key](docs/checks/README-mutable-container-key.md)
Sergio Martins's avatar
Sergio Martins committed
250
    - [overloaded-signal](docs/checks/README-overloaded-signal.md)
251 252 253 254 255 256 257
    - [qcolor-from-literal](docs/checks/README-qcolor-from-literal.md)
    - [qdatetime-utc](docs/checks/README-qdatetime-utc.md)    (fix-qdatetime-utc)
    - [qenums](docs/checks/README-qenums.md)
    - [qfileinfo-exists](docs/checks/README-qfileinfo-exists.md)
    - [qgetenv](docs/checks/README-qgetenv.md)    (fix-qgetenv)
    - [qmap-with-pointer-key](docs/checks/README-qmap-with-pointer-key.md)
    - [qstring-arg](docs/checks/README-qstring-arg.md)
258
    - [qstring-comparison-to-implicit-char](docs/checks/README-qstring-comparison-to-implicit-char.md)
259 260 261 262 263 264 265 266 267
    - [qstring-insensitive-allocation](docs/checks/README-qstring-insensitive-allocation.md)
    - [qstring-ref](docs/checks/README-qstring-ref.md)    (fix-missing-qstringref)
    - [qt-macros](docs/checks/README-qt-macros.md)
    - [strict-iterators](docs/checks/README-strict-iterators.md)
    - [temporary-iterator](docs/checks/README-temporary-iterator.md)
    - [unused-non-trivial-variable](docs/checks/README-unused-non-trivial-variable.md)
    - [writing-to-temporary](docs/checks/README-writing-to-temporary.md)
    - [wrong-qevent-cast](docs/checks/README-wrong-qevent-cast.md)
    - [wrong-qglobalstatic](docs/checks/README-wrong-qglobalstatic.md)
268

269
- Checks from Level 1:
270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286
    - [auto-unexpected-qstringbuilder](docs/checks/README-auto-unexpected-qstringbuilder.md)    (fix-auto-unexpected-qstringbuilder)
    - [child-event-qobject-cast](docs/checks/README-child-event-qobject-cast.md)
    - [connect-3arg-lambda](docs/checks/README-connect-3arg-lambda.md)
    - [const-signal-or-slot](docs/checks/README-const-signal-or-slot.md)
    - [detaching-temporary](docs/checks/README-detaching-temporary.md)
    - [foreach](docs/checks/README-foreach.md)
    - [incorrect-emit](docs/checks/README-incorrect-emit.md)
    - [inefficient-qlist-soft](docs/checks/README-inefficient-qlist-soft.md)
    - [install-event-filter](docs/checks/README-install-event-filter.md)
    - [non-pod-global-static](docs/checks/README-non-pod-global-static.md)
    - [overridden-signal](docs/checks/README-overridden-signal.md)
    - [post-event](docs/checks/README-post-event.md)
    - [qdeleteall](docs/checks/README-qdeleteall.md)
    - [qhash-namespace](docs/checks/README-qhash-namespace.md)
    - [qlatin1string-non-ascii](docs/checks/README-qlatin1string-non-ascii.md)
    - [qproperty-without-notify](docs/checks/README-qproperty-without-notify.md)
    - [qstring-left](docs/checks/README-qstring-left.md)
287
    - [range-loop](docs/checks/README-range-loop.md)    (fix-range-loop-add-ref,fix-range-loop-add-qasconst)
288 289 290 291
    - [returning-data-from-temporary](docs/checks/README-returning-data-from-temporary.md)
    - [rule-of-two-soft](docs/checks/README-rule-of-two-soft.md)
    - [skipped-base-method](docs/checks/README-skipped-base-method.md)
    - [virtual-signal](docs/checks/README-virtual-signal.md)
292

293
- Checks from Level 2:
294 295 296
    - [base-class-event](docs/checks/README-base-class-event.md)
    - [copyable-polymorphic](docs/checks/README-copyable-polymorphic.md)
    - [ctor-missing-parent-argument](docs/checks/README-ctor-missing-parent-argument.md)
297
    - [function-args-by-ref](docs/checks/README-function-args-by-ref.md)    (fix-function-args-by-ref)
298 299 300 301 302 303 304 305 306 307 308
    - [function-args-by-value](docs/checks/README-function-args-by-value.md)
    - [global-const-char-pointer](docs/checks/README-global-const-char-pointer.md)
    - [implicit-casts](docs/checks/README-implicit-casts.md)
    - [missing-qobject-macro](docs/checks/README-missing-qobject-macro.md)
    - [missing-typeinfo](docs/checks/README-missing-typeinfo.md)
    - [old-style-connect](docs/checks/README-old-style-connect.md)    (fix-old-style-connect)
    - [qstring-allocations](docs/checks/README-qstring-allocations.md)    (fix-qlatin1string-allocations,fix-fromLatin1_fromUtf8-allocations,fix-fromCharPtrAllocations)
    - [returning-void-expression](docs/checks/README-returning-void-expression.md)
    - [rule-of-three](docs/checks/README-rule-of-three.md)
    - [static-pmf](docs/checks/README-static-pmf.md)
    - [virtual-call-ctor](docs/checks/README-virtual-call-ctor.md)
309

310
# Selecting which checks to enable
311

312
You may want to choose which checks to enable before starting to compile.
313 314
If you don't specify anything then all checks from level0 and level1 will run.
To 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.
315
You can disable checks by prefixing with `no-`, in case you don't want all checks from a given level.
316

Aurélien Gâteau's avatar
Aurélien Gâteau committed
317
## Example via env variable
318
```
Nikolai Kosjar's avatar
Nikolai Kosjar committed
319
export CLAZY_CHECKS="unneeded-cast,qmap-with-pointer-key,virtual-call-ctor" # Enables only these 3 checks
320
export CLAZY_CHECKS="level0,no-qenums" # Enables all checks from level0, except for qenums
321 322
export CLAZY_CHECKS="level0,detaching-temporary" # Enables all from level0 and also detaching-temporary
```
Aurélien Gâteau's avatar
Aurélien Gâteau committed
323
## Example via compiler argument
324
`clazy -Xclang -plugin-arg-clazy -Xclang level0,detaching-temporary`
Sergio Martins's avatar
Sergio Martins committed
325
Don't forget to re-run cmake/qmake/etc if you altered the c++ flags to specify flags.
326

327
# clazy-standalone and JSON database support
328 329 330 331 332

The `clazy-standalone` binary allows you to run clazy over a compilation database JSON file, in the same
way you would use `clang-tidy` or other clang tooling. This way you don't need to build your application,
only the static analysis is performed.

333 334
Note: If you're using the AppImage, use `Clazy-x86_64.AppImage --standalone` instead of `clazy-standalone`.

335 336 337 338
`clazy-standalone` supports the same env variables as the clazy plugin. You can also specify a list of checks via
the `-checks` argument.


339
Running on one cpp file:
340 341
`clazy-standalone -checks=install-event-filter,qmap-with-pointer-key,level0 -p compile_commands.json my.file.cpp`

342
Running on all cpp files:
343 344 345 346 347 348 349
`find . -name "*cpp" | xargs clazy-standalone -checks=level2 -p default/compile_commands.json`

See https://clang.llvm.org/docs/JSONCompilationDatabase.html for how to generate the compile_commands.json file. Basically it's generated
by 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`:

`qbs generate --generator clangdb`

Sergio Martins's avatar
Sergio Martins committed
350
**Note:** Be sure the clazy-standalone binary is located in the same folder as the clang binary, otherwise it will have trouble
351 352 353 354
finding builtin headers, like stddef.h. Alternatively, you can symlink to the folder containing the builtin headers:

(Assuming clazy was built with `-DCMAKE_INSTALL_PREFIX=/myprefix/`)

Sergio Martins's avatar
Sergio Martins committed
355
```
356
$ touch foo.c && clang++ '-###' -c foo.c 2>&1 | tr ' ' '\n' | grep -A1 resource # Make sure this clang here is not Apple clang. Use for example clang++-mp-8.0 if on macOS and haven't run `port select` yet.
Sergio Martins's avatar
Sergio Martins committed
357
  "-resource-dir"
358 359 360 361
  "/opt/local/libexec/llvm-8.0/lib/clang/8.0.1" # The interesting part is /opt/local/libexec/llvm-8.0
$ ln -sf /opt/local/libexec/llvm-8.0/lib/clang/ /myprefix/lib/clang
$ mkdir /myprefix/include/
$ ln -sf /opt/local/libexec/llvm-8.0/include/c++/ /myprefix/include/c++ # Required on macOS
Sergio Martins's avatar
Sergio Martins committed
362
```
363

364 365
If that doesn't work, run `clang -v` and check what's the InstalledDir. Move clazy-standalone to that folder.

366 367
`clang-tidy` support will be added after <https://bugs.llvm.org//show_bug.cgi?id=32739> is fixed.

368
# Enabling Fixits
369

Sergio Martins's avatar
Sergio Martins committed
370 371
Some checks support fixits, in which clazy will help re-write your source files whenever it can fix something.
Simply pass `-Xclang -plugin-arg-clazy -Xclang export-fixes` to clang, or `-export-fixes=somefile.yaml` for `clazy-standalone`.
372
Alternatively, set the `CLAZY_EXPORT_FIXES` env variable (works only with the plugin, not with standalone).
Sergio Martins's avatar
Sergio Martins committed
373
Then run `clang-apply-replacements <folder_with_yaml_files>`, which will modify your code.
374

Sergio Martins's avatar
Sergio Martins committed
375 376 377
When using fixits, prefer to run only a single check each time, so they don't conflict
with each other modifying the same source lines.

Sergio Martins's avatar
Sergio Martins committed
378
**WARNING**: Backup your code and make sure all changes done by clazy are correct.
379

380
# Troubleshooting
381

382
- clang: symbol lookup error: `/usr/lib/x86_64-linux-gnu/ClazyPlugin.so: undefined symbol: _ZNK5clang15DeclarationName11getAsStringEv`.
Aurélien Gâteau's avatar
Aurélien Gâteau committed
383
  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]).
384 385 386

  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.

Aurélien Gâteau's avatar
Aurélien Gâteau committed
387 388
[1]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html
[2]: https://llvm.org/bugs/show_bug.cgi?id=23529
389

390 391
- [Fedora] cmake can't find LLVM ?
  Try building llvm/clang yourself
392
  (There are reports that /usr/share/llvm/cmake/LLVM-Config.cmake is buggy).
393

394
- [Fedora] CommandLine Error: `Option 'opt-bisect-limit' registered more than once!`
395 396 397 398 399 400 401
  Remove the llvm-static package and use the dynamically linked libraries instead.
  Alternatively, if you want to use llvm-static, see next item.

- CommandLine Error: `Option 'foo' registered more than once!`
  Means you're building against a static version of LLVM (*.a files instead of *.so).
  Try passing to cmake -DLINK_CLAZY_TO_LLVM=OFF when building clazy, this was tested
  successfully against a static LLVM 7.0, and might work with other versions.
402

Aurélien Gâteau's avatar
Aurélien Gâteau committed
403
- Some checks are mysteriously not producing warnings or not applying fixits ?
404
  Check if you have ccache interfering and turn it off.
405

406 407 408
- fatal error: 'stddef.h' file not found, while using `clazy-standalone`
  Be sure the clazy-standalone binary is located in the same folder as the clang binary.

David Faure's avatar
David Faure committed
409
- Be sure to disable pch.
Sergio Martins's avatar
Sergio Martins committed
410 411 412

- macOS: Be sure you're not using Apple Clang

413 414 415
- macOS: System Integrity Protection blocks the use of DYLD_LIBRARY_PATH. With SIP enabled you need to pass the full path
  to ClazyPlugin.dylib, otherwise you'll get `image not found` error.

416 417 418 419
- Windows: fatal error LNK1112: module machine type ‘X86’ conflicts with target machine type ‘x64’
  If you're building in 32-bit, open clazy-cl.bat and insert a -m32 argument.
  Should read: %~dp0\clang\clang.exe –driver-mode=cl -m32 (...)

Sergio Martins's avatar
Sergio Martins committed
420 421
# Qt4 compatibility mode

422
When running on codebases that must still compile with Qt4, you can pass `--qt4compat`
423
(a convenience option equivalent to passing `-Xclang -plugin-arg-clazy -Xclang qt4-compat`)
Sergio Martins's avatar
Sergio Martins committed
424 425
to disable checks that only make sense with Qt5.

426 427 428 429
For example, to build a CMake project with Qt4 compatibility use:
 `CXX="clazy --qt4compat"; cmake .`
and rebuild.

430
# Reducing warning noise
431

432
If you think you found a false-positive, file a bug report. But do make sure to test first without icecc/distcc enabled.
433

434 435
If you want to suppress warnings from headers of Qt or 3rd party code, include them with `-isystem` instead of `-I` (gcc/clang only).
For MSVC use `/external`, which is available since VS 15.6.
436

437 438 439 440
Alternatively you can set the CLAZY_HEADER_FILTER env variable to a regexp matching the path where you want warnings,
for example `CLAZY_HEADER_FILTER=.*myapplication.*`.

You can also exclude paths using a regexp by setting CLAZY_IGNORE_DIRS, for example `CLAZY_IGNORE_DIRS=.*my_qt_folder.*`.
441

442 443 444
You can also suppress individual warnings by file or by line by inserting comments:

- To disable clazy in a specific source file, insert this comment, anywhere in the file:
445
`// clazy:skip`
446

447
- To disable specific checks in a source file, insert a comment such as
448
`// clazy:excludeall=check1,check2`
449

450
- To disable specific checks in specific source lines, insert a comment in the same line as the warning:
451
`(...) // clazy:exclude=check1,check2`
452

Aurélien Gâteau's avatar
Aurélien Gâteau committed
453 454
Don't include the `clazy-` prefix. If, for example, you want to disable qstring-allocations you would write:
`// clazy:exclude=qstring-allocations` not `clazy-qstring-allocations`.
455

456
# Reporting bugs and wishes
Sergio Martins's avatar
Sergio Martins committed
457

Aurélien Gâteau's avatar
Aurélien Gâteau committed
458
- bug tracker: <https://bugs.kde.org/enter_bug.cgi?product=clazy>
459
- IRC: #kde-clazy (freenode)
460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476
- E-mail: <smartins at kde.org>

# Authors

- Sérgio Martins

with contributions from:

- Allen Winter
- Kevin Funk
- Mathias Hasselmann
- Laurent Montel
- Albert Astals Cid
- Aurélien Gâteau
- Hannah von Reth
- Volker Krause
- Christian Ehrlicher
Sergio Martins's avatar
Sergio Martins committed
477
- Christian Gagneraud
478
- Nikolai Kosjar
479 480 481 482 483

and thanks to:

- Klarälvdalens Datakonsult AB (<http://www.kdab.com>), for letting me work on clazy as a research project

Sergio Martins's avatar
Sergio Martins committed
484

485
# Contributing patches
Sergio Martins's avatar
Sergio Martins committed
486

487
New features go to master and bug fixes go to the 1.7 branch.
488 489
The prefered way to contributing is by using KDE's GitLab instance,
see <https://community.kde.org/Infrastructure/GitLab>.
490 491

If 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
Sergio Martins's avatar
Sergio Martins committed
492
the 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).