| 1 |
scan-build |
| 2 |
========== |
| 3 |
|
| 4 |
A package designed to wrap a build so that all calls to gcc/clang are |
| 5 |
intercepted and logged into a [compilation database][1] and/or piped to |
| 6 |
the clang static analyzer. Includes intercept-build tool, which logs |
| 7 |
the build, as well as scan-build tool, which logs the build and runs |
| 8 |
the clang static analyzer on it. |
| 9 |
|
| 10 |
Portability |
| 11 |
----------- |
| 12 |
|
| 13 |
Should be working on UNIX operating systems. |
| 14 |
|
| 15 |
- It has been tested on FreeBSD, GNU/Linux and OS X. |
| 16 |
- Prepared to work on windows, but need help to make it. |
| 17 |
|
| 18 |
|
| 19 |
Prerequisites |
| 20 |
------------- |
| 21 |
|
| 22 |
1. **python** interpreter (version 3.6 or later). |
| 23 |
|
| 24 |
|
| 25 |
How to use |
| 26 |
---------- |
| 27 |
|
| 28 |
To run the Clang static analyzer against a project goes like this: |
| 29 |
|
| 30 |
$ scan-build <your build command> |
| 31 |
|
| 32 |
To generate a compilation database file goes like this: |
| 33 |
|
| 34 |
$ intercept-build <your build command> |
| 35 |
|
| 36 |
To run the Clang static analyzer against a project with compilation database |
| 37 |
goes like this: |
| 38 |
|
| 39 |
$ analyze-build |
| 40 |
|
| 41 |
Use `--help` to know more about the commands. |
| 42 |
|
| 43 |
|
| 44 |
How to use the experimental Cross Translation Unit analysis |
| 45 |
----------------------------------------------------------- |
| 46 |
|
| 47 |
To run the CTU analysis, a compilation database file has to be created: |
| 48 |
|
| 49 |
$ intercept-build <your build command> |
| 50 |
|
| 51 |
To run the Clang Static Analyzer against a compilation database |
| 52 |
with CTU analysis enabled, execute: |
| 53 |
|
| 54 |
$ analyze-build --ctu |
| 55 |
|
| 56 |
For CTU analysis an additional (external definition) collection-phase is required. |
| 57 |
For debugging purposes, it is possible to separately execute the collection |
| 58 |
and the analysis phase. By doing this, the intermediate files used for |
| 59 |
the analysis are kept on the disk in `./ctu-dir`. |
| 60 |
|
| 61 |
# Collect and store the data required by the CTU analysis |
| 62 |
$ analyze-build --ctu-collect-only |
| 63 |
|
| 64 |
# Analyze using the previously collected data |
| 65 |
$ analyze-build --ctu-analyze-only |
| 66 |
|
| 67 |
Use `--help` to get more information about the commands. |
| 68 |
|
| 69 |
|
| 70 |
Limitations |
| 71 |
----------- |
| 72 |
|
| 73 |
Generally speaking, the `intercept-build` and `analyze-build` tools together |
| 74 |
does the same job as `scan-build` does. So, you can expect the same output |
| 75 |
from this line as simple `scan-build` would do: |
| 76 |
|
| 77 |
$ intercept-build <your build command> && analyze-build |
| 78 |
|
| 79 |
The major difference is how and when the analyzer is run. The `scan-build` |
| 80 |
tool has three distinct model to run the analyzer: |
| 81 |
|
| 82 |
1. Use compiler wrappers to make actions. |
| 83 |
The compiler wrappers does run the real compiler and the analyzer. |
| 84 |
This is the default behaviour, can be enforced with `--override-compiler` |
| 85 |
flag. |
| 86 |
|
| 87 |
2. Use special library to intercept compiler calls during the build process. |
| 88 |
The analyzer run against each modules after the build finished. |
| 89 |
Use `--intercept-first` flag to get this model. |
| 90 |
|
| 91 |
3. Use compiler wrappers to intercept compiler calls during the build process. |
| 92 |
The analyzer run against each modules after the build finished. |
| 93 |
Use `--intercept-first` and `--override-compiler` flags together to get |
| 94 |
this model. |
| 95 |
|
| 96 |
The 1. and 3. are using compiler wrappers, which works only if the build |
| 97 |
process respects the `CC` and `CXX` environment variables. (Some build |
| 98 |
process can override these variable as command line parameter only. This case |
| 99 |
you need to pass the compiler wrappers manually. eg.: `intercept-build |
| 100 |
--override-compiler make CC=intercept-cc CXX=intercept-c++ all` where the |
| 101 |
original build command would have been `make all` only.) |
| 102 |
|
| 103 |
The 1. runs the analyzer right after the real compilation. So, if the build |
| 104 |
process removes removes intermediate modules (generated sources) the analyzer |
| 105 |
output still kept. |
| 106 |
|
| 107 |
The 2. and 3. generate the compilation database first, and filters out those |
| 108 |
modules which are not exists. So, it's suitable for incremental analysis during |
| 109 |
the development. |
| 110 |
|
| 111 |
The 2. mode is available only on FreeBSD and Linux. Where library preload |
| 112 |
is available from the dynamic loader. Not supported on OS X (unless System |
| 113 |
Integrity Protection feature is turned off). |
| 114 |
|
| 115 |
`intercept-build` command uses only the 2. and 3. mode to generate the |
| 116 |
compilation database. `analyze-build` does only run the analyzer against the |
| 117 |
captured compiler calls. |
| 118 |
|
| 119 |
|
| 120 |
Known problems |
| 121 |
-------------- |
| 122 |
|
| 123 |
Because it uses `LD_PRELOAD` or `DYLD_INSERT_LIBRARIES` environment variables, |
| 124 |
it does not append to it, but overrides it. So builds which are using these |
| 125 |
variables might not work. (I don't know any build tool which does that, but |
| 126 |
please let me know if you do.) |
| 127 |
|
| 128 |
|
| 129 |
Problem reports |
| 130 |
--------------- |
| 131 |
|
| 132 |
If you find a bug in this documentation or elsewhere in the program or would |
| 133 |
like to propose an improvement, please use the project's [issue tracker][3]. |
| 134 |
Please describing the bug and where you found it. If you have a suggestion |
| 135 |
how to fix it, include that as well. Patches are also welcome. |
| 136 |
|
| 137 |
|
| 138 |
License |
| 139 |
------- |
| 140 |
|
| 141 |
The project is licensed under Apache-2.0 with LLVM exceptions. |
| 142 |
See LICENSE.TXT for details. |
| 143 |
|
| 144 |
[1]: http://clang.llvm.org/docs/JSONCompilationDatabase.html |
| 145 |
[2]: https://pypi.python.org/pypi/scan-build |
| 146 |
[3]: https://llvm.org/bugs/enter_bug.cgi?product=clang |