PageRenderTime 27ms CodeModel.GetById 16ms RepoModel.GetById 1ms app.codeStats 0ms

/external/clang/www/analyzer/scan-build.html

https://bitbucket.org/rlyspn/androidrr
HTML | 344 lines | 233 code | 72 blank | 39 comment | 0 complexity | e3ee4598f3f78a0fb283b8866ac790b9 MD5 | raw file
    

  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
    2. 

  2.           "http://www.w3.org/TR/html4/strict.dtd">
    3. 

  3. <html>
    4. 

  4. <head>
    5. 

  5.   <title>scan-build: running the analyzer from the command line</title>
    6. 

  6.   <link type="text/css" rel="stylesheet" href="content.css">
    7. 

  7.   <link type="text/css" rel="stylesheet" href="menu.css">
    8. 

  8.   <script type="text/javascript" src="scripts/menu.js"></script>
    9. 

  9.   <script type="text/javascript" src="scripts/dbtree.js"></script>
    10. 

  10. </head>
    11. 

  11. <body>
    12. 

  12. 

  13. <div id="page">
    14. 

  14. <!--#include virtual="menu.html.incl"-->
    15. 

  15. <div id="content">
    16. 

  16. 

  17. <h1>scan-build: running the analyzer from the command line</h1>
    18. 

  18. 

  19. <table style="margin-top:0px" width="100%" cellpadding="0px" cellspacing="0">
    20. 

  20. <tr><td>
    21. 

  21. 

  22. <h3>What is it?</h3>
    23. 

  23. <p><b>scan-build</b> is a command line utility that enables a user to run the
    24. 

  24. static analyzer over their codebase as part of performing a regular build (from
    25. 

  25. the command line).</p>
    26. 

  26. 

  27. <h3>How does it work?</h3>
    28. 

  28. <p>During a project build, as source files are compiled they are also analyzed
    29. 

  29. in tandem by the static analyzer.</p>
    30. 

  30. 

  31. <p>Upon completion of the build, results are then presented to the user within a
    32. 

  32. web browser.</p>
    33. 

  33. 

  34. <h3>Will it work with any build system?</h3>
    35. 

  35. <p><b>scan-build</b> has little or no knowledge about how you build your code.
    36. 

  36. It works by overriding the <tt>CC</tt> and <tt>CXX</tt> environment variables to
    37. 

  37. (hopefully) change your build to use a &quot;fake&quot; compiler instead of the
    38. 

  38. one that would normally build your project. This fake compiler executes either 
    39. 

  39. <tt>clang</tt> or <tt>gcc</tt> (depending on the platform) to compile your 
    40. 

  40. code and then executes the static analyzer to analyze your code.</p>
    41. 

  41. 

  42. <p>This &quot;poor man's interposition&quot; works amazingly well in many cases
    43. 

  43. and falls down in others. Please consult the information on this page on making
    44. 

  44. the best use of <b>scan-build</b>, which includes getting it to work when the
    45. 

  45. aforementioned hack fails to work.</p>
    46. 

  46. 

  47. </td>
    48. 

  48. <td style="padding-left:10px; text-align:center">
    49. 

  49.   <img src="images/scan_build_cmd.png" width="450px" alt="scan-build"><br>
    50. 

  50.   <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" alt="analyzer in browser"></a>
    51. 

  51. <br><b>Viewing static analyzer results in a web browser</b>
    52. 

  52. </td></tr></table>
    53. 

  53. 

  54. <h2>Contents</h2>
    55. 

  55. 

  56. <ul id="collapsetree" class="dbtree onclick multiple">
    57. 

  57. <li><a href="#scanbuild">Getting Started</a>
    58. 

  58.  <ul>
    59. 

  59.   <li><a href="#scanbuild_basicusage">Basic Usage</a></li>
    60. 

  60.   <li><a href="#scanbuild_otheroptions">Other Options</a></li>
    61. 

  61.   <li><a href="#scanbuild_output">Output of scan-build</a></li>
    62. 

  62.  </ul>
    63. 

  63. </li>
    64. 

  64. <li><a href="#recommendedguidelines">Recommended Usage Guidelines</a>
    65. 

  65.  <ul>
    66. 

  66.   <li><a href="#recommended_debug">Always Analyze a Project in its &quot;Debug&quot; Configuration</a></li>
    67. 

  67.   <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li>
    68. 

  68.   <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li>
    69. 

  69.  </ul>
    70. 

  70. </li>
    71. 

  71. <li><a href="#iphone">Analyzing iPhone Projects</a></li>
    72. 

  72. </ul>
    73. 

  73. 

  74. <h2 id="scanbuild">Getting Started</h2>
    75. 

  75. 

  76. <p>The <tt>scan-build</tt> command can be used to analyze an entire project by
    77. 

  77. essentially interposing on a project's build process. This means that to run the
    78. 

  78. analyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze
    79. 

  79. the source files compiled by <tt>gcc</tt>/<tt>clang</tt> during a project build. 
    80. 

  80. This means that any files that are not compiled will also not be analyzed.</p>
    81. 

  81. 

  82. <h3 id="scanbuild_basicusage">Basic Usage</h3>
    83. 

  83. 

  84. <p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the
    85. 

  85. word &quot;scan-build&quot; in front of your build command:</p>
    86. 

  86. 

  87. <pre class="code_example">
    88. 

  88. $ <span class="code_highlight">scan-build</span> make
    89. 

  89. $ <span class="code_highlight">scan-build</span> xcodebuild
    90. 

  90. </pre>
    91. 

  91. 

  92. <p>In the first case <tt>scan-build</tt> analyzes the code of a project built
    93. 

  93. with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project
    94. 

  94. built using <tt>xcodebuild</tt>.<p>
    95. 

  95.   
    96. 

  96. <p>Here is the general format for invoking <tt>scan-build</tt>:</p>
    97. 

  97. 

  98. <pre class="code_example">
    99. 

  99. $ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight">&lt;command&gt;</span> <i>[command options]</i>
    100. 

  100. </pre>
    101. 

  101. 

  102. <p>Operationally, <tt>scan-build</tt> literally runs &lt;command&gt; with all of the
    103. 

  103. subsequent options passed to it. For example, one can pass <tt>-j4</tt> to
    104. 

  104. <tt>make</tt> get a parallel build over 4 cores:</p>
    105. 

  105. 

  106. <pre class="code_example">
    107. 

  107. $ scan-build make <span class="code_highlight">-j4</span>
    108. 

  108. </pre>
    109. 

  109. 

  110. <p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the
    111. 

  111. options after the build command; it simply passes them through. In general,
    112. 

  112. <tt>scan-build</tt> should support parallel builds, but <b>not distributed
    113. 

  113. builds</b>.</p>
    114. 

  114. 

  115. <p>It is also possible to use <tt>scan-build</tt> to analyze specific
    116. 

  116. files:</p>
    117. 

  117. 

  118. <pre class="code_example">
    119. 

  119.  $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span>
    120. 

  120. </pre>
    121. 

  121. 

  122. <p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed.
    123. 

  123. </p>
    124. 

  124. 

  125. <h3 id="scanbuild_otheroptions">Other Options</h3>
    126. 

  126. 

  127. <p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These
    128. 

  128. options prefix the build command. For example:</p>
    129. 

  129. 

  130. <pre class="code_example">
    131. 

  131.  $ scan-build <span class="code_highlight">-k -V</span> make
    132. 

  132.  $ scan-build <span class="code_highlight">-k -V</span> xcodebuild
    133. 

  133. </pre>
    134. 

  134. 

  135. <p>Here is a subset of useful options:</p>
    136. 

  136. 

  137. <table class="options">
    138. 

  138. <thead><tr><td>Option</td><td>Description</td></tr></thead>
    139. 

  139. 

  140. <tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories
    141. 

  141. will be created as needed to represent separate "runs" of the analyzer. If this
    142. 

  142. option is not specified, a directory is created in <tt>/tmp</tt> to store the
    143. 

  143. reports.</td></tr>
    144. 

  144. 

  145. <tr><td><b>-h</b><br><i>(or&nbsp;no&nbsp;arguments)</i></td><td>Display all
    146. 

  146. <tt>scan-build</tt> options.</td></tr>
    147. 

  147. 

  148. <tr><td><b>-k</b><br><b>--keep-going</b></td><td>Add a "keep on
    149. 

  149. going" option to the specified build command. <p>This option currently supports
    150. 

  150. <tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one
    151. 

  151. can specify this behavior directly using build options.</p></td></tr>
    152. 

  152. 

  153. <tr><td><b>-v</b></td><td>Verbose output from scan-build and the analyzer. <b>A
    154. 

  154. second and third "-v" increases verbosity</b>, and is useful for filing bug
    155. 

  155. reports against the analyzer.</td></tr>
    156. 

  156. 

  157. <tr><td><b>-V</b></td><td>View analysis results in a web browser when the build
    158. 

  158. command completes.</td></tr> </table>
    159. 

  159. 

  160. <p>A complete list of options can be obtained by running <tt>scan-build</tt>
    161. 

  161. with no arguments.</p>
    162. 

  162. 

  163. <h3 id="scanbuild_output">Output of scan-build</h3>
    164. 

  164. 

  165. <p>
    166. 

  166. The output of scan-build is a set of HTML files, each one which represents a
    167. 

  167. separate bug report. A single <tt>index.html</tt> file is generated for
    168. 

  168. surveying all of the bugs. You can then just open <tt>index.html</tt> in a web
    169. 

  169. browser to view the bug reports.
    170. 

  170. </p>
    171. 

  171. 

  172. <p>
    173. 

  173. Where the HTML files are generated is specified with a <b>-o</b> option to
    174. 

  174. <tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt>
    175. 

  175. is created to store the files (<tt>scan-build</tt> will print a message telling
    176. 

  176. you where they are). If you want to view the reports immediately after the build
    177. 

  177. completes, pass <b>-V</b> to <tt>scan-build</tt>.
    178. 

  178. </p>
    179. 

  179. 

  180. 

  181. <h2 id="recommendedguidelines">Recommended Usage Guidelines</h2>
    182. 

  182. 

  183. <p>This section describes a few recommendations with running the analyzer.</p>
    184. 

  184. 

  185. <h3 id="recommended_debug">ALWAYS analyze a project in its &quot;debug&quot; configuration</h3>
    186. 

  186. 

  187. <p>Most projects can be built in a &quot;debug&quot; mode that enables assertions.
    188. 

  188. Assertions are picked up by the static analyzer to prune infeasible paths, which
    189. 

  189. in some cases can greatly reduce the number of false positives (bogus error
    190. 

  190. reports) emitted by the tool.</p>
    191. 

  191. 

  192. <h3 id="recommend_verbose">Use verbose output when debugging scan-build</h3>
    193. 

  193. 

  194. <p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
    195. 

  195. what it's doing; two <b>-v</b> options emit more information. Redirecting the
    196. 

  196. output of <tt>scan-build</tt> to a text file (make sure to redirect standard
    197. 

  197. error) is useful for filing bug reports against <tt>scan-build</tt> or the
    198. 

  198. analyzer, as we can see the exact options (and files) passed to the analyzer.
    199. 

  199. For more comprehensible logs, don't perform a parallel build.</p>
    200. 

    201. 

  201. <h3 id="recommended_autoconf">Run './configure' through scan-build</h3>
    202. 

  202. 

  203. <p>If an analyzed project uses an autoconf generated <tt>configure</tt> script,
    204. 

  204. you will probably need to run <tt>configure</tt> script through
    205. 

  205. <tt>scan-build</tt> in order to analyze the project.</p>
    206. 

  206. 

  207. <p><b>Example</b></p>
    208. 

  208. 

  209. <pre class="code_example">
    210. 

  210. $ scan-build ./configure
    211. 

  211. $ scan-build make
    212. 

  212. </pre>
    213. 

  213. 

  214. <p>The reason <tt>configure</tt> also needs to be run through
    215. 

  215. <tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by
    216. 

  216. <i>interposing</i> on the compiler. This interposition is currently done by
    217. 

  217. <tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to
    218. 

  218. <tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake
    219. 

  219. compiler, forwarding its command line arguments over to the compiler to perform
    220. 

  220. regular compilation and <tt>clang</tt> to perform static analysis.</p>
    221. 

  221. 

  222. <p>Running <tt>configure</tt> typically generates makefiles that have hardwired
    223. 

  223. paths to the compiler, and by running <tt>configure</tt> through
    224. 

  224. <tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p>
    225. 

  225. 

  226. <!-- 
    227. 

  227. <h2 id="Debugging">Debugging the Analyzer</h2>
    228. 

  228. 

  229. <p>This section provides information on debugging the analyzer, and troubleshooting
    230. 

  230. it when you have problems analyzing a particular project.</p>
    231. 

  231. 

  232. <h3>How it Works</h3>
    233. 

  233. 

  234. <p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
    235. 

  235. <tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
    236. 

  236. environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
    237. 

  237. report files.</p>
    238. 

  238. 

  239. <p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
    240. 

  240. projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
    241. 

  241. called. This will cause the compiled code <b>to not be analyzed.</b></p> If you
    242. 

  242. find that your code isn't being analyzed, check to see if <tt>CC</tt> is
    243. 

  243. hardcoded. If this is the case, you can hardcode it instead to the <b>full
    244. 

  244. path</b> to <tt>ccc-analyzer</tt>.</p>
    245. 

  245. 

  246. <p>When applicable, you can also run <tt>./configure</tt> for a project through
    247. 

  247. <tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based
    248. 

  248. on the environment passed in from <tt>scan-build</tt>:
    249. 

  249. 

  250. <pre>
    251. 

  251.   $ scan-build <b>./configure</b>
    252. 

  252. </pre>
    253. 

  253. 

  254. <p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in
    255. 

  255. most cases will not actually analyze the configure tests run by
    256. 

  256. <tt>configure</tt>.</p>
    257. 

  257. 

  258. <p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to
    259. 

  259. compile the actual code in addition to running the analyzer (which occurs by it
    260. 

  260. calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
    261. 

  261. the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
    262. 

  262. report bugs of this kind).
    263. 

  263.  -->
    264. 

  264. 

  265. <h2 id="iphone">Analyzing iPhone Projects</h2>
    266. 

  266. 

  267. <p>Conceptually Xcode projects for iPhone applications are nearly the same as
    268. 

  268. their cousins for desktop applications. <b>scan-build</b> can analyze these
    269. 

  269. projects as well, but users often encounter problems with just building their
    270. 

  270. iPhone projects from the command line because there are a few extra preparative
    271. 

  271. steps they need to take (e.g., setup code signing).</p>
    272. 

  272. 

  273. <h3>Recommendation: use &quot;Build and Analyze&quot;</h3>
    274. 

  274. 

  275. <p>The absolute easiest way to analyze iPhone projects is to use the <a
    276. 

  276. href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html"><i>Build
    277. 

  277. and Analyze</i> feature in Xcode 3.2</a> (which is based on the Clang Static
    278. 

  278. Analyzer). There a user can analyze their project with the click of a button
    279. 

  279. without most of the setup described later.</p>
    280. 

  280. 

  281. <p><a href="/xcode.html">Instructions are available</a> on this
    282. 

  282. website on how to use open source builds of the analyzer as a replacement for
    283. 

  283. the one bundled with Xcode.</p>
    284. 

  284. 

  285. <h3>Using scan-build directly</h3>
    286. 

  286. 

  287. <p>If you wish to use <b>scan-build</b> with your iPhone project, keep the
    288. 

  288. following things in mind:</p>
    289. 

  289. 

  290. <ul>
    291. 

  291.  <li>Analyze your project in the <tt>Debug</tt> configuration, either by setting
    292. 

  292. this as your configuration with Xcode or by passing <tt>-configuration
    293. 

  293. Debug</tt> to <tt>xcodebuild</tt>.</li>
    294. 

  294.  <li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is
    295. 

  295. possible to analyze your code when targeting the device, but this is much
    296. 

  296. easier to do when using Xcode's <i>Build and Analyze</i> feature.</li>
    297. 

  297.  <li>Check that your code signing SDK is set to the simulator SDK as well, and make sure this option is set to <tt>Don't Code Sign</tt>.</li>
    298. 

  298. </ul>
    299. 

  299. 

  300. <p>Note that you can most of this without actually modifying your project. For
    301. 

  301. example, if your application targets iPhoneOS 2.2, you could run
    302. 

  302. <b>scan-build</b> in the following manner from the command line:</p>
    303. 

  303. 

  304. <pre class="code_example">
    305. 

  305. $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2
    306. 

  306. </pre>
    307. 

  307. 

  308. Alternatively, if your application targets iPhoneOS 3.0:
    309. 

  309. 

  310. <pre class="code_example">
    311. 

  311. $ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0
    312. 

  312. </pre>
    313. 

  313. 

  314. <h3>Gotcha: using the right compiler</h3>
    315. 

  315. 

  316. <p>Recall that <b>scan-build</b> analyzes your project by using a compiler to
    317. 

  317. compile the project and <tt>clang</tt> to analyze your project. The script uses 
    318. 

  318. simple heuristics to determine which compiler should be used (it defaults to 
    319. 

  319. <tt>clang</tt> on Darwin and <tt>gcc</tt> on other platforms). When analyzing
    320. 

  320. iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one
    321. 

  321. Xcode would use to build your project. For example, this could be because 
    322. 

  322. multiple versions of a compiler may be installed on your system, especially if 
    323. 

  323. you are developing for the iPhone.</p>
    324. 

  324. 

  325. <p>When compiling your application to run on the simulator, it is important that <b>scan-build</b>
    326. 

  326. finds the correct version of <tt>gcc/clang</tt>. Otherwise, you may see strange build
    327. 

  327. errors that only happen when you run <tt>scan-build</tt>.
    328. 

  328. 

  329. <p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt>
    330. 

  330. options to hardwire which compiler scan-build should use for building your code.
    331. 

  331. Note that although you are chiefly interested in analyzing your project, keep in
    332. 

  332. mind that running the analyzer is intimately tied to the build, and not being
    333. 

  333. able to compile your code means it won't get fully analyzed (if at all).</p>
    334. 

    335. 

  335. <p>If you aren't certain which compiler Xcode uses to build your project, try
    336. 

  336. just running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the
    337. 

  337. full path to the compiler that Xcode is using, and use that as an argument to
    338. 

  338. <tt>--use-cc</tt>.</p>
    339. 

  339. 

  340. </div>
    341. 

  341. </div>
    342. 

  342. </body>
    343. 

  343. </html>
    344. 

  344. 

  345.