| Ted Kremenek | 591b907 | 2009-06-08 21:21:24 +0000 | [diff] [blame^] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <title>Running the Analyzer</title> |
| 6 | <link type="text/css" rel="stylesheet" href="menu.css" /> |
| 7 | <link type="text/css" rel="stylesheet" href="content.css" /> |
| 8 | <style> |
| 9 | thead { |
| 10 | background-color:#eee; color:#666666; |
| 11 | font-weight: bold; cursor: default; |
| 12 | text-align:center; |
| 13 | border-top: 2px solid #cccccc; |
| 14 | border-bottom: 2px solid #cccccc; |
| 15 | font-weight: bold; font-family: Verdana |
| 16 | } |
| 17 | table { border: 1px #cccccc solid } |
| 18 | table { border-collapse: collapse; border-spacing: 0px } |
| 19 | table { margin-left:0px; margin-top:20px; margin-bottom:20px } |
| 20 | td { border-bottom: 1px #cccccc dotted } |
| 21 | td { padding:5px; padding-left:8px; padding-right:8px } |
| 22 | td { text-align:left; font-size:9pt } |
| 23 | td.View { padding-left: 10px } |
| 24 | </style> |
| 25 | </head> |
| 26 | <body> |
| 27 | |
| 28 | <!--#include virtual="menu.html.incl"--> |
| 29 | |
| 30 | <div id="content"> |
| 31 | |
| 32 | <h1>Running the Analyzer</h1> |
| 33 | |
| 34 | <p>While the static analyzer engine can be used as a library, many users will |
| 35 | likely use the command-line interface to the analyzer to analyze projects. There |
| 36 | are essentially two commands one can use the run the analyzer:</p> |
| 37 | |
| 38 | <ul> |
| 39 | <li><b>scan-build</b>: The <tt>scan-build</tt> command can be used to analyze |
| 40 | an entire project.</li> |
| 41 | <li><b>clang</b>: The <tt>clang</tt> command is both Clang's compiler and |
| 42 | static analysis driver. This can be used both to compile and analyze |
| 43 | individual source files. |
| 44 | </ul> |
| 45 | |
| 46 | <h3>Contents</h3> |
| 47 | |
| 48 | <ul> |
| 49 | <li><a href="#scanbuild">scan-build</a></li> |
| 50 | <ul> |
| 51 | <li><a href="#scanbuild_basicusage">Basic Usage</a></li> |
| 52 | <li><a href="#scanbuild_otheroptions">Other Options</a></li> |
| 53 | <li><a href="#scanbuild_output">Output of scan-build</a></li> |
| 54 | </ul> |
| 55 | <li><a href="#recommendedguidelines">Recommended Usage Guidelines</a></li> |
| 56 | <ul> |
| 57 | <li><a href="#recommended_debug">Always Analyze a Project in its "Debug" Configuration</a></li> |
| 58 | <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li> |
| 59 | <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li> |
| 60 | </ul> |
| 61 | </ul> |
| 62 | |
| 63 | <h2 id="scanbuild">scan-build</h2> |
| 64 | |
| 65 | <p>The <tt>scan-build</tt> command can be used to analyze an entire project by |
| 66 | essentially interposing on a project's build process. This means that to run the |
| 67 | analyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze |
| 68 | the source files compiled by <tt>gcc</tt> during a project build. This means |
| 69 | that any files that are not compiled will also not be analyzed.</p> |
| 70 | |
| 71 | <h3 id="scanbuild_basicusage">Basic Usage</h3> |
| 72 | |
| 73 | <p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the |
| 74 | word "scan-build" in front of your build command:</p> |
| 75 | |
| 76 | <pre class="code_example"> |
| 77 | $ <span class="code_highlight">scan-build</span> make |
| 78 | $ <span class="code_highlight">scan-build</span> xcodebuild |
| 79 | </pre> |
| 80 | |
| 81 | <p>In the first case <tt>scan-build</tt> analyzes the code of a project built |
| 82 | with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project |
| 83 | built using <tt>xcodebuild</tt>.<p> |
| 84 | |
| 85 | <p>Here is the general format for invoking <tt>scan-build</tt>:</p> |
| 86 | |
| 87 | <pre class="code_example"> |
| 88 | $ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight"><command></span> <i>[command options]</i> |
| 89 | </pre> |
| 90 | |
| 91 | <p>Operationally, <tt>scan-build</tt> literally runs <command> with all of the |
| 92 | subsequent options passed to it. For example, one can pass <nobr><tt>-j4</tt></nobr> to |
| 93 | <tt>make</tt> get a parallel build over 4 cores:</p> |
| 94 | |
| 95 | <pre class="code_example"> |
| 96 | $ scan-build make <span class="code_highlight">-j4</span> |
| 97 | </pre> |
| 98 | |
| 99 | <p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the |
| 100 | options after the build command; it simply passes them through. In general, |
| 101 | <tt>scan-build</tt> should support parallel builds, but <b>not distributed |
| 102 | builds</b>.</p> |
| 103 | |
| 104 | <p>It is also possible to use <tt>scan-build</tt> to analyze specific |
| 105 | files:</p> |
| 106 | |
| 107 | <pre class="code_example"> |
| 108 | $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span> |
| 109 | </pre> |
| 110 | |
| 111 | <p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed. |
| 112 | </p> |
| 113 | |
| 114 | <h3 id="scanbuild_otheroptions">Other Options</h3> |
| 115 | |
| 116 | <p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These |
| 117 | options prefix the build command. For example:</p> |
| 118 | |
| 119 | <pre class="code_example"> |
| 120 | $ scan-build <span class="code_highlight">-k -V</span> make |
| 121 | $ scan-build <span class="code_highlight">-k -V</span> xcodebuild |
| 122 | </pre> |
| 123 | |
| 124 | <p>Here is a subset of useful options:</p> |
| 125 | |
| 126 | <table> |
| 127 | <thead><tr><td>Option</td><td>Description</td></tr></thead> |
| 128 | |
| 129 | <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories |
| 130 | will be created as needed to represent separate "runs" of the analyzer. If this |
| 131 | option is not specified, a directory is created in <tt>/tmp</tt> to store the |
| 132 | reports.</td><tr> |
| 133 | |
| 134 | <tr><td><b>-h</b><br><i><nobr>(or no arguments)</nobr></i></td><td>Display all |
| 135 | <tt>scan-build</tt> options.</td></tr> |
| 136 | |
| 137 | <tr><td><b>-k</b><br><nobr><b>--keep-going</b></nobr></td><td>Add a "keep on |
| 138 | going" option to the specified build command. <p>This option currently supports |
| 139 | <tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one |
| 140 | can specify this behavior directly using build options.</p></td></tr> |
| 141 | |
| 142 | <tr><td><b>-v<b></td><td>Verbose output from scan-build and the analyzer. <b>A |
| 143 | second and third "-v" increases verbosity</b>, and is useful for filing bug |
| 144 | reports against the analyzer.</td></tr> |
| 145 | |
| 146 | <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build |
| 147 | command completes.</td></tr> </table> |
| 148 | |
| 149 | <p>A complete list of options can be obtained by running <tt>scan-build</tt> |
| 150 | with no arguments.</p> |
| 151 | |
| 152 | <h3 id="scanbuild_output">Output of scan-build</h3> |
| 153 | |
| 154 | <p> |
| 155 | The output of scan-build is a set of HTML files, each one which represents a |
| 156 | separate bug report. A single <tt>index.html</tt> file is generated for |
| 157 | surveying all of the bugs. You can then just open <tt>index.html</tt> in a web |
| 158 | browser to view the bug reports. |
| 159 | </p> |
| 160 | |
| 161 | <p> |
| 162 | Where the HTML files are generated is specified with a <b>-o</b> option to |
| 163 | <tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt> |
| 164 | is created to store the files (<tt>scan-build</tt> will print a message telling |
| 165 | you where they are). If you want to view the reports immediately after the build |
| 166 | completes, pass <b>-V</b> to <tt>scan-build</tt>. |
| 167 | </p> |
| 168 | |
| 169 | |
| 170 | <h2 id="recommendedguidelines">Recommended Usage Guidelines</h2> |
| 171 | |
| 172 | <p>This section describes a few recommendations with running the analyzer.</p> |
| 173 | |
| 174 | <h3 id="recommended_debug">Always Analyze a Project in its "Debug" Configuration</h3> |
| 175 | |
| 176 | <p>Most projects can be built in a "debug" mode that enables assertions. |
| 177 | Assertions are picked up by the static analyzer to prune infeasible paths, which |
| 178 | in some cases can greatly reduce the number of false positives (bogus error |
| 179 | reports) emitted by the tool.</p> |
| 180 | |
| 181 | <h3 id="recommend_verbose">Use Verbose Output when Debugging scan-build</h3> |
| 182 | |
| 183 | <p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about |
| 184 | what it's doing; two <b>-v</b> options emit more information. Redirecting the |
| 185 | output of <tt>scan-build</tt> to a text file (make sure to redirect standard |
| 186 | error) is useful for filing bug reports against <tt>scan-build</tt> or the |
| 187 | analyzer, as we can see the exact options (and files) passed to the analyzer. |
| 188 | For more comprehensible logs, don't perform a parallel build.</p> |
| 189 | |
| 190 | <h3 id="recommended_autoconf">Run './configure' through scan-build</h3> |
| 191 | |
| 192 | <p>If an analyzed project uses an autoconf generated <tt>configure</tt> script, |
| 193 | you will probably need to run <tt>configure</tt> script through |
| 194 | <tt>scan-build</tt> in order to analyze the project.</p> |
| 195 | |
| 196 | <p><b>Example</b></p> |
| 197 | |
| 198 | <pre class="code_example"> |
| 199 | $ scan-build ./configure |
| 200 | $ scan-build make |
| 201 | </pre> |
| 202 | |
| 203 | <p>The reason <tt>configure</tt> also needs to be run through |
| 204 | <tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by |
| 205 | <i>interposing</i> on the compiler. This interposition is currently done by |
| 206 | <tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to |
| 207 | <tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake |
| 208 | compiler, forwarding its command line arguments over to <tt>gcc</tt> to perform |
| 209 | regular compilation and <tt>clang</tt> to perform static analysis.</p> |
| 210 | |
| 211 | <p>Running <tt>configure</tt> typically generates makefiles that have hardwired |
| 212 | paths to the compiler, and by running <tt>configure</tt> through |
| 213 | <tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p.> |
| 214 | |
| 215 | <!-- |
| 216 | <h2 id="Debugging">Debugging the Analyzer</h2> |
| 217 | |
| 218 | <p>This section provides information on debugging the analyzer, and troubleshooting |
| 219 | it when you have problems analyzing a particular project.</p> |
| 220 | |
| 221 | <h3>How it Works</h3> |
| 222 | |
| 223 | <p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable |
| 224 | <tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other |
| 225 | environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML |
| 226 | report files.</p> |
| 227 | |
| 228 | <p>Some Makefiles (or equivalent project files) hardcode the compiler; for such |
| 229 | projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be |
| 230 | called. This will cause the compiled code <b>to not be analyzed.</b></p> If you |
| 231 | find that your code isn't being analyzed, check to see if <tt>CC</tt> is |
| 232 | hardcoded. If this is the case, you can hardcode it instead to the <b>full |
| 233 | path</b> to <tt>ccc-analyzer</tt>.</p> |
| 234 | |
| 235 | <p>When applicable, you can also run <tt>./configure</tt> for a project through |
| 236 | <tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based |
| 237 | on the environment passed in from <tt>scan-build</tt>: |
| 238 | |
| 239 | <pre> |
| 240 | $ scan-build <b>./configure</b> |
| 241 | </pre> |
| 242 | |
| 243 | <p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in |
| 244 | most cases will not actually analyze the configure tests run by |
| 245 | <tt>configure</tt>.</p> |
| 246 | |
| 247 | <p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to |
| 248 | compile the actual code in addition to running the analyzer (which occurs by it |
| 249 | calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all |
| 250 | the arguments over to <tt>gcc</tt>, but this may not work perfectly (please |
| 251 | report bugs of this kind). |
| 252 | --> |
| 253 | |
| 254 | </div> |
| 255 | </body> |
| 256 | </html> |
| 257 | |