106f32e7eSjoergscan-build 206f32e7eSjoerg========== 306f32e7eSjoerg 406f32e7eSjoergA package designed to wrap a build so that all calls to gcc/clang are 506f32e7eSjoergintercepted and logged into a [compilation database][1] and/or piped to 606f32e7eSjoergthe clang static analyzer. Includes intercept-build tool, which logs 706f32e7eSjoergthe build, as well as scan-build tool, which logs the build and runs 806f32e7eSjoergthe clang static analyzer on it. 906f32e7eSjoerg 1006f32e7eSjoergPortability 1106f32e7eSjoerg----------- 1206f32e7eSjoerg 1306f32e7eSjoergShould be working on UNIX operating systems. 1406f32e7eSjoerg 1506f32e7eSjoerg- It has been tested on FreeBSD, GNU/Linux and OS X. 1606f32e7eSjoerg- Prepared to work on windows, but need help to make it. 1706f32e7eSjoerg 1806f32e7eSjoerg 1906f32e7eSjoergPrerequisites 2006f32e7eSjoerg------------- 2106f32e7eSjoerg 22*13fbcb42Sjoerg1. **python** interpreter (version 3.6 or later). 2306f32e7eSjoerg 2406f32e7eSjoerg 2506f32e7eSjoergHow to use 2606f32e7eSjoerg---------- 2706f32e7eSjoerg 2806f32e7eSjoergTo run the Clang static analyzer against a project goes like this: 2906f32e7eSjoerg 3006f32e7eSjoerg $ scan-build <your build command> 3106f32e7eSjoerg 3206f32e7eSjoergTo generate a compilation database file goes like this: 3306f32e7eSjoerg 3406f32e7eSjoerg $ intercept-build <your build command> 3506f32e7eSjoerg 3606f32e7eSjoergTo run the Clang static analyzer against a project with compilation database 3706f32e7eSjoerggoes like this: 3806f32e7eSjoerg 3906f32e7eSjoerg $ analyze-build 4006f32e7eSjoerg 4106f32e7eSjoergUse `--help` to know more about the commands. 4206f32e7eSjoerg 4306f32e7eSjoerg 4406f32e7eSjoergHow to use the experimental Cross Translation Unit analysis 4506f32e7eSjoerg----------------------------------------------------------- 4606f32e7eSjoerg 4706f32e7eSjoergTo run the CTU analysis, a compilation database file has to be created: 4806f32e7eSjoerg 4906f32e7eSjoerg $ intercept-build <your build command> 5006f32e7eSjoerg 5106f32e7eSjoergTo run the Clang Static Analyzer against a compilation database 5206f32e7eSjoergwith CTU analysis enabled, execute: 5306f32e7eSjoerg 5406f32e7eSjoerg $ analyze-build --ctu 5506f32e7eSjoerg 5606f32e7eSjoergFor CTU analysis an additional (external definition) collection-phase is required. 5706f32e7eSjoergFor debugging purposes, it is possible to separately execute the collection 5806f32e7eSjoergand the analysis phase. By doing this, the intermediate files used for 5906f32e7eSjoergthe analysis are kept on the disk in `./ctu-dir`. 6006f32e7eSjoerg 6106f32e7eSjoerg # Collect and store the data required by the CTU analysis 6206f32e7eSjoerg $ analyze-build --ctu-collect-only 6306f32e7eSjoerg 6406f32e7eSjoerg # Analyze using the previously collected data 6506f32e7eSjoerg $ analyze-build --ctu-analyze-only 6606f32e7eSjoerg 6706f32e7eSjoergUse `--help` to get more information about the commands. 6806f32e7eSjoerg 6906f32e7eSjoerg 7006f32e7eSjoergLimitations 7106f32e7eSjoerg----------- 7206f32e7eSjoerg 7306f32e7eSjoergGenerally speaking, the `intercept-build` and `analyze-build` tools together 7406f32e7eSjoergdoes the same job as `scan-build` does. So, you can expect the same output 7506f32e7eSjoergfrom this line as simple `scan-build` would do: 7606f32e7eSjoerg 7706f32e7eSjoerg $ intercept-build <your build command> && analyze-build 7806f32e7eSjoerg 7906f32e7eSjoergThe major difference is how and when the analyzer is run. The `scan-build` 8006f32e7eSjoergtool has three distinct model to run the analyzer: 8106f32e7eSjoerg 8206f32e7eSjoerg1. Use compiler wrappers to make actions. 8306f32e7eSjoerg The compiler wrappers does run the real compiler and the analyzer. 8406f32e7eSjoerg This is the default behaviour, can be enforced with `--override-compiler` 8506f32e7eSjoerg flag. 8606f32e7eSjoerg 8706f32e7eSjoerg2. Use special library to intercept compiler calls during the build process. 8806f32e7eSjoerg The analyzer run against each modules after the build finished. 8906f32e7eSjoerg Use `--intercept-first` flag to get this model. 9006f32e7eSjoerg 9106f32e7eSjoerg3. Use compiler wrappers to intercept compiler calls during the build process. 9206f32e7eSjoerg The analyzer run against each modules after the build finished. 9306f32e7eSjoerg Use `--intercept-first` and `--override-compiler` flags together to get 9406f32e7eSjoerg this model. 9506f32e7eSjoerg 9606f32e7eSjoergThe 1. and 3. are using compiler wrappers, which works only if the build 9706f32e7eSjoergprocess respects the `CC` and `CXX` environment variables. (Some build 9806f32e7eSjoergprocess can override these variable as command line parameter only. This case 9906f32e7eSjoergyou need to pass the compiler wrappers manually. eg.: `intercept-build 10006f32e7eSjoerg--override-compiler make CC=intercept-cc CXX=intercept-c++ all` where the 10106f32e7eSjoergoriginal build command would have been `make all` only.) 10206f32e7eSjoerg 10306f32e7eSjoergThe 1. runs the analyzer right after the real compilation. So, if the build 10406f32e7eSjoergprocess removes removes intermediate modules (generated sources) the analyzer 10506f32e7eSjoergoutput still kept. 10606f32e7eSjoerg 10706f32e7eSjoergThe 2. and 3. generate the compilation database first, and filters out those 10806f32e7eSjoergmodules which are not exists. So, it's suitable for incremental analysis during 10906f32e7eSjoergthe development. 11006f32e7eSjoerg 11106f32e7eSjoergThe 2. mode is available only on FreeBSD and Linux. Where library preload 11206f32e7eSjoergis available from the dynamic loader. Not supported on OS X (unless System 11306f32e7eSjoergIntegrity Protection feature is turned off). 11406f32e7eSjoerg 11506f32e7eSjoerg`intercept-build` command uses only the 2. and 3. mode to generate the 11606f32e7eSjoergcompilation database. `analyze-build` does only run the analyzer against the 11706f32e7eSjoergcaptured compiler calls. 11806f32e7eSjoerg 11906f32e7eSjoerg 12006f32e7eSjoergKnown problems 12106f32e7eSjoerg-------------- 12206f32e7eSjoerg 12306f32e7eSjoergBecause it uses `LD_PRELOAD` or `DYLD_INSERT_LIBRARIES` environment variables, 12406f32e7eSjoergit does not append to it, but overrides it. So builds which are using these 12506f32e7eSjoergvariables might not work. (I don't know any build tool which does that, but 12606f32e7eSjoergplease let me know if you do.) 12706f32e7eSjoerg 12806f32e7eSjoerg 12906f32e7eSjoergProblem reports 13006f32e7eSjoerg--------------- 13106f32e7eSjoerg 13206f32e7eSjoergIf you find a bug in this documentation or elsewhere in the program or would 13306f32e7eSjoerglike to propose an improvement, please use the project's [issue tracker][3]. 13406f32e7eSjoergPlease describing the bug and where you found it. If you have a suggestion 13506f32e7eSjoerghow to fix it, include that as well. Patches are also welcome. 13606f32e7eSjoerg 13706f32e7eSjoerg 13806f32e7eSjoergLicense 13906f32e7eSjoerg------- 14006f32e7eSjoerg 14106f32e7eSjoergThe project is licensed under Apache-2.0 with LLVM exceptions. 14206f32e7eSjoergSee LICENSE.TXT for details. 14306f32e7eSjoerg 14406f32e7eSjoerg [1]: http://clang.llvm.org/docs/JSONCompilationDatabase.html 14506f32e7eSjoerg [2]: https://pypi.python.org/pypi/scan-build 14606f32e7eSjoerg [3]: https://llvm.org/bugs/enter_bug.cgi?product=clang 147