| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +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>Build and Analyze: running the analyzer within Xcode</title> |
| 6 | <link type="text/css" rel="stylesheet" href="content.css" /> |
| 7 | <link type="text/css" rel="stylesheet" href="menu.css" /> |
| 8 | <script type="text/javascript" src="scripts/menu.js"></script> |
| 9 | <script type="text/javascript" src="scripts/dbtree.js"></script> |
| 10 | </head> |
| 11 | <body> |
| 12 | |
| 13 | <div id="page"> |
| 14 | <!--#include virtual="menu.html.incl"--> |
| 15 | <div id="content"> |
| 16 | |
| 17 | <h1>Build and Analyze: running the analyzer within Xcode</h1> |
| 18 | |
| 19 | <table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0"> |
| 20 | <tr><td> |
| 21 | |
| 22 | <h3>What is it?</h3> |
| 23 | <p><i>Build and Analyze</i> is an Xcode feature (introduced in Xcode 3.2) that |
| 24 | allows users to run the Clang Static Analyzer <a |
| 25 | href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html">directly |
| 26 | within Xcode</a>.</p> |
| 27 | |
| 28 | <p>It integrates directly with the Xcode build system and |
| 29 | presents analysis results directly within Xcode's editor.</p> |
| 30 | |
| 31 | <h3>Can I use the open source analyzer builds with Xcode?</h3> |
| 32 | |
| 33 | <p><b>Yes</b>. Instructions are included below.</p> |
| 34 | |
| 35 | </td> |
| 36 | <td style="padding-left:10px"> |
| 37 | <center> |
| Ted Kremenek | 631bde5 | 2010-02-19 18:12:09 +0000 | [diff] [blame] | 38 | <a href="images/analyzer_xcode.png"><img src="images/analyzer_xcode.png" width="620px" border=0></a> |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 39 | <br><b>Viewing static analyzer results in Xcode</b></center> |
| 40 | </td></tr></table> |
| 41 | |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 42 | <h3>Key features:</h3> |
| 43 | <ul> |
| 44 | <li><b>Integrated workflow:</b> Results are integrated within Xcode. There is |
| 45 | no experience of using a separate tool, and activating the analyzer requires a |
| 46 | single keystroke or mouse click.</li> |
| 47 | <li><b>Transparency:</b> Works effortlessly with Xcode projects (including iPhone projects). |
| 48 | <li><b>Cons:</b> Doesn't work well with non-Xcode projects. For those, |
| Ted Kremenek | 4d9d49a | 2010-02-19 17:33:30 +0000 | [diff] [blame] | 49 | consider using <a href="/scan-build.html"><b>scan-build</b></a>. |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 50 | </ul> |
| Ted Kremenek | 4d9d49a | 2010-02-19 17:33:30 +0000 | [diff] [blame] | 51 | |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 52 | |
| 53 | <h2>Getting Started</h2> |
| 54 | |
| 55 | <p>Xcode 3.2 is available as a free download from Apple, with <a |
| 56 | href="http://developer.apple.com/mac/library/featuredarticles/StaticAnalysis/index.html">instructions available</a> |
| 57 | for using <i>Build and Analyze</i>.</p> |
| 58 | |
| 59 | <h2>Using open source analyzer builds with <i>Build and Analyze</i></h2> |
| 60 | |
| 61 | <p>By default, Xcode uses the version of <tt>clang</tt> that came bundled with |
| 62 | it to provide the results for <i>Build and Analyze</i>. It is possible to change |
| 63 | Xcode's behavior to use an alternate version of <tt>clang</tt> for this purpose |
| 64 | while continuing to use the <tt>clang</tt> that came with Xcode for compiling |
| 65 | projects.</p> |
| 66 | |
| 67 | <h3>Why try open source builds?</h3> |
| 68 | |
| 69 | <p>The advantage of using open source analyzer builds (provided on this website) |
| 70 | is that they are often newer than the analyzer provided with Xcode, and thus can |
| 71 | contain bug fixes, new checks, or simply better analysis.</p> |
| 72 | |
| 73 | <p>On the other hand, new checks can be experimental, with results of variable |
| 74 | quality. Users are encouraged to <a href="filing_bugs.html">file bug reports</a> |
| 75 | (for any version of the analyzer) where they encounter false positives or other |
| 76 | issues.</p> |
| 77 | |
| 78 | <h3>set-xcode-analyzer</h3> |
| 79 | |
| 80 | <p>Starting with analyzer build checker-234, analyzer builds contain a command |
| 81 | line utility called <tt>set-xcode-analyzer</tt> that allows users to change what |
| 82 | copy of <tt>clang</tt> that Xcode uses for <i>Build and Analyze</i>:</p> |
| 83 | |
| 84 | <pre class="code_example"> |
| 85 | $ <b>set-xcode-analyzer -h</b> |
| 86 | Usage: set-xcode-analyzer [options] |
| 87 | |
| 88 | Options: |
| 89 | -h, --help show this help message and exit |
| 90 | --use-checker-build=PATH |
| 91 | Use the Clang located at the provided absolute path, |
| 92 | e.g. /Users/foo/checker-1 |
| 93 | --use-xcode-clang Use the Clang bundled with Xcode |
| 94 | </pre> |
| 95 | |
| 96 | <p>Operationally, <b>set-xcode-analyzer</b> edits Xcode's configuration files |
| 97 | (in <tt>/Developer</tt>) to point it to use the version of <tt>clang</tt> you |
| 98 | specify for static analysis. Within this model it provides you two basic modes:</p> |
| 99 | |
| 100 | <ul> |
| 101 | <li><b>--use-xcode-clang</b>: Switch Xcode (back) to using the <tt>clang</tt> that came bundled with it for static analysis.</li> |
| 102 | <li><b>--use-checker-build</b>: Switch Xcode to using the <tt>clang</tt> provided by the specified analyzer build.</li> |
| 103 | </ul> |
| 104 | |
| 105 | <h4>Examples</h4> |
| 106 | |
| Ted Kremenek | 8c0b964 | 2010-02-19 08:24:37 +0000 | [diff] [blame] | 107 | <p><b>Example 1</b>: Telling Xcode to use checker-235 for <i>Build and Analyze</i>:</p> |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 108 | |
| 109 | <pre class="code_example"> |
| 110 | $ pwd |
| 111 | /tmp |
| 112 | $ tar xjf checker-235.tar.bz2 |
| 113 | $ checker-235/set-xcode-analyzer --use-checker-build=/tmp/checker-235 |
| 114 | </pre> |
| 115 | |
| Ted Kremenek | 8c0b964 | 2010-02-19 08:24:37 +0000 | [diff] [blame] | 116 | <p>Note that you typically won't install an analyzer build in <tt>/tmp</tt>, but |
| 117 | the point of this example is that <tt>set-xcode-analyzer</tt> just wants a full |
| 118 | path to an untarred analyzer build.</p> |
| 119 | |
| 120 | <p><b>Example 2</b>: Telling Xcode to use a very specific version of <tt>clang</tt>:</p> |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 121 | |
| 122 | <pre class="code_example"> |
| 123 | $ set-xcode-analyzer --use-checker-build=~/mycrazyclangbuild/bin/clang |
| 124 | </pre> |
| 125 | |
| Ted Kremenek | 8c0b964 | 2010-02-19 08:24:37 +0000 | [diff] [blame] | 126 | <p><b>Example 3</b>: Resetting Xcode to its default behavior:</p> |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 127 | |
| 128 | <pre class="code_example"> |
| Ted Kremenek | 1a202b4 | 2010-02-28 05:14:08 +0000 | [diff] [blame] | 129 | $ set-xcode-analyzer --use-xcode-clang |
| Ted Kremenek | 0f39996 | 2010-02-19 08:14:02 +0000 | [diff] [blame] | 130 | </pre> |
| 131 | |
| 132 | </div> |
| 133 | </div> |
| 134 | </body> |
| 135 | </html> |
| 136 | |