diff options
| author | Endre Fülöp <endre.fulop@sigmatechnology.com> | 2024-07-05 08:16:53 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2024-07-05 08:16:53 +0200 |
| commit | 093aaca2b0ad23ded5dcb45e8f837ffb7b21ffb3 (patch) | |
| tree | c4f899a98edd404ad94f75a541441950303287a3 /clang/www | |
| parent | 7c4dbad550cfed8c501fb82ad0883542ac989b35 (diff) | |
| download | llvm-093aaca2b0ad23ded5dcb45e8f837ffb7b21ffb3.zip llvm-093aaca2b0ad23ded5dcb45e8f837ffb7b21ffb3.tar.gz llvm-093aaca2b0ad23ded5dcb45e8f837ffb7b21ffb3.tar.bz2 | |
[clang][analyzer][doc] Migrate user-related docs from HTML to RST (#97034)
User documentation currently found at https://clang-analyzer.llvm.org is migrated to RST format.
This commit migrates all the relevant content, including suspicious or even clearly outdated parts. These issues will be cleaned up in separate follow-up commits (where the diff is not obscured by the format change). However, a few typos are fixed, and some parts (availability of binary releases, integration with XCode) are marked (with [Legacy] tags) to highlight that they are outdated.
The primary motivation for this change is to update the facts in the docs and make them discoverable from the RST-generated doc-tree as well (many subpages are not accessible at all, as the menu generation for the HTML-based page is not working at all).
This commit migrates all the relevant content, including parts that are
suspicious or even clearly outdated. These issues will be cleaned up in
separate follow-up commits (where the diff is not obscured by the format
change). However, a few typos are fixed and some parts (availability of
binary releases, integration with XCode) are marked (with [Legacy] tags)
to highlight that they are outdated.
The primary motivation for this change is to update the facts in the
docs and make them discoverable from the RST-generated doc-tree as well
(many subpages are not accessible **at all**, as the menu generation for
the HTML based page is not working at all).
Diffstat (limited to 'clang/www')
| -rw-r--r-- | clang/www/analyzer/codechecker.html | 68 | ||||
| -rw-r--r-- | clang/www/analyzer/command-line.html | 61 | ||||
| -rw-r--r-- | clang/www/analyzer/filing_bugs.html | 37 | ||||
| -rw-r--r-- | clang/www/analyzer/index.html | 2 | ||||
| -rw-r--r-- | clang/www/analyzer/installation.html | 103 | ||||
| -rw-r--r-- | clang/www/analyzer/latest_checker.html.incl | 1 | ||||
| -rw-r--r-- | clang/www/analyzer/scan-build.html | 376 | ||||
| -rw-r--r-- | clang/www/analyzer/xcode.html | 136 |
8 files changed, 57 insertions, 727 deletions
diff --git a/clang/www/analyzer/codechecker.html b/clang/www/analyzer/codechecker.html index 469b3ce..6f6b489 100644 --- a/clang/www/analyzer/codechecker.html +++ b/clang/www/analyzer/codechecker.html @@ -2,7 +2,9 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> - <title>CodeChecker: running the analyzer from the command line</title> + <title>The CodeChecker documentation has moved to clang.llvm.org</title> + <link rel="canonical" href="https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#codechecker"/> + <meta http-equiv="refresh" content="0;url=https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#codechecker" /> <link type="text/css" rel="stylesheet" href="content.css"> <link type="text/css" rel="stylesheet" href="menu.css"> <script type="text/javascript" src="scripts/menu.js"></script> @@ -13,61 +15,11 @@ <!--#include virtual="menu.html.incl"--> <div id="content"> -<h1>CodeChecker: running the analyzer from the command line</h1> +<h1>The Codechecker documentation has moved to clang.llvm.org</h1> +<p style="color:red; font-size:200%">This page is deprecated and will be removed in release 21.0</p> +<a href="https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#codechecker">The new site</a> +<script>window.location='https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#codechecker'</script> -<h2>Basic Usage</h2> - -<p> -Install CodeChecker as described here: <a href="https://github.com/Ericsson/codechecker/#Install-guide"> CodeChecker Install Guide.</a> -</p> - -<p> -Create a compilation database. If you use cmake then pass the <tt>-DCMAKE_EXPORT_COMPILE_COMMANDS=1</tt> parameter to cmake. Cmake will create a <tt>compile_commands.json</tt> file. -If you have a Makefile based or similar build system then you can log the build commands with the help of CodeChecker: -<pre class="code_example"> -make clean -CodeChecker log -b "make" -o compile_commands.json -</pre> -</p> - -<p> -Analyze your project. -<pre class="code_example"> -CodeChecker analyze compile_commands.json -o ./reports -</pre> -</p> - -<p> -View the analysis results. -Print the detailed results in the command line: -<pre class="code_example"> -CodeChecker parse --print-steps ./reports -</pre> -Or view the detailed results in a browser: -<pre class="code_example"> -CodeChecker parse ./reports -e html -o ./reports_html -firefox ./reports_html/index.html -</pre> -</p> - -<p> -Optional: store the analysis results in a DB. -<pre class="code_example"> -mkdir ./ws -CodeChecker server -w ./ws -v 8555 & -CodeChecker store ./reports --name my-project --url http://localhost:8555/Default -</pre> -</p> - -<p> -Optional: manage (categorize, suppress) the results in your web browser: -<pre class="code_example"> -firefox http://localhost:8555/Default -</pre> -</p> - -<h2>Detailed Usage</h2> - -<p> -For extended documentation please refer to the <a href="https://github.com/Ericsson/codechecker/blob/master/docs/usage.md">official site of CodeChecker</a>! -</p> +</div> <!-- content --> +</div> <!-- page --> +</body> diff --git a/clang/www/analyzer/command-line.html b/clang/www/analyzer/command-line.html index e536a77..a91829e 100644 --- a/clang/www/analyzer/command-line.html +++ b/clang/www/analyzer/command-line.html @@ -2,7 +2,9 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> - <title>Running the analyzer from the command line</title> + <title>The command line documentation has moved to clang.llvm.org</title> + <link rel="canonical" href="https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html"/> + <meta http-equiv="refresh" content="0;url=https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html" /> <link type="text/css" rel="stylesheet" href="content.css"> <link type="text/css" rel="stylesheet" href="menu.css"> <script type="text/javascript" src="scripts/menu.js"></script> @@ -13,55 +15,12 @@ <!--#include virtual="menu.html.incl"--> <div id="content"> -<h1>Running the analyzer from the command line</h1> +<h1>The command line documentation has moved to clang.llvm.org</h1> +<p style="color:red; font-size:200%">This page is deprecated and will be removed in release 21.0</p> +<a href="https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html">The new site</a> +<script>window.location='https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html'</script> -<p> Static Analyzer is by design a GUI tool. Its purpose is to find buggy execution -paths in the program, and such paths are very hard to comprehend by looking at -a non-interactive standard output. It is possible, however, to invoke the -Static Analyzer from the command line in order to obtain analysis results, and -then later view them interactively in a graphical interface. The following -tools are used commonly to run the analyzer from the command line. Both tools -are wrapper scripts to drive the analysis and the underlying invocations of the -Clang compiler: -<ol> - <li><a href="scan-build.html">Scan-Build</a> - is an old and simple command-line tool that emits static analyzer warnings as HTML files while compiling your project. You can view the analysis results in your web browser. - </li> - <ul> - <li> - Useful for individual developers who simply want to view static analysis results at their desk, or in a very simple collaborative environment. - </li> - <li> - Works on all major platforms (Windows, Linux, macOS) and is available as a package in many Linux distributions. - </li> - <li> - Does not include support for cross-translation-unit analysis. - </li> - </ul> - <li><a href="codechecker.html">CodeChecker</a> - is a web server that runs the Static Analyzer on your projects on demand and maintains a database of issues. - </li> - <ul> - <li> - Perfect for managing large amounts of Static Analyzer warnings in a collaborative environment. - </li> - <li> - Generally much more feature-rich than scan-build. - </li> - <li>Supports incremental analysis: Results can be stored in a database, subsequent analysis runs can be compared to list the newly added defects.</li> - <li><a href="https://clang.llvm.org/docs/analyzer/user-docs/CrossTranslationUnit.html">Cross Translation Unit (CTU) analysis</a> is supported fully on Linux via CodeChecker.</li> - <li>Can run clang-tidy checkers too.</li> - <li>Open source, but out-of-tree, i.e. not part of the LLVM project.</li> - </ul> -</ol> -</p> - -<p> -</p> -<p> -</p> - -</div> -</div> +</div> <!-- content --> +</div> <!-- page --> </body> -</html> + diff --git a/clang/www/analyzer/filing_bugs.html b/clang/www/analyzer/filing_bugs.html index f7183a9..b78d9e7 100644 --- a/clang/www/analyzer/filing_bugs.html +++ b/clang/www/analyzer/filing_bugs.html @@ -2,8 +2,10 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> + <title>The filing bugs documentation has moved to clang.llvm.org</title> + <link rel="canonical" href="https://clang.llvm.org/docs/analyzer/user-docs/FilingBugs.html"/> + <meta http-equiv="refresh" content="0;url=https://clang.llvm.org/docs/analyzer/user-docs/FilingBugs.html" /> <meta charset="UTF-8"> - <title>Filing Bugs and Feature Requests</title> <link type="text/css" rel="stylesheet" href="menu.css"> <link type="text/css" rel="stylesheet" href="content.css"> <script type="text/javascript" src="scripts/menu.js"></script> @@ -14,32 +16,11 @@ <!--#include virtual="menu.html.incl"--> <div id="content"> -<h1>Filing Bugs and Feature Requests</h1> +<h1>The filing bugs documentation has moved to clang.llvm.org</h1> +<p style="color:red; font-size:200%">This page is deprecated and will be removed in release 21.0</p> +<a href="https://clang.llvm.org/docs/analyzer/user-docs/FilingBugs.html">The new site</a> +<script>window.location='https://clang.llvm.org/docs/analyzer/user-docs/FilingBugs.html'</script> -<p>We encourage users to file bug reports for any problems that they encounter. -We also welcome feature requests. When filing a bug report, please do the -following:</p> - -<ul> - -<li>Include the checker build (for prebuilt Mac OS X binaries) or the git hash. -</li> - -<li>Provide a self-contained, reduced test case that exhibits the issue you are -experiencing.</li> - -<li>Test cases don't tell us everything. Please briefly describe the problem you -are seeing, including what you thought should have been the expected behavior -and why.</li> - -</ul> - -<p>Please <a href="https://llvm.org/docs/HowToSubmitABug.html">file -bugs and feature requests</a> in -<a href="https://github.com/llvm/llvm-project/issues">LLVM's issue tracker</a> -and label the report with the <code>clang:static analyzer</code> label.</p> - -</div> -</div> +</div> <!-- content --> +</div> <!-- page --> </body> -</html> diff --git a/clang/www/analyzer/index.html b/clang/www/analyzer/index.html index 7beef7e..ea0ed49 100644 --- a/clang/www/analyzer/index.html +++ b/clang/www/analyzer/index.html @@ -96,7 +96,7 @@ applications.</p> <h3 style="margin:0px;padding:0px">Mac OS X</h3> <ul> <li>Latest build (10.8+):<br> - <!--#include virtual="latest_checker.html.incl"--> + <b><a href="downloads/checker-279.tar.bz2">checker-279.tar.bz2</a></b> (built November 14, 2016) </li> <li><a href="/release_notes.html">Release notes</a></li> <li>This build can be used both from the command line and from within Xcode</li> diff --git a/clang/www/analyzer/installation.html b/clang/www/analyzer/installation.html index cb3fa89..b463677 100644 --- a/clang/www/analyzer/installation.html +++ b/clang/www/analyzer/installation.html @@ -2,7 +2,9 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> - <title>Obtaining the Static Analyzer</title> + <title>The installation documentation has moved to clang.llvm.org</title> + <link rel="canonical" href="https://clang.llvm.org/docs/analyzer/user-docs/Installation.html"/> + <meta http-equiv="refresh" content="0;url=https://clang.llvm.org/docs/analyzer/user-docs/Installation.html" /> <link type="text/css" rel="stylesheet" href="menu.css"> <link type="text/css" rel="stylesheet" href="content.css"> <script type="text/javascript" src="scripts/menu.js"></script> @@ -13,98 +15,11 @@ <!--#include virtual="menu.html.incl"--> <div id="content"> -<h1>Obtaining the Static Analyzer</h1> +<h1>The installation documentation has moved to clang.llvm.org</h1> +<p style="color:red; font-size:200%">This page is deprecated and will be removed in release 21.0</p> +<a href="https://clang.llvm.org/docs/analyzer/user-docs/Installation.html">The new site</a> +<script>window.location='https://clang.llvm.org/docs/analyzer/user-docs/Installation.html'</script> -<p>This page describes how to download and install the analyzer. Once -the analyzer is installed, follow the <a -href="/scan-build.html">instructions</a> on using <tt>scan-build</tt> to -get started analyzing your code.</p> - -<h2>Packaged Builds (Mac OS X)</h2> - -<p>Semi-regular pre-built binaries of the analyzer are available on Mac -OS X. These are built to run on OS X 10.7 and later.</p> - -<p>Builds are released frequently. Often the differences between build -numbers being a few bug fixes or minor feature improvements. When using -the analyzer, we recommend that you check back here occasionally for new -builds, especially if the build you are using is more than a couple -weeks old.</p> - -<p>The latest build is: - <!--#include virtual="latest_checker.html.incl"--> -</p> - -<p>Packaged builds for other platforms may eventually be provided, but -we need volunteers who are willing to help provide such regular builds. -If you wish to help contribute regular builds of the analyzer on other -platforms, please email the <a -href="https://lists.llvm.org/mailman/listinfo/cfe-dev">Clang -Developers' mailing list</a>.</p> - -<h3>Using Packaged Builds</h3> - -<p>To use a package build, simply unpack it anywhere. If the build -archive has the name <b><tt>checker-XXX.tar.bz2</tt></b> then the -archive will expand to a directory called <b><tt>checker-XXX</tt></b>. -You do not need to place this directory or the contents of this -directory in any special place. Uninstalling the analyzer is as simple -as deleting this directory.</p> - -<p>Most of the files in the <b><tt>checker-XXX</tt></b> directory will -be supporting files for the analyzer that you can simply ignore. Most -users will only care about two files, which are located at the top of -the <b><tt>checker-XXX</tt></b> directory:</p> - -<ul> -<li><b>scan-build</b>: <tt>scan-build</tt> is the high-level command line utility for running the analyzer</li> -<li><b>scan-view</b>: <tt>scan-view</tt> a companion command line -utility to <tt>scan-build</tt>, <tt>scan-view</tt> is used to view -analysis results generated by <tt>scan-build</tt>. There is an option -that one can pass to <tt>scan-build</tt> to cause <tt>scan-view</tt> to -run as soon as it the analysis of a build completes</li> -</ul> - -<h4>Running scan-build</h4> - -<p>For specific details on using <tt>scan-build</tt>, please see -<tt>scan-build</tt>'s <a href="/scan-build">documentation</a>.</p> - -<p>To run <tt>scan-build</tt>, either add the -<b><tt>checker-XXX</tt></b> directory to your path or specify a complete -path for <tt>scan-build</tt> when running it. It is also possible to use -a symbolic link to <tt>scan-build</tt>, such one located in a directory -in your path. When <tt>scan-build</tt> runs it will automatically -determine where to find its accompanying files.</p> - -<h2 id="OtherPlatforms">Other Platforms (Building the Analyzer from Source)</h2> - -<p>For other platforms, you must build Clang and LLVM manually. To do -so, please follow the instructions for <a -href="https://clang.llvm.org/get_started.html#build">building Clang from -source code</a>.<p> - -<p>Once the Clang is built, you need to add the following to your path:</p> - -<ul> - -<li>The location of the <tt>clang</tt> binary. - -<p>For example, if you built a <em>Debug+Asserts</em> build of LLVM/Clang (the -default), the resultant <tt>clang</tt> binary will be in <tt>$(OBJDIR)/Debug+Asserts/bin</tt> -(where <tt>$(OBJDIR)</tt> is often the same as the root source directory). You -can also do <tt>make install</tt> to install the LLVM/Clang libraries and -binaries to the installation directory of your choice (specified when you run -<tt>configure</tt>).</p></li> - -<li>The locations of the <tt>scan-build</tt> and <tt>scan-view</tt> -programs. - -<p>These are installed via <tt>make install</tt> into the bin directory -when clang is built.</p></li> - -</ul> -</div> -</div> +</div> <!-- content --> +</div> <!-- page --> </body> -</html> diff --git a/clang/www/analyzer/latest_checker.html.incl b/clang/www/analyzer/latest_checker.html.incl deleted file mode 100644 index 439a245..0000000 --- a/clang/www/analyzer/latest_checker.html.incl +++ /dev/null @@ -1 +0,0 @@ -<b><a href="downloads/checker-279.tar.bz2">checker-279.tar.bz2</a></b> (built November 14, 2016) diff --git a/clang/www/analyzer/scan-build.html b/clang/www/analyzer/scan-build.html index a2e5f6a..1d42ce0 100644 --- a/clang/www/analyzer/scan-build.html +++ b/clang/www/analyzer/scan-build.html @@ -2,7 +2,9 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> - <title>scan-build: running the analyzer from the command line</title> + <title>The scan-build documentation has moved to clang.llvm.org</title> + <link rel="canonical" href="https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#scan-build"/> + <meta http-equiv="refresh" content="0;url=https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#scan-build" /> <link type="text/css" rel="stylesheet" href="content.css"> <link type="text/css" rel="stylesheet" href="menu.css"> <script type="text/javascript" src="scripts/menu.js"></script> @@ -13,371 +15,11 @@ <!--#include virtual="menu.html.incl"--> <div id="content"> -<h1>scan-build: running the analyzer from the command line</h1> +<h1>The scan-build documentation has moved to clang.llvm.org</h1> +<p style="color:red; font-size:200%">This page is deprecated and will be removed in release 21.0</p> +<a href="https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#scan-build">The new site</a> +<script>window.location='https://clang.llvm.org/docs/analyzer/user-docs/CommandLineUsage.html#scan-build'</script> -<table style="margin-top:0px" width="100%" cellpadding="0px" cellspacing="0"> -<tr><td> - -<h3>What is it?</h3> -<p><b>scan-build</b> is a command line utility that enables a user to run the -static analyzer over their codebase as part of performing a regular build (from -the command line).</p> - -<h3>How does it work?</h3> -<p>During a project build, as source files are compiled they are also analyzed -in tandem by the static analyzer.</p> - -<p>Upon completion of the build, results are then presented to the user within a -web browser.</p> - -<h3>Will it work with any build system?</h3> -<p><b>scan-build</b> has little or no knowledge about how you build your code. -It works by overriding the <tt>CC</tt> and <tt>CXX</tt> environment variables to -(hopefully) change your build to use a "fake" compiler instead of the -one that would normally build your project. This fake compiler executes either -<tt>clang</tt> or <tt>gcc</tt> (depending on the platform) to compile your -code and then executes the static analyzer to analyze your code.</p> - -<p>This "poor man's interposition" works amazingly well in many cases -and falls down in others. Please consult the information on this page on making -the best use of <b>scan-build</b>, which includes getting it to work when the -aforementioned hack fails to work.</p> - -</td> -<td style="padding-left:10px; text-align:center"> - <img src="images/scan_build_cmd.png" width="450px" alt="scan-build"><br> - <a href="images/analyzer_html.png"><img src="images/analyzer_html.png" width="450px" alt="analyzer in browser"></a> -<br><b>Viewing static analyzer results in a web browser</b> -</td></tr></table> - -<h2>Contents</h2> - -<ul> -<li><a href="#scanbuild">Getting Started</a> - <ul> - <li><a href="#scanbuild_basicusage">Basic Usage</a></li> - <li><a href="#scanbuild_forwindowsusers">For Windows Users</a></li> - <li><a href="#scanbuild_otheroptions">Other Options</a></li> - <li><a href="#scanbuild_output">Output of scan-build</a></li> - </ul> -</li> -<li><a href="#recommendedguidelines">Recommended Usage Guidelines</a> - <ul> - <li><a href="#recommended_debug">Always Analyze a Project in its "Debug" Configuration</a></li> - <li><a href="#recommended_verbose">Use Verbose Output when Debugging scan-build</a></li> - <li><a href="#recommended_autoconf">Run './configure' through scan-build</a></li> - </ul> -</li> -<li><a href="#iphone">Analyzing iPhone Projects</a></li> -</ul> - -<h2 id="scanbuild">Getting Started</h2> - -<p>The <tt>scan-build</tt> command can be used to analyze an entire project by -essentially interposing on a project's build process. This means that to run the -analyzer using <tt>scan-build</tt>, you will use <tt>scan-build</tt> to analyze -the source files compiled by <tt>gcc</tt>/<tt>clang</tt> during a project build. -This means that any files that are not compiled will also not be analyzed.</p> - -<h3 id="scanbuild_basicusage">Basic Usage</h3> - -<p>Basic usage of <tt>scan-build</tt> is designed to be simple: just place the -word "scan-build" in front of your build command:</p> - -<pre class="code_example"> -$ <span class="code_highlight">scan-build</span> make -$ <span class="code_highlight">scan-build</span> xcodebuild -</pre> - -<p>In the first case <tt>scan-build</tt> analyzes the code of a project built -with <tt>make</tt> and in the second case <tt>scan-build</tt> analyzes a project -built using <tt>xcodebuild</tt>.<p> - -<p>Here is the general format for invoking <tt>scan-build</tt>:</p> - -<pre class="code_example"> -$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> <span class="code_highlight"><command></span> <i>[command options]</i> -</pre> - -<p>Operationally, <tt>scan-build</tt> literally runs <command> with all of the -subsequent options passed to it. For example, one can pass <tt>-j4</tt> to -<tt>make</tt> get a parallel build over 4 cores:</p> - -<pre class="code_example"> -$ scan-build make <span class="code_highlight">-j4</span> -</pre> - -<p>In almost all cases, <tt>scan-build</tt> makes no effort to interpret the -options after the build command; it simply passes them through. In general, -<tt>scan-build</tt> should support parallel builds, but <b>not distributed -builds</b>.</p> - -<p>It is also possible to use <tt>scan-build</tt> to analyze specific -files:</p> - -<pre class="code_example"> - $ scan-build gcc -c <span class="code_highlight">t1.c t2.c</span> -</pre> - -<p>This example causes the files <tt>t1.c</tt> and <tt>t2.c</tt> to be analyzed. -</p> - -<h3 id="scanbuild_forwindowsusers">For Windows Users</h3> - -<p>Windows users must have Perl installed to use scan-build.</p> - -<p><tt>scan-build.bat</tt> script allows you to launch scan-build in the same -way as it described in the Basic Usage section above. To invoke scan-build from -an arbitrary location, add the path to the folder containing scan-build.bat to -your PATH environment variable.</p> - -<p>If you have unexpected compilation/make problems when running scan-build -with MinGW/MSYS the following information may be helpful:</p> - -<ul> - <li> If getting unexpected <tt>"fatal error: no input files"</tt> while -building with MSYS make from the Windows cmd, try one of these solutions:</li> - <ul> - <li> Use MinGW <tt>mingw32-make</tt> instead of MSYS <tt>make</tt> and -exclude the path to MSYS from PATH to prevent <tt>mingw32-make</tt> from using -MSYS utils. MSYS utils are dependent on the MSYS runtime and they are not -intended for being run from the Windows cmd. Specifically, makefile commands -with backslashed quotes may be heavily corrupted when passed for execution.</li> - <li> Run <tt>make</tt> from the sh shell: -<pre class="code_example"> -$ <span class="code_highlight">scan-build</span> <i>[scan-build options]</i> sh -c "make <i>[make options]</i>" -</pre></li> - </ul> - <li> If getting <tt>"Error : *** target pattern contains no `%'"</tt> while -using GNU Make 3.81, try to use another version of make.</li> -</ul> - -<h3 id="scanbuild_otheroptions">Other Options</h3> - -<p>As mentioned above, extra options can be passed to <tt>scan-build</tt>. These -options prefix the build command. For example:</p> - -<pre class="code_example"> - $ scan-build <span class="code_highlight">-k -V</span> make - $ scan-build <span class="code_highlight">-k -V</span> xcodebuild -</pre> - -<p>Here is a subset of useful options:</p> - -<table class="options"> -<colgroup><col class="option"><col class="description"></colgroup> -<thead><tr><td>Option</td><td>Description</td></tr></thead> - -<tr><td><b>-o</b></td><td>Target directory for HTML report files. Subdirectories -will be created as needed to represent separate "runs" of the analyzer. If this -option is not specified, a directory is created in <tt>/tmp</tt> to store the -reports.</td></tr> - -<tr><td><b>-h</b><br><i>(or no arguments)</i></td><td>Display all -<tt>scan-build</tt> options.</td></tr> - -<tr><td><b>-k</b><br><b>--keep-going</b></td><td>Add a "keep on -going" option to the specified build command. <p>This option currently supports -<tt>make</tt> and <tt>xcodebuild</tt>.</p> <p>This is a convenience option; one -can specify this behavior directly using build options.</p></td></tr> - -<tr><td><b>-v</b></td><td>Verbose output from scan-build and the analyzer. <b>A -second and third "-v" increases verbosity</b>, and is useful for filing bug -reports against the analyzer.</td></tr> - -<tr><td><b>-V</b></td><td>View analysis results in a web browser when the build -command completes.</td></tr> - -<tr><td><b>--use-analyzer Xcode</b><br><i>or</i><br> -<b>--use-analyzer [path to clang]</b></td><td><tt>scan-build</tt> uses the -'clang' executable relative to itself for static analysis. One can override this -behavior with this option by using the 'clang' packaged with Xcode (on OS X) or -from the PATH.</p></td></tr> </table> - -<p>A complete list of options can be obtained by running <tt>scan-build</tt> -with no arguments.</p> - -<h3 id="scanbuild_output">Output of scan-build</h3> - -<p> -The output of scan-build is a set of HTML files, each one which represents a -separate bug report. A single <tt>index.html</tt> file is generated for -surveying all of the bugs. You can then just open <tt>index.html</tt> in a web -browser to view the bug reports. -</p> - -<p> -Where the HTML files are generated is specified with a <b>-o</b> option to -<tt>scan-build</tt>. If <b>-o</b> isn't specified, a directory in <tt>/tmp</tt> -is created to store the files (<tt>scan-build</tt> will print a message telling -you where they are). If you want to view the reports immediately after the build -completes, pass <b>-V</b> to <tt>scan-build</tt>. -</p> - - -<h2 id="recommendedguidelines">Recommended Usage Guidelines</h2> - -<p>This section describes a few recommendations with running the analyzer.</p> - -<h3 id="recommended_debug">ALWAYS analyze a project in its "debug" configuration</h3> - -<p>Most projects can be built in a "debug" mode that enables assertions. -Assertions are picked up by the static analyzer to prune infeasible paths, which -in some cases can greatly reduce the number of false positives (bogus error -reports) emitted by the tool.</p> - -<p>Another option is to use <tt>--force-analyze-debug-code</tt> flag of -<b>scan-build</b> tool which would enable assertions automatically.</p> - -<h3 id="recommend_verbose">Use verbose output when debugging scan-build</h3> - -<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about -what it's doing; two <b>-v</b> options emit more information. Redirecting the -output of <tt>scan-build</tt> to a text file (make sure to redirect standard -error) is useful for filing bug reports against <tt>scan-build</tt> or the -analyzer, as we can see the exact options (and files) passed to the analyzer. -For more comprehensible logs, don't perform a parallel build.</p> - -<h3 id="recommended_autoconf">Run './configure' through scan-build</h3> - -<p>If an analyzed project uses an autoconf generated <tt>configure</tt> script, -you will probably need to run <tt>configure</tt> script through -<tt>scan-build</tt> in order to analyze the project.</p> - -<p><b>Example</b></p> - -<pre class="code_example"> -$ scan-build ./configure -$ scan-build --keep-cc make -</pre> - -<p>The reason <tt>configure</tt> also needs to be run through -<tt>scan-build</tt> is because <tt>scan-build</tt> scans your source files by -<i>interposing</i> on the compiler. This interposition is currently done by -<tt>scan-build</tt> temporarily setting the environment variable <tt>CC</tt> to -<tt>ccc-analyzer</tt>. The program <tt>ccc-analyzer</tt> acts like a fake -compiler, forwarding its command line arguments over to the compiler to perform -regular compilation and <tt>clang</tt> to perform static analysis.</p> - -<p>Running <tt>configure</tt> typically generates makefiles that have hardwired -paths to the compiler, and by running <tt>configure</tt> through -<tt>scan-build</tt> that path is set to <tt>ccc-analyzer</tt>.</p> - -<!-- -<h2 id="Debugging">Debugging the Analyzer</h2> - -<p>This section provides information on debugging the analyzer, and troubleshooting -it when you have problems analyzing a particular project.</p> - -<h3>How it Works</h3> - -<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable -<tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other -environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML -report files.</p> - -<p>Some Makefiles (or equivalent project files) hardcode the compiler; for such -projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be -called. This will cause the compiled code <b>to not be analyzed.</b></p> If you -find that your code isn't being analyzed, check to see if <tt>CC</tt> is -hardcoded. If this is the case, you can hardcode it instead to the <b>full -path</b> to <tt>ccc-analyzer</tt>.</p> - -<p>When applicable, you can also run <tt>./configure</tt> for a project through -<tt>scan-build</tt> so that configure sets up the location of <tt>CC</tt> based -on the environment passed in from <tt>scan-build</tt>: - -<pre> - $ scan-build <b>./configure</b> -</pre> - -<p><tt>scan-build</tt> has special knowledge about <tt>configure</tt>, so it in -most cases will not actually analyze the configure tests run by -<tt>configure</tt>.</p> - -<p>Under the hood, <tt>ccc-analyzer</tt> directly invokes <tt>gcc</tt> to -compile the actual code in addition to running the analyzer (which occurs by it -calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all -the arguments over to <tt>gcc</tt>, but this may not work perfectly (please -report bugs of this kind). - --> - -<h2 id="iphone">Analyzing iPhone Projects</h2> - -<p>Conceptually Xcode projects for iPhone applications are nearly the same as -their cousins for desktop applications. <b>scan-build</b> can analyze these -projects as well, but users often encounter problems with just building their -iPhone projects from the command line because there are a few extra preparative -steps they need to take (e.g., setup code signing).</p> - -<h3>Recommendation: use "Build and Analyze"</h3> - -<p>The absolute easiest way to analyze iPhone projects is to use the -<a href="https://developer.apple.com/library/ios/recipes/xcode_help-source_editor/chapters/Analyze.html#//apple_ref/doc/uid/TP40009975-CH4-SW1"><i>Analyze</i> -feature in Xcode</a> (which is based on the Clang Static Analyzer). There a -user can analyze their project right from a menu without most of the setup -described later.</p> - -<p><a href="/xcode.html">Instructions are available</a> on this -website on how to use open source builds of the analyzer as a replacement for -the one bundled with Xcode.</p> - -<h3>Using scan-build directly</h3> - -<p>If you wish to use <b>scan-build</b> with your iPhone project, keep the -following things in mind:</p> - -<ul> - <li>Analyze your project in the <tt>Debug</tt> configuration, either by setting -this as your configuration with Xcode or by passing <tt>-configuration -Debug</tt> to <tt>xcodebuild</tt>.</li> - <li>Analyze your project using the <tt>Simulator</tt> as your base SDK. It is -possible to analyze your code when targeting the device, but this is much -easier to do when using Xcode's <i>Build and Analyze</i> feature.</li> - <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> -</ul> - -<p>Note that you can most of this without actually modifying your project. For -example, if your application targets iPhoneOS 2.2, you could run -<b>scan-build</b> in the following manner from the command line:</p> - -<pre class="code_example"> -$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator2.2 -</pre> - -Alternatively, if your application targets iPhoneOS 3.0: - -<pre class="code_example"> -$ scan-build xcodebuild -configuration Debug -sdk iphonesimulator3.0 -</pre> - -<h3>Gotcha: using the right compiler</h3> - -<p>Recall that <b>scan-build</b> analyzes your project by using a compiler to -compile the project and <tt>clang</tt> to analyze your project. The script uses -simple heuristics to determine which compiler should be used (it defaults to -<tt>clang</tt> on Darwin and <tt>gcc</tt> on other platforms). When analyzing -iPhone projects, <b>scan-build</b> may pick the wrong compiler than the one -Xcode would use to build your project. For example, this could be because -multiple versions of a compiler may be installed on your system, especially if -you are developing for the iPhone.</p> - -<p>When compiling your application to run on the simulator, it is important that <b>scan-build</b> -finds the correct version of <tt>gcc/clang</tt>. Otherwise, you may see strange build -errors that only happen when you run <tt>scan-build</tt>. - -<p><b>scan-build</b> provides the <tt>--use-cc</tt> and <tt>--use-c++</tt> -options to hardwire which compiler scan-build should use for building your code. -Note that although you are chiefly interested in analyzing your project, keep in -mind that running the analyzer is intimately tied to the build, and not being -able to compile your code means it won't get fully analyzed (if at all).</p> - -<p>If you aren't certain which compiler Xcode uses to build your project, try -just running <tt>xcodebuild</tt> (without <b>scan-build</b>). You should see the -full path to the compiler that Xcode is using, and use that as an argument to -<tt>--use-cc</tt>.</p> - -</div> -</div> +</div> <!-- content --> +</div> <!-- page --> </body> -</html> diff --git a/clang/www/analyzer/xcode.html b/clang/www/analyzer/xcode.html index d6e44bc..2a76836 100644 --- a/clang/www/analyzer/xcode.html +++ b/clang/www/analyzer/xcode.html @@ -2,7 +2,9 @@ "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> - <title>Running the analyzer within Xcode</title> + <title>The Xcode documentation has moved to clang.llvm.org</title> + <link rel="canonical" href="https://clang.llvm.org/docs/analyzer/user-docs/UsingWithXCode.html"/> + <meta http-equiv="refresh" content="0;url=https://clang.llvm.org/docs/analyzer/user-docs/UsingWithXCode.html" /> <link type="text/css" rel="stylesheet" href="content.css"> <link type="text/css" rel="stylesheet" href="menu.css"> <script type="text/javascript" src="scripts/menu.js"></script> @@ -13,131 +15,11 @@ <!--#include virtual="menu.html.incl"--> <div id="content"> -<h1>Running the analyzer within Xcode</h1> +<h1>The Xcode documentation has moved to clang.llvm.org</h1> +<p style="color:red; font-size:200%">This page is deprecated and will be removed in release 21.0</p> +<a href="https://clang.llvm.org/docs/analyzer/user-docs/UsingWithXCode.html">The new site</a> +<script>window.location='https://clang.llvm.org/docs/analyzer/user-docs/UsingWithXCode.html'</script> -<table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0"> -<tr><td> - -<h3>What is it?</h3> - -<p>Since Xcode 3.2, users have been able to run the Clang Static Analyzer -<a -href="https://developer.apple.com/library/ios/recipes/xcode_help-source_editor/chapters/Analyze.html#//apple_ref/doc/uid/TP40009975-CH4-SW1">directly -within Xcode</a>.</p> - -<p>It integrates directly with the Xcode build system and -presents analysis results directly within Xcode's editor.</p> - -<h3>Can I use the open source analyzer builds with Xcode?</h3> - -<p><b>Yes</b>. Instructions are included below.</p> - -</td> -<td style="padding-left:10px; text-align:center"> - <a href="images/analyzer_xcode.png"><img src="images/analyzer_xcode.png" width="620px" alt="analyzer in xcode"></a> -<br><b>Viewing static analyzer results in Xcode</b> -</td></tr></table> - -<h3>Key features:</h3> -<ul> - <li><b>Integrated workflow:</b> Results are integrated within Xcode. There is - no experience of using a separate tool, and activating the analyzer requires a - single keystroke or mouse click.</li> - <li><b>Transparency:</b> Works effortlessly with Xcode projects (including iPhone projects). - <li><b>Cons:</b> Doesn't work well with non-Xcode projects. For those, - consider using <a href="scan-build.html"><b>scan-build</b></a>. -</ul> - - -<h2>Getting Started</h2> - -<p>Xcode is available as a free download from Apple on the <a -href="https://itunes.apple.com/us/app/xcode/id497799835?mt=12">Mac -App Store</a>, with <a -href="https://developer.apple.com/library/ios/recipes/xcode_help-source_editor/chapters/Analyze.html#//apple_ref/doc/uid/TP40009975-CH4-SW1">instructions -available</a> for using the analyzer.</p> - -<h2>Using open source analyzer builds with Xcode</h2> - -<p>By default, Xcode uses the version of <tt>clang</tt> that came bundled with -it to analyze your code. It is possible to change Xcode's behavior to use an -alternate version of <tt>clang</tt> for this purpose while continuing to use -the <tt>clang</tt> that came with Xcode for compiling projects.</p> - -<h3>Why try open source builds?</h3> - -<p>The advantage of using open source analyzer builds (provided on this website) -is that they are often newer than the analyzer provided with Xcode, and thus can -contain bug fixes, new checks, or simply better analysis.</p> - -<p>On the other hand, new checks can be experimental, with results of variable -quality. Users are encouraged to <a href="filing_bugs.html">file bug reports</a> -(for any version of the analyzer) where they encounter false positives or other -issues.</p> - -<h3>set-xcode-analyzer</h3> - -<p>Starting with analyzer build checker-234, analyzer builds contain a command -line utility called <tt>set-xcode-analyzer</tt> that allows users to change what -copy of <tt>clang</tt> that Xcode uses for analysis:</p> - -<pre class="code_example"> -$ <b>set-xcode-analyzer -h</b> -Usage: set-xcode-analyzer [options] - -Options: - -h, --help show this help message and exit - --use-checker-build=PATH - Use the Clang located at the provided absolute path, - e.g. /Users/foo/checker-1 - --use-xcode-clang Use the Clang bundled with Xcode -</pre> - -<p>Operationally, <b>set-xcode-analyzer</b> edits Xcode's configuration files -to point it to use the version of <tt>clang</tt> you specify for static -analysis. Within this model it provides you two basic modes:</p> - -<ul> - <li><b>--use-xcode-clang</b>: Switch Xcode (back) to using the <tt>clang</tt> that came bundled with it for static analysis.</li> - <li><b>--use-checker-build</b>: Switch Xcode to using the <tt>clang</tt> provided by the specified analyzer build.</li> -</ul> - -<h4>Things to keep in mind</h4> - -<ul> - <li>You should quit Xcode prior to running <tt>set-xcode-analyzer</tt>.</li> <li>You will need to run <tt>set-xcode-analyzer</tt> under -<b><tt>sudo</tt></b> in order to have write privileges to modify the Xcode -configuration files.</li> -</ul> - -<h4>Examples</h4> - -<p><b>Example 1</b>: Telling Xcode to use checker-235:</p> - -<pre class="code_example"> -$ pwd -/tmp -$ tar xjf checker-235.tar.bz2 -$ sudo checker-235/set-xcode-analyzer --use-checker-build=/tmp/checker-235 -</pre> - -<p>Note that you typically won't install an analyzer build in <tt>/tmp</tt>, but -the point of this example is that <tt>set-xcode-analyzer</tt> just wants a full -path to an untarred analyzer build.</p> - -<p><b>Example 2</b>: Telling Xcode to use a very specific version of <tt>clang</tt>:</p> - -<pre class="code_example"> -$ sudo set-xcode-analyzer --use-checker-build=~/mycrazyclangbuild/bin/clang -</pre> - -<p><b>Example 3</b>: Resetting Xcode to its default behavior:</p> - -<pre class="code_example"> -$ sudo set-xcode-analyzer --use-xcode-clang -</pre> - -</div> -</div> +</div> <!-- content --> +</div> <!-- page --> </body> -</html> |