1f4a2713aSLionel Sambuc<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2f4a2713aSLionel Sambuc "http://www.w3.org/TR/html4/strict.dtd"> 3f4a2713aSLionel Sambuc<html> 4f4a2713aSLionel Sambuc<head> 5f4a2713aSLionel Sambuc <title>scan-build: running the analyzer from the command line</title> 6f4a2713aSLionel Sambuc <link type="text/css" rel="stylesheet" href="content.css"> 7f4a2713aSLionel Sambuc <link type="text/css" rel="stylesheet" href="menu.css"> 8f4a2713aSLionel Sambuc <script type="text/javascript" src="scripts/menu.js"></script> 9f4a2713aSLionel Sambuc</head> 10f4a2713aSLionel Sambuc<body> 11f4a2713aSLionel Sambuc 12f4a2713aSLionel Sambuc<div id="page"> 13f4a2713aSLionel Sambuc<!--#include virtual="menu.html.incl"--> 14f4a2713aSLionel Sambuc<div id="content"> 15f4a2713aSLionel Sambuc 16f4a2713aSLionel Sambuc<h1>scan-build: running the analyzer from the command line</h1> 17f4a2713aSLionel Sambuc 18f4a2713aSLionel Sambuc<table style="margin-top:0px" width="100%" cellpadding="0px" cellspacing="0"> 19f4a2713aSLionel Sambuc<tr><td> 20f4a2713aSLionel Sambuc 21f4a2713aSLionel Sambuc<h3>What is it?</h3> 22f4a2713aSLionel Sambuc<p><b>scan-build</b> is a command line utility that enables a user to run the 23f4a2713aSLionel Sambucstatic analyzer over their codebase as part of performing a regular build (from 24f4a2713aSLionel Sambucthe command line).</p> 25f4a2713aSLionel Sambuc 26f4a2713aSLionel Sambuc<h3>How does it work?</h3> 27f4a2713aSLionel Sambuc<p>During a project build, as source files are compiled they are also analyzed 28f4a2713aSLionel Sambucin tandem by the static analyzer.</p> 29f4a2713aSLionel Sambuc 30f4a2713aSLionel Sambuc<p>Upon completion of the build, results are then presented to the user within a 31f4a2713aSLionel Sambucweb browser.</p> 32f4a2713aSLionel Sambuc 33f4a2713aSLionel Sambuc<h3>Will it work with any build system?</h3> 34f4a2713aSLionel Sambuc<p><b>scan-build</b> has little or no knowledge about how you build your code. 35f4a2713aSLionel SambucIt works by overriding the <tt>CC</tt> and <tt>CXX</tt> environment variables to 36f4a2713aSLionel Sambuc(hopefully) change your build to use a "fake" compiler instead of the 37f4a2713aSLionel Sambucone that would normally build your project. This fake compiler executes either 38f4a2713aSLionel Sambuc<tt>clang</tt> or <tt>gcc</tt> (depending on the platform) to compile your 39f4a2713aSLionel Sambuccode and then executes the static analyzer to analyze your code.</p> 40f4a2713aSLionel Sambuc 41f4a2713aSLionel Sambuc<p>This "poor man's interposition" works amazingly well in many cases 42f4a2713aSLionel Sambucand falls down in others. Please consult the information on this page on making 43f4a2713aSLionel Sambucthe best use of <b>scan-build</b>, which includes getting it to work when the 44f4a2713aSLionel Sambucaforementioned hack fails to work.</p> 45f4a2713aSLionel Sambuc 46f4a2713aSLionel Sambuc</td> 47f4a2713aSLionel Sambuc<td style="padding-left:10px; text-align:center"> 48f4a2713aSLionel Sambuc <img src="images/scan_build_cmd.png" width="450px" alt="scan-build"><br> 49f4a2713aSLionel Sambuc <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" alt="analyzer in browser"></a> 50f4a2713aSLionel Sambuc<br><b>Viewing static analyzer results in a web browser</b> 51f4a2713aSLionel Sambuc</td></tr></table> 52f4a2713aSLionel Sambuc 53f4a2713aSLionel Sambuc<h2>Contents</h2> 54f4a2713aSLionel Sambuc 55*0a6a1f1dSLionel Sambuc<ul> 56f4a2713aSLionel Sambuc<li><a href="#scanbuild">Getting Started</a> 57f4a2713aSLionel Sambuc <ul> 58f4a2713aSLionel Sambuc <li><a href="#scanbuild_basicusage">Basic Usage</a></li> 59f4a2713aSLionel Sambuc <li><a href="#scanbuild_forwindowsusers">For Windows Users</a></li> 60f4a2713aSLionel Sambuc <li><a href="#scanbuild_otheroptions">Other Options</a></li> 61f4a2713aSLionel Sambuc <li><a href="#scanbuild_output">Output of scan-build</a></li> 62f4a2713aSLionel Sambuc </ul> 63f4a2713aSLionel Sambuc</li> 64f4a2713aSLionel Sambuc<li><a href="#recommendedguidelines">Recommended Usage Guidelines</a> 65f4a2713aSLionel Sambuc <ul> 66f4a2713aSLionel Sambuc <li><a href="#recommended_debug">Always Analyze a Project in its "Debug" Configuration</a></li> 67f4a2713aSLionel Sambuc <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li> 68f4a2713aSLionel Sambuc <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li> 69f4a2713aSLionel Sambuc </ul> 70f4a2713aSLionel Sambuc</li> 71f4a2713aSLionel Sambuc<li><a href="#iphone">Analyzing iPhone Projects</a></li> 72f4a2713aSLionel Sambuc</ul> 73f4a2713aSLionel Sambuc 74f4a2713aSLionel Sambuc<h2 id="scanbuild">Getting Started</h2> 75f4a2713aSLionel Sambuc 76f4a2713aSLionel Sambuc<p>The <tt>scan-build</tt> command can be used to analyze an entire project by 77f4a2713aSLionel Sambucessentially interposing on a project's build process. This means that to run the 78f4a2713aSLionel Sambucanalyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze 79f4a2713aSLionel Sambucthe source files compiled by <tt>gcc</tt>/<tt>clang</tt> during a project build. 80f4a2713aSLionel SambucThis means that any files that are not compiled will also not be analyzed.</p> 81f4a2713aSLionel Sambuc 82f4a2713aSLionel Sambuc<h3 id="scanbuild_basicusage">Basic Usage</h3> 83f4a2713aSLionel Sambuc 84f4a2713aSLionel Sambuc<p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the 85f4a2713aSLionel Sambucword "scan-build" in front of your build command:</p> 86f4a2713aSLionel Sambuc 87f4a2713aSLionel Sambuc<pre class="code_example"> 88f4a2713aSLionel Sambuc$ <span class="code_highlight">scan-build</span> make 89f4a2713aSLionel Sambuc$ <span class="code_highlight">scan-build</span> xcodebuild 90f4a2713aSLionel Sambuc</pre> 91f4a2713aSLionel Sambuc 92f4a2713aSLionel Sambuc<p>In the first case <tt>scan-build</tt> analyzes the code of a project built 93f4a2713aSLionel Sambucwith <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project 94f4a2713aSLionel Sambucbuilt using <tt>xcodebuild</tt>.<p> 95f4a2713aSLionel Sambuc 96f4a2713aSLionel Sambuc<p>Here is the general format for invoking <tt>scan-build</tt>:</p> 97f4a2713aSLionel Sambuc 98f4a2713aSLionel Sambuc<pre class="code_example"> 99f4a2713aSLionel Sambuc$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight"><command></span> <i>[command options]</i> 100f4a2713aSLionel Sambuc</pre> 101f4a2713aSLionel Sambuc 102f4a2713aSLionel Sambuc<p>Operationally, <tt>scan-build</tt> literally runs <command> with all of the 103f4a2713aSLionel Sambucsubsequent options passed to it. For example, one can pass <tt>-j4</tt> to 104f4a2713aSLionel Sambuc<tt>make</tt> get a parallel build over 4 cores:</p> 105f4a2713aSLionel Sambuc 106f4a2713aSLionel Sambuc<pre class="code_example"> 107f4a2713aSLionel Sambuc$ scan-build make <span class="code_highlight">-j4</span> 108f4a2713aSLionel Sambuc</pre> 109f4a2713aSLionel Sambuc 110f4a2713aSLionel Sambuc<p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the 111f4a2713aSLionel Sambucoptions after the build command; it simply passes them through. In general, 112f4a2713aSLionel Sambuc<tt>scan-build</tt> should support parallel builds, but <b>not distributed 113f4a2713aSLionel Sambucbuilds</b>.</p> 114f4a2713aSLionel Sambuc 115f4a2713aSLionel Sambuc<p>It is also possible to use <tt>scan-build</tt> to analyze specific 116f4a2713aSLionel Sambucfiles:</p> 117f4a2713aSLionel Sambuc 118f4a2713aSLionel Sambuc<pre class="code_example"> 119f4a2713aSLionel Sambuc $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span> 120f4a2713aSLionel Sambuc</pre> 121f4a2713aSLionel Sambuc 122f4a2713aSLionel Sambuc<p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed. 123f4a2713aSLionel Sambuc</p> 124f4a2713aSLionel Sambuc 125f4a2713aSLionel Sambuc<h3 id="scanbuild_forwindowsusers">For Windows Users</h3> 126f4a2713aSLionel Sambuc 127*0a6a1f1dSLionel Sambuc<p>Windows users must have Perl installed to use scan-build.</p> 128f4a2713aSLionel Sambuc 129*0a6a1f1dSLionel Sambuc<p><tt>scan-build.bat</tt> script allows you to launch scan-build in the same 130*0a6a1f1dSLionel Sambucway as it described in the Basic Usage section above. To invoke scan-build from 131*0a6a1f1dSLionel Sambucan arbitrary location, add the path to the folder containing scan-build.bat to 132*0a6a1f1dSLionel Sambucyour PATH environment variable.</p> 133*0a6a1f1dSLionel Sambuc 134*0a6a1f1dSLionel Sambuc<p>If you have unexpected compilation/make problems when running scan-build 135*0a6a1f1dSLionel Sambucwith MinGW/MSYS the following information may be helpful:</p> 136*0a6a1f1dSLionel Sambuc 137*0a6a1f1dSLionel Sambuc<ul> 138*0a6a1f1dSLionel Sambuc <li> If getting unexpected <tt>"fatal error: no input files"</tt> while 139*0a6a1f1dSLionel Sambucbuilding with MSYS make from the Windows cmd, try one of the these 140*0a6a1f1dSLionel Sambucsolutions:</li> 141*0a6a1f1dSLionel Sambuc <ul> 142*0a6a1f1dSLionel Sambuc <li> Use MinGW <tt>mingw32-make</tt> instead of MSYS <tt>make</tt> and 143*0a6a1f1dSLionel Sambucexclude the path to MSYS from PATH to prevent <tt>mingw32-make</tt> from using 144*0a6a1f1dSLionel SambucMSYS utils. MSYS utils are dependent on the MSYS runtime and they are not 145*0a6a1f1dSLionel Sambucintended for being run from the Windows cmd. Specifically, makefile commands 146*0a6a1f1dSLionel Sambucwith backslashed quotes may be heavily corrupted when passed for execution.</li> 147*0a6a1f1dSLionel Sambuc <li> Run <tt>make</tt> from the sh shell: 148*0a6a1f1dSLionel Sambuc<pre class="code_example"> 149*0a6a1f1dSLionel Sambuc$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> sh -c "make <i>[make options]</i>" 150*0a6a1f1dSLionel Sambuc</pre></li> 151*0a6a1f1dSLionel Sambuc </ul> 152*0a6a1f1dSLionel Sambuc <li> If getting <tt>"Error : *** target pattern contains no `%'"</tt> while 153*0a6a1f1dSLionel Sambucusing GNU Make 3.81, try to use another version of make.</li> 154*0a6a1f1dSLionel Sambuc</ul> 155f4a2713aSLionel Sambuc 156f4a2713aSLionel Sambuc<h3 id="scanbuild_otheroptions">Other Options</h3> 157f4a2713aSLionel Sambuc 158f4a2713aSLionel Sambuc<p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These 159f4a2713aSLionel Sambucoptions prefix the build command. For example:</p> 160f4a2713aSLionel Sambuc 161f4a2713aSLionel Sambuc<pre class="code_example"> 162f4a2713aSLionel Sambuc $ scan-build <span class="code_highlight">-k -V</span> make 163f4a2713aSLionel Sambuc $ scan-build <span class="code_highlight">-k -V</span> xcodebuild 164f4a2713aSLionel Sambuc</pre> 165f4a2713aSLionel Sambuc 166f4a2713aSLionel Sambuc<p>Here is a subset of useful options:</p> 167f4a2713aSLionel Sambuc 168f4a2713aSLionel Sambuc<table class="options"> 169f4a2713aSLionel Sambuc<colgroup><col class="option"><col class="description"></colgroup> 170f4a2713aSLionel Sambuc<thead><tr><td>Option</td><td>Description</td></tr></thead> 171f4a2713aSLionel Sambuc 172f4a2713aSLionel Sambuc<tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories 173f4a2713aSLionel Sambucwill be created as needed to represent separate "runs" of the analyzer. If this 174f4a2713aSLionel Sambucoption is not specified, a directory is created in <tt>/tmp</tt> to store the 175f4a2713aSLionel Sambucreports.</td></tr> 176f4a2713aSLionel Sambuc 177f4a2713aSLionel Sambuc<tr><td><b>-h</b><br><i>(or no arguments)</i></td><td>Display all 178f4a2713aSLionel Sambuc<tt>scan-build</tt> options.</td></tr> 179f4a2713aSLionel Sambuc 180f4a2713aSLionel Sambuc<tr><td><b>-k</b><br><b>--keep-going</b></td><td>Add a "keep on 181f4a2713aSLionel Sambucgoing" option to the specified build command. <p>This option currently supports 182f4a2713aSLionel Sambuc<tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one 183f4a2713aSLionel Sambuccan specify this behavior directly using build options.</p></td></tr> 184f4a2713aSLionel Sambuc 185f4a2713aSLionel Sambuc<tr><td><b>-v</b></td><td>Verbose output from scan-build and the analyzer. <b>A 186f4a2713aSLionel Sambucsecond and third "-v" increases verbosity</b>, and is useful for filing bug 187f4a2713aSLionel Sambucreports against the analyzer.</td></tr> 188f4a2713aSLionel Sambuc 189f4a2713aSLionel Sambuc<tr><td><b>-V</b></td><td>View analysis results in a web browser when the build 190f4a2713aSLionel Sambuccommand completes.</td></tr> 191f4a2713aSLionel Sambuc 192f4a2713aSLionel Sambuc<tr><td><b>--use-analyzer Xcode</b><br><i>or</i><br> 193f4a2713aSLionel Sambuc<b>--use-analyzer [path to clang]</b></td><td><tt>scan-build</tt> uses the 194f4a2713aSLionel Sambuc'clang' executable relative to itself for static analysis. One can override this 195f4a2713aSLionel Sambucbehavior with this option by using the 'clang' packaged with Xcode (on OS X) or 196f4a2713aSLionel Sambucfrom the PATH.</p></td></tr> </table> 197f4a2713aSLionel Sambuc 198f4a2713aSLionel Sambuc<p>A complete list of options can be obtained by running <tt>scan-build</tt> 199f4a2713aSLionel Sambucwith no arguments.</p> 200f4a2713aSLionel Sambuc 201f4a2713aSLionel Sambuc<h3 id="scanbuild_output">Output of scan-build</h3> 202f4a2713aSLionel Sambuc 203f4a2713aSLionel Sambuc<p> 204f4a2713aSLionel SambucThe output of scan-build is a set of HTML files, each one which represents a 205f4a2713aSLionel Sambucseparate bug report. A single <tt>index.html</tt> file is generated for 206f4a2713aSLionel Sambucsurveying all of the bugs. You can then just open <tt>index.html</tt> in a web 207f4a2713aSLionel Sambucbrowser to view the bug reports. 208f4a2713aSLionel Sambuc</p> 209f4a2713aSLionel Sambuc 210f4a2713aSLionel Sambuc<p> 211f4a2713aSLionel SambucWhere the HTML files are generated is specified with a <b>-o</b> option to 212f4a2713aSLionel Sambuc<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt> 213f4a2713aSLionel Sambucis created to store the files (<tt>scan-build</tt> will print a message telling 214f4a2713aSLionel Sambucyou where they are). If you want to view the reports immediately after the build 215f4a2713aSLionel Sambuccompletes, pass <b>-V</b> to <tt>scan-build</tt>. 216f4a2713aSLionel Sambuc</p> 217f4a2713aSLionel Sambuc 218f4a2713aSLionel Sambuc 219f4a2713aSLionel Sambuc<h2 id="recommendedguidelines">Recommended Usage Guidelines</h2> 220f4a2713aSLionel Sambuc 221f4a2713aSLionel Sambuc<p>This section describes a few recommendations with running the analyzer.</p> 222f4a2713aSLionel Sambuc 223f4a2713aSLionel Sambuc<h3 id="recommended_debug">ALWAYS analyze a project in its "debug" configuration</h3> 224f4a2713aSLionel Sambuc 225f4a2713aSLionel Sambuc<p>Most projects can be built in a "debug" mode that enables assertions. 226f4a2713aSLionel SambucAssertions are picked up by the static analyzer to prune infeasible paths, which 227f4a2713aSLionel Sambucin some cases can greatly reduce the number of false positives (bogus error 228f4a2713aSLionel Sambucreports) emitted by the tool.</p> 229f4a2713aSLionel Sambuc 230f4a2713aSLionel Sambuc<h3 id="recommend_verbose">Use verbose output when debugging scan-build</h3> 231f4a2713aSLionel Sambuc 232f4a2713aSLionel Sambuc<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about 233f4a2713aSLionel Sambucwhat it's doing; two <b>-v</b> options emit more information. Redirecting the 234f4a2713aSLionel Sambucoutput of <tt>scan-build</tt> to a text file (make sure to redirect standard 235f4a2713aSLionel Sambucerror) is useful for filing bug reports against <tt>scan-build</tt> or the 236f4a2713aSLionel Sambucanalyzer, as we can see the exact options (and files) passed to the analyzer. 237f4a2713aSLionel SambucFor more comprehensible logs, don't perform a parallel build.</p> 238f4a2713aSLionel Sambuc 239f4a2713aSLionel Sambuc<h3 id="recommended_autoconf">Run './configure' through scan-build</h3> 240f4a2713aSLionel Sambuc 241f4a2713aSLionel Sambuc<p>If an analyzed project uses an autoconf generated <tt>configure</tt> script, 242f4a2713aSLionel Sambucyou will probably need to run <tt>configure</tt> script through 243f4a2713aSLionel Sambuc<tt>scan-build</tt> in order to analyze the project.</p> 244f4a2713aSLionel Sambuc 245f4a2713aSLionel Sambuc<p><b>Example</b></p> 246f4a2713aSLionel Sambuc 247f4a2713aSLionel Sambuc<pre class="code_example"> 248f4a2713aSLionel Sambuc$ scan-build ./configure 249f4a2713aSLionel Sambuc$ scan-build make 250f4a2713aSLionel Sambuc</pre> 251f4a2713aSLionel Sambuc 252f4a2713aSLionel Sambuc<p>The reason <tt>configure</tt> also needs to be run through 253f4a2713aSLionel Sambuc<tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by 254f4a2713aSLionel Sambuc<i>interposing</i> on the compiler. This interposition is currently done by 255f4a2713aSLionel Sambuc<tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to 256f4a2713aSLionel Sambuc<tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake 257f4a2713aSLionel Sambuccompiler, forwarding its command line arguments over to the compiler to perform 258f4a2713aSLionel Sambucregular compilation and <tt>clang</tt> to perform static analysis.</p> 259f4a2713aSLionel Sambuc 260f4a2713aSLionel Sambuc<p>Running <tt>configure</tt> typically generates makefiles that have hardwired 261f4a2713aSLionel Sambucpaths to the compiler, and by running <tt>configure</tt> through 262f4a2713aSLionel Sambuc<tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p> 263f4a2713aSLionel Sambuc 264f4a2713aSLionel Sambuc<!-- 265f4a2713aSLionel Sambuc<h2 id="Debugging">Debugging the Analyzer</h2> 266f4a2713aSLionel Sambuc 267f4a2713aSLionel Sambuc<p>This section provides information on debugging the analyzer, and troubleshooting 268f4a2713aSLionel Sambucit when you have problems analyzing a particular project.</p> 269f4a2713aSLionel Sambuc 270f4a2713aSLionel Sambuc<h3>How it Works</h3> 271f4a2713aSLionel Sambuc 272f4a2713aSLionel Sambuc<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable 273f4a2713aSLionel Sambuc<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other 274f4a2713aSLionel Sambucenvironment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML 275f4a2713aSLionel Sambucreport files.</p> 276f4a2713aSLionel Sambuc 277f4a2713aSLionel Sambuc<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such 278f4a2713aSLionel Sambucprojects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be 279f4a2713aSLionel Sambuccalled. This will cause the compiled code <b>to not be analyzed.</b></p> If you 280f4a2713aSLionel Sambucfind that your code isn't being analyzed, check to see if <tt>CC</tt> is 281f4a2713aSLionel Sambuchardcoded. If this is the case, you can hardcode it instead to the <b>full 282f4a2713aSLionel Sambucpath</b> to <tt>ccc-analyzer</tt>.</p> 283f4a2713aSLionel Sambuc 284f4a2713aSLionel Sambuc<p>When applicable, you can also run <tt>./configure</tt> for a project through 285f4a2713aSLionel Sambuc<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based 286f4a2713aSLionel Sambucon the environment passed in from <tt>scan-build</tt>: 287f4a2713aSLionel Sambuc 288f4a2713aSLionel Sambuc<pre> 289f4a2713aSLionel Sambuc $ scan-build <b>./configure</b> 290f4a2713aSLionel Sambuc</pre> 291f4a2713aSLionel Sambuc 292f4a2713aSLionel Sambuc<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in 293f4a2713aSLionel Sambucmost cases will not actually analyze the configure tests run by 294f4a2713aSLionel Sambuc<tt>configure</tt>.</p> 295f4a2713aSLionel Sambuc 296f4a2713aSLionel Sambuc<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to 297f4a2713aSLionel Sambuccompile the actual code in addition to running the analyzer (which occurs by it 298f4a2713aSLionel Sambuccalling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all 299f4a2713aSLionel Sambucthe arguments over to <tt>gcc</tt>, but this may not work perfectly (please 300f4a2713aSLionel Sambucreport bugs of this kind). 301f4a2713aSLionel Sambuc --> 302f4a2713aSLionel Sambuc 303f4a2713aSLionel Sambuc<h2 id="iphone">Analyzing iPhone Projects</h2> 304f4a2713aSLionel Sambuc 305f4a2713aSLionel Sambuc<p>Conceptually Xcode projects for iPhone applications are nearly the same as 306f4a2713aSLionel Sambuctheir cousins for desktop applications. <b>scan-build</b> can analyze these 307f4a2713aSLionel Sambucprojects as well, but users often encounter problems with just building their 308f4a2713aSLionel SambuciPhone projects from the command line because there are a few extra preparative 309f4a2713aSLionel Sambucsteps they need to take (e.g., setup code signing).</p> 310f4a2713aSLionel Sambuc 311f4a2713aSLionel Sambuc<h3>Recommendation: use "Build and Analyze"</h3> 312f4a2713aSLionel Sambuc 313f4a2713aSLionel Sambuc<p>The absolute easiest way to analyze iPhone projects is to use the <a 314f4a2713aSLionel Sambuchref="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html"><i>Build 315f4a2713aSLionel Sambucand Analyze</i> feature in Xcode 3.2</a> (which is based on the Clang Static 316f4a2713aSLionel SambucAnalyzer). There a user can analyze their project with the click of a button 317f4a2713aSLionel Sambucwithout most of the setup described later.</p> 318f4a2713aSLionel Sambuc 319f4a2713aSLionel Sambuc<p><a href="/xcode.html">Instructions are available</a> on this 320f4a2713aSLionel Sambucwebsite on how to use open source builds of the analyzer as a replacement for 321f4a2713aSLionel Sambucthe one bundled with Xcode.</p> 322f4a2713aSLionel Sambuc 323f4a2713aSLionel Sambuc<h3>Using scan-build directly</h3> 324f4a2713aSLionel Sambuc 325f4a2713aSLionel Sambuc<p>If you wish to use <b>scan-build</b> with your iPhone project, keep the 326f4a2713aSLionel Sambucfollowing things in mind:</p> 327f4a2713aSLionel Sambuc 328f4a2713aSLionel Sambuc<ul> 329f4a2713aSLionel Sambuc <li>Analyze your project in the <tt>Debug</tt> configuration, either by setting 330f4a2713aSLionel Sambucthis as your configuration with Xcode or by passing <tt>-configuration 331f4a2713aSLionel SambucDebug</tt> to <tt>xcodebuild</tt>.</li> 332f4a2713aSLionel Sambuc <li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is 333f4a2713aSLionel Sambucpossible to analyze your code when targeting the device, but this is much 334f4a2713aSLionel Sambuceasier to do when using Xcode's <i>Build and Analyze</i> feature.</li> 335f4a2713aSLionel Sambuc <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> 336f4a2713aSLionel Sambuc</ul> 337f4a2713aSLionel Sambuc 338f4a2713aSLionel Sambuc<p>Note that you can most of this without actually modifying your project. For 339f4a2713aSLionel Sambucexample, if your application targets iPhoneOS 2.2, you could run 340f4a2713aSLionel Sambuc<b>scan-build</b> in the following manner from the command line:</p> 341f4a2713aSLionel Sambuc 342f4a2713aSLionel Sambuc<pre class="code_example"> 343f4a2713aSLionel Sambuc$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2 344f4a2713aSLionel Sambuc</pre> 345f4a2713aSLionel Sambuc 346f4a2713aSLionel SambucAlternatively, if your application targets iPhoneOS 3.0: 347f4a2713aSLionel Sambuc 348f4a2713aSLionel Sambuc<pre class="code_example"> 349f4a2713aSLionel Sambuc$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0 350f4a2713aSLionel Sambuc</pre> 351f4a2713aSLionel Sambuc 352f4a2713aSLionel Sambuc<h3>Gotcha: using the right compiler</h3> 353f4a2713aSLionel Sambuc 354f4a2713aSLionel Sambuc<p>Recall that <b>scan-build</b> analyzes your project by using a compiler to 355f4a2713aSLionel Sambuccompile the project and <tt>clang</tt> to analyze your project. The script uses 356f4a2713aSLionel Sambucsimple heuristics to determine which compiler should be used (it defaults to 357f4a2713aSLionel Sambuc<tt>clang</tt> on Darwin and <tt>gcc</tt> on other platforms). When analyzing 358f4a2713aSLionel SambuciPhone projects, <b>scan-build</b> may pick the wrong compiler than the one 359f4a2713aSLionel SambucXcode would use to build your project. For example, this could be because 360f4a2713aSLionel Sambucmultiple versions of a compiler may be installed on your system, especially if 361f4a2713aSLionel Sambucyou are developing for the iPhone.</p> 362f4a2713aSLionel Sambuc 363f4a2713aSLionel Sambuc<p>When compiling your application to run on the simulator, it is important that <b>scan-build</b> 364f4a2713aSLionel Sambucfinds the correct version of <tt>gcc/clang</tt>. Otherwise, you may see strange build 365f4a2713aSLionel Sambucerrors that only happen when you run <tt>scan-build</tt>. 366f4a2713aSLionel Sambuc 367f4a2713aSLionel Sambuc<p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt> 368f4a2713aSLionel Sambucoptions to hardwire which compiler scan-build should use for building your code. 369f4a2713aSLionel SambucNote that although you are chiefly interested in analyzing your project, keep in 370f4a2713aSLionel Sambucmind that running the analyzer is intimately tied to the build, and not being 371f4a2713aSLionel Sambucable to compile your code means it won't get fully analyzed (if at all).</p> 372f4a2713aSLionel Sambuc 373f4a2713aSLionel Sambuc<p>If you aren't certain which compiler Xcode uses to build your project, try 374f4a2713aSLionel Sambucjust running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the 375f4a2713aSLionel Sambucfull path to the compiler that Xcode is using, and use that as an argument to 376f4a2713aSLionel Sambuc<tt>--use-cc</tt>.</p> 377f4a2713aSLionel Sambuc 378f4a2713aSLionel Sambuc</div> 379f4a2713aSLionel Sambuc</div> 380f4a2713aSLionel Sambuc</body> 381f4a2713aSLionel Sambuc</html> 382f4a2713aSLionel Sambuc 383
