README.md 24.3 KB
Newer Older
Sergio Martins's avatar
Sergio Martins committed
1
2
3
*WARNING:* master is the development branch. Please use the v1.10 branch.

clazy v1.11
4
5
6
7
8
9
10
11
===========

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)
12
   * [Pre-built binaries](#pre-built-binaries)
Sergio Martins's avatar
Sergio Martins committed
13
14
15
16
17
18
19
   * [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)
Sergio Martins's avatar
Sergio Martins committed
20
21
         * [Build clazy](#build-clazy-1)
      * [macOS with MacPorts](#macos-with-macports)
Sergio Martins's avatar
Sergio Martins committed
22
23
24
25
26
         * [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)
27
   * [Setting up your project to build with clazy](#setting-up-your-project-to-build-with-clazy)
28
   * [List of checks](#list-of-checks)
29
30
31
   * [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)
32
   * [clazy-standalone and JSON database support](#clazy-standalone-and-json-database-support)
33
34
   * [Enabling Fixits](#enabling-fixits)
   * [Troubleshooting](#troubleshooting)
Sergio Martins's avatar
Sergio Martins committed
35
   * [Qt4 compatibility mode](#qt4-compatibility-mode)
36
37
   * [Reducing warning noise](#reducing-warning-noise)
   * [Reporting bugs and wishes](#reporting-bugs-and-wishes)
38
   * [Authors](#authors)
39
40
   * [Contributing patches](#contributing-patches)

41
# Source Code
Sergio Martins's avatar
Sergio Martins committed
42
43
44

You can get clazy from:

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

48
49
50
51
52
53
54

# Supported platforms

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


55
56
# Pre-built binaries

57
Pre-built clazy binaries for MSVC and Linux AppImage are produced by KDAB, you can get them from https://downloads.kdab.com/clazy/.
58

Sergio Martins's avatar
Sergio Martins committed
59
60
# Build Instructions
## Linux
Sergio Martins's avatar
Sergio Martins committed
61

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

Sergio Martins's avatar
Sergio Martins committed
69
### Build and install clang
70
clang and LLVM >= 8.0 are required.
Sergio Martins's avatar
Sergio Martins committed
71
72
73
74

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


75
```
76
  $ git clone https://github.com/llvm-mirror/llvm.git <some_directory>
Sergio Martins's avatar
Sergio Martins committed
77
78
  $ 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
79
  $ mkdir <some_directory>/build && cd <some_directory>/build
80
81
82
  $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DLLVM_TARGETS_TO_BUILD=X86 -DCMAKE_BUILD_TYPE=Release -G Ninja ..
  $ cmake --build .
  $ cmake --build . --target install
83
```
Sergio Martins's avatar
Sergio Martins committed
84

Sergio Martins's avatar
Sergio Martins committed
85
### Build clazy
86
```
87
  $ cd clazy/
88
89
90
  $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_BUILD_TYPE=Release -G Ninja
  $ cmake --build .
  $ cmake --build . --target install
91
```
92

93
See troubleshooting section if you have problems.
94

Sergio Martins's avatar
Sergio Martins committed
95
## Windows
96

Sergio Martins's avatar
Sergio Martins committed
97
### Build and install clang
98
These instructions assume your terminal is suitable for development.
99
Ninja (or equivalent), git, cmake, and cl (msvc2019) should be in your PATH.
100

101
clang and LLVM >= 9.0 are required.
Sergio Martins's avatar
Sergio Martins committed
102
103

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

105
```
106
  > git clone https://github.com/llvm/llvm-project.git -b llvmorg-11.0.0 <some_directory>
107
108
  > mkdir build # Important that this is outside of the source directory
  > cd build
109
  > 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
110
111
  > cmake --build .
  > cmake --build . --target install
112
  > Add c:\my_install_folder\llvm\bin\ to PATH
113
```
114

115
116
117
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.

Sergio Martins's avatar
Sergio Martins committed
118
### Build clazy
Sergio Martins's avatar
Sergio Martins committed
119
120
121

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

122
```
123
  > cd clazy\
124
125
126
  > 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
127
```
128

Sergio Martins's avatar
Sergio Martins committed
129
## macOS with MacPorts
130

Sergio Martins's avatar
Sergio Martins committed
131
### Install clang
132
```
133
134
135
$ 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
136
```
137

Sergio Martins's avatar
Sergio Martins committed
138
### Build clazy
139
140
```
  $ export CXX=clang++
141
142
143
  $ cmake -G Ninja
  $ cmake --build .
  $ cmake --build . --target install
144
145
```

Sergio Martins's avatar
Sergio Martins committed
146
## macOS with Homebrew
147

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

```
Yurii Kolesnykov's avatar
Yurii Kolesnykov committed
151
$ brew install kde-mac/kde/clazy
152
153
154
155
156
```

for stable branch, or for master:

```
Yurii Kolesnykov's avatar
Yurii Kolesnykov committed
157
$ brew install kde-mac/kde/clazy --HEAD
158
159
160
161
```

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
162
163
For building yourself, read on. You'll have to install clang and build clazy from source.

Sergio Martins's avatar
Sergio Martins committed
164
### Install clang
165
166
167

```
$ brew install --with-clang llvm
168
```
169

Sergio Martins's avatar
Sergio Martins committed
170
### Build clazy
171
```
Sergio Martins's avatar
Sergio Martins committed
172
  $ export CXX=clang++
173
  $ export LLVM_ROOT=/usr/local/opt/llvm
174
175
176
  $ cmake -G Ninja
  $ cmake --build .
  $ cmake --build . --target install
177
178
```

179
# Setting up your project to build with clazy
180

Martin Delille's avatar
Martin Delille committed
181
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.
182
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).
183

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

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

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

194
195
To build a CMake project use:
 `cmake . -DCMAKE_CXX_COMPILER=clazy`
196
197
and rebuild.

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

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

Sergio Martins's avatar
Sergio Martins committed
203
Alternatively, if you want to use clang directly, without the wrapper:
204
`qmake -spec linux-clang QMAKE_CXXFLAGS="-Xclang -load -Xclang ClazyPlugin.so -Xclang -add-plugin -Xclang clazy"`
205

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

Sergio Martins's avatar
Sergio Martins committed
208

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

Sergio Martins's avatar
Sergio Martins committed
211
212
213
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.

214
# List of checks
Sergio Martins's avatar
Sergio Martins committed
215
216

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

222
clazy runs all checks from level1 by default.
223

224
- Checks from Manual Level:
225
    - [assert-with-side-effects](docs/checks/README-assert-with-side-effects.md)
226
    - [container-inside-loop](docs/checks/README-container-inside-loop.md)
227
    - [detaching-member](docs/checks/README-detaching-member.md)
228
    - [heap-allocated-small-trivial-type](docs/checks/README-heap-allocated-small-trivial-type.md)
Sergio Martins's avatar
Sergio Martins committed
229
    - [ifndef-define-typo](docs/checks/README-ifndef-define-typo.md)
230
    - [isempty-vs-count](docs/checks/README-isempty-vs-count.md)
231
    - [jni-signatures](docs/checks/README-jni-signatures.md)
232
    - [qhash-with-char-pointer-key](docs/checks/README-qhash-with-char-pointer-key.md)
233
    - [qproperty-type-mismatch](docs/checks/README-qproperty-type-mismatch.md)
234
    - [qrequiredresult-candidates](docs/checks/README-qrequiredresult-candidates.md)
235
236
237
    - [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)
238
    - [qt6-deprecated-api-fixes](docs/checks/README-qt6-deprecated-api-fixes.md)    (fix-qt6-deprecated-api-fixes)
239
    - [qt6-fwd-fixes](docs/checks/README-qt6-fwd-fixes.md)    (fix-qt6-fwd-fixes)
240
    - [qt6-header-fixes](docs/checks/README-qt6-header-fixes.md)    (fix-qt6-header-fixes)
241
    - [qt6-qhash-signature](docs/checks/README-qt6-qhash-signature.md)    (fix-qt6-qhash-signature)
242
    - [qt6-qlatin1stringchar-to-u](docs/checks/README-qt6-qlatin1stringchar-to-u.md)    (fix-qt6-qlatin1stringchar-to-u)
243
    - [qvariant-template-instantiation](docs/checks/README-qvariant-template-instantiation.md)
244
    - [raw-environment-function](docs/checks/README-raw-environment-function.md)
245
    - [reserve-candidates](docs/checks/README-reserve-candidates.md)
246
    - [signal-with-return-value](docs/checks/README-signal-with-return-value.md)
247
    - [thread-with-slots](docs/checks/README-thread-with-slots.md)
248
    - [tr-non-literal](docs/checks/README-tr-non-literal.md)
249
    - [unexpected-flag-enumerator-value](docs/checks/README-unexpected-flag-enumerator-value.md)
250
    - [unneeded-cast](docs/checks/README-unneeded-cast.md)
251
    - [use-arrow-operator-instead-of-data](docs/checks/README-use-arrow-operator-instead-of-data.md)
252
    - [use-chrono-in-qtimer](docs/checks/README-use-chrono-in-qtimer.md)
253
254

- Checks from Level 0:
255
256
257
258
    - [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)
259
    - [empty-qstringliteral](docs/checks/README-empty-qstringliteral.md)
260
261
262
    - [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)
263
    - [lowercase-qml-type-name](docs/checks/README-lowercase-qml-type-name.md)
264
    - [mutable-container-key](docs/checks/README-mutable-container-key.md)
Sergio Martins's avatar
Sergio Martins committed
265
    - [overloaded-signal](docs/checks/README-overloaded-signal.md)
266
267
268
269
270
271
272
    - [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)
273
    - [qstring-comparison-to-implicit-char](docs/checks/README-qstring-comparison-to-implicit-char.md)
274
275
276
277
278
279
    - [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)
280
    - [use-static-qregularexpression](docs/checks/README-use-static-qregularexpression.md)
281
282
283
    - [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)
284

285
- Checks from Level 1:
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
    - [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)
    - [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)
302
303
    - [range-loop-detach](docs/checks/README-range-loop-detach.md)    (fix-range-loop-add-qasconst)
    - [range-loop-reference](docs/checks/README-range-loop-reference.md)    (fix-range-loop-add-ref)
304
305
306
307
    - [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)
308

309
- Checks from Level 2:
310
311
312
    - [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)
313
    - [function-args-by-ref](docs/checks/README-function-args-by-ref.md)    (fix-function-args-by-ref)
314
315
316
    - [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)
317
    - [missing-qobject-macro](docs/checks/README-missing-qobject-macro.md)    (fix-missing-qobject-macro)
318
319
320
321
322
323
324
    - [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)
325

326
# Selecting which checks to enable
327

328
You may want to choose which checks to enable before starting to compile.
329
330
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.
331
You can disable checks by prefixing with `no-`, in case you don't want all checks from a given level.
332

Aurélien Gâteau's avatar
Aurélien Gâteau committed
333
## Example via env variable
334
```
Nikolai Kosjar's avatar
Nikolai Kosjar committed
335
export CLAZY_CHECKS="unneeded-cast,qmap-with-pointer-key,virtual-call-ctor" # Enables only these 3 checks
336
export CLAZY_CHECKS="level0,no-qenums" # Enables all checks from level0, except for qenums
337
338
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
339
## Example via compiler argument
340
`clazy -Xclang -plugin-arg-clazy -Xclang level0,detaching-temporary`
Sergio Martins's avatar
Sergio Martins committed
341
Don't forget to re-run cmake/qmake/etc if you altered the c++ flags to specify flags.
342

343
# clazy-standalone and JSON database support
344
345
346
347
348

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.

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

351
352
353
354
`clazy-standalone` supports the same env variables as the clazy plugin. You can also specify a list of checks via
the `-checks` argument.


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

358
Running on all cpp files:
359
360
361
362
363
364
365
`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
366
**Note:** Be sure the clazy-standalone binary is located in the same folder as the clang binary, otherwise it will have trouble
367
368
369
370
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
371
```
372
$ 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
373
  "-resource-dir"
374
375
376
377
  "/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
378
```
379

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

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

384
# Enabling Fixits
385

Sergio Martins's avatar
Sergio Martins committed
386
387
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`.
388
Alternatively, set the `CLAZY_EXPORT_FIXES` env variable (works only with the plugin, not with standalone).
Sergio Martins's avatar
Sergio Martins committed
389
Then run `clang-apply-replacements <folder_with_yaml_files>`, which will modify your code.
390

Sergio Martins's avatar
Sergio Martins committed
391
392
393
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
394
**WARNING**: Backup your code and make sure all changes done by clazy are correct.
395

396
# Troubleshooting
397

398
- 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
399
  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]).
400
401
402

  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
403
404
[1]: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html
[2]: https://llvm.org/bugs/show_bug.cgi?id=23529
405

406
407
- [Fedora] cmake can't find LLVM ?
  Try building llvm/clang yourself
408
  (There are reports that /usr/share/llvm/cmake/LLVM-Config.cmake is buggy).
409

410
- [Fedora] CommandLine Error: `Option 'opt-bisect-limit' registered more than once!`
411
412
413
414
415
416
417
  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.
418

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

422
423
424
- 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
425
- Be sure to disable pch.
Sergio Martins's avatar
Sergio Martins committed
426
427
428

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

429
430
431
- 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.

432
433
434
435
- 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
436
437
# Qt4 compatibility mode

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

442
443
444
445
For example, to build a CMake project with Qt4 compatibility use:
 `CXX="clazy --qt4compat"; cmake .`
and rebuild.

446
# Reducing warning noise
447

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

450
451
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.
452

453
454
455
456
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.*`.
457

458
459
460
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:
461
`// clazy:skip`
462

463
- To disable specific checks in a source file, insert a comment such as
464
`// clazy:excludeall=check1,check2`
465

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

Aurélien Gâteau's avatar
Aurélien Gâteau committed
469
470
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`.
471

472
# Reporting bugs and wishes
Sergio Martins's avatar
Sergio Martins committed
473

Aurélien Gâteau's avatar
Aurélien Gâteau committed
474
- bug tracker: <https://bugs.kde.org/enter_bug.cgi?product=clazy>
475
- IRC: #kde-clazy (irc.libera.chat)
476
477
- E-mail: <smartins at kde.org>

478
479
480
481
482
483
When reporting a bug *please* include a minimal compilable testcase. No matter
how simple it is, it saves me time from deciphering a bug report. Time spent
doing triaging is time not spent writing fixes.

A minimal testcase is also something I can copy to the test suite.

484
485
Make sure you can reproduce with clazy (outside of QtCreator), otherwise it can be a QtCreator bug instead,
which you can report at <https://bugreports.qt.io/>.
486
487


488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
# 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
503
- Christian Gagneraud
504
- Nikolai Kosjar
505
- Jesper K. Pedersen
506
- Lucie Gerard
507
- Christian Schärf
508
- Waqar Ahmed
509
510

qt6-* porting checks written by Lucie Gerard <lucie.gerard@qt.io>
511
512
513
514
515

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
516

517
# Contributing patches
Sergio Martins's avatar
Sergio Martins committed
518

519
New features go to master and bug fixes go to the 1.10 branch.
520
521
The prefered way to contributing is by using KDE's GitLab instance,
see <https://community.kde.org/Infrastructure/GitLab>.
522
523

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
524
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).