From: Anna Zaks Date: Wed, 2 Nov 2011 17:49:20 +0000 (+0000) Subject: [analyzer] Start writing Checker Developer Manual. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d67fc49da93be0e3c1620b70746cc1bfae9878b0;p=clang [analyzer] Start writing Checker Developer Manual. So far added the skeleton + several more or less complete sections: Getting Started Idea for a Checker AST Visitors Useful Commands/Debugging Hints git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@143554 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/www/analyzer/checker_dev_manual.html b/www/analyzer/checker_dev_manual.html new file mode 100644 index 0000000000..b31b11b477 --- /dev/null +++ b/www/analyzer/checker_dev_manual.html @@ -0,0 +1,181 @@ + + + + Checker Developer Manual + + + + + + +
+ + +
+ +

This Page Is Under Construction

+ +

Checker Developer Manual

+ +

The static analyzer engine performs symbolic execution of the program and +relies on a set of checkers to implement the logic for detecting and +constructing bug reports. This page provides hints and guidelines for anyone +who is interested in implementing their own checker. The static analyzer is a +part of the Clang project, so consult Hacking on Clang +and LLVM Programmer's Manual +for general developer guidelines and information.

+ + + +

Getting Started

+
    +
  • To check out the source code and build the project, follow steps 1-4 of the Clang Getting Started + page.
    • + +
  • The analyzer source code is located under the Clang source tree: +
    + $ cd llvm/tools/clang + +
    See: include/clang/StaticAnalyzer, lib/StaticAnalyzer, test/Analysis.
    • + +
  • The analyzer regression tests can be executed from the Clang's build directory: +
    + $ cd ../../../; cd build/tools/clang; TESTDIRS=Analysis make test +
    • + +
  • Analyze a file with the specified checker: +
    + $ clang -cc1 -analyze -analyzer-checker=core.DivideZero test.c +
    • + +
  • List the available checkers: +
    + $ clang -cc1 -analyzer-checker-help +
    • + +
  • See the analyzer help for different output formats, fine tuning, and debug options: +
    + $ clang -cc1 -help | grep "analyzer" +
    • + +
+ +

Static Analyzer Overview

+ ExplidedGraph, ExplodedNode (ProgramPoint, State)
+ Engine-Checker Interaction
+ Symbols
+ + +

Idea for a Checker

+ Here are several questions which you should consider when evaluating your checker idea: +
    +
  • Can the check be effectively implemented without path-sensitive analysis? See AST Visitors.
    • + +
  • How high the false positive rate is going to be? Looking at the occurrences + of the issue you want to write a checker for in the existing code bases might give you some + ideas.
    • + +
  • How the current limitations of the analysis will effect the false alarm + rate? Currently, the analyzer only reasons about one procedure at a time (no + inter-procedural analysis). Also, it uses a simple range tracking based solver to model symbolic + execution.
    • + +
  • Consult the Bugzilla database + to get some ideas for new checkers and consider starting with improving/fixing + bugs in the existing checkers.
    • +
+ +

Checker Skeleton

+ The source code for all the checkers goes into clang/lib/StaticAnalyzer/Checkers.

+ There are two main decisions you need to make: +

    +
  • Which events the checker should be tracking.
    • +
  • What data you want to store as part of the checker-specific program state. Try to minimize the checker state as much as possible.
    • +
+ Describe the registration process. + +

Bug Reports

+ +

AST Visitors

+ Some checks might not require path-sensitivity to be effective. Simple AST walk + might be sufficient. If that is the case, consider implementing a Clang compiler warning. + On the other hand, a check might not be acceptable as a compiler + warning; for example, because of a relatively high false positive rate. In this + situation, AST callbacks checkASTDecl and + checkASTCodeBody are your best friends. + +

Testing

+ Every patch should be well tested with Clang regression tests. The checker tests + live in clang/test/Analysis folder. To run all of the analyzer tests, + execute the following from the clang build directory: + 
+    $ TESTDIRS=Analysis make test
+
+ +

Useful Commands/Debugging Hints

+
    +
  • +While investigating a checker-related issue, instruct the analyzer to only execute a single checker: +
    +$ clang -cc1 -analyze -analyzer-checker=osx.KeychainAPI test.c + +
    • +
  • +To dump AST: +
    +$ clang -cc1 -ast-dump test.c + +
    • +
  • +To view/dump CFG use debug.ViewCFG or debug.DumpCFG checkers: +
    +$ clang -cc1 -analyze -analyzer-checker=debug.ViewCFG test.c + +
    • +
  • +To see all available debug checkers: +
    +$ clang -cc1 -analyzer-checker-help | grep "debug" + +
    • +
  • +To see which function is failing while processing a large file use -analyzer-display-progress option. +
    • +
  • +While debugging execute clang -cc1 -analyze -analyzer-checker=core instead of clang --analyze, as the later would call the compiler in a separate process. +
    • +
  • +To view ExplodedGraph (the state graph explored by the analyzer) while debugging, goto a frame that has clang::ento::ExprEngine object and execute: +
    +(gdb) p ViewGraph(0) + +
    • +
  • +To see clang::Expr while debugging use the following command. If you pass in a SourceManager object, it will also dump the corresponding line in the source code. +
    +(gdb) p E->dump() + +
    • +
  • +To dump AST of a method that the current ExplodedNode belongs to: +
    +(gdb) p ENode->getCodeDecl().getBody()->dump(getContext().getSourceManager()) + +
    • +
+ +
+
+ +