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