clang/www/analyzer/index.html

   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>Clang Static Analyzer</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   <!-- Generated from: http://www.spiffycorners.com/index.php -->
  10
  11 <style type="text/css">
  12 .spiffy{display:block}
  13 .spiffy *{
  14   display:block;
  15   height:1px;
  16   overflow:hidden;
  17   font-size:.01em;
  18   background:#EBF0FA}
  19 .spiffy1{
  20   margin-left:3px;
  21   margin-right:3px;
  22   padding-left:1px;
  23   padding-right:1px;
  24   border-left:1px solid #f6f8fc;
  25   border-right:1px solid #f6f8fc;
  26   background:#f0f3fb}
  27 .spiffy2{
  28   margin-left:1px;
  29   margin-right:1px;
  30   padding-right:1px;
  31   padding-left:1px;
  32   border-left:1px solid #fdfdfe;
  33   border-right:1px solid #fdfdfe;
  34   background:#eef2fa}
  35 .spiffy3{
  36   margin-left:1px;
  37   margin-right:1px;
  38   border-left:1px solid #eef2fa;
  39   border-right:1px solid #eef2fa;}
  40 .spiffy4{
  41   border-left:1px solid #f6f8fc;
  42   border-right:1px solid #f6f8fc}
  43 .spiffy5{
  44   border-left:1px solid #f0f3fb;
  45   border-right:1px solid #f0f3fb}
  46 .spiffyfg{
  47   background:#EBF0FA}
  48
  49 .spiffyfg h2 {
  50   margin:0px;  padding:10px;
  51 }
  52
  53   #left { float:left; }
  54   #left h2 { margin:1px; padding-top:0px; }
  55   #right { float:left; margin-left:20px; margin-right:20px; padding:0px ;}
  56   #right h2 { padding:0px; margin:0px; }
  57   #wrappedcontent { padding:15px;}
  58 </style>
  59 </head>
  60 <body>
  61
  62 <div id="page">
  63 <!--#include virtual="menu.html.incl"-->
  64 <div id="content">
  65
  66
  67 <table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0">
  68 <tr><td>
  69
  70 <h1>Clang Static Analyzer</h1>
  71
  72 <p>The Clang Static Analyzer is a source code analysis tool that finds bugs in
  73 C, C++, and Objective-C programs.</p>
  74
  75 <p>The analyzer is 100% open source and is part of the <a href="https://clang.llvm.org">Clang</a>
  76 project. Like the rest of Clang, the analyzer is implemented as a C++ library
  77 that can be used by other tools and applications.</p>
  78
  79 <div style="padding:0; margin-top:10px; font-size: 90%">
  80  <b class="spiffy">
  81  <b class="spiffy1"><b></b></b>
  82  <b class="spiffy2"><b></b></b>
  83  <b class="spiffy3"></b>
  84  <b class="spiffy4"></b>
  85  <b class="spiffy5"></b></b>
  86  <div class="spiffyfg">
  87   <div style="padding:15px">
  88
  89     <p>To get started with the Clang Static Analyzer, visit the
  90     <a href="https://releases.llvm.org/download.html">LLVM
  91     releases page</a> for download and installation instructions. The official
  92     releases include both the analyzer and <a href="scan-build.html">scan-build</a>,
  93     a command-line tool for running the analyzer on your codebase.</p>
  94
  95     <p>If you're installing Clang from a different source, such as
  96     a Linux package repository, then scan-build may be packaged
  97     separately as an individual package, or as part of
  98     a "clang tools" package.</p>
  99
 100     <p>If your IDE is using Clang, it may natively integrate the static analyzer.
 101     On macOS, the easiest way to use the static analyzer is to invoke it
 102     <a href="https://clang.llvm.org/docs/analyzer/user-docs/UsingWithXCode.html">directly
 103     from Xcode</a>.</p>
 104
 105     <p>Additionally, if you're using <a href="https://clang.llvm.org/extra/clang-tidy/">clang-tidy</a>,
 106     you can naturally make the static analyzer run alongside clang-tidy
 107     by enabling the <a href="https://clang.llvm.org/extra/clang-tidy/checks/list.html">clang-analyzer</a>
 108     checks.</p>
 109   </div>
 110  </div>
 111  <b class="spiffy">
 112  <b class="spiffy5"></b>
 113  <b class="spiffy4"></b>
 114  <b class="spiffy3"></b>
 115  <b class="spiffy2"><b></b></b>
 116  <b class="spiffy1"><b></b></b></b>
 117 </div>
 118
 119
 120 </td><td style="padding-left:10px">
 121 <a href="images/analyzer_xcode.png"><img src="images/analyzer_xcode.png" width="450" alt="analyzer in xcode"></a>
 122 <div style="text-align:center"><b>Viewing static analyzer results in Xcode</b></div>
 123 <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450" alt="analyzer in browser"></a>
 124 <div style="text-align:center"><b>Viewing static analyzer results in a web browser</b></div>
 125 </td></tr></table>
 126
 127 <h2 id="StaticAnalysis">What is Static Analysis?</h2>
 128
 129 <p>The term "static analysis" is conflated, but here we use it to mean
 130 a collection of algorithms and techniques used to analyze source code in order
 131 to automatically find bugs. The idea is similar in spirit to compiler warnings
 132 (which can be useful for finding coding errors) but to take that idea a step
 133 further and find bugs that are traditionally found using run-time debugging
 134 techniques such as testing.</p>
 135
 136 <p>Static analysis bug-finding tools have evolved over the last several decades
 137 from basic syntactic checkers to those that find deep bugs by reasoning about
 138 the semantics of code. The goal of the Clang Static Analyzer is to provide a
 139 industrial-quality static analysis framework for analyzing C, C++, and
 140 Objective-C programs that is freely available, extensible, and has a high quality of implementation.</p>
 141
 142 <h3 id="Clang">Part of Clang and LLVM</h3>
 143
 144 <p>As its name implies, the Clang Static Analyzer is built on top of <a
 145 href="https://clang.llvm.org">Clang</a> and <a href="https://llvm.org">LLVM</a>.
 146 Strictly speaking, the analyzer is part of Clang, as Clang consists of a set of
 147 reusable C++ libraries for building powerful source-level tools. The static
 148 analysis engine used by the Clang Static Analyzer is a Clang library, and has
 149 the capability to be reused in different contexts and by different clients.</p>
 150
 151 <h2>Important Points to Consider</h2>
 152
 153 <p>While we believe that the static analyzer is already very useful for finding
 154 bugs, we ask you to bear in mind a few points when using it.</p>
 155
 156 <h3>Work-in-Progress</h3>
 157
 158 <p>The analyzer is a continuous work-in-progress. There are many planned
 159 enhancements to improve both the precision and scope of its analysis algorithms
 160 as well as the kinds of bugs it will find. While there are fundamental
 161 limitations to what static analysis can do, we have a long way to go before
 162 hitting that wall.</p>
 163
 164 <h3>Slower than Compilation</h3>
 165
 166 <p>Operationally, using static analysis to
 167 automatically find deep program bugs is about trading CPU time for the hardening
 168 of code. Because of the deep analysis performed by state-of-the-art static
 169 analysis tools, static analysis can be much slower than compilation.</p>
 170
 171 <p>While the Clang Static Analyzer is being designed to be as fast and
 172 light-weight as possible, please do not expect it to be as fast as compiling a
 173 program (even with optimizations enabled). Some of the algorithms needed to find
 174 bugs require in the worst case exponential time.</p>
 175
 176 <p>The Clang Static Analyzer runs in a reasonable amount of time by both
 177 bounding the amount of checking work it will do as well as using clever
 178 algorithms to reduce the amount of work it must do to find bugs.</p>
 179
 180 <h3>False Positives</h3>
 181
 182 <p>Static analysis is not perfect. It can falsely flag bugs in a program where
 183 the code behaves correctly. Because some code checks require more analysis
 184 precision than others, the frequency of false positives can vary widely between
 185 different checks. Our long-term goal is to have the analyzer have a low false
 186 positive rate for most code on all checks.</p>
 187
 188 <p>Please help us in this endeavor by <a href="filing_bugs.html">reporting false
 189 positives</a>. False positives cannot be addressed unless we know about
 190 them.</p>
 191
 192 <h3>More Checks</h3>
 193
 194 <p>Static analysis is not magic; a static analyzer can only find bugs that it
 195 has been specifically engineered to find. If there are specific kinds of bugs
 196 you would like the Clang Static Analyzer to find, please feel free to
 197 file <a href="filing_bugs.html">feature requests</a> or contribute your own
 198 patches.</p>
 199
 200 </div>
 201 </div>
 202 </body>
 203 </html>