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 Limitations 45 ----------- 46 47 Generally speaking, the `intercept-build` and `analyze-build` tools together 48 does the same job as `scan-build` does. So, you can expect the same output 49 from this line as simple `scan-build` would do: 50 51 $ intercept-build <your build command> && analyze-build 52 53 The major difference is how and when the analyzer is run. The `scan-build` 54 tool has three distinct model to run the analyzer: 55 56 1. Use compiler wrappers to make actions. 57 The compiler wrappers does run the real compiler and the analyzer. 58 This is the default behaviour, can be enforced with `--override-compiler` 59 flag. 60 61 2. Use special library to intercept compiler calls durring the build process. 62 The analyzer run against each modules after the build finished. 63 Use `--intercept-first` flag to get this model. 64 65 3. Use compiler wrappers to intercept compiler calls durring the build process. 66 The analyzer run against each modules after the build finished. 67 Use `--intercept-first` and `--override-compiler` flags together to get 68 this model. 69 70 The 1. and 3. are using compiler wrappers, which works only if the build 71 process respects the `CC` and `CXX` environment variables. (Some build 72 process can override these variable as command line parameter only. This case 73 you need to pass the compiler wrappers manually. eg.: `intercept-build 74 --override-compiler make CC=intercept-cc CXX=intercept-c++ all` where the 75 original build command would have been `make all` only.) 76 77 The 1. runs the analyzer right after the real compilation. So, if the build 78 process removes removes intermediate modules (generated sources) the analyzer 79 output still kept. 80 81 The 2. and 3. generate the compilation database first, and filters out those 82 modules which are not exists. So, it's suitable for incremental analysis durring 83 the development. 84 85 The 2. mode is available only on FreeBSD and Linux. Where library preload 86 is available from the dynamic loader. Not supported on OS X (unless System 87 Integrity Protection feature is turned off). 88 89 `intercept-build` command uses only the 2. and 3. mode to generate the 90 compilation database. `analyze-build` does only run the analyzer against the 91 captured compiler calls. 92 93 94 Known problems 95 -------------- 96 97 Because it uses `LD_PRELOAD` or `DYLD_INSERT_LIBRARIES` environment variables, 98 it does not append to it, but overrides it. So builds which are using these 99 variables might not work. (I don't know any build tool which does that, but 100 please let me know if you do.) 101 102 103 Problem reports 104 --------------- 105 106 If you find a bug in this documentation or elsewhere in the program or would 107 like to propose an improvement, please use the project's [issue tracker][3]. 108 Please describing the bug and where you found it. If you have a suggestion 109 how to fix it, include that as well. Patches are also welcome. 110 111 112 License 113 ------- 114 115 The project is licensed under University of Illinois/NCSA Open Source License. 116 See LICENSE.TXT for details. 117 118 [1]: http://clang.llvm.org/docs/JSONCompilationDatabase.html 119 [2]: https://pypi.python.org/pypi/scan-build 120 [3]: https://llvm.org/bugs/enter_bug.cgi?product=clang 121
