| 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 2.7, 3.2, 3.3, 3.4, 3.5). |
|---|
| 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 |
|---|
| 147 | |
|---|