1*67e74705SXin Liscan-build 2*67e74705SXin Li========== 3*67e74705SXin Li 4*67e74705SXin LiA package designed to wrap a build so that all calls to gcc/clang are 5*67e74705SXin Liintercepted and logged into a [compilation database][1] and/or piped to 6*67e74705SXin Lithe clang static analyzer. Includes intercept-build tool, which logs 7*67e74705SXin Lithe build, as well as scan-build tool, which logs the build and runs 8*67e74705SXin Lithe clang static analyzer on it. 9*67e74705SXin Li 10*67e74705SXin LiPortability 11*67e74705SXin Li----------- 12*67e74705SXin Li 13*67e74705SXin LiShould be working on UNIX operating systems. 14*67e74705SXin Li 15*67e74705SXin Li- It has been tested on FreeBSD, GNU/Linux and OS X. 16*67e74705SXin Li- Prepared to work on windows, but need help to make it. 17*67e74705SXin Li 18*67e74705SXin Li 19*67e74705SXin LiPrerequisites 20*67e74705SXin Li------------- 21*67e74705SXin Li 22*67e74705SXin Li1. **python** interpreter (version 2.7, 3.2, 3.3, 3.4, 3.5). 23*67e74705SXin Li 24*67e74705SXin Li 25*67e74705SXin LiHow to use 26*67e74705SXin Li---------- 27*67e74705SXin Li 28*67e74705SXin LiTo run the Clang static analyzer against a project goes like this: 29*67e74705SXin Li 30*67e74705SXin Li $ scan-build <your build command> 31*67e74705SXin Li 32*67e74705SXin LiTo generate a compilation database file goes like this: 33*67e74705SXin Li 34*67e74705SXin Li $ intercept-build <your build command> 35*67e74705SXin Li 36*67e74705SXin LiTo run the Clang static analyzer against a project with compilation database 37*67e74705SXin Ligoes like this: 38*67e74705SXin Li 39*67e74705SXin Li $ analyze-build 40*67e74705SXin Li 41*67e74705SXin LiUse `--help` to know more about the commands. 42*67e74705SXin Li 43*67e74705SXin Li 44*67e74705SXin LiLimitations 45*67e74705SXin Li----------- 46*67e74705SXin Li 47*67e74705SXin LiGenerally speaking, the `intercept-build` and `analyze-build` tools together 48*67e74705SXin Lidoes the same job as `scan-build` does. So, you can expect the same output 49*67e74705SXin Lifrom this line as simple `scan-build` would do: 50*67e74705SXin Li 51*67e74705SXin Li $ intercept-build <your build command> && analyze-build 52*67e74705SXin Li 53*67e74705SXin LiThe major difference is how and when the analyzer is run. The `scan-build` 54*67e74705SXin Litool has three distinct model to run the analyzer: 55*67e74705SXin Li 56*67e74705SXin Li1. Use compiler wrappers to make actions. 57*67e74705SXin Li The compiler wrappers does run the real compiler and the analyzer. 58*67e74705SXin Li This is the default behaviour, can be enforced with `--override-compiler` 59*67e74705SXin Li flag. 60*67e74705SXin Li 61*67e74705SXin Li2. Use special library to intercept compiler calls durring the build process. 62*67e74705SXin Li The analyzer run against each modules after the build finished. 63*67e74705SXin Li Use `--intercept-first` flag to get this model. 64*67e74705SXin Li 65*67e74705SXin Li3. Use compiler wrappers to intercept compiler calls durring the build process. 66*67e74705SXin Li The analyzer run against each modules after the build finished. 67*67e74705SXin Li Use `--intercept-first` and `--override-compiler` flags together to get 68*67e74705SXin Li this model. 69*67e74705SXin Li 70*67e74705SXin LiThe 1. and 3. are using compiler wrappers, which works only if the build 71*67e74705SXin Liprocess respects the `CC` and `CXX` environment variables. (Some build 72*67e74705SXin Liprocess can override these variable as command line parameter only. This case 73*67e74705SXin Liyou need to pass the compiler wrappers manually. eg.: `intercept-build 74*67e74705SXin Li--override-compiler make CC=intercept-cc CXX=intercept-c++ all` where the 75*67e74705SXin Lioriginal build command would have been `make all` only.) 76*67e74705SXin Li 77*67e74705SXin LiThe 1. runs the analyzer right after the real compilation. So, if the build 78*67e74705SXin Liprocess removes removes intermediate modules (generated sources) the analyzer 79*67e74705SXin Lioutput still kept. 80*67e74705SXin Li 81*67e74705SXin LiThe 2. and 3. generate the compilation database first, and filters out those 82*67e74705SXin Limodules which are not exists. So, it's suitable for incremental analysis durring 83*67e74705SXin Lithe development. 84*67e74705SXin Li 85*67e74705SXin LiThe 2. mode is available only on FreeBSD and Linux. Where library preload 86*67e74705SXin Liis available from the dynamic loader. Not supported on OS X (unless System 87*67e74705SXin LiIntegrity Protection feature is turned off). 88*67e74705SXin Li 89*67e74705SXin Li`intercept-build` command uses only the 2. and 3. mode to generate the 90*67e74705SXin Licompilation database. `analyze-build` does only run the analyzer against the 91*67e74705SXin Licaptured compiler calls. 92*67e74705SXin Li 93*67e74705SXin Li 94*67e74705SXin LiKnown problems 95*67e74705SXin Li-------------- 96*67e74705SXin Li 97*67e74705SXin LiBecause it uses `LD_PRELOAD` or `DYLD_INSERT_LIBRARIES` environment variables, 98*67e74705SXin Liit does not append to it, but overrides it. So builds which are using these 99*67e74705SXin Livariables might not work. (I don't know any build tool which does that, but 100*67e74705SXin Liplease let me know if you do.) 101*67e74705SXin Li 102*67e74705SXin Li 103*67e74705SXin LiProblem reports 104*67e74705SXin Li--------------- 105*67e74705SXin Li 106*67e74705SXin LiIf you find a bug in this documentation or elsewhere in the program or would 107*67e74705SXin Lilike to propose an improvement, please use the project's [issue tracker][3]. 108*67e74705SXin LiPlease describing the bug and where you found it. If you have a suggestion 109*67e74705SXin Lihow to fix it, include that as well. Patches are also welcome. 110*67e74705SXin Li 111*67e74705SXin Li 112*67e74705SXin LiLicense 113*67e74705SXin Li------- 114*67e74705SXin Li 115*67e74705SXin LiThe project is licensed under University of Illinois/NCSA Open Source License. 116*67e74705SXin LiSee LICENSE.TXT for details. 117*67e74705SXin Li 118*67e74705SXin Li [1]: http://clang.llvm.org/docs/JSONCompilationDatabase.html 119*67e74705SXin Li [2]: https://pypi.python.org/pypi/scan-build 120*67e74705SXin Li [3]: https://llvm.org/bugs/enter_bug.cgi?product=clang 121