From: Daniel Dunbar Date: Mon, 7 Jan 2013 20:38:55 +0000 (+0000) Subject: [docs/analyzer] Convert existing debug-checks document to Sphinx and link into doctree. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a6a87f1e620c6cd8d9cfaba2861d525f6690e7ba;p=clang [docs/analyzer] Convert existing debug-checks document to Sphinx and link into doctree. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@171786 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/analyzer/DebugChecks.rst b/docs/analyzer/DebugChecks.rst new file mode 100644 index 0000000000..b3c33b93f1 --- /dev/null +++ b/docs/analyzer/DebugChecks.rst @@ -0,0 +1,133 @@ +============ +Debug Checks +============ + +.. contents:: + :local: + +The analyzer contains a number of checkers which can aid in debugging. Enable +them by using the "-analyzer-checker=" flag, followed by the name of the +checker. + +General Analysis Dumpers +======================== + +These checkers are used to dump the results of various infrastructural analyses +to stderr. Some checkers also have "view" variants, which will display a graph +using a 'dot' format viewer (such as Graphviz on OS X) instead. + +- debug.DumpCallGraph, debug.ViewCallGraph: Show the call graph generated for + the current translation unit. This is used to determine the order in which to + analyze functions when inlining is enabled. + +- debug.DumpCFG, debug.ViewCFG: Show the CFG generated for each top-level + function being analyzed. + +- debug.DumpDominators: Shows the dominance tree for the CFG of each top-level + function. + +- debug.DumpLiveVars: Show the results of live variable analysis for each + top-level function being analyzed. + + +Path Tracking +============= + +These checkers print information about the path taken by the analyzer engine. + +- debug.DumpCalls: Prints out every function or method call encountered during a + path traversal. This is indented to show the call stack, but does NOT do any + special handling of branches, meaning different paths could end up + interleaved. + +- debug.DumpTraversal: Prints the name of each branch statement encountered + during a path traversal ("IfStmt", "WhileStmt", etc). Currently used to check + whether the analysis engine is doing BFS or DFS. + + +State Checking +============== + +These checkers will print out information about the analyzer state in the form +of analysis warnings. They are intended for use with the -verify functionality +in regression tests. + +- debug.TaintTest: Prints out the word "tainted" for every expression that + carries taint. At the time of this writing, taint was only introduced by the + checks under experimental.security.taint.TaintPropagation; this checker may + eventually move to the security.taint package. + +- debug.ExprInspection: Responds to certain function calls, which are modeled + after builtins. These function calls should affect the program state other + than the evaluation of their arguments; to use them, you will need to declare + them within your test file. The available functions are described below. + +(FIXME: debug.ExprInspection should probably be renamed, since it no longer only +inspects expressions.) + + +ExprInspection checks +--------------------- + +- void clang_analyzer_eval(bool); + + Prints TRUE if the argument is known to have a non-zero value, FALSE if the + argument is known to have a zero or null value, and UNKNOWN if the argument + isn't sufficiently constrained on this path. You can use this to test other + values by using expressions like "x == 5". Note that this functionality is + currently DISABLED in inlined functions, since different calls to the same + inlined function could provide different information, making it difficult to + write proper -verify directives. + + In C, the argument can be typed as 'int' or as '_Bool'. + + Example usage:: + + clang_analyzer_eval(x); // expected-warning{{UNKNOWN}} + if (!x) return; + clang_analyzer_eval(x); // expected-warning{{TRUE}} + + +- void clang_analyzer_checkInlined(bool); + + If a call occurs within an inlined function, prints TRUE or FALSE according to + the value of its argument. If a call occurs outside an inlined function, + nothing is printed. + + The intended use of this checker is to assert that a function is inlined at + least once (by passing 'true' and expecting a warning), or to assert that a + function is never inlined (by passing 'false' and expecting no warning). The + argument is technically unnecessary but is intended to clarify intent. + + You might wonder why we can't print TRUE if a function is ever inlined and + FALSE if it is not. The problem is that any inlined function could conceivably + also be analyzed as a top-level function (in which case both TRUE and FALSE + would be printed), depending on the value of the -analyzer-inlining option. + + In C, the argument can be typed as 'int' or as '_Bool'. + + Example usage:: + + int inlined() { + clang_analyzer_checkInlined(true); // expected-warning{{TRUE}} + return 42; + } + + void topLevel() { + clang_analyzer_checkInlined(false); // no-warning (not inlined) + int value = inlined(); + // This assertion will not be valid if the previous call was not inlined. + clang_analyzer_eval(value == 42); // expected-warning{{TRUE}} + } + + +Statistics +========== + +The debug.Stats checker collects various information about the analysis of each +function, such as how many blocks were reached and if the analyzer timed out. + +There is also an additional -analyzer-stats flag, which enables various +statistics within the analyzer engine. Note the Stats checker (which produces at +least one bug report per function) may actually change the values reported by +-analyzer-stats. diff --git a/docs/analyzer/conf.py b/docs/analyzer/conf.py index 1e7067d1f5..dff9610ac6 100644 --- a/docs/analyzer/conf.py +++ b/docs/analyzer/conf.py @@ -120,7 +120,7 @@ html_theme = 'haiku' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/docs/analyzer/debug-checks.txt b/docs/analyzer/debug-checks.txt deleted file mode 100644 index 6ac451fbbb..0000000000 --- a/docs/analyzer/debug-checks.txt +++ /dev/null @@ -1,89 +0,0 @@ -The analyzer contains a number of checkers which can aid in debugging. Enable them by using the "-analyzer-checker=" flag, followed by the name of the checker. - -General Analysis Dumpers -======================== -These checkers are used to dump the results of various infrastructural analyses to stderr. Some checkers also have "view" variants, which will display a graph using a 'dot' format viewer (such as Graphviz on OS X) instead. - -- debug.DumpCallGraph, debug.ViewCallGraph: Show the call graph generated for the current translation unit. This is used to determine the order in which to analyze functions when inlining is enabled. -- debug.DumpCFG, debug.ViewCFG: Show the CFG generated for each top-level function being analyzed. -- debug.DumpDominators: Shows the dominance tree for the CFG of each top-level function. -- debug.DumpLiveVars: Show the results of live variable analysis for each top-level function being analyzed. - - -Path Tracking -============= -These checkers print information about the path taken by the analyzer engine. - -- debug.DumpCalls: Prints out every function or method call encountered during a path traversal. This is indented to show the call stack, but does NOT do any special handling of branches, meaning different paths could end up interleaved. -- debug.DumpTraversal: Prints the name of each branch statement encountered during a path traversal ("IfStmt", "WhileStmt", etc). Currently used to check whether the analysis engine is doing BFS or DFS. - - -State Checking -============== -These checkers will print out information about the analyzer state in the form of analysis warnings. They are intended for use with the -verify functionality in regression tests. - -- debug.TaintTest: Prints out the word "tainted" for every expression that carries taint. At the time of this writing, taint was only introduced by the checks under experimental.security.taint.TaintPropagation; this checker may eventually move to the security.taint package. -- debug.ExprInspection: Responds to certain function calls, which are modeled after builtins. These function calls should affect the program state other than the evaluation of their arguments; to use them, you will need to declare them within your test file. The available functions are described below. - -(FIXME: debug.ExprInspection should probably be renamed, since it no longer only inspects expressions.) - - -ExprInspection checks ---------------------- - -- void clang_analyzer_eval(bool); - -Prints TRUE if the argument is known to have a non-zero value, - FALSE if the argument is known to have a zero or null value, and - UNKNOWN if the argument isn't sufficiently constrained on this path. -You can use this to test other values by using expressions like "x == 5". -Note that this functionality is currently DISABLED in inlined functions, -since different calls to the same inlined function could provide different -information, making it difficult to write proper -verify directives. - -In C, the argument can be typed as 'int' or as '_Bool'. - -Example usage: - clang_analyzer_eval(x); // expected-warning{{UNKNOWN}} - if (!x) return; - clang_analyzer_eval(x); // expected-warning{{TRUE}} - - -- void clang_analyzer_checkInlined(bool); - -If a call occurs within an inlined function, prints TRUE or FALSE according to -the value of its argument. If a call occurs outside an inlined function, -nothing is printed. - -The intended use of this checker is to assert that a function is inlined at -least once (by passing 'true' and expecting a warning), or to assert that a -function is never inlined (by passing 'false' and expecting no warning). The -argument is technically unnecessary but is intended to clarify intent. - -You might wonder why we can't print TRUE if a function is ever inlined and -FALSE if it is not. The problem is that any inlined function could conceivably -also be analyzed as a top-level function (in which case both TRUE and FALSE -would be printed), depending on the value of the -analyzer-inlining option. - -In C, the argument can be typed as 'int' or as '_Bool'. - -Example usage: - int inlined() { - clang_analyzer_checkInlined(true); // expected-warning{{TRUE}} - return 42; - } - - void topLevel() { - clang_analyzer_checkInlined(false); // no-warning (not inlined) - int value = inlined(); - // This assertion will not be valid if the previous call was not inlined. - clang_analyzer_eval(value == 42); // expected-warning{{TRUE}} - } - - - -Statistics -========== -The debug.Stats checker collects various information about the analysis of each function, such as how many blocks were reached and if the analyzer timed out. - -There is also an additional -analyzer-stats flag, which enables various statistics within the analyzer engine. Note the Stats checker (which produces at least one bug report per function) may actually change the values reported by -analyzer-stats. diff --git a/docs/analyzer/index.rst b/docs/analyzer/index.rst index 90563beca7..767567f22f 100644 --- a/docs/analyzer/index.rst +++ b/docs/analyzer/index.rst @@ -11,6 +11,7 @@ Contents: .. toctree:: :maxdepth: 2 + DebugChecks Indices and tables