Home | History | Annotate | only in /external/clang/tools/scan-build-py
Up to higher level directory
NameDateSize
bin/21-Aug-2018
libear/21-Aug-2018
libscanbuild/21-Aug-2018
README.md21-Aug-20184K
tests/21-Aug-2018

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 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