clang/tools/scan-build-py/README.md

   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 3.6 or later).
  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