[www-releases] r336152 - Add 6.0.1 docs
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Mon Jul 2 16:21:47 PDT 2018
Added: www-releases/trunk/6.0.1/docs/CodingStandards.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CodingStandards.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CodingStandards.html (added)
+++ www-releases/trunk/6.0.1/docs/CodingStandards.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,1588 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Coding Standards — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="CommandLine 2.0 Library Manual" href="CommandLine.html" />
+ <link rel="prev" title="LLVM Atomic Instructions and Concurrency Guide" href="Atomics.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="CommandLine.html" title="CommandLine 2.0 Library Manual"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-coding-standards">
+<h1>LLVM Coding Standards<a class="headerlink" href="#llvm-coding-standards" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#languages-libraries-and-standards" id="id2">Languages, Libraries, and Standards</a><ul>
+<li><a class="reference internal" href="#c-standard-versions" id="id3">C++ Standard Versions</a></li>
+<li><a class="reference internal" href="#c-standard-library" id="id4">C++ Standard Library</a></li>
+<li><a class="reference internal" href="#supported-c-11-language-and-library-features" id="id5">Supported C++11 Language and Library Features</a></li>
+<li><a class="reference internal" href="#other-languages" id="id6">Other Languages</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#mechanical-source-issues" id="id7">Mechanical Source Issues</a><ul>
+<li><a class="reference internal" href="#source-code-formatting" id="id8">Source Code Formatting</a><ul>
+<li><a class="reference internal" href="#commenting" id="id9">Commenting</a><ul>
+<li><a class="reference internal" href="#file-headers" id="id10">File Headers</a></li>
+<li><a class="reference internal" href="#class-overviews" id="id11">Class overviews</a></li>
+<li><a class="reference internal" href="#method-information" id="id12">Method information</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#comment-formatting" id="id13">Comment Formatting</a></li>
+<li><a class="reference internal" href="#doxygen-use-in-documentation-comments" id="id14">Doxygen Use in Documentation Comments</a></li>
+<li><a class="reference internal" href="#include-style" id="id15"><tt class="docutils literal"><span class="pre">#include</span></tt> Style</a></li>
+<li><a class="reference internal" href="#source-code-width" id="id16">Source Code Width</a></li>
+<li><a class="reference internal" href="#use-spaces-instead-of-tabs" id="id17">Use Spaces Instead of Tabs</a></li>
+<li><a class="reference internal" href="#indent-code-consistently" id="id18">Indent Code Consistently</a><ul>
+<li><a class="reference internal" href="#format-lambdas-like-blocks-of-code" id="id19">Format Lambdas Like Blocks Of Code</a></li>
+<li><a class="reference internal" href="#braced-initializer-lists" id="id20">Braced Initializer Lists</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#language-and-compiler-issues" id="id21">Language and Compiler Issues</a><ul>
+<li><a class="reference internal" href="#treat-compiler-warnings-like-errors" id="id22">Treat Compiler Warnings Like Errors</a></li>
+<li><a class="reference internal" href="#write-portable-code" id="id23">Write Portable Code</a></li>
+<li><a class="reference internal" href="#do-not-use-rtti-or-exceptions" id="id24">Do not use RTTI or Exceptions</a></li>
+<li><a class="reference internal" href="#do-not-use-static-constructors" id="id25">Do not use Static Constructors</a></li>
+<li><a class="reference internal" href="#use-of-class-and-struct-keywords" id="id26">Use of <tt class="docutils literal"><span class="pre">class</span></tt> and <tt class="docutils literal"><span class="pre">struct</span></tt> Keywords</a></li>
+<li><a class="reference internal" href="#do-not-use-braced-initializer-lists-to-call-a-constructor" id="id27">Do not use Braced Initializer Lists to Call a Constructor</a></li>
+<li><a class="reference internal" href="#use-auto-type-deduction-to-make-code-more-readable" id="id28">Use <tt class="docutils literal"><span class="pre">auto</span></tt> Type Deduction to Make Code More Readable</a></li>
+<li><a class="reference internal" href="#beware-unnecessary-copies-with-auto" id="id29">Beware unnecessary copies with <tt class="docutils literal"><span class="pre">auto</span></tt></a></li>
+<li><a class="reference internal" href="#beware-of-non-determinism-due-to-ordering-of-pointers" id="id30">Beware of non-determinism due to ordering of pointers</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#style-issues" id="id31">Style Issues</a><ul>
+<li><a class="reference internal" href="#the-high-level-issues" id="id32">The High-Level Issues</a><ul>
+<li><a class="reference internal" href="#a-public-header-file-is-a-module" id="id33">A Public Header File <strong>is</strong> a Module</a></li>
+<li><a class="reference internal" href="#include-as-little-as-possible" id="id34"><tt class="docutils literal"><span class="pre">#include</span></tt> as Little as Possible</a></li>
+<li><a class="reference internal" href="#keep-internal-headers-private" id="id35">Keep “Internal” Headers Private</a></li>
+<li><a class="reference internal" href="#use-early-exits-and-continue-to-simplify-code" id="id36">Use Early Exits and <tt class="docutils literal"><span class="pre">continue</span></tt> to Simplify Code</a></li>
+<li><a class="reference internal" href="#don-t-use-else-after-a-return" id="id37">Don’t use <tt class="docutils literal"><span class="pre">else</span></tt> after a <tt class="docutils literal"><span class="pre">return</span></tt></a></li>
+<li><a class="reference internal" href="#turn-predicate-loops-into-predicate-functions" id="id38">Turn Predicate Loops into Predicate Functions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-low-level-issues" id="id39">The Low-Level Issues</a><ul>
+<li><a class="reference internal" href="#name-types-functions-variables-and-enumerators-properly" id="id40">Name Types, Functions, Variables, and Enumerators Properly</a></li>
+<li><a class="reference internal" href="#assert-liberally" id="id41">Assert Liberally</a></li>
+<li><a class="reference internal" href="#do-not-use-using-namespace-std" id="id42">Do Not Use <tt class="docutils literal"><span class="pre">using</span> <span class="pre">namespace</span> <span class="pre">std</span></tt></a></li>
+<li><a class="reference internal" href="#provide-a-virtual-method-anchor-for-classes-in-headers" id="id43">Provide a Virtual Method Anchor for Classes in Headers</a></li>
+<li><a class="reference internal" href="#don-t-use-default-labels-in-fully-covered-switches-over-enumerations" id="id44">Don’t use default labels in fully covered switches over enumerations</a></li>
+<li><a class="reference internal" href="#use-range-based-for-loops-wherever-possible" id="id45">Use range-based <tt class="docutils literal"><span class="pre">for</span></tt> loops wherever possible</a></li>
+<li><a class="reference internal" href="#don-t-evaluate-end-every-time-through-a-loop" id="id46">Don’t evaluate <tt class="docutils literal"><span class="pre">end()</span></tt> every time through a loop</a></li>
+<li><a class="reference internal" href="#include-iostream-is-forbidden" id="id47"><tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt> is Forbidden</a></li>
+<li><a class="reference internal" href="#use-raw-ostream" id="id48">Use <tt class="docutils literal"><span class="pre">raw_ostream</span></tt></a></li>
+<li><a class="reference internal" href="#avoid-std-endl" id="id49">Avoid <tt class="docutils literal"><span class="pre">std::endl</span></tt></a></li>
+<li><a class="reference internal" href="#don-t-use-inline-when-defining-a-function-in-a-class-definition" id="id50">Don’t use <tt class="docutils literal"><span class="pre">inline</span></tt> when defining a function in a class definition</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#microscopic-details" id="id51">Microscopic Details</a><ul>
+<li><a class="reference internal" href="#spaces-before-parentheses" id="id52">Spaces Before Parentheses</a></li>
+<li><a class="reference internal" href="#prefer-preincrement" id="id53">Prefer Preincrement</a></li>
+<li><a class="reference internal" href="#namespace-indentation" id="id54">Namespace Indentation</a></li>
+<li><a class="reference internal" href="#anonymous-namespaces" id="id55">Anonymous Namespaces</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#see-also" id="id56">See Also</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document attempts to describe a few coding standards that are being used in
+the LLVM source tree. Although no coding standards should be regarded as
+absolute requirements to be followed in all instances, coding standards are
+particularly important for large-scale code bases that follow a library-based
+design (like LLVM).</p>
+<p>While this document may provide guidance for some mechanical formatting issues,
+whitespace, or other “microscopic details”, these are not fixed standards.
+Always follow the golden rule:</p>
+<blockquote id="golden-rule">
+<div><strong>If you are extending, enhancing, or bug fixing already implemented code,
+use the style that is already being used so that the source is uniform and
+easy to follow.</strong></div></blockquote>
+<p>Note that some code bases (e.g. <tt class="docutils literal"><span class="pre">libc++</span></tt>) have really good reasons to deviate
+from the coding standards. In the case of <tt class="docutils literal"><span class="pre">libc++</span></tt>, this is because the
+naming and other conventions are dictated by the C++ standard. If you think
+there is a specific good reason to deviate from the standards here, please bring
+it up on the LLVM-dev mailing list.</p>
+<p>There are some conventions that are not uniformly followed in the code base
+(e.g. the naming convention). This is because they are relatively new, and a
+lot of code was written before they were put in place. Our long term goal is
+for the entire codebase to follow the convention, but we explicitly <em>do not</em>
+want patches that do large-scale reformatting of existing code. On the other
+hand, it is reasonable to rename the methods of a class if you’re about to
+change it in some other way. Just do the reformatting as a separate commit
+from the functionality change.</p>
+<p>The ultimate goal of these guidelines is to increase the readability and
+maintainability of our common source base. If you have suggestions for topics to
+be included, please mail them to <a class="reference external" href="mailto:sabre%40nondot.org">Chris</a>.</p>
+</div>
+<div class="section" id="languages-libraries-and-standards">
+<h2><a class="toc-backref" href="#id2">Languages, Libraries, and Standards</a><a class="headerlink" href="#languages-libraries-and-standards" title="Permalink to this headline">¶</a></h2>
+<p>Most source code in LLVM and other LLVM projects using these coding standards
+is C++ code. There are some places where C code is used either due to
+environment restrictions, historical restrictions, or due to third-party source
+code imported into the tree. Generally, our preference is for standards
+conforming, modern, and portable C++ code as the implementation language of
+choice.</p>
+<div class="section" id="c-standard-versions">
+<h3><a class="toc-backref" href="#id3">C++ Standard Versions</a><a class="headerlink" href="#c-standard-versions" title="Permalink to this headline">¶</a></h3>
+<p>LLVM, Clang, and LLD are currently written using C++11 conforming code,
+although we restrict ourselves to features which are available in the major
+toolchains supported as host compilers. The LLDB project is even more
+aggressive in the set of host compilers supported and thus uses still more
+features. Regardless of the supported features, code is expected to (when
+reasonable) be standard, portable, and modern C++11 code. We avoid unnecessary
+vendor-specific extensions, etc.</p>
+</div>
+<div class="section" id="c-standard-library">
+<h3><a class="toc-backref" href="#id4">C++ Standard Library</a><a class="headerlink" href="#c-standard-library" title="Permalink to this headline">¶</a></h3>
+<p>Use the C++ standard library facilities whenever they are available for
+a particular task. LLVM and related projects emphasize and rely on the standard
+library facilities for as much as possible. Common support libraries providing
+functionality missing from the standard library for which there are standard
+interfaces or active work on adding standard interfaces will often be
+implemented in the LLVM namespace following the expected standard interface.</p>
+<p>There are some exceptions such as the standard I/O streams library which are
+avoided. Also, there is much more detailed information on these subjects in the
+<a class="reference internal" href="ProgrammersManual.html"><em>LLVM Programmer’s Manual</em></a>.</p>
+</div>
+<div class="section" id="supported-c-11-language-and-library-features">
+<h3><a class="toc-backref" href="#id5">Supported C++11 Language and Library Features</a><a class="headerlink" href="#supported-c-11-language-and-library-features" title="Permalink to this headline">¶</a></h3>
+<p>While LLVM, Clang, and LLD use C++11, not all features are available in all of
+the toolchains which we support. The set of features supported for use in LLVM
+is the intersection of those supported in the minimum requirements described
+in the <a class="reference internal" href="GettingStarted.html"><em>Getting Started with the LLVM System</em></a> page, section <cite>Software</cite>.
+The ultimate definition of this set is what build bots with those respective
+toolchains accept. Don’t argue with the build bots. However, we have some
+guidance below to help you know what to expect.</p>
+<p>Each toolchain provides a good reference for what it accepts:</p>
+<ul class="simple">
+<li>Clang: <a class="reference external" href="http://clang.llvm.org/cxx_status.html">http://clang.llvm.org/cxx_status.html</a></li>
+<li>GCC: <a class="reference external" href="http://gcc.gnu.org/projects/cxx0x.html">http://gcc.gnu.org/projects/cxx0x.html</a></li>
+<li>MSVC: <a class="reference external" href="http://msdn.microsoft.com/en-us/library/hh567368.aspx">http://msdn.microsoft.com/en-us/library/hh567368.aspx</a></li>
+</ul>
+<p>In most cases, the MSVC list will be the dominating factor. Here is a summary
+of the features that are expected to work. Features not on this list are
+unlikely to be supported by our host compilers.</p>
+<ul class="simple">
+<li>Rvalue references: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html">N2118</a><ul>
+<li>But <em>not</em> Rvalue references for <tt class="docutils literal"><span class="pre">*this</span></tt> or member qualifiers (<a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm">N2439</a>)</li>
+</ul>
+</li>
+<li>Static assert: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html">N1720</a></li>
+<li><tt class="docutils literal"><span class="pre">auto</span></tt> type deduction: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf">N1984</a>, <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1737.pdf">N1737</a></li>
+<li>Trailing return types: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm">N2541</a></li>
+<li>Lambdas: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf">N2927</a><ul>
+<li>But <em>not</em> lambdas with default arguments.</li>
+</ul>
+</li>
+<li><tt class="docutils literal"><span class="pre">decltype</span></tt>: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf">N2343</a></li>
+<li>Nested closing right angle brackets: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html">N1757</a></li>
+<li>Extern templates: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm">N1987</a></li>
+<li><tt class="docutils literal"><span class="pre">nullptr</span></tt>: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf">N2431</a></li>
+<li>Strongly-typed and forward declarable enums: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf">N2347</a>, <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2764.pdf">N2764</a></li>
+<li>Local and unnamed types as template arguments: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm">N2657</a></li>
+<li>Range-based for-loop: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2930.html">N2930</a><ul>
+<li>But <tt class="docutils literal"><span class="pre">{}</span></tt> are required around inner <tt class="docutils literal"><span class="pre">do</span> <span class="pre">{}</span> <span class="pre">while()</span></tt> loops. As a result,
+<tt class="docutils literal"><span class="pre">{}</span></tt> are required around function-like macros inside range-based for
+loops.</li>
+</ul>
+</li>
+<li><tt class="docutils literal"><span class="pre">override</span></tt> and <tt class="docutils literal"><span class="pre">final</span></tt>: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2928.htm">N2928</a>, <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm">N3206</a>, <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm">N3272</a></li>
+<li>Atomic operations and the C++11 memory model: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2429.htm">N2429</a></li>
+<li>Variadic templates: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf">N2242</a></li>
+<li>Explicit conversion operators: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf">N2437</a></li>
+<li>Defaulted and deleted functions: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">N2346</a></li>
+<li>Initializer lists: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm">N2627</a></li>
+<li>Delegating constructors: <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf">N1986</a></li>
+<li>Default member initializers (non-static data member initializers): <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2756.htm">N2756</a><ul>
+<li>Feel free to use these wherever they make sense and where the <cite>=</cite>
+syntax is allowed. Don’t use braced initialization syntax.</li>
+</ul>
+</li>
+</ul>
+<p>The supported features in the C++11 standard libraries are less well tracked,
+but also much greater. Most of the standard libraries implement most of C++11’s
+library. The most likely lowest common denominator is Linux support. For
+libc++, the support is just poorly tested and undocumented but expected to be
+largely complete. YMMV. For libstdc++, the support is documented in detail in
+<a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc-4.8.0/libstdc++/manual/manual/status.html#status.iso.2011">the libstdc++ manual</a>. There are some very minor missing facilities that are
+unlikely to be common problems, and there are a few larger gaps that are worth
+being aware of:</p>
+<ul class="simple">
+<li>Not all of the type traits are implemented</li>
+<li>No regular expression library.</li>
+<li>While most of the atomics library is well implemented, the fences are
+missing. Fortunately, they are rarely needed.</li>
+<li>The locale support is incomplete.</li>
+</ul>
+<p>Other than these areas you should assume the standard library is available and
+working as expected until some build bot tells you otherwise. If you’re in an
+uncertain area of one of the above points, but you cannot test on a Linux
+system, your best approach is to minimize your use of these features, and watch
+the Linux build bots to find out if your usage triggered a bug. For example, if
+you hit a type trait which doesn’t work we can then add support to LLVM’s
+traits header to emulate it.</p>
+</div>
+<div class="section" id="other-languages">
+<h3><a class="toc-backref" href="#id6">Other Languages</a><a class="headerlink" href="#other-languages" title="Permalink to this headline">¶</a></h3>
+<p>Any code written in the Go programming language is not subject to the
+formatting rules below. Instead, we adopt the formatting rules enforced by
+the <a class="reference external" href="https://golang.org/cmd/gofmt/">gofmt</a> tool.</p>
+<p>Go code should strive to be idiomatic. Two good sets of guidelines for what
+this means are <a class="reference external" href="https://golang.org/doc/effective_go.html">Effective Go</a> and <a class="reference external" href="https://github.com/golang/go/wiki/CodeReviewComments">Go Code Review Comments</a>.</p>
+</div>
+</div>
+<div class="section" id="mechanical-source-issues">
+<h2><a class="toc-backref" href="#id7">Mechanical Source Issues</a><a class="headerlink" href="#mechanical-source-issues" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="source-code-formatting">
+<h3><a class="toc-backref" href="#id8">Source Code Formatting</a><a class="headerlink" href="#source-code-formatting" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="commenting">
+<h4><a class="toc-backref" href="#id9">Commenting</a><a class="headerlink" href="#commenting" title="Permalink to this headline">¶</a></h4>
+<p>Comments are one critical part of readability and maintainability. Everyone
+knows they should comment their code, and so should you. When writing comments,
+write them as English prose, which means they should use proper capitalization,
+punctuation, etc. Aim to describe what the code is trying to do and why, not
+<em>how</em> it does it at a micro level. Here are a few critical things to document:</p>
+<div class="section" id="file-headers">
+<span id="header-file-comment"></span><h5><a class="toc-backref" href="#id10">File Headers</a><a class="headerlink" href="#file-headers" title="Permalink to this headline">¶</a></h5>
+<p>Every source file should have a header on it that describes the basic purpose of
+the file. If a file does not have a header, it should not be checked into the
+tree. The standard header looks like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//</span>
+<span class="c1">//</span>
+<span class="c1">// The LLVM Compiler Infrastructure</span>
+<span class="c1">//</span>
+<span class="c1">// This file is distributed under the University of Illinois Open Source</span>
+<span class="c1">// License. See LICENSE.TXT for details.</span>
+<span class="c1">//</span>
+<span class="c1">//===----------------------------------------------------------------------===//</span>
+<span class="c1">///</span>
+<span class="c1">/// \file</span>
+<span class="c1">/// This file contains the declaration of the Instruction class, which is the</span>
+<span class="c1">/// base class for all of the VM instructions.</span>
+<span class="c1">///</span>
+<span class="c1">//===----------------------------------------------------------------------===//</span>
+</pre></div>
+</div>
+<p>A few things to note about this particular format: The “<tt class="docutils literal"><span class="pre">-*-</span> <span class="pre">C++</span> <span class="pre">-*-</span></tt>” string
+on the first line is there to tell Emacs that the source file is a C++ file, not
+a C file (Emacs assumes <tt class="docutils literal"><span class="pre">.h</span></tt> files are C files by default).</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This tag is not necessary in <tt class="docutils literal"><span class="pre">.cpp</span></tt> files. The name of the file is also
+on the first line, along with a very short description of the purpose of the
+file. This is important when printing out code and flipping though lots of
+pages.</p>
+</div>
+<p>The next section in the file is a concise note that defines the license that the
+file is released under. This makes it perfectly clear what terms the source
+code can be distributed under and should not be modified in any way.</p>
+<p>The main body is a <tt class="docutils literal"><span class="pre">doxygen</span></tt> comment (identified by the <tt class="docutils literal"><span class="pre">///</span></tt> comment
+marker instead of the usual <tt class="docutils literal"><span class="pre">//</span></tt>) describing the purpose of the file. The
+first sentence (or a passage beginning with <tt class="docutils literal"><span class="pre">\brief</span></tt>) is used as an abstract.
+Any additional information should be separated by a blank line. If an
+algorithm is being implemented or something tricky is going on, a reference
+to the paper where it is published should be included, as well as any notes or
+<em>gotchas</em> in the code to watch out for.</p>
+</div>
+<div class="section" id="class-overviews">
+<h5><a class="toc-backref" href="#id11">Class overviews</a><a class="headerlink" href="#class-overviews" title="Permalink to this headline">¶</a></h5>
+<p>Classes are one fundamental part of a good object oriented design. As such, a
+class definition should have a comment block that explains what the class is
+used for and how it works. Every non-trivial class is expected to have a
+<tt class="docutils literal"><span class="pre">doxygen</span></tt> comment block.</p>
+</div>
+<div class="section" id="method-information">
+<h5><a class="toc-backref" href="#id12">Method information</a><a class="headerlink" href="#method-information" title="Permalink to this headline">¶</a></h5>
+<p>Methods defined in a class (as well as any global functions) should also be
+documented properly. A quick note about what it does and a description of the
+borderline behaviour is all that is necessary here (unless something
+particularly tricky or insidious is going on). The hope is that people can
+figure out how to use your interfaces without reading the code itself.</p>
+<p>Good things to talk about here are what happens when something unexpected
+happens: does the method return null? Abort? Format your hard disk?</p>
+</div>
+</div>
+<div class="section" id="comment-formatting">
+<h4><a class="toc-backref" href="#id13">Comment Formatting</a><a class="headerlink" href="#comment-formatting" title="Permalink to this headline">¶</a></h4>
+<p>In general, prefer C++ style comments (<tt class="docutils literal"><span class="pre">//</span></tt> for normal comments, <tt class="docutils literal"><span class="pre">///</span></tt> for
+<tt class="docutils literal"><span class="pre">doxygen</span></tt> documentation comments). They take less space, require
+less typing, don’t have nesting problems, etc. There are a few cases when it is
+useful to use C style (<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">*/</span></tt>) comments however:</p>
+<ol class="arabic simple">
+<li>When writing C code: Obviously if you are writing C code, use C style
+comments.</li>
+<li>When writing a header file that may be <tt class="docutils literal"><span class="pre">#include</span></tt>d by a C source file.</li>
+<li>When writing a source file that is used by a tool that only accepts C style
+comments.</li>
+</ol>
+<p>Commenting out large blocks of code is discouraged, but if you really have to do
+this (for documentation purposes or as a suggestion for debug printing), use
+<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">0</span></tt> and <tt class="docutils literal"><span class="pre">#endif</span></tt>. These nest properly and are better behaved in general
+than C style comments.</p>
+</div>
+<div class="section" id="doxygen-use-in-documentation-comments">
+<h4><a class="toc-backref" href="#id14">Doxygen Use in Documentation Comments</a><a class="headerlink" href="#doxygen-use-in-documentation-comments" title="Permalink to this headline">¶</a></h4>
+<p>Use the <tt class="docutils literal"><span class="pre">\file</span></tt> command to turn the standard file header into a file-level
+comment.</p>
+<p>Include descriptive paragraphs for all public interfaces (public classes,
+member and non-member functions). Don’t just restate the information that can
+be inferred from the API name. The first sentence (or a paragraph beginning
+with <tt class="docutils literal"><span class="pre">\brief</span></tt>) is used as an abstract. Try to use a single sentence as the
+<tt class="docutils literal"><span class="pre">\brief</span></tt> adds visual clutter. Put detailed discussion into separate
+paragraphs.</p>
+<p>To refer to parameter names inside a paragraph, use the <tt class="docutils literal"><span class="pre">\p</span> <span class="pre">name</span></tt> command.
+Don’t use the <tt class="docutils literal"><span class="pre">\arg</span> <span class="pre">name</span></tt> command since it starts a new paragraph that
+contains documentation for the parameter.</p>
+<p>Wrap non-inline code examples in <tt class="docutils literal"><span class="pre">\code</span> <span class="pre">...</span> <span class="pre">\endcode</span></tt>.</p>
+<p>To document a function parameter, start a new paragraph with the
+<tt class="docutils literal"><span class="pre">\param</span> <span class="pre">name</span></tt> command. If the parameter is used as an out or an in/out
+parameter, use the <tt class="docutils literal"><span class="pre">\param</span> <span class="pre">[out]</span> <span class="pre">name</span></tt> or <tt class="docutils literal"><span class="pre">\param</span> <span class="pre">[in,out]</span> <span class="pre">name</span></tt> command,
+respectively.</p>
+<p>To describe function return value, start a new paragraph with the <tt class="docutils literal"><span class="pre">\returns</span></tt>
+command.</p>
+<p>A minimal documentation comment:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">/// Sets the xyzzy property to \p Baz.</span>
+<span class="kt">void</span> <span class="n">setXyzzy</span><span class="p">(</span><span class="kt">bool</span> <span class="n">Baz</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>A documentation comment that uses all Doxygen features in a preferred way:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">/// Does foo and bar.</span>
+<span class="c1">///</span>
+<span class="c1">/// Does not do foo the usual way if \p Baz is true.</span>
+<span class="c1">///</span>
+<span class="c1">/// Typical usage:</span>
+<span class="c1">/// \code</span>
+<span class="c1">/// fooBar(false, "quux", Res);</span>
+<span class="c1">/// \endcode</span>
+<span class="c1">///</span>
+<span class="c1">/// \param Quux kind of foo to do.</span>
+<span class="c1">/// \param [out] Result filled with bar sequence on foo success.</span>
+<span class="c1">///</span>
+<span class="c1">/// \returns true on success.</span>
+<span class="kt">bool</span> <span class="n">fooBar</span><span class="p">(</span><span class="kt">bool</span> <span class="n">Baz</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">Quux</span><span class="p">,</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="o">&</span><span class="n">Result</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Don’t duplicate the documentation comment in the header file and in the
+implementation file. Put the documentation comments for public APIs into the
+header file. Documentation comments for private APIs can go to the
+implementation file. In any case, implementation files can include additional
+comments (not necessarily in Doxygen markup) to explain implementation details
+as needed.</p>
+<p>Don’t duplicate function or class name at the beginning of the comment.
+For humans it is obvious which function or class is being documented;
+automatic documentation processing tools are smart enough to bind the comment
+to the correct declaration.</p>
+<p>Wrong:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// In Something.h:</span>
+
+<span class="c1">/// Something - An abstraction for some complicated thing.</span>
+<span class="k">class</span> <span class="nc">Something</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="c1">/// fooBar - Does foo and bar.</span>
+ <span class="kt">void</span> <span class="n">fooBar</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="c1">// In Something.cpp:</span>
+
+<span class="c1">/// fooBar - Does foo and bar.</span>
+<span class="kt">void</span> <span class="n">Something</span><span class="o">::</span><span class="n">fooBar</span><span class="p">()</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Correct:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// In Something.h:</span>
+
+<span class="c1">/// An abstraction for some complicated thing.</span>
+<span class="k">class</span> <span class="nc">Something</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="c1">/// Does foo and bar.</span>
+ <span class="kt">void</span> <span class="n">fooBar</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="c1">// In Something.cpp:</span>
+
+<span class="c1">// Builds a B-tree in order to do foo. See paper by...</span>
+<span class="kt">void</span> <span class="n">Something</span><span class="o">::</span><span class="n">fooBar</span><span class="p">()</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>It is not required to use additional Doxygen features, but sometimes it might
+be a good idea to do so.</p>
+<p>Consider:</p>
+<ul class="simple">
+<li>adding comments to any narrow namespace containing a collection of
+related functions or types;</li>
+<li>using top-level groups to organize a collection of related functions at
+namespace scope where the grouping is smaller than the namespace;</li>
+<li>using member groups and additional comments attached to member
+groups to organize within a class.</li>
+</ul>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Something</span> <span class="p">{</span>
+ <span class="c1">/// \name Functions that do Foo.</span>
+ <span class="c1">/// @{</span>
+ <span class="kt">void</span> <span class="n">fooBar</span><span class="p">();</span>
+ <span class="kt">void</span> <span class="n">fooBaz</span><span class="p">();</span>
+ <span class="c1">/// @}</span>
+ <span class="p">...</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="include-style">
+<h4><a class="toc-backref" href="#id15"><tt class="docutils literal"><span class="pre">#include</span></tt> Style</a><a class="headerlink" href="#include-style" title="Permalink to this headline">¶</a></h4>
+<p>Immediately after the <a class="reference internal" href="#header-file-comment">header file comment</a> (and include guards if working on a
+header file), the <a class="reference internal" href="#minimal-list-of-includes">minimal list of #includes</a> required by the file should be
+listed. We prefer these <tt class="docutils literal"><span class="pre">#include</span></tt>s to be listed in this order:</p>
+<ol class="arabic simple" id="local-private-headers">
+<span id="main-module-header"></span><li>Main Module Header</li>
+<li>Local/Private Headers</li>
+<li>LLVM project/subproject headers (<tt class="docutils literal"><span class="pre">clang/...</span></tt>, <tt class="docutils literal"><span class="pre">lldb/...</span></tt>, <tt class="docutils literal"><span class="pre">llvm/...</span></tt>, etc)</li>
+<li>System <tt class="docutils literal"><span class="pre">#include</span></tt>s</li>
+</ol>
+<p>and each category should be sorted lexicographically by the full path.</p>
+<p>The <a class="reference internal" href="#main-module-header">Main Module Header</a> file applies to <tt class="docutils literal"><span class="pre">.cpp</span></tt> files which implement an
+interface defined by a <tt class="docutils literal"><span class="pre">.h</span></tt> file. This <tt class="docutils literal"><span class="pre">#include</span></tt> should always be included
+<strong>first</strong> regardless of where it lives on the file system. By including a
+header file first in the <tt class="docutils literal"><span class="pre">.cpp</span></tt> files that implement the interfaces, we ensure
+that the header does not have any hidden dependencies which are not explicitly
+<tt class="docutils literal"><span class="pre">#include</span></tt>d in the header, but should be. It is also a form of documentation
+in the <tt class="docutils literal"><span class="pre">.cpp</span></tt> file to indicate where the interfaces it implements are defined.</p>
+<p>LLVM project and subproject headers should be grouped from most specific to least
+specific, for the same reasons described above. For example, LLDB depends on
+both clang and LLVM, and clang depends on LLVM. So an LLDB source file should
+include <tt class="docutils literal"><span class="pre">lldb</span></tt> headers first, followed by <tt class="docutils literal"><span class="pre">clang</span></tt> headers, followed by
+<tt class="docutils literal"><span class="pre">llvm</span></tt> headers, to reduce the possibility (for example) of an LLDB header
+accidentally picking up a missing include due to the previous inclusion of that
+header in the main source file or some earlier header file. clang should
+similarly include its own headers before including llvm headers. This rule
+applies to all LLVM subprojects.</p>
+</div>
+<div class="section" id="source-code-width">
+<span id="fit-into-80-columns"></span><h4><a class="toc-backref" href="#id16">Source Code Width</a><a class="headerlink" href="#source-code-width" title="Permalink to this headline">¶</a></h4>
+<p>Write your code to fit within 80 columns of text. This helps those of us who
+like to print out code and look at your code in an <tt class="docutils literal"><span class="pre">xterm</span></tt> without resizing
+it.</p>
+<p>The longer answer is that there must be some limit to the width of the code in
+order to reasonably allow developers to have multiple files side-by-side in
+windows on a modest display. If you are going to pick a width limit, it is
+somewhat arbitrary but you might as well pick something standard. Going with 90
+columns (for example) instead of 80 columns wouldn’t add any significant value
+and would be detrimental to printing out code. Also many other projects have
+standardized on 80 columns, so some people have already configured their editors
+for it (vs something else, like 90 columns).</p>
+<p>This is one of many contentious issues in coding standards, but it is not up for
+debate.</p>
+</div>
+<div class="section" id="use-spaces-instead-of-tabs">
+<h4><a class="toc-backref" href="#id17">Use Spaces Instead of Tabs</a><a class="headerlink" href="#use-spaces-instead-of-tabs" title="Permalink to this headline">¶</a></h4>
+<p>In all cases, prefer spaces to tabs in source files. People have different
+preferred indentation levels, and different styles of indentation that they
+like; this is fine. What isn’t fine is that different editors/viewers expand
+tabs out to different tab stops. This can cause your code to look completely
+unreadable, and it is not worth dealing with.</p>
+<p>As always, follow the <a class="reference internal" href="#golden-rule">Golden Rule</a> above: follow the style of
+existing code if you are modifying and extending it. If you like four spaces of
+indentation, <strong>DO NOT</strong> do that in the middle of a chunk of code with two spaces
+of indentation. Also, do not reindent a whole source file: it makes for
+incredible diffs that are absolutely worthless.</p>
+</div>
+<div class="section" id="indent-code-consistently">
+<h4><a class="toc-backref" href="#id18">Indent Code Consistently</a><a class="headerlink" href="#indent-code-consistently" title="Permalink to this headline">¶</a></h4>
+<p>Okay, in your first year of programming you were told that indentation is
+important. If you didn’t believe and internalize this then, now is the time.
+Just do it. With the introduction of C++11, there are some new formatting
+challenges that merit some suggestions to help have consistent, maintainable,
+and tool-friendly formatting and indentation.</p>
+<div class="section" id="format-lambdas-like-blocks-of-code">
+<h5><a class="toc-backref" href="#id19">Format Lambdas Like Blocks Of Code</a><a class="headerlink" href="#format-lambdas-like-blocks-of-code" title="Permalink to this headline">¶</a></h5>
+<p>When formatting a multi-line lambda, format it like a block of code, that’s
+what it is. If there is only one multi-line lambda in a statement, and there
+are no expressions lexically after it in the statement, drop the indent to the
+standard two space indent for a block of code, as if it were an if-block opened
+by the preceding part of the statement:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">sort</span><span class="p">(</span><span class="n">foo</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">foo</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="n">Foo</span> <span class="n">a</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">b</span><span class="p">)</span> <span class="o">-></span> <span class="kt">bool</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="n">blah</span> <span class="o"><</span> <span class="n">b</span><span class="p">.</span><span class="n">blah</span><span class="p">)</span>
+ <span class="k">return</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="n">baz</span> <span class="o"><</span> <span class="n">b</span><span class="p">.</span><span class="n">baz</span><span class="p">)</span>
+ <span class="k">return</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">a</span><span class="p">.</span><span class="n">bam</span> <span class="o"><</span> <span class="n">b</span><span class="p">.</span><span class="n">bam</span><span class="p">;</span>
+<span class="p">});</span>
+</pre></div>
+</div>
+<p>To take best advantage of this formatting, if you are designing an API which
+accepts a continuation or single callable argument (be it a functor, or
+a <tt class="docutils literal"><span class="pre">std::function</span></tt>), it should be the last argument if at all possible.</p>
+<p>If there are multiple multi-line lambdas in a statement, or there is anything
+interesting after the lambda in the statement, indent the block two spaces from
+the indent of the <tt class="docutils literal"><span class="pre">[]</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">dyn_switch</span><span class="p">(</span><span class="n">V</span><span class="o">-></span><span class="n">stripPointerCasts</span><span class="p">(),</span>
+ <span class="p">[]</span> <span class="p">(</span><span class="n">PHINode</span> <span class="o">*</span><span class="n">PN</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// process phis...</span>
+ <span class="p">},</span>
+ <span class="p">[]</span> <span class="p">(</span><span class="n">SelectInst</span> <span class="o">*</span><span class="n">SI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// process selects...</span>
+ <span class="p">},</span>
+ <span class="p">[]</span> <span class="p">(</span><span class="n">LoadInst</span> <span class="o">*</span><span class="n">LI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// process loads...</span>
+ <span class="p">},</span>
+ <span class="p">[]</span> <span class="p">(</span><span class="n">AllocaInst</span> <span class="o">*</span><span class="n">AI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// process allocas...</span>
+ <span class="p">});</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="braced-initializer-lists">
+<h5><a class="toc-backref" href="#id20">Braced Initializer Lists</a><a class="headerlink" href="#braced-initializer-lists" title="Permalink to this headline">¶</a></h5>
+<p>With C++11, there are significantly more uses of braced lists to perform
+initialization. These allow you to easily construct aggregate temporaries in
+expressions among other niceness. They now have a natural way of ending up
+nested within each other and within function calls in order to build up
+aggregates (such as option structs) from local variables. To make matters
+worse, we also have many more uses of braces in an expression context that are
+<em>not</em> performing initialization.</p>
+<p>The historically common formatting of braced initialization of aggregate
+variables does not mix cleanly with deep nesting, general expression contexts,
+function arguments, and lambdas. We suggest new code use a simple rule for
+formatting braced initialization lists: act as-if the braces were parentheses
+in a function call. The formatting rules exactly match those already well
+understood for formatting nested function calls. Examples:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">foo</span><span class="p">({</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">},</span> <span class="p">{</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">});</span>
+
+<span class="n">llvm</span><span class="o">::</span><span class="n">Constant</span> <span class="o">*</span><span class="n">Mask</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="n">llvm</span><span class="o">::</span><span class="n">ConstantInt</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">Type</span><span class="o">::</span><span class="n">getInt32Ty</span><span class="p">(</span><span class="n">getLLVMContext</span><span class="p">()),</span> <span class="mi">0</span><span class="p">),</span>
+ <span class="n">llvm</span><span class="o">::</span><span class="n">ConstantInt</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">Type</span><span class="o">::</span><span class="n">getInt32Ty</span><span class="p">(</span><span class="n">getLLVMContext</span><span class="p">()),</span> <span class="mi">1</span><span class="p">),</span>
+ <span class="n">llvm</span><span class="o">::</span><span class="n">ConstantInt</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">Type</span><span class="o">::</span><span class="n">getInt32Ty</span><span class="p">(</span><span class="n">getLLVMContext</span><span class="p">()),</span> <span class="mi">2</span><span class="p">)};</span>
+</pre></div>
+</div>
+<p>This formatting scheme also makes it particularly easy to get predictable,
+consistent, and automatic formatting with tools like <a class="reference external" href="http://clang.llvm.org/docs/ClangFormat.html">Clang Format</a>.</p>
+</div>
+</div>
+</div>
+<div class="section" id="language-and-compiler-issues">
+<h3><a class="toc-backref" href="#id21">Language and Compiler Issues</a><a class="headerlink" href="#language-and-compiler-issues" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="treat-compiler-warnings-like-errors">
+<h4><a class="toc-backref" href="#id22">Treat Compiler Warnings Like Errors</a><a class="headerlink" href="#treat-compiler-warnings-like-errors" title="Permalink to this headline">¶</a></h4>
+<p>If your code has compiler warnings in it, something is wrong — you aren’t
+casting values correctly, you have “questionable” constructs in your code, or
+you are doing something legitimately wrong. Compiler warnings can cover up
+legitimate errors in output and make dealing with a translation unit difficult.</p>
+<p>It is not possible to prevent all warnings from all compilers, nor is it
+desirable. Instead, pick a standard compiler (like <tt class="docutils literal"><span class="pre">gcc</span></tt>) that provides a
+good thorough set of warnings, and stick to it. At least in the case of
+<tt class="docutils literal"><span class="pre">gcc</span></tt>, it is possible to work around any spurious errors by changing the
+syntax of the code slightly. For example, a warning that annoys me occurs when
+I write code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">V</span> <span class="o">=</span> <span class="n">getValue</span><span class="p">())</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">gcc</span></tt> will warn me that I probably want to use the <tt class="docutils literal"><span class="pre">==</span></tt> operator, and that I
+probably mistyped it. In most cases, I haven’t, and I really don’t want the
+spurious errors. To fix this particular problem, I rewrite the code like
+this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">((</span><span class="n">V</span> <span class="o">=</span> <span class="n">getValue</span><span class="p">()))</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>which shuts <tt class="docutils literal"><span class="pre">gcc</span></tt> up. Any <tt class="docutils literal"><span class="pre">gcc</span></tt> warning that annoys you can be fixed by
+massaging the code appropriately.</p>
+</div>
+<div class="section" id="write-portable-code">
+<h4><a class="toc-backref" href="#id23">Write Portable Code</a><a class="headerlink" href="#write-portable-code" title="Permalink to this headline">¶</a></h4>
+<p>In almost all cases, it is possible and within reason to write completely
+portable code. If there are cases where it isn’t possible to write portable
+code, isolate it behind a well defined (and well documented) interface.</p>
+<p>In practice, this means that you shouldn’t assume much about the host compiler
+(and Visual Studio tends to be the lowest common denominator). If advanced
+features are used, they should only be an implementation detail of a library
+which has a simple exposed API, and preferably be buried in <tt class="docutils literal"><span class="pre">libSystem</span></tt>.</p>
+</div>
+<div class="section" id="do-not-use-rtti-or-exceptions">
+<h4><a class="toc-backref" href="#id24">Do not use RTTI or Exceptions</a><a class="headerlink" href="#do-not-use-rtti-or-exceptions" title="Permalink to this headline">¶</a></h4>
+<p>In an effort to reduce code and executable size, LLVM does not use RTTI
+(e.g. <tt class="docutils literal"><span class="pre">dynamic_cast<>;</span></tt>) or exceptions. These two language features violate
+the general C++ principle of <em>“you only pay for what you use”</em>, causing
+executable bloat even if exceptions are never used in the code base, or if RTTI
+is never used for a class. Because of this, we turn them off globally in the
+code.</p>
+<p>That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
+templates like <a class="reference internal" href="ProgrammersManual.html#isa"><em>isa<>, cast<>, and dyn_cast<></em></a>.
+This form of RTTI is opt-in and can be
+<a class="reference internal" href="HowToSetUpLLVMStyleRTTI.html"><em>added to any class</em></a>. It is also
+substantially more efficient than <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt>.</p>
+</div>
+<div class="section" id="do-not-use-static-constructors">
+<span id="static-constructor"></span><h4><a class="toc-backref" href="#id25">Do not use Static Constructors</a><a class="headerlink" href="#do-not-use-static-constructors" title="Permalink to this headline">¶</a></h4>
+<p>Static constructors and destructors (e.g. global variables whose types have a
+constructor or destructor) should not be added to the code base, and should be
+removed wherever possible. Besides <a class="reference external" href="http://yosefk.com/c++fqa/ctors.html#fqa-10.12">well known problems</a> where the order of
+initialization is undefined between globals in different source files, the
+entire concept of static constructors is at odds with the common use case of
+LLVM as a library linked into a larger application.</p>
+<p>Consider the use of LLVM as a JIT linked into another application (perhaps for
+<a class="reference external" href="http://llvm.org/Users.html">OpenGL, custom languages</a>, <a class="reference external" href="http://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf">shaders in movies</a>, etc). Due to the
+design of static constructors, they must be executed at startup time of the
+entire application, regardless of whether or how LLVM is used in that larger
+application. There are two problems with this:</p>
+<ul class="simple">
+<li>The time to run the static constructors impacts startup time of applications
+— a critical time for GUI apps, among others.</li>
+<li>The static constructors cause the app to pull many extra pages of memory off
+the disk: both the code for the constructor in each <tt class="docutils literal"><span class="pre">.o</span></tt> file and the small
+amount of data that gets touched. In addition, touched/dirty pages put more
+pressure on the VM system on low-memory machines.</li>
+</ul>
+<p>We would really like for there to be zero cost for linking in an additional LLVM
+target or other library into an application, but static constructors violate
+this goal.</p>
+<p>That said, LLVM unfortunately does contain static constructors. It would be a
+<a class="reference external" href="http://llvm.org/PR11944">great project</a> for someone to purge all static
+constructors from LLVM, and then enable the <tt class="docutils literal"><span class="pre">-Wglobal-constructors</span></tt> warning
+flag (when building with Clang) to ensure we do not regress in the future.</p>
+</div>
+<div class="section" id="use-of-class-and-struct-keywords">
+<h4><a class="toc-backref" href="#id26">Use of <tt class="docutils literal"><span class="pre">class</span></tt> and <tt class="docutils literal"><span class="pre">struct</span></tt> Keywords</a><a class="headerlink" href="#use-of-class-and-struct-keywords" title="Permalink to this headline">¶</a></h4>
+<p>In C++, the <tt class="docutils literal"><span class="pre">class</span></tt> and <tt class="docutils literal"><span class="pre">struct</span></tt> keywords can be used almost
+interchangeably. The only difference is when they are used to declare a class:
+<tt class="docutils literal"><span class="pre">class</span></tt> makes all members private by default while <tt class="docutils literal"><span class="pre">struct</span></tt> makes all
+members public by default.</p>
+<p>Unfortunately, not all compilers follow the rules and some will generate
+different symbols based on whether <tt class="docutils literal"><span class="pre">class</span></tt> or <tt class="docutils literal"><span class="pre">struct</span></tt> was used to declare
+the symbol (e.g., MSVC). This can lead to problems at link time.</p>
+<ul class="simple">
+<li>All declarations and definitions of a given <tt class="docutils literal"><span class="pre">class</span></tt> or <tt class="docutils literal"><span class="pre">struct</span></tt> must use
+the same keyword. For example:</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span><span class="p">;</span>
+
+<span class="c1">// Breaks mangling in MSVC.</span>
+<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">Data</span><span class="p">;</span> <span class="p">};</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li>As a rule of thumb, <tt class="docutils literal"><span class="pre">struct</span></tt> should be kept to structures where <em>all</em>
+members are declared public.</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Foo feels like a class... this is strange.</span>
+<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="kt">int</span> <span class="n">Data</span><span class="p">;</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">Foo</span><span class="p">()</span> <span class="o">:</span> <span class="n">Data</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
+ <span class="kt">int</span> <span class="n">getData</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Data</span><span class="p">;</span> <span class="p">}</span>
+ <span class="kt">void</span> <span class="n">setData</span><span class="p">(</span><span class="kt">int</span> <span class="n">D</span><span class="p">)</span> <span class="p">{</span> <span class="n">Data</span> <span class="o">=</span> <span class="n">D</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="c1">// Bar isn't POD, but it does look like a struct.</span>
+<span class="k">struct</span> <span class="n">Bar</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">Data</span><span class="p">;</span>
+ <span class="n">Bar</span><span class="p">()</span> <span class="o">:</span> <span class="n">Data</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="do-not-use-braced-initializer-lists-to-call-a-constructor">
+<h4><a class="toc-backref" href="#id27">Do not use Braced Initializer Lists to Call a Constructor</a><a class="headerlink" href="#do-not-use-braced-initializer-lists-to-call-a-constructor" title="Permalink to this headline">¶</a></h4>
+<p>In C++11 there is a “generalized initialization syntax” which allows calling
+constructors using braced initializer lists. Do not use these to call
+constructors with any interesting logic or if you care that you’re calling some
+<em>particular</em> constructor. Those should look like function calls using
+parentheses rather than like aggregate initialization. Similarly, if you need
+to explicitly name the type and call its constructor to create a temporary,
+don’t use a braced initializer list. Instead, use a braced initializer list
+(without any type for temporaries) when doing aggregate initialization or
+something notionally equivalent. Examples:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="c1">// Construct a Foo by reading data from the disk in the whizbang format, ...</span>
+ <span class="n">Foo</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">filename</span><span class="p">);</span>
+
+ <span class="c1">// Construct a Foo by looking up the Nth element of some global data ...</span>
+ <span class="n">Foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">N</span><span class="p">);</span>
+
+ <span class="c1">// ...</span>
+<span class="p">};</span>
+
+<span class="c1">// The Foo constructor call is very deliberate, no braces.</span>
+<span class="n">std</span><span class="o">::</span><span class="n">fill</span><span class="p">(</span><span class="n">foo</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">foo</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">Foo</span><span class="p">(</span><span class="s">"name"</span><span class="p">));</span>
+
+<span class="c1">// The pair is just being constructed like an aggregate, use braces.</span>
+<span class="n">bar_map</span><span class="p">.</span><span class="n">insert</span><span class="p">({</span><span class="n">my_key</span><span class="p">,</span> <span class="n">my_value</span><span class="p">});</span>
+</pre></div>
+</div>
+<p>If you use a braced initializer list when initializing a variable, use an equals before the open curly brace:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">data</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="use-auto-type-deduction-to-make-code-more-readable">
+<h4><a class="toc-backref" href="#id28">Use <tt class="docutils literal"><span class="pre">auto</span></tt> Type Deduction to Make Code More Readable</a><a class="headerlink" href="#use-auto-type-deduction-to-make-code-more-readable" title="Permalink to this headline">¶</a></h4>
+<p>Some are advocating a policy of “almost always <tt class="docutils literal"><span class="pre">auto</span></tt>” in C++11, however LLVM
+uses a more moderate stance. Use <tt class="docutils literal"><span class="pre">auto</span></tt> if and only if it makes the code more
+readable or easier to maintain. Don’t “almost always” use <tt class="docutils literal"><span class="pre">auto</span></tt>, but do use
+<tt class="docutils literal"><span class="pre">auto</span></tt> with initializers like <tt class="docutils literal"><span class="pre">cast<Foo>(...)</span></tt> or other places where the
+type is already obvious from the context. Another time when <tt class="docutils literal"><span class="pre">auto</span></tt> works well
+for these purposes is when the type would have been abstracted away anyways,
+often behind a container’s typedef such as <tt class="docutils literal"><span class="pre">std::vector<T>::iterator</span></tt>.</p>
+</div>
+<div class="section" id="beware-unnecessary-copies-with-auto">
+<h4><a class="toc-backref" href="#id29">Beware unnecessary copies with <tt class="docutils literal"><span class="pre">auto</span></tt></a><a class="headerlink" href="#beware-unnecessary-copies-with-auto" title="Permalink to this headline">¶</a></h4>
+<p>The convenience of <tt class="docutils literal"><span class="pre">auto</span></tt> makes it easy to forget that its default behavior
+is a copy. Particularly in range-based <tt class="docutils literal"><span class="pre">for</span></tt> loops, careless copies are
+expensive.</p>
+<p>As a rule of thumb, use <tt class="docutils literal"><span class="pre">auto</span> <span class="pre">&</span></tt> unless you need to copy the result, and use
+<tt class="docutils literal"><span class="pre">auto</span> <span class="pre">*</span></tt> when copying pointers.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Typically there's no reason to copy.</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">const</span> <span class="k">auto</span> <span class="o">&</span><span class="n">Val</span> <span class="o">:</span> <span class="n">Container</span><span class="p">)</span> <span class="p">{</span> <span class="n">observe</span><span class="p">(</span><span class="n">Val</span><span class="p">);</span> <span class="p">}</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">&</span><span class="n">Val</span> <span class="o">:</span> <span class="n">Container</span><span class="p">)</span> <span class="p">{</span> <span class="n">Val</span><span class="p">.</span><span class="n">change</span><span class="p">();</span> <span class="p">}</span>
+
+<span class="c1">// Remove the reference if you really want a new copy.</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Val</span> <span class="o">:</span> <span class="n">Container</span><span class="p">)</span> <span class="p">{</span> <span class="n">Val</span><span class="p">.</span><span class="n">change</span><span class="p">();</span> <span class="n">saveSomewhere</span><span class="p">(</span><span class="n">Val</span><span class="p">);</span> <span class="p">}</span>
+
+<span class="c1">// Copy pointers, but make it clear that they're pointers.</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">const</span> <span class="k">auto</span> <span class="o">*</span><span class="n">Ptr</span> <span class="o">:</span> <span class="n">Container</span><span class="p">)</span> <span class="p">{</span> <span class="n">observe</span><span class="p">(</span><span class="o">*</span><span class="n">Ptr</span><span class="p">);</span> <span class="p">}</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="n">Ptr</span> <span class="o">:</span> <span class="n">Container</span><span class="p">)</span> <span class="p">{</span> <span class="n">Ptr</span><span class="o">-></span><span class="n">change</span><span class="p">();</span> <span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="beware-of-non-determinism-due-to-ordering-of-pointers">
+<h4><a class="toc-backref" href="#id30">Beware of non-determinism due to ordering of pointers</a><a class="headerlink" href="#beware-of-non-determinism-due-to-ordering-of-pointers" title="Permalink to this headline">¶</a></h4>
+<p>In general, there is no relative ordering among pointers. As a result,
+when unordered containers like sets and maps are used with pointer keys
+the iteration order is undefined. Hence, iterating such containers may
+result in non-deterministic code generation. While the generated code
+might not necessarily be “wrong code”, this non-determinism might result
+in unexpected runtime crashes or simply hard to reproduce bugs on the
+customer side making it harder to debug and fix.</p>
+<p>As a rule of thumb, in case an ordered result is expected, remember to
+sort an unordered container before iteration. Or use ordered containers
+like vector/MapVector/SetVector if you want to iterate pointer keys.</p>
+</div>
+</div>
+</div>
+<div class="section" id="style-issues">
+<h2><a class="toc-backref" href="#id31">Style Issues</a><a class="headerlink" href="#style-issues" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="the-high-level-issues">
+<h3><a class="toc-backref" href="#id32">The High-Level Issues</a><a class="headerlink" href="#the-high-level-issues" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="a-public-header-file-is-a-module">
+<h4><a class="toc-backref" href="#id33">A Public Header File <strong>is</strong> a Module</a><a class="headerlink" href="#a-public-header-file-is-a-module" title="Permalink to this headline">¶</a></h4>
+<p>C++ doesn’t do too well in the modularity department. There is no real
+encapsulation or data hiding (unless you use expensive protocol classes), but it
+is what we have to work with. When you write a public header file (in the LLVM
+source tree, they live in the top level “<tt class="docutils literal"><span class="pre">include</span></tt>” directory), you are
+defining a module of functionality.</p>
+<p>Ideally, modules should be completely independent of each other, and their
+header files should only <tt class="docutils literal"><span class="pre">#include</span></tt> the absolute minimum number of headers
+possible. A module is not just a class, a function, or a namespace: it’s a
+collection of these that defines an interface. This interface may be several
+functions, classes, or data structures, but the important issue is how they work
+together.</p>
+<p>In general, a module should be implemented by one or more <tt class="docutils literal"><span class="pre">.cpp</span></tt> files. Each
+of these <tt class="docutils literal"><span class="pre">.cpp</span></tt> files should include the header that defines their interface
+first. This ensures that all of the dependences of the module header have been
+properly added to the module header itself, and are not implicit. System
+headers should be included after user headers for a translation unit.</p>
+</div>
+<div class="section" id="include-as-little-as-possible">
+<span id="minimal-list-of-includes"></span><h4><a class="toc-backref" href="#id34"><tt class="docutils literal"><span class="pre">#include</span></tt> as Little as Possible</a><a class="headerlink" href="#include-as-little-as-possible" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">#include</span></tt> hurts compile time performance. Don’t do it unless you have to,
+especially in header files.</p>
+<p>But wait! Sometimes you need to have the definition of a class to use it, or to
+inherit from it. In these cases go ahead and <tt class="docutils literal"><span class="pre">#include</span></tt> that header file. Be
+aware however that there are many cases where you don’t need to have the full
+definition of a class. If you are using a pointer or reference to a class, you
+don’t need the header file. If you are simply returning a class instance from a
+prototyped function or method, you don’t need it. In fact, for most cases, you
+simply don’t need the definition of a class. And not <tt class="docutils literal"><span class="pre">#include</span></tt>ing speeds up
+compilation.</p>
+<p>It is easy to try to go too overboard on this recommendation, however. You
+<strong>must</strong> include all of the header files that you are using — you can include
+them either directly or indirectly through another header file. To make sure
+that you don’t accidentally forget to include a header file in your module
+header, make sure to include your module header <strong>first</strong> in the implementation
+file (as mentioned above). This way there won’t be any hidden dependencies that
+you’ll find out about later.</p>
+</div>
+<div class="section" id="keep-internal-headers-private">
+<h4><a class="toc-backref" href="#id35">Keep “Internal” Headers Private</a><a class="headerlink" href="#keep-internal-headers-private" title="Permalink to this headline">¶</a></h4>
+<p>Many modules have a complex implementation that causes them to use more than one
+implementation (<tt class="docutils literal"><span class="pre">.cpp</span></tt>) file. It is often tempting to put the internal
+communication interface (helper classes, extra functions, etc) in the public
+module header file. Don’t do this!</p>
+<p>If you really need to do something like this, put a private header file in the
+same directory as the source files, and include it locally. This ensures that
+your private interface remains private and undisturbed by outsiders.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">It’s okay to put extra implementation methods in a public class itself. Just
+make them private (or protected) and all is well.</p>
+</div>
+</div>
+<div class="section" id="use-early-exits-and-continue-to-simplify-code">
+<span id="early-exits"></span><h4><a class="toc-backref" href="#id36">Use Early Exits and <tt class="docutils literal"><span class="pre">continue</span></tt> to Simplify Code</a><a class="headerlink" href="#use-early-exits-and-continue-to-simplify-code" title="Permalink to this headline">¶</a></h4>
+<p>When reading code, keep in mind how much state and how many previous decisions
+have to be remembered by the reader to understand a block of code. Aim to
+reduce indentation where possible when it doesn’t make it more difficult to
+understand the code. One great way to do this is by making use of early exits
+and the <tt class="docutils literal"><span class="pre">continue</span></tt> keyword in long loops. As an example of using an early
+exit from a function, consider this “bad” code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Value</span> <span class="o">*</span><span class="n">doSomething</span><span class="p">(</span><span class="n">Instruction</span> <span class="o">*</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">isa</span><span class="o"><</span><span class="n">TerminatorInst</span><span class="o">></span><span class="p">(</span><span class="n">I</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="n">I</span><span class="o">-></span><span class="n">hasOneUse</span><span class="p">()</span> <span class="o">&&</span> <span class="n">doOtherThing</span><span class="p">(</span><span class="n">I</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">...</span> <span class="n">some</span> <span class="kt">long</span> <span class="n">code</span> <span class="p">....</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This code has several problems if the body of the <tt class="docutils literal"><span class="pre">'if'</span></tt> is large. When
+you’re looking at the top of the function, it isn’t immediately clear that this
+<em>only</em> does interesting things with non-terminator instructions, and only
+applies to things with the other predicates. Second, it is relatively difficult
+to describe (in comments) why these predicates are important because the <tt class="docutils literal"><span class="pre">if</span></tt>
+statement makes it difficult to lay out the comments. Third, when you’re deep
+within the body of the code, it is indented an extra level. Finally, when
+reading the top of the function, it isn’t clear what the result is if the
+predicate isn’t true; you have to read to the end of the function to know that
+it returns null.</p>
+<p>It is much preferred to format the code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Value</span> <span class="o">*</span><span class="n">doSomething</span><span class="p">(</span><span class="n">Instruction</span> <span class="o">*</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Terminators never need 'something' done to them because ...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">TerminatorInst</span><span class="o">></span><span class="p">(</span><span class="n">I</span><span class="p">))</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="c1">// We conservatively avoid transforming instructions with multiple uses</span>
+ <span class="c1">// because goats like cheese.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">I</span><span class="o">-></span><span class="n">hasOneUse</span><span class="p">())</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="c1">// This is really just here for example.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">doOtherThing</span><span class="p">(</span><span class="n">I</span><span class="p">))</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="p">...</span> <span class="n">some</span> <span class="kt">long</span> <span class="n">code</span> <span class="p">....</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This fixes these problems. A similar problem frequently happens in <tt class="docutils literal"><span class="pre">for</span></tt>
+loops. A silly example is something like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">Instruction</span> <span class="o">&</span><span class="n">I</span> <span class="o">:</span> <span class="n">BB</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="o">*</span><span class="n">BO</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">BinaryOperator</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">I</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">Value</span> <span class="o">*</span><span class="n">LHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">Value</span> <span class="o">*</span><span class="n">RHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">LHS</span> <span class="o">!=</span> <span class="n">RHS</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>When you have very, very small loops, this sort of structure is fine. But if it
+exceeds more than 10-15 lines, it becomes difficult for people to read and
+understand at a glance. The problem with this sort of code is that it gets very
+nested very quickly. Meaning that the reader of the code has to keep a lot of
+context in their brain to remember what is going immediately on in the loop,
+because they don’t know if/when the <tt class="docutils literal"><span class="pre">if</span></tt> conditions will have <tt class="docutils literal"><span class="pre">else</span></tt>s etc.
+It is strongly preferred to structure the loop like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">Instruction</span> <span class="o">&</span><span class="n">I</span> <span class="o">:</span> <span class="n">BB</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">auto</span> <span class="o">*</span><span class="n">BO</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">BinaryOperator</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">I</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">BO</span><span class="p">)</span> <span class="k">continue</span><span class="p">;</span>
+
+ <span class="n">Value</span> <span class="o">*</span><span class="n">LHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">Value</span> <span class="o">*</span><span class="n">RHS</span> <span class="o">=</span> <span class="n">BO</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">LHS</span> <span class="o">==</span> <span class="n">RHS</span><span class="p">)</span> <span class="k">continue</span><span class="p">;</span>
+
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This has all the benefits of using early exits for functions: it reduces nesting
+of the loop, it makes it easier to describe why the conditions are true, and it
+makes it obvious to the reader that there is no <tt class="docutils literal"><span class="pre">else</span></tt> coming up that they
+have to push context into their brain for. If a loop is large, this can be a
+big understandability win.</p>
+</div>
+<div class="section" id="don-t-use-else-after-a-return">
+<h4><a class="toc-backref" href="#id37">Don’t use <tt class="docutils literal"><span class="pre">else</span></tt> after a <tt class="docutils literal"><span class="pre">return</span></tt></a><a class="headerlink" href="#don-t-use-else-after-a-return" title="Permalink to this headline">¶</a></h4>
+<p>For similar reasons above (reduction of indentation and easier reading), please
+do not use <tt class="docutils literal"><span class="pre">'else'</span></tt> or <tt class="docutils literal"><span class="pre">'else</span> <span class="pre">if'</span></tt> after something that interrupts control
+flow — like <tt class="docutils literal"><span class="pre">return</span></tt>, <tt class="docutils literal"><span class="pre">break</span></tt>, <tt class="docutils literal"><span class="pre">continue</span></tt>, <tt class="docutils literal"><span class="pre">goto</span></tt>, etc. For
+example, this is <em>bad</em>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">case</span> <span class="sc">'J'</span><span class="o">:</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Signed</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getsigjmp_bufType</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_sigjmp_buf</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">QualType</span><span class="p">();</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getjmp_bufType</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_jmp_buf</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">QualType</span><span class="p">();</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It is better to write it like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">case</span> <span class="sc">'J'</span><span class="o">:</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Signed</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getsigjmp_bufType</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_sigjmp_buf</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">QualType</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getjmp_bufType</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">Error</span> <span class="o">=</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_jmp_buf</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">QualType</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Or better yet (in this case) as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">case</span> <span class="sc">'J'</span><span class="o">:</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Signed</span><span class="p">)</span>
+ <span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getsigjmp_bufType</span><span class="p">();</span>
+ <span class="k">else</span>
+ <span class="n">Type</span> <span class="o">=</span> <span class="n">Context</span><span class="p">.</span><span class="n">getjmp_bufType</span><span class="p">();</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">Type</span><span class="p">.</span><span class="n">isNull</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">Error</span> <span class="o">=</span> <span class="n">Signed</span> <span class="o">?</span> <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_sigjmp_buf</span> <span class="o">:</span>
+ <span class="n">ASTContext</span><span class="o">::</span><span class="n">GE_Missing_jmp_buf</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">QualType</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The idea is to reduce indentation and the amount of code you have to keep track
+of when reading the code.</p>
+</div>
+<div class="section" id="turn-predicate-loops-into-predicate-functions">
+<h4><a class="toc-backref" href="#id38">Turn Predicate Loops into Predicate Functions</a><a class="headerlink" href="#turn-predicate-loops-into-predicate-functions" title="Permalink to this headline">¶</a></h4>
+<p>It is very common to write small loops that just compute a boolean value. There
+are a number of ways that people commonly write these, but an example of this
+sort of thing is:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">FoundFoo</span> <span class="o">=</span> <span class="kc">false</span><span class="p">;</span>
+<span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">E</span> <span class="o">=</span> <span class="n">BarList</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">BarList</span><span class="p">[</span><span class="n">I</span><span class="p">]</span><span class="o">-></span><span class="n">isFoo</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">FoundFoo</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+
+<span class="k">if</span> <span class="p">(</span><span class="n">FoundFoo</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This sort of code is awkward to write, and is almost always a bad sign. Instead
+of this sort of loop, we strongly prefer to use a predicate function (which may
+be <a class="reference internal" href="#static">static</a>) that uses <a class="reference internal" href="#early-exits">early exits</a> to compute the predicate. We prefer the
+code to be structured like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">/// \returns true if the specified list has an element that is a foo.</span>
+<span class="k">static</span> <span class="kt">bool</span> <span class="n">containsFoo</span><span class="p">(</span><span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">Bar</span><span class="o">*></span> <span class="o">&</span><span class="n">List</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">E</span> <span class="o">=</span> <span class="n">List</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">List</span><span class="p">[</span><span class="n">I</span><span class="p">]</span><span class="o">-></span><span class="n">isFoo</span><span class="p">())</span>
+ <span class="k">return</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="k">return</span> <span class="kc">false</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="p">...</span>
+
+<span class="k">if</span> <span class="p">(</span><span class="n">containsFoo</span><span class="p">(</span><span class="n">BarList</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>There are many reasons for doing this: it reduces indentation and factors out
+code which can often be shared by other code that checks for the same predicate.
+More importantly, it <em>forces you to pick a name</em> for the function, and forces
+you to write a comment for it. In this silly example, this doesn’t add much
+value. However, if the condition is complex, this can make it a lot easier for
+the reader to understand the code that queries for this predicate. Instead of
+being faced with the in-line details of how we check to see if the BarList
+contains a foo, we can trust the function name and continue reading with better
+locality.</p>
+</div>
+</div>
+<div class="section" id="the-low-level-issues">
+<h3><a class="toc-backref" href="#id39">The Low-Level Issues</a><a class="headerlink" href="#the-low-level-issues" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="name-types-functions-variables-and-enumerators-properly">
+<h4><a class="toc-backref" href="#id40">Name Types, Functions, Variables, and Enumerators Properly</a><a class="headerlink" href="#name-types-functions-variables-and-enumerators-properly" title="Permalink to this headline">¶</a></h4>
+<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
+enough how important it is to use <em>descriptive</em> names. Pick names that match
+the semantics and role of the underlying entities, within reason. Avoid
+abbreviations unless they are well known. After picking a good name, make sure
+to use consistent capitalization for the name, as inconsistency requires clients
+to either memorize the APIs or to look it up to find the exact spelling.</p>
+<p>In general, names should be in camel case (e.g. <tt class="docutils literal"><span class="pre">TextFileReader</span></tt> and
+<tt class="docutils literal"><span class="pre">isLValue()</span></tt>). Different kinds of declarations have different rules:</p>
+<ul>
+<li><p class="first"><strong>Type names</strong> (including classes, structs, enums, typedefs, etc) should be
+nouns and start with an upper-case letter (e.g. <tt class="docutils literal"><span class="pre">TextFileReader</span></tt>).</p>
+</li>
+<li><p class="first"><strong>Variable names</strong> should be nouns (as they represent state). The name should
+be camel case, and start with an upper case letter (e.g. <tt class="docutils literal"><span class="pre">Leader</span></tt> or
+<tt class="docutils literal"><span class="pre">Boats</span></tt>).</p>
+</li>
+<li><p class="first"><strong>Function names</strong> should be verb phrases (as they represent actions), and
+command-like function should be imperative. The name should be camel case,
+and start with a lower case letter (e.g. <tt class="docutils literal"><span class="pre">openFile()</span></tt> or <tt class="docutils literal"><span class="pre">isFoo()</span></tt>).</p>
+</li>
+<li><p class="first"><strong>Enum declarations</strong> (e.g. <tt class="docutils literal"><span class="pre">enum</span> <span class="pre">Foo</span> <span class="pre">{...}</span></tt>) are types, so they should
+follow the naming conventions for types. A common use for enums is as a
+discriminator for a union, or an indicator of a subclass. When an enum is
+used for something like this, it should have a <tt class="docutils literal"><span class="pre">Kind</span></tt> suffix
+(e.g. <tt class="docutils literal"><span class="pre">ValueKind</span></tt>).</p>
+</li>
+<li><p class="first"><strong>Enumerators</strong> (e.g. <tt class="docutils literal"><span class="pre">enum</span> <span class="pre">{</span> <span class="pre">Foo,</span> <span class="pre">Bar</span> <span class="pre">}</span></tt>) and <strong>public member variables</strong>
+should start with an upper-case letter, just like types. Unless the
+enumerators are defined in their own small namespace or inside a class,
+enumerators should have a prefix corresponding to the enum declaration name.
+For example, <tt class="docutils literal"><span class="pre">enum</span> <span class="pre">ValueKind</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">};</span></tt> may contain enumerators like
+<tt class="docutils literal"><span class="pre">VK_Argument</span></tt>, <tt class="docutils literal"><span class="pre">VK_BasicBlock</span></tt>, etc. Enumerators that are just
+convenience constants are exempt from the requirement for a prefix. For
+instance:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+ <span class="n">MaxSize</span> <span class="o">=</span> <span class="mi">42</span><span class="p">,</span>
+ <span class="n">Density</span> <span class="o">=</span> <span class="mi">12</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</li>
+</ul>
+<p>As an exception, classes that mimic STL classes can have member names in STL’s
+style of lower-case words separated by underscores (e.g. <tt class="docutils literal"><span class="pre">begin()</span></tt>,
+<tt class="docutils literal"><span class="pre">push_back()</span></tt>, and <tt class="docutils literal"><span class="pre">empty()</span></tt>). Classes that provide multiple
+iterators should add a singular prefix to <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt>
+(e.g. <tt class="docutils literal"><span class="pre">global_begin()</span></tt> and <tt class="docutils literal"><span class="pre">use_begin()</span></tt>).</p>
+<p>Here are some examples of good and bad names:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">VehicleMaker</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="n">Factory</span><span class="o"><</span><span class="n">Tire</span><span class="o">></span> <span class="n">F</span><span class="p">;</span> <span class="c1">// Bad -- abbreviation and non-descriptive.</span>
+ <span class="n">Factory</span><span class="o"><</span><span class="n">Tire</span><span class="o">></span> <span class="n">Factory</span><span class="p">;</span> <span class="c1">// Better.</span>
+ <span class="n">Factory</span><span class="o"><</span><span class="n">Tire</span><span class="o">></span> <span class="n">TireFactory</span><span class="p">;</span> <span class="c1">// Even better -- if VehicleMaker has more than one</span>
+ <span class="c1">// kind of factories.</span>
+<span class="p">};</span>
+
+<span class="n">Vehicle</span> <span class="n">makeVehicle</span><span class="p">(</span><span class="n">VehicleType</span> <span class="n">Type</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">VehicleMaker</span> <span class="n">M</span><span class="p">;</span> <span class="c1">// Might be OK if having a short life-span.</span>
+ <span class="n">Tire</span> <span class="n">Tmp1</span> <span class="o">=</span> <span class="n">M</span><span class="p">.</span><span class="n">makeTire</span><span class="p">();</span> <span class="c1">// Bad -- 'Tmp1' provides no information.</span>
+ <span class="n">Light</span> <span class="n">Headlight</span> <span class="o">=</span> <span class="n">M</span><span class="p">.</span><span class="n">makeLight</span><span class="p">(</span><span class="s">"head"</span><span class="p">);</span> <span class="c1">// Good -- descriptive.</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="assert-liberally">
+<h4><a class="toc-backref" href="#id41">Assert Liberally</a><a class="headerlink" href="#assert-liberally" title="Permalink to this headline">¶</a></h4>
+<p>Use the “<tt class="docutils literal"><span class="pre">assert</span></tt>” macro to its fullest. Check all of your preconditions and
+assumptions, you never know when a bug (not necessarily even yours) might be
+caught early by an assertion, which reduces debugging time dramatically. The
+“<tt class="docutils literal"><span class="pre"><cassert></span></tt>” header file is probably already included by the header files you
+are using, so it doesn’t cost anything to use it.</p>
+<p>To further assist with debugging, make sure to put some kind of error message in
+the assertion statement, which is printed if the assertion is tripped. This
+helps the poor debugger make sense of why an assertion is being made and
+enforced, and hopefully what to do about it. Here is one complete example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kr">inline</span> <span class="n">Value</span> <span class="o">*</span><span class="n">getOperand</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">I</span> <span class="o"><</span> <span class="n">Operands</span><span class="p">.</span><span class="n">size</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"getOperand() out of range!"</span><span class="p">);</span>
+ <span class="k">return</span> <span class="n">Operands</span><span class="p">[</span><span class="n">I</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here are more examples:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">assert</span><span class="p">(</span><span class="n">Ty</span><span class="o">-></span><span class="n">isPointerType</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"Can't allocate a non-pointer type!"</span><span class="p">);</span>
+
+<span class="n">assert</span><span class="p">((</span><span class="n">Opcode</span> <span class="o">==</span> <span class="n">Shl</span> <span class="o">||</span> <span class="n">Opcode</span> <span class="o">==</span> <span class="n">Shr</span><span class="p">)</span> <span class="o">&&</span> <span class="s">"ShiftInst Opcode invalid!"</span><span class="p">);</span>
+
+<span class="n">assert</span><span class="p">(</span><span class="n">idx</span> <span class="o"><</span> <span class="n">getNumSuccessors</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"Successor # out of range!"</span><span class="p">);</span>
+
+<span class="n">assert</span><span class="p">(</span><span class="n">V1</span><span class="p">.</span><span class="n">getType</span><span class="p">()</span> <span class="o">==</span> <span class="n">V2</span><span class="p">.</span><span class="n">getType</span><span class="p">()</span> <span class="o">&&</span> <span class="s">"Constant types must be identical!"</span><span class="p">);</span>
+
+<span class="n">assert</span><span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">PHINode</span><span class="o">></span><span class="p">(</span><span class="n">Succ</span><span class="o">-></span><span class="n">front</span><span class="p">())</span> <span class="o">&&</span> <span class="s">"Only works on PHId BBs!"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>You get the idea.</p>
+<p>In the past, asserts were used to indicate a piece of code that should not be
+reached. These were typically of the form:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">assert</span><span class="p">(</span><span class="mi">0</span> <span class="o">&&</span> <span class="s">"Invalid radix for integer literal"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This has a few issues, the main one being that some compilers might not
+understand the assertion, or warn about a missing return in builds where
+assertions are compiled out.</p>
+<p>Today, we have something much better: <tt class="docutils literal"><span class="pre">llvm_unreachable</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">llvm_unreachable</span><span class="p">(</span><span class="s">"Invalid radix for integer literal"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>When assertions are enabled, this will print the message if it’s ever reached
+and then exit the program. When assertions are disabled (i.e. in release
+builds), <tt class="docutils literal"><span class="pre">llvm_unreachable</span></tt> becomes a hint to compilers to skip generating
+code for this branch. If the compiler does not support this, it will fall back
+to the “abort” implementation.</p>
+<p>Neither assertions or <tt class="docutils literal"><span class="pre">llvm_unreachable</span></tt> will abort the program on a release
+build. If the error condition can be triggered by user input then the
+recoverable error mechanism described in <a class="reference internal" href="ProgrammersManual.html"><em>LLVM Programmer’s Manual</em></a> should be
+used instead. In cases where this is not practical, <tt class="docutils literal"><span class="pre">report_fatal_error</span></tt> may
+be used.</p>
+<p>Another issue is that values used only by assertions will produce an “unused
+value” warning when assertions are disabled. For example, this code will warn:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">unsigned</span> <span class="n">Size</span> <span class="o">=</span> <span class="n">V</span><span class="p">.</span><span class="n">size</span><span class="p">();</span>
+<span class="n">assert</span><span class="p">(</span><span class="n">Size</span> <span class="o">></span> <span class="mi">42</span> <span class="o">&&</span> <span class="s">"Vector smaller than it should be"</span><span class="p">);</span>
+
+<span class="kt">bool</span> <span class="n">NewToSet</span> <span class="o">=</span> <span class="n">Myset</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">Value</span><span class="p">);</span>
+<span class="n">assert</span><span class="p">(</span><span class="n">NewToSet</span> <span class="o">&&</span> <span class="s">"The value shouldn't be in the set yet"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>These are two interesting different cases. In the first case, the call to
+<tt class="docutils literal"><span class="pre">V.size()</span></tt> is only useful for the assert, and we don’t want it executed when
+assertions are disabled. Code like this should move the call into the assert
+itself. In the second case, the side effects of the call must happen whether
+the assert is enabled or not. In this case, the value should be cast to void to
+disable the warning. To be specific, it is preferred to write the code like
+this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">assert</span><span class="p">(</span><span class="n">V</span><span class="p">.</span><span class="n">size</span><span class="p">()</span> <span class="o">></span> <span class="mi">42</span> <span class="o">&&</span> <span class="s">"Vector smaller than it should be"</span><span class="p">);</span>
+
+<span class="kt">bool</span> <span class="n">NewToSet</span> <span class="o">=</span> <span class="n">Myset</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">Value</span><span class="p">);</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="n">NewToSet</span><span class="p">;</span>
+<span class="n">assert</span><span class="p">(</span><span class="n">NewToSet</span> <span class="o">&&</span> <span class="s">"The value shouldn't be in the set yet"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="do-not-use-using-namespace-std">
+<h4><a class="toc-backref" href="#id42">Do Not Use <tt class="docutils literal"><span class="pre">using</span> <span class="pre">namespace</span> <span class="pre">std</span></tt></a><a class="headerlink" href="#do-not-use-using-namespace-std" title="Permalink to this headline">¶</a></h4>
+<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
+namespace with an “<tt class="docutils literal"><span class="pre">std::</span></tt>” prefix, rather than rely on “<tt class="docutils literal"><span class="pre">using</span> <span class="pre">namespace</span>
+<span class="pre">std;</span></tt>”.</p>
+<p>In header files, adding a <tt class="docutils literal"><span class="pre">'using</span> <span class="pre">namespace</span> <span class="pre">XXX'</span></tt> directive pollutes the
+namespace of any source file that <tt class="docutils literal"><span class="pre">#include</span></tt>s the header. This is clearly a
+bad thing.</p>
+<p>In implementation files (e.g. <tt class="docutils literal"><span class="pre">.cpp</span></tt> files), the rule is more of a stylistic
+rule, but is still important. Basically, using explicit namespace prefixes
+makes the code <strong>clearer</strong>, because it is immediately obvious what facilities
+are being used and where they are coming from. And <strong>more portable</strong>, because
+namespace clashes cannot occur between LLVM code and other namespaces. The
+portability rule is important because different standard library implementations
+expose different symbols (potentially ones they shouldn’t), and future revisions
+to the C++ standard will add more symbols to the <tt class="docutils literal"><span class="pre">std</span></tt> namespace. As such, we
+never use <tt class="docutils literal"><span class="pre">'using</span> <span class="pre">namespace</span> <span class="pre">std;'</span></tt> in LLVM.</p>
+<p>The exception to the general rule (i.e. it’s not an exception for the <tt class="docutils literal"><span class="pre">std</span></tt>
+namespace) is for implementation files. For example, all of the code in the
+LLVM project implements code that lives in the ‘llvm’ namespace. As such, it is
+ok, and actually clearer, for the <tt class="docutils literal"><span class="pre">.cpp</span></tt> files to have a <tt class="docutils literal"><span class="pre">'using</span> <span class="pre">namespace</span>
+<span class="pre">llvm;'</span></tt> directive at the top, after the <tt class="docutils literal"><span class="pre">#include</span></tt>s. This reduces
+indentation in the body of the file for source editors that indent based on
+braces, and keeps the conceptual context cleaner. The general form of this rule
+is that any <tt class="docutils literal"><span class="pre">.cpp</span></tt> file that implements code in any namespace may use that
+namespace (and its parents’), but should not use any others.</p>
+</div>
+<div class="section" id="provide-a-virtual-method-anchor-for-classes-in-headers">
+<h4><a class="toc-backref" href="#id43">Provide a Virtual Method Anchor for Classes in Headers</a><a class="headerlink" href="#provide-a-virtual-method-anchor-for-classes-in-headers" title="Permalink to this headline">¶</a></h4>
+<p>If a class is defined in a header file and has a vtable (either it has virtual
+methods or it derives from classes with virtual methods), it must always have at
+least one out-of-line virtual method in the class. Without this, the compiler
+will copy the vtable and RTTI into every <tt class="docutils literal"><span class="pre">.o</span></tt> file that <tt class="docutils literal"><span class="pre">#include</span></tt>s the
+header, bloating <tt class="docutils literal"><span class="pre">.o</span></tt> file sizes and increasing link times.</p>
+</div>
+<div class="section" id="don-t-use-default-labels-in-fully-covered-switches-over-enumerations">
+<h4><a class="toc-backref" href="#id44">Don’t use default labels in fully covered switches over enumerations</a><a class="headerlink" href="#don-t-use-default-labels-in-fully-covered-switches-over-enumerations" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">-Wswitch</span></tt> warns if a switch, without a default label, over an enumeration
+does not cover every enumeration value. If you write a default label on a fully
+covered switch over an enumeration then the <tt class="docutils literal"><span class="pre">-Wswitch</span></tt> warning won’t fire
+when new elements are added to that enumeration. To help avoid adding these
+kinds of defaults, Clang has the warning <tt class="docutils literal"><span class="pre">-Wcovered-switch-default</span></tt> which is
+off by default but turned on when building LLVM with a version of Clang that
+supports the warning.</p>
+<p>A knock-on effect of this stylistic requirement is that when building LLVM with
+GCC you may get warnings related to “control may reach end of non-void function”
+if you return from each case of a covered switch-over-enum because GCC assumes
+that the enum expression may take any representable value, not just those of
+individual enumerators. To suppress this warning, use <tt class="docutils literal"><span class="pre">llvm_unreachable</span></tt> after
+the switch.</p>
+</div>
+<div class="section" id="use-range-based-for-loops-wherever-possible">
+<h4><a class="toc-backref" href="#id45">Use range-based <tt class="docutils literal"><span class="pre">for</span></tt> loops wherever possible</a><a class="headerlink" href="#use-range-based-for-loops-wherever-possible" title="Permalink to this headline">¶</a></h4>
+<p>The introduction of range-based <tt class="docutils literal"><span class="pre">for</span></tt> loops in C++11 means that explicit
+manipulation of iterators is rarely necessary. We use range-based <tt class="docutils literal"><span class="pre">for</span></tt>
+loops wherever possible for all newly added code. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">Instruction</span> <span class="o">&</span><span class="n">I</span> <span class="o">:</span> <span class="o">*</span><span class="n">BB</span><span class="p">)</span>
+ <span class="p">...</span> <span class="n">use</span> <span class="n">I</span> <span class="p">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="don-t-evaluate-end-every-time-through-a-loop">
+<h4><a class="toc-backref" href="#id46">Don’t evaluate <tt class="docutils literal"><span class="pre">end()</span></tt> every time through a loop</a><a class="headerlink" href="#don-t-evaluate-end-every-time-through-a-loop" title="Permalink to this headline">¶</a></h4>
+<p>In cases where range-based <tt class="docutils literal"><span class="pre">for</span></tt> loops can’t be used and it is necessary
+to write an explicit iterator-based loop, pay close attention to whether
+<tt class="docutils literal"><span class="pre">end()</span></tt> is re-evaluted on each loop iteration. One common mistake is to
+write a loop in this style:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="n">I</span> <span class="o">=</span> <span class="n">BB</span><span class="o">-></span><span class="n">begin</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">BB</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
+ <span class="p">...</span> <span class="n">use</span> <span class="n">I</span> <span class="p">...</span>
+</pre></div>
+</div>
+<p>The problem with this construct is that it evaluates “<tt class="docutils literal"><span class="pre">BB->end()</span></tt>” every time
+through the loop. Instead of writing the loop like this, we strongly prefer
+loops to be written so that they evaluate it once before the loop starts. A
+convenient way to do this is like so:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="n">I</span> <span class="o">=</span> <span class="n">BB</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">BB</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
+ <span class="p">...</span> <span class="n">use</span> <span class="n">I</span> <span class="p">...</span>
+</pre></div>
+</div>
+<p>The observant may quickly point out that these two loops may have different
+semantics: if the container (a basic block in this case) is being mutated, then
+“<tt class="docutils literal"><span class="pre">BB->end()</span></tt>” may change its value every time through the loop and the second
+loop may not in fact be correct. If you actually do depend on this behavior,
+please write the loop in the first form and add a comment indicating that you
+did it intentionally.</p>
+<p>Why do we prefer the second form (when correct)? Writing the loop in the first
+form has two problems. First it may be less efficient than evaluating it at the
+start of the loop. In this case, the cost is probably minor — a few extra
+loads every time through the loop. However, if the base expression is more
+complex, then the cost can rise quickly. I’ve seen loops where the end
+expression was actually something like: “<tt class="docutils literal"><span class="pre">SomeMap[X]->end()</span></tt>” and map lookups
+really aren’t cheap. By writing it in the second form consistently, you
+eliminate the issue entirely and don’t even have to think about it.</p>
+<p>The second (even bigger) issue is that writing the loop in the first form hints
+to the reader that the loop is mutating the container (a fact that a comment
+would handily confirm!). If you write the loop in the second form, it is
+immediately obvious without even looking at the body of the loop that the
+container isn’t being modified, which makes it easier to read the code and
+understand what it does.</p>
+<p>While the second form of the loop is a few extra keystrokes, we do strongly
+prefer it.</p>
+</div>
+<div class="section" id="include-iostream-is-forbidden">
+<h4><a class="toc-backref" href="#id47"><tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt> is Forbidden</a><a class="headerlink" href="#include-iostream-is-forbidden" title="Permalink to this headline">¶</a></h4>
+<p>The use of <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt> in library files is hereby <strong>forbidden</strong>,
+because many common implementations transparently inject a <a class="reference internal" href="#static-constructor">static constructor</a>
+into every translation unit that includes it.</p>
+<p>Note that using the other stream headers (<tt class="docutils literal"><span class="pre"><sstream></span></tt> for example) is not
+problematic in this regard — just <tt class="docutils literal"><span class="pre"><iostream></span></tt>. However, <tt class="docutils literal"><span class="pre">raw_ostream</span></tt>
+provides various APIs that are better performing for almost every use than
+<tt class="docutils literal"><span class="pre">std::ostream</span></tt> style APIs.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">New code should always use <a class="reference internal" href="#raw-ostream">raw_ostream</a> for writing, or the
+<tt class="docutils literal"><span class="pre">llvm::MemoryBuffer</span></tt> API for reading files.</p>
+</div>
+</div>
+<div class="section" id="use-raw-ostream">
+<span id="raw-ostream"></span><h4><a class="toc-backref" href="#id48">Use <tt class="docutils literal"><span class="pre">raw_ostream</span></tt></a><a class="headerlink" href="#use-raw-ostream" title="Permalink to this headline">¶</a></h4>
+<p>LLVM includes a lightweight, simple, and efficient stream implementation in
+<tt class="docutils literal"><span class="pre">llvm/Support/raw_ostream.h</span></tt>, which provides all of the common features of
+<tt class="docutils literal"><span class="pre">std::ostream</span></tt>. All new code should use <tt class="docutils literal"><span class="pre">raw_ostream</span></tt> instead of
+<tt class="docutils literal"><span class="pre">ostream</span></tt>.</p>
+<p>Unlike <tt class="docutils literal"><span class="pre">std::ostream</span></tt>, <tt class="docutils literal"><span class="pre">raw_ostream</span></tt> is not a template and can be forward
+declared as <tt class="docutils literal"><span class="pre">class</span> <span class="pre">raw_ostream</span></tt>. Public headers should generally not include
+the <tt class="docutils literal"><span class="pre">raw_ostream</span></tt> header, but use forward declarations and constant references
+to <tt class="docutils literal"><span class="pre">raw_ostream</span></tt> instances.</p>
+</div>
+<div class="section" id="avoid-std-endl">
+<h4><a class="toc-backref" href="#id49">Avoid <tt class="docutils literal"><span class="pre">std::endl</span></tt></a><a class="headerlink" href="#avoid-std-endl" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">std::endl</span></tt> modifier, when used with <tt class="docutils literal"><span class="pre">iostreams</span></tt> outputs a newline to
+the output stream specified. In addition to doing this, however, it also
+flushes the output stream. In other words, these are equivalent:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
+<span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="sc">'\n'</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">flush</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Most of the time, you probably have no reason to flush the output stream, so
+it’s better to use a literal <tt class="docutils literal"><span class="pre">'\n'</span></tt>.</p>
+</div>
+<div class="section" id="don-t-use-inline-when-defining-a-function-in-a-class-definition">
+<h4><a class="toc-backref" href="#id50">Don’t use <tt class="docutils literal"><span class="pre">inline</span></tt> when defining a function in a class definition</a><a class="headerlink" href="#don-t-use-inline-when-defining-a-function-in-a-class-definition" title="Permalink to this headline">¶</a></h4>
+<p>A member function defined in a class definition is implicitly inline, so don’t
+put the <tt class="docutils literal"><span class="pre">inline</span></tt> keyword in this case.</p>
+<p>Don’t:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="kr">inline</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Do:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="kt">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="microscopic-details">
+<h3><a class="toc-backref" href="#id51">Microscopic Details</a><a class="headerlink" href="#microscopic-details" title="Permalink to this headline">¶</a></h3>
+<p>This section describes preferred low-level formatting guidelines along with
+reasoning on why we prefer them.</p>
+<div class="section" id="spaces-before-parentheses">
+<h4><a class="toc-backref" href="#id52">Spaces Before Parentheses</a><a class="headerlink" href="#spaces-before-parentheses" title="Permalink to this headline">¶</a></h4>
+<p>We prefer to put a space before an open parenthesis only in control flow
+statements, but not in normal function call expressions and function-like
+macros. For example, this is good:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">X</span><span class="p">)</span> <span class="p">...</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">I</span> <span class="o">!=</span> <span class="mi">100</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">...</span>
+<span class="k">while</span> <span class="p">(</span><span class="n">LLVMRocks</span><span class="p">)</span> <span class="p">...</span>
+
+<span class="n">somefunc</span><span class="p">(</span><span class="mi">42</span><span class="p">);</span>
+<span class="n">assert</span><span class="p">(</span><span class="mi">3</span> <span class="o">!=</span> <span class="mi">4</span> <span class="o">&&</span> <span class="s">"laws of math are failing me"</span><span class="p">);</span>
+
+<span class="n">A</span> <span class="o">=</span> <span class="n">foo</span><span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="mi">92</span><span class="p">)</span> <span class="o">+</span> <span class="n">bar</span><span class="p">(</span><span class="n">X</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and this is bad:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span><span class="p">(</span><span class="n">X</span><span class="p">)</span> <span class="p">...</span>
+<span class="k">for</span><span class="p">(</span><span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">I</span> <span class="o">!=</span> <span class="mi">100</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">...</span>
+<span class="k">while</span><span class="p">(</span><span class="n">LLVMRocks</span><span class="p">)</span> <span class="p">...</span>
+
+<span class="n">somefunc</span> <span class="p">(</span><span class="mi">42</span><span class="p">);</span>
+<span class="n">assert</span> <span class="p">(</span><span class="mi">3</span> <span class="o">!=</span> <span class="mi">4</span> <span class="o">&&</span> <span class="s">"laws of math are failing me"</span><span class="p">);</span>
+
+<span class="n">A</span> <span class="o">=</span> <span class="n">foo</span> <span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="mi">92</span><span class="p">)</span> <span class="o">+</span> <span class="n">bar</span> <span class="p">(</span><span class="n">X</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The reason for doing this is not completely arbitrary. This style makes control
+flow operators stand out more, and makes expressions flow better. The function
+call operator binds very tightly as a postfix operator. Putting a space after a
+function name (as in the last example) makes it appear that the code might bind
+the arguments of the left-hand-side of a binary operator with the argument list
+of a function and the name of the right side. More specifically, it is easy to
+misread the “<tt class="docutils literal"><span class="pre">A</span></tt>” example as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">A</span> <span class="o">=</span> <span class="n">foo</span> <span class="p">((</span><span class="mi">42</span><span class="p">,</span> <span class="mi">92</span><span class="p">)</span> <span class="o">+</span> <span class="n">bar</span><span class="p">)</span> <span class="p">(</span><span class="n">X</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>when skimming through the code. By avoiding a space in a function, we avoid
+this misinterpretation.</p>
+</div>
+<div class="section" id="prefer-preincrement">
+<h4><a class="toc-backref" href="#id53">Prefer Preincrement</a><a class="headerlink" href="#prefer-preincrement" title="Permalink to this headline">¶</a></h4>
+<p>Hard fast rule: Preincrement (<tt class="docutils literal"><span class="pre">++X</span></tt>) may be no slower than postincrement
+(<tt class="docutils literal"><span class="pre">X++</span></tt>) and could very well be a lot faster than it. Use preincrementation
+whenever possible.</p>
+<p>The semantics of postincrement include making a copy of the value being
+incremented, returning it, and then preincrementing the “work value”. For
+primitive types, this isn’t a big deal. But for iterators, it can be a huge
+issue (for example, some iterators contains stack and set objects in them...
+copying an iterator could invoke the copy ctor’s of these as well). In general,
+get in the habit of always using preincrement, and you won’t have a problem.</p>
+</div>
+<div class="section" id="namespace-indentation">
+<h4><a class="toc-backref" href="#id54">Namespace Indentation</a><a class="headerlink" href="#namespace-indentation" title="Permalink to this headline">¶</a></h4>
+<p>In general, we strive to reduce indentation wherever possible. This is useful
+because we want code to <a class="reference internal" href="#fit-into-80-columns">fit into 80 columns</a> without wrapping horribly, but
+also because it makes it easier to understand the code. To facilitate this and
+avoid some insanely deep nesting on occasion, don’t indent namespaces. If it
+helps readability, feel free to add a comment indicating what namespace is
+being closed by a <tt class="docutils literal"><span class="pre">}</span></tt>. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
+<span class="k">namespace</span> <span class="n">knowledge</span> <span class="p">{</span>
+
+<span class="c1">/// This class represents things that Smith can have an intimate</span>
+<span class="c1">/// understanding of and contains the data associated with it.</span>
+<span class="k">class</span> <span class="nc">Grokable</span> <span class="p">{</span>
+<span class="p">...</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="k">explicit</span> <span class="n">Grokable</span><span class="p">()</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="o">~</span><span class="n">Grokable</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="p">...</span>
+
+<span class="p">};</span>
+
+<span class="p">}</span> <span class="c1">// end namespace knowledge</span>
+<span class="p">}</span> <span class="c1">// end namespace llvm</span>
+</pre></div>
+</div>
+<p>Feel free to skip the closing comment when the namespace being closed is
+obvious for any reason. For example, the outer-most namespace in a header file
+is rarely a source of confusion. But namespaces both anonymous and named in
+source files that are being closed half way through the file probably could use
+clarification.</p>
+</div>
+<div class="section" id="anonymous-namespaces">
+<span id="static"></span><h4><a class="toc-backref" href="#id55">Anonymous Namespaces</a><a class="headerlink" href="#anonymous-namespaces" title="Permalink to this headline">¶</a></h4>
+<p>After talking about namespaces in general, you may be wondering about anonymous
+namespaces in particular. Anonymous namespaces are a great language feature
+that tells the C++ compiler that the contents of the namespace are only visible
+within the current translation unit, allowing more aggressive optimization and
+eliminating the possibility of symbol name collisions. Anonymous namespaces are
+to C++ as “static” is to C functions and global variables. While “<tt class="docutils literal"><span class="pre">static</span></tt>”
+is available in C++, anonymous namespaces are more general: they can make entire
+classes private to a file.</p>
+<p>The problem with anonymous namespaces is that they naturally want to encourage
+indentation of their body, and they reduce locality of reference: if you see a
+random function definition in a C++ file, it is easy to see if it is marked
+static, but seeing if it is in an anonymous namespace requires scanning a big
+chunk of the file.</p>
+<p>Because of this, we have a simple guideline: make anonymous namespaces as small
+as possible, and only use them for class declarations. For example, this is
+good:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+<span class="k">class</span> <span class="nc">StringSort</span> <span class="p">{</span>
+<span class="p">...</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">StringSort</span><span class="p">(...)</span>
+ <span class="kt">bool</span> <span class="k">operator</span><span class="o"><</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">RHS</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="p">}</span> <span class="c1">// end anonymous namespace</span>
+
+<span class="k">static</span> <span class="kt">void</span> <span class="n">runHelper</span><span class="p">()</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+
+<span class="kt">bool</span> <span class="n">StringSort</span><span class="o">::</span><span class="k">operator</span><span class="o"><</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">RHS</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This is bad:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="p">{</span>
+
+<span class="k">class</span> <span class="nc">StringSort</span> <span class="p">{</span>
+<span class="p">...</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">StringSort</span><span class="p">(...)</span>
+ <span class="kt">bool</span> <span class="k">operator</span><span class="o"><</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">RHS</span><span class="p">)</span> <span class="k">const</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="n">runHelper</span><span class="p">()</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+
+<span class="kt">bool</span> <span class="n">StringSort</span><span class="o">::</span><span class="k">operator</span><span class="o"><</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">RHS</span><span class="p">)</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+
+<span class="p">}</span> <span class="c1">// end anonymous namespace</span>
+</pre></div>
+</div>
+<p>This is bad specifically because if you’re looking at “<tt class="docutils literal"><span class="pre">runHelper</span></tt>” in the middle
+of a large C++ file, that you have no immediate way to tell if it is local to
+the file. When it is marked static explicitly, this is immediately obvious.
+Also, there is no reason to enclose the definition of “<tt class="docutils literal"><span class="pre">operator<</span></tt>” in the
+namespace just because it was declared there.</p>
+</div>
+</div>
+</div>
+<div class="section" id="see-also">
+<h2><a class="toc-backref" href="#id56">See Also</a><a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>A lot of these comments and recommendations have been culled from other sources.
+Two particularly important books for our work are:</p>
+<ol class="arabic simple">
+<li><a class="reference external" href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective C++</a>
+by Scott Meyers. Also interesting and useful are “More Effective C++” and
+“Effective STL” by the same author.</li>
+<li><a class="reference external" href="http://www.amazon.com/Large-Scale-Software-Design-John-Lakos/dp/0201633620/ref=sr_1_1">Large-Scale C++ Software Design</a>
+by John Lakos</li>
+</ol>
+<p>If you get some free time, and you haven’t read them: do so, you might learn
+something.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="CommandLine.html" title="CommandLine 2.0 Library Manual"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/FileCheck.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/FileCheck.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/FileCheck.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/FileCheck.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,556 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>FileCheck - Flexible pattern matching file verifier — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="tblgen - Target Description To C++ Code Generator" href="tblgen.html" />
+ <link rel="prev" title="llvm-bcanalyzer - LLVM bitcode analyzer" href="llvm-bcanalyzer.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="tblgen.html" title="tblgen - Target Description To C++ Code Generator"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="filecheck-flexible-pattern-matching-file-verifier">
+<h1>FileCheck - Flexible pattern matching file verifier<a class="headerlink" href="#filecheck-flexible-pattern-matching-file-verifier" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">FileCheck</strong> <em>match-filename</em> [<em>–check-prefix=XXX</em>] [<em>–strict-whitespace</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">FileCheck</strong> reads two files (one from standard input, and one
+specified on the command line) and uses one to verify the other. This
+behavior is particularly useful for the testsuite, which wants to verify that
+the output of some tool (e.g. <strong class="program">llc</strong>) contains the expected information
+(for example, a movsd from esp or whatever is interesting). This is similar to
+using <strong class="program">grep</strong>, but it is optimized for matching multiple different
+inputs in one file in a specific order.</p>
+<p>The <tt class="docutils literal"><span class="pre">match-filename</span></tt> file specifies the file that contains the patterns to
+match. The file to verify is read from standard input unless the
+<a class="reference internal" href="#cmdoption--input-file"><em class="xref std std-option">--input-file</em></a> option is used.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--check-prefix">
+<tt class="descname">--check-prefix</tt><tt class="descclassname"> prefix</tt><a class="headerlink" href="#cmdoption--check-prefix" title="Permalink to this definition">¶</a></dt>
+<dd><p>FileCheck searches the contents of <tt class="docutils literal"><span class="pre">match-filename</span></tt> for patterns to
+match. By default, these patterns are prefixed with “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>”.
+If you’d like to use a different prefix (e.g. because the same input
+file is checking multiple different tool or options), the
+<a class="reference internal" href="#cmdoption--check-prefix"><em class="xref std std-option">--check-prefix</em></a> argument allows you to specify one or more
+prefixes to match. Multiple prefixes are useful for tests which might
+change for different run options, but most lines remain the same.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--check-prefixes">
+<tt class="descname">--check-prefixes</tt><tt class="descclassname"> prefix1,prefix2,...</tt><a class="headerlink" href="#cmdoption--check-prefixes" title="Permalink to this definition">¶</a></dt>
+<dd><p>An alias of <a class="reference internal" href="#cmdoption--check-prefix"><em class="xref std std-option">--check-prefix</em></a> that allows multiple prefixes to be
+specified as a comma separated list.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--input-file">
+<tt class="descname">--input-file</tt><tt class="descclassname"> filename</tt><a class="headerlink" href="#cmdoption--input-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>File to check (defaults to stdin).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--match-full-lines">
+<tt class="descname">--match-full-lines</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--match-full-lines" title="Permalink to this definition">¶</a></dt>
+<dd><p>By default, FileCheck allows matches of anywhere on a line. This
+option will require all positive matches to cover an entire
+line. Leading and trailing whitespace is ignored, unless
+<a class="reference internal" href="#cmdoption--strict-whitespace"><em class="xref std std-option">--strict-whitespace</em></a> is also specified. (Note: negative
+matches from <tt class="docutils literal"><span class="pre">CHECK-NOT</span></tt> are not affected by this option!)</p>
+<p>Passing this option is equivalent to inserting <tt class="docutils literal"><span class="pre">{{^</span> <span class="pre">*}}</span></tt> or
+<tt class="docutils literal"><span class="pre">{{^}}</span></tt> before, and <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">*$}}</span></tt> or <tt class="docutils literal"><span class="pre">{{$}}</span></tt> after every positive
+check pattern.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--strict-whitespace">
+<tt class="descname">--strict-whitespace</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--strict-whitespace" title="Permalink to this definition">¶</a></dt>
+<dd><p>By default, FileCheck canonicalizes input horizontal whitespace (spaces and
+tabs) which causes it to ignore these differences (a space will match a tab).
+The <a class="reference internal" href="#cmdoption--strict-whitespace"><em class="xref std std-option">--strict-whitespace</em></a> argument disables this behavior. End-of-line
+sequences are canonicalized to UNIX-style <tt class="docutils literal"><span class="pre">\n</span></tt> in all modes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--implicit-check-not">
+<tt class="descname">--implicit-check-not</tt><tt class="descclassname"> check-pattern</tt><a class="headerlink" href="#cmdoption--implicit-check-not" title="Permalink to this definition">¶</a></dt>
+<dd><p>Adds implicit negative checks for the specified patterns between positive
+checks. The option allows writing stricter tests without stuffing them with
+<tt class="docutils literal"><span class="pre">CHECK-NOT</span></tt>s.</p>
+<p>For example, “<tt class="docutils literal"><span class="pre">--implicit-check-not</span> <span class="pre">warning:</span></tt>” can be useful when testing
+diagnostic messages from tools that don’t have an option similar to <tt class="docutils literal"><span class="pre">clang</span>
+<span class="pre">-verify</span></tt>. With this option FileCheck will verify that input does not contain
+warnings not covered by any <tt class="docutils literal"><span class="pre">CHECK:</span></tt> patterns.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--enable-var-scope">
+<tt class="descname">--enable-var-scope</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--enable-var-scope" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enables scope for regex variables.</p>
+<p>Variables with names that start with <tt class="docutils literal"><span class="pre">$</span></tt> are considered global and
+remain set throughout the file.</p>
+<p>All other variables get undefined after each encountered <tt class="docutils literal"><span class="pre">CHECK-LABEL</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-D">
+<tt class="descname">-D</tt><tt class="descclassname"><VAR=VALUE></tt><a class="headerlink" href="#cmdoption-D" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets a filecheck variable <tt class="docutils literal"><span class="pre">VAR</span></tt> with value <tt class="docutils literal"><span class="pre">VALUE</span></tt> that can be used in
+<tt class="docutils literal"><span class="pre">CHECK:</span></tt> lines.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-version">
+<tt class="descname">-version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the version number of this program.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">FileCheck</strong> verifies that the file matches the expected contents,
+it exits with 0. Otherwise, if not, or if an error occurs, it will exit with a
+non-zero value.</p>
+</div>
+<div class="section" id="tutorial">
+<h2>TUTORIAL<a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h2>
+<p>FileCheck is typically used from LLVM regression tests, being invoked on the RUN
+line of the test. A simple example of using FileCheck from a RUN line looks
+like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s</span>
+</pre></div>
+</div>
+<p>This syntax says to pipe the current file (“<tt class="docutils literal"><span class="pre">%s</span></tt>”) into <tt class="docutils literal"><span class="pre">llvm-as</span></tt>, pipe
+that into <tt class="docutils literal"><span class="pre">llc</span></tt>, then pipe the output of <tt class="docutils literal"><span class="pre">llc</span></tt> into <tt class="docutils literal"><span class="pre">FileCheck</span></tt>. This
+means that FileCheck will be verifying its standard input (the llc output)
+against the filename argument specified (the original <tt class="docutils literal"><span class="pre">.ll</span></tt> file specified by
+“<tt class="docutils literal"><span class="pre">%s</span></tt>”). To see how this works, let’s look at the rest of the <tt class="docutils literal"><span class="pre">.ll</span></tt> file
+(after the RUN line):</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">void</span> <span class="vg">@sub1</span><span class="p">(</span><span class="k">i32</span><span class="p">*</span> <span class="nv">%p</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%v</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+<span class="c">; CHECK: sub1:</span>
+<span class="c">; CHECK: subl</span>
+ <span class="nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.atomic.load.sub.i32.p0i32</span><span class="p">(</span><span class="k">i32</span><span class="p">*</span> <span class="nv">%p</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%v</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@inc4</span><span class="p">(</span><span class="k">i64</span><span class="p">*</span> <span class="nv">%p</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+<span class="c">; CHECK: inc4:</span>
+<span class="c">; CHECK: incq</span>
+ <span class="nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i64</span> <span class="vg">@llvm.atomic.load.add.i64.p0i64</span><span class="p">(</span><span class="k">i64</span><span class="p">*</span> <span class="nv">%p</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here you can see some “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>” lines specified in comments. Now you can
+see how the file is piped into <tt class="docutils literal"><span class="pre">llvm-as</span></tt>, then <tt class="docutils literal"><span class="pre">llc</span></tt>, and the machine code
+output is what we are verifying. FileCheck checks the machine code output to
+verify that it matches what the “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>” lines specify.</p>
+<p>The syntax of the “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>” lines is very simple: they are fixed strings that
+must occur in order. FileCheck defaults to ignoring horizontal whitespace
+differences (e.g. a space is allowed to match a tab) but otherwise, the contents
+of the “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>” line is required to match some thing in the test file exactly.</p>
+<p>One nice thing about FileCheck (compared to grep) is that it allows merging
+test cases together into logical groups. For example, because the test above
+is checking for the “<tt class="docutils literal"><span class="pre">sub1:</span></tt>” and “<tt class="docutils literal"><span class="pre">inc4:</span></tt>” labels, it will not match
+unless there is a “<tt class="docutils literal"><span class="pre">subl</span></tt>” in between those labels. If it existed somewhere
+else in the file, that would not count: “<tt class="docutils literal"><span class="pre">grep</span> <span class="pre">subl</span></tt>” matches if “<tt class="docutils literal"><span class="pre">subl</span></tt>”
+exists anywhere in the file.</p>
+<div class="section" id="the-filecheck-check-prefix-option">
+<h3>The FileCheck -check-prefix option<a class="headerlink" href="#the-filecheck-check-prefix-option" title="Permalink to this headline">¶</a></h3>
+<p>The FileCheck <cite>-check-prefix</cite> option allows multiple test
+configurations to be driven from one <cite>.ll</cite> file. This is useful in many
+circumstances, for example, testing different architectural variants with
+<strong class="program">llc</strong>. Here’s a simple example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \</span>
+<span class="c">; RUN: | FileCheck %s -check-prefix=X32</span>
+<span class="c">; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \</span>
+<span class="c">; RUN: | FileCheck %s -check-prefix=X64</span>
+
+<span class="k">define</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="vg">@pinsrd_1</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%s</span><span class="p">,</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="nv">%tmp</span><span class="p">)</span> <span class="k">nounwind</span> <span class="p">{</span>
+ <span class="nv">%tmp1</span> <span class="p">=</span> <span class="k">insertelement</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span><span class="c">; %tmp, i32 %s, i32 1</span>
+ <span class="k">ret</span> <span class="p"><</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="nv">%tmp1</span>
+<span class="c">; X32: pinsrd_1:</span>
+<span class="c">; X32: pinsrd $1, 4(%esp), %xmm0</span>
+
+<span class="c">; X64: pinsrd_1:</span>
+<span class="c">; X64: pinsrd $1, %edi, %xmm0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case, we’re testing that we get the expected code generation with
+both 32-bit and 64-bit code generation.</p>
+</div>
+<div class="section" id="the-check-next-directive">
+<h3>The “CHECK-NEXT:” directive<a class="headerlink" href="#the-check-next-directive" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes you want to match lines and would like to verify that matches
+happen on exactly consecutive lines with no other lines in between them. In
+this case, you can use “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>” and “<tt class="docutils literal"><span class="pre">CHECK-NEXT:</span></tt>” directives to specify
+this. If you specified a custom check prefix, just use “<tt class="docutils literal"><span class="pre"><PREFIX>-NEXT:</span></tt>”.
+For example, something like this works as you’d expect:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">void</span> <span class="vg">@t2</span><span class="p">(<</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">>*</span> <span class="nv">%r</span><span class="p">,</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">>*</span> <span class="nv">%A</span><span class="p">,</span> <span class="kt">double</span> <span class="nv">%B</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nv">%tmp3</span> <span class="p">=</span> <span class="k">load</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">>*</span> <span class="nv">%A</span><span class="p">,</span> <span class="k">align</span> <span class="m">16</span>
+ <span class="nv">%tmp7</span> <span class="p">=</span> <span class="k">insertelement</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">></span> <span class="k">undef</span><span class="p">,</span> <span class="kt">double</span> <span class="nv">%B</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span>
+ <span class="nv">%tmp9</span> <span class="p">=</span> <span class="k">shufflevector</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">></span> <span class="nv">%tmp3</span><span class="p">,</span>
+ <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">></span> <span class="nv">%tmp7</span><span class="p">,</span>
+ <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="k">i32</span><span class="p">></span> <span class="p"><</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span> <span class="p">></span>
+ <span class="k">store</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">></span> <span class="nv">%tmp9</span><span class="p">,</span> <span class="p"><</span><span class="m">2</span> <span class="k">x</span> <span class="kt">double</span><span class="p">>*</span> <span class="nv">%r</span><span class="p">,</span> <span class="k">align</span> <span class="m">16</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+
+<span class="c">; CHECK: t2:</span>
+<span class="c">; CHECK: movl 8(%esp), %eax</span>
+<span class="c">; CHECK-NEXT: movapd (%eax), %xmm0</span>
+<span class="c">; CHECK-NEXT: movhpd 12(%esp), %xmm0</span>
+<span class="c">; CHECK-NEXT: movl 4(%esp), %eax</span>
+<span class="c">; CHECK-NEXT: movapd %xmm0, (%eax)</span>
+<span class="c">; CHECK-NEXT: ret</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>“<tt class="docutils literal"><span class="pre">CHECK-NEXT:</span></tt>” directives reject the input unless there is exactly one
+newline between it and the previous directive. A “<tt class="docutils literal"><span class="pre">CHECK-NEXT:</span></tt>” cannot be
+the first directive in a file.</p>
+</div>
+<div class="section" id="the-check-same-directive">
+<h3>The “CHECK-SAME:” directive<a class="headerlink" href="#the-check-same-directive" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes you want to match lines and would like to verify that matches happen
+on the same line as the previous match. In this case, you can use “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>”
+and “<tt class="docutils literal"><span class="pre">CHECK-SAME:</span></tt>” directives to specify this. If you specified a custom
+check prefix, just use “<tt class="docutils literal"><span class="pre"><PREFIX>-SAME:</span></tt>”.</p>
+<p>“<tt class="docutils literal"><span class="pre">CHECK-SAME:</span></tt>” is particularly powerful in conjunction with “<tt class="docutils literal"><span class="pre">CHECK-NOT:</span></tt>”
+(described below).</p>
+<p>For example, the following works like you’d expect:</p>
+<div class="highlight-llvm"><pre>!0 = !DILocation(line: 5, scope: !1, inlinedAt: !2)
+
+; CHECK: !DILocation(line: 5,
+; CHECK-NOT: column:
+; CHECK-SAME: scope: ![[SCOPE:[0-9]+]]</pre>
+</div>
+<p>“<tt class="docutils literal"><span class="pre">CHECK-SAME:</span></tt>” directives reject the input if there are any newlines between
+it and the previous directive. A “<tt class="docutils literal"><span class="pre">CHECK-SAME:</span></tt>” cannot be the first
+directive in a file.</p>
+</div>
+<div class="section" id="the-check-not-directive">
+<h3>The “CHECK-NOT:” directive<a class="headerlink" href="#the-check-not-directive" title="Permalink to this headline">¶</a></h3>
+<p>The “<tt class="docutils literal"><span class="pre">CHECK-NOT:</span></tt>” directive is used to verify that a string doesn’t occur
+between two matches (or before the first match, or after the last match). For
+example, to verify that a load is removed by a transformation, a test like this
+can be used:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i8</span> <span class="vg">@coerce_offset0</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%V</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%P</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%V</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%P</span>
+
+ <span class="nv">%P2</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%P</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
+ <span class="nv">%P3</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%P2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span>
+
+ <span class="nv">%A</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%P3</span>
+ <span class="k">ret</span> <span class="k">i8</span> <span class="nv">%A</span>
+<span class="c">; CHECK: @coerce_offset0</span>
+<span class="c">; CHECK-NOT: load</span>
+<span class="c">; CHECK: ret i8</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-check-dag-directive">
+<h3>The “CHECK-DAG:” directive<a class="headerlink" href="#the-check-dag-directive" title="Permalink to this headline">¶</a></h3>
+<p>If it’s necessary to match strings that don’t occur in a strictly sequential
+order, “<tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt>” could be used to verify them between two matches (or
+before the first match, or after the last match). For example, clang emits
+vtable globals in reverse order. Using <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt>, we can keep the checks
+in the natural order:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// RUN: %clang_cc1 %s -emit-llvm -o - | FileCheck %s</span>
+
+<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="k">virtual</span> <span class="kt">void</span> <span class="n">method</span><span class="p">();</span> <span class="p">};</span>
+<span class="n">Foo</span> <span class="n">f</span><span class="p">;</span> <span class="c1">// emit vtable</span>
+<span class="c1">// CHECK-DAG: @_ZTV3Foo =</span>
+
+<span class="k">struct</span> <span class="n">Bar</span> <span class="p">{</span> <span class="k">virtual</span> <span class="kt">void</span> <span class="n">method</span><span class="p">();</span> <span class="p">};</span>
+<span class="n">Bar</span> <span class="n">b</span><span class="p">;</span>
+<span class="c1">// CHECK-DAG: @_ZTV3Bar =</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">CHECK-NOT:</span></tt> directives could be mixed with <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt> directives to
+exclude strings between the surrounding <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt> directives. As a result,
+the surrounding <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt> directives cannot be reordered, i.e. all
+occurrences matching <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt> before <tt class="docutils literal"><span class="pre">CHECK-NOT:</span></tt> must not fall behind
+occurrences matching <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt> after <tt class="docutils literal"><span class="pre">CHECK-NOT:</span></tt>. For example,</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; CHECK-DAG: BEFORE</span>
+<span class="c">; CHECK-NOT: NOT</span>
+<span class="c">; CHECK-DAG: AFTER</span>
+</pre></div>
+</div>
+<p>This case will reject input strings where <tt class="docutils literal"><span class="pre">BEFORE</span></tt> occurs after <tt class="docutils literal"><span class="pre">AFTER</span></tt>.</p>
+<p>With captured variables, <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt> is able to match valid topological
+orderings of a DAG with edges from the definition of a variable to its use.
+It’s useful, e.g., when your test cases need to match different output
+sequences from the instruction scheduler. For example,</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; CHECK-DAG: add [[REG1:r[0-9]+]], r1, r2</span>
+<span class="c">; CHECK-DAG: add [[REG2:r[0-9]+]], r3, r4</span>
+<span class="c">; CHECK: mul r5, [[REG1]], [[REG2]]</span>
+</pre></div>
+</div>
+<p>In this case, any order of that two <tt class="docutils literal"><span class="pre">add</span></tt> instructions will be allowed.</p>
+<p>If you are defining <cite>and</cite> using variables in the same <tt class="docutils literal"><span class="pre">CHECK-DAG:</span></tt> block,
+be aware that the definition rule can match <cite>after</cite> its use.</p>
+<p>So, for instance, the code below will pass:</p>
+<div class="highlight-text"><div class="highlight"><pre>; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
+; CHECK-DAG: vmov.32 [[REG2]][1]
+vmov.32 d0[1]
+vmov.32 d0[0]
+</pre></div>
+</div>
+<p>While this other code, will not:</p>
+<div class="highlight-text"><div class="highlight"><pre>; CHECK-DAG: vmov.32 [[REG2:d[0-9]+]][0]
+; CHECK-DAG: vmov.32 [[REG2]][1]
+vmov.32 d1[1]
+vmov.32 d0[0]
+</pre></div>
+</div>
+<p>While this can be very useful, it’s also dangerous, because in the case of
+register sequence, you must have a strong order (read before write, copy before
+use, etc). If the definition your test is looking for doesn’t match (because
+of a bug in the compiler), it may match further away from the use, and mask
+real bugs away.</p>
+<p>In those cases, to enforce the order, use a non-DAG directive between DAG-blocks.</p>
+</div>
+<div class="section" id="the-check-label-directive">
+<h3>The “CHECK-LABEL:” directive<a class="headerlink" href="#the-check-label-directive" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes in a file containing multiple tests divided into logical blocks, one
+or more <tt class="docutils literal"><span class="pre">CHECK:</span></tt> directives may inadvertently succeed by matching lines in a
+later block. While an error will usually eventually be generated, the check
+flagged as causing the error may not actually bear any relationship to the
+actual source of the problem.</p>
+<p>In order to produce better error messages in these cases, the “<tt class="docutils literal"><span class="pre">CHECK-LABEL:</span></tt>”
+directive can be used. It is treated identically to a normal <tt class="docutils literal"><span class="pre">CHECK</span></tt>
+directive except that FileCheck makes an additional assumption that a line
+matched by the directive cannot also be matched by any other check present in
+<tt class="docutils literal"><span class="pre">match-filename</span></tt>; this is intended to be used for lines containing labels or
+other unique identifiers. Conceptually, the presence of <tt class="docutils literal"><span class="pre">CHECK-LABEL</span></tt> divides
+the input stream into separate blocks, each of which is processed independently,
+preventing a <tt class="docutils literal"><span class="pre">CHECK:</span></tt> directive in one block matching a line in another block.
+If <tt class="docutils literal"><span class="pre">--enable-var-scope</span></tt> is in effect, all local variables are cleared at the
+beginning of the block.</p>
+<p>For example,</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="vg">@C_ctor_base</span><span class="p">(</span><span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+<span class="c">; CHECK-LABEL: C_ctor_base:</span>
+<span class="c">; CHECK: mov [[SAVETHIS:r[0-9]+]], r0</span>
+<span class="c">; CHECK: bl A_ctor_base</span>
+<span class="c">; CHECK: mov r0, [[SAVETHIS]]</span>
+ <span class="nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span> <span class="k">to</span> <span class="nv">%struct.A</span><span class="p">*</span>
+ <span class="nv">%call</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="nv">%struct.A</span><span class="p">*</span> <span class="vg">@A_ctor_base</span><span class="p">(</span><span class="nv">%struct.A</span><span class="p">*</span> <span class="nv-Anonymous">%0</span><span class="p">)</span>
+ <span class="nv-Anonymous">%1</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span> <span class="k">to</span> <span class="nv">%struct.B</span><span class="p">*</span>
+ <span class="nv">%call2</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="nv">%struct.B</span><span class="p">*</span> <span class="vg">@B_ctor_base</span><span class="p">(</span><span class="nv">%struct.B</span><span class="p">*</span> <span class="nv-Anonymous">%1</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%x</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="nv">%struct.C</span><span class="p">*</span> <span class="nv">%this</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="nv">%struct.D</span><span class="p">*</span> <span class="vg">@D_ctor_base</span><span class="p">(</span><span class="nv">%struct.D</span><span class="p">*</span> <span class="nv">%this</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+<span class="c">; CHECK-LABEL: D_ctor_base:</span>
+</pre></div>
+</div>
+<p>The use of <tt class="docutils literal"><span class="pre">CHECK-LABEL:</span></tt> directives in this case ensures that the three
+<tt class="docutils literal"><span class="pre">CHECK:</span></tt> directives only accept lines corresponding to the body of the
+<tt class="docutils literal"><span class="pre">@C_ctor_base</span></tt> function, even if the patterns match lines found later in
+the file. Furthermore, if one of these three <tt class="docutils literal"><span class="pre">CHECK:</span></tt> directives fail,
+FileCheck will recover by continuing to the next block, allowing multiple test
+failures to be detected in a single invocation.</p>
+<p>There is no requirement that <tt class="docutils literal"><span class="pre">CHECK-LABEL:</span></tt> directives contain strings that
+correspond to actual syntactic labels in a source or output language: they must
+simply uniquely match a single line in the file being verified.</p>
+<p><tt class="docutils literal"><span class="pre">CHECK-LABEL:</span></tt> directives cannot contain variable definitions or uses.</p>
+</div>
+<div class="section" id="filecheck-pattern-matching-syntax">
+<h3>FileCheck Pattern Matching Syntax<a class="headerlink" href="#filecheck-pattern-matching-syntax" title="Permalink to this headline">¶</a></h3>
+<p>All FileCheck directives take a pattern to match.
+For most uses of FileCheck, fixed string matching is perfectly sufficient. For
+some things, a more flexible form of matching is desired. To support this,
+FileCheck allows you to specify regular expressions in matching strings,
+surrounded by double braces: <tt class="docutils literal"><span class="pre">{{yourregex}}</span></tt>. FileCheck implements a POSIX
+regular expression matcher; it supports Extended POSIX regular expressions
+(ERE). Because we want to use fixed string matching for a majority of what we
+do, FileCheck has been designed to support mixing and matching fixed string
+matching with regular expressions. This allows you to write things like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}</span>
+</pre></div>
+</div>
+<p>In this case, any offset from the ESP register will be allowed, and any xmm
+register will be allowed.</p>
+<p>Because regular expressions are enclosed with double braces, they are
+visually distinct, and you don’t need to use escape characters within the double
+braces like you would in C. In the rare case that you want to match double
+braces explicitly from the input, you can use something ugly like
+<tt class="docutils literal"><span class="pre">{{[{][{]}}</span></tt> as your pattern.</p>
+</div>
+<div class="section" id="filecheck-variables">
+<h3>FileCheck Variables<a class="headerlink" href="#filecheck-variables" title="Permalink to this headline">¶</a></h3>
+<p>It is often useful to match a pattern and then verify that it occurs again
+later in the file. For codegen tests, this can be useful to allow any register,
+but verify that that register is used consistently later. To do this,
+<strong class="program">FileCheck</strong> allows named variables to be defined and substituted into
+patterns. Here is a simple example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; CHECK: test5:</span>
+<span class="c">; CHECK: notw [[REGISTER:%[a-z]+]]</span>
+<span class="c">; CHECK: andw {{.*}}[[REGISTER]]</span>
+</pre></div>
+</div>
+<p>The first check line matches a regex <tt class="docutils literal"><span class="pre">%[a-z]+</span></tt> and captures it into the
+variable <tt class="docutils literal"><span class="pre">REGISTER</span></tt>. The second line verifies that whatever is in
+<tt class="docutils literal"><span class="pre">REGISTER</span></tt> occurs later in the file after an “<tt class="docutils literal"><span class="pre">andw</span></tt>”. <strong class="program">FileCheck</strong>
+variable references are always contained in <tt class="docutils literal"><span class="pre">[[</span> <span class="pre">]]</span></tt> pairs, and their names can
+be formed with the regex <tt class="docutils literal"><span class="pre">[a-zA-Z_][a-zA-Z0-9_]*</span></tt>. If a colon follows the name,
+then it is a definition of the variable; otherwise, it is a use.</p>
+<p><strong class="program">FileCheck</strong> variables can be defined multiple times, and uses always
+get the latest value. Variables can also be used later on the same line they
+were defined on. For example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; CHECK: op [[REG:r[0-9]+]], [[REG]]</span>
+</pre></div>
+</div>
+<p>Can be useful if you want the operands of <tt class="docutils literal"><span class="pre">op</span></tt> to be the same register,
+and don’t care exactly which register it is.</p>
+<p>If <tt class="docutils literal"><span class="pre">--enable-var-scope</span></tt> is in effect, variables with names that
+start with <tt class="docutils literal"><span class="pre">$</span></tt> are considered to be global. All others variables are
+local. All local variables get undefined at the beginning of each
+CHECK-LABEL block. Global variables are not affected by CHECK-LABEL.
+This makes it easier to ensure that individual tests are not affected
+by variables set in preceding tests.</p>
+</div>
+<div class="section" id="filecheck-expressions">
+<h3>FileCheck Expressions<a class="headerlink" href="#filecheck-expressions" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes there’s a need to verify output which refers line numbers of the
+match file, e.g. when testing compiler diagnostics. This introduces a certain
+fragility of the match file structure, as “<tt class="docutils literal"><span class="pre">CHECK:</span></tt>” lines contain absolute
+line numbers in the same file, which have to be updated whenever line numbers
+change due to text addition or deletion.</p>
+<p>To support this case, FileCheck allows using <tt class="docutils literal"><span class="pre">[[@LINE]]</span></tt>,
+<tt class="docutils literal"><span class="pre">[[@LINE+<offset>]]</span></tt>, <tt class="docutils literal"><span class="pre">[[@LINE-<offset>]]</span></tt> expressions in patterns. These
+expressions expand to a number of the line where a pattern is located (with an
+optional integer offset).</p>
+<p>This way match patterns can be put near the relevant test lines and include
+relative line number references, for example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// CHECK: test.cpp:[[@LINE+4]]:6: error: expected ';' after top level declarator</span>
+<span class="c1">// CHECK-NEXT: {{^int a}}</span>
+<span class="c1">// CHECK-NEXT: {{^ \^}}</span>
+<span class="c1">// CHECK-NEXT: {{^ ;}}</span>
+<span class="kt">int</span> <span class="n">a</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="matching-newline-characters">
+<h3>Matching Newline Characters<a class="headerlink" href="#matching-newline-characters" title="Permalink to this headline">¶</a></h3>
+<p>To match newline characters in regular expressions the character class
+<tt class="docutils literal"><span class="pre">[[:space:]]</span></tt> can be used. For example, the following pattern:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"</span>
+</pre></div>
+</div>
+<p>matches output of the form (from llvm-dwarfdump):</p>
+<div class="highlight-text"><div class="highlight"><pre>DW_AT_location [DW_FORM_sec_offset] (0x00000233)
+DW_AT_name [DW_FORM_strp] ( .debug_str[0x000000c9] = "intd")
+</pre></div>
+</div>
+<p>letting us set the <strong class="program">FileCheck</strong> variable <tt class="docutils literal"><span class="pre">DLOC</span></tt> to the desired value
+<tt class="docutils literal"><span class="pre">0x00000233</span></tt>, extracted from the line immediately preceding “<tt class="docutils literal"><span class="pre">intd</span></tt>”.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="tblgen.html" title="tblgen - Target Description To C++ Code Generator"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/bugpoint.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/bugpoint.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/bugpoint.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/bugpoint.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,266 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>bugpoint - automatic test case reduction tool — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-extract - extract a function from an LLVM module" href="llvm-extract.html" />
+ <link rel="prev" title="dsymutil - manipulate archived DWARF debug symbol files" href="dsymutil.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol files"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="bugpoint-automatic-test-case-reduction-tool">
+<h1>bugpoint - automatic test case reduction tool<a class="headerlink" href="#bugpoint-automatic-test-case-reduction-tool" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>bugpoint</strong> [<em>options</em>] [<em>input LLVM ll/bc files</em>] [<em>LLVM passes</em>] <strong>–args</strong>
+<em>program arguments</em></p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>bugpoint</strong> narrows down the source of problems in LLVM tools and passes. It
+can be used to debug three types of failures: optimizer crashes, miscompilations
+by optimizers, or bad native code generation (including problems in the static
+and JIT compilers). It aims to reduce large test cases to small, useful ones.
+For more information on the design and inner workings of <strong>bugpoint</strong>, as well as
+advice for using bugpoint, see <a class="reference internal" href="../Bugpoint.html"><em>LLVM bugpoint tool: design and usage</em></a> in the LLVM
+distribution.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>–additional-so</strong> <em>library</em></p>
+<blockquote>
+<div>Load the dynamic shared object <em>library</em> into the test program whenever it is
+run. This is useful if you are debugging programs which depend on non-LLVM
+libraries (such as the X or curses libraries) to run.</div></blockquote>
+<p><strong>–append-exit-code</strong>=<em>{true,false}</em></p>
+<blockquote>
+<div>Append the test programs exit code to the output file so that a change in exit
+code is considered a test failure. Defaults to false.</div></blockquote>
+<p><strong>–args</strong> <em>program args</em></p>
+<blockquote>
+<div><p>Pass all arguments specified after <strong>–args</strong> to the test program whenever it runs.
+Note that if any of the <em>program args</em> start with a “<tt class="docutils literal"><span class="pre">-</span></tt>”, you should use:</p>
+<div class="highlight-bash"><div class="highlight"><pre>bugpoint <span class="o">[</span>bugpoint args<span class="o">]</span> --args -- <span class="o">[</span>program args<span class="o">]</span>
+</pre></div>
+</div>
+<p>The “<tt class="docutils literal"><span class="pre">--</span></tt>” right after the <strong>–args</strong> option tells <strong>bugpoint</strong> to consider
+any options starting with “<tt class="docutils literal"><span class="pre">-</span></tt>” to be part of the <strong>–args</strong> option, not as
+options to <strong>bugpoint</strong> itself.</p>
+</div></blockquote>
+<p><strong>–tool-args</strong> <em>tool args</em></p>
+<blockquote>
+<div><p>Pass all arguments specified after <strong>–tool-args</strong> to the LLVM tool under test
+(<strong>llc</strong>, <strong>lli</strong>, etc.) whenever it runs. You should use this option in the
+following way:</p>
+<div class="highlight-bash"><div class="highlight"><pre>bugpoint <span class="o">[</span>bugpoint args<span class="o">]</span> --tool-args -- <span class="o">[</span>tool args<span class="o">]</span>
+</pre></div>
+</div>
+<p>The “<tt class="docutils literal"><span class="pre">--</span></tt>” right after the <strong>–tool-args</strong> option tells <strong>bugpoint</strong> to
+consider any options starting with “<tt class="docutils literal"><span class="pre">-</span></tt>” to be part of the <strong>–tool-args</strong>
+option, not as options to <strong>bugpoint</strong> itself. (See <strong>–args</strong>, above.)</p>
+</div></blockquote>
+<p><strong>–safe-tool-args</strong> <em>tool args</em></p>
+<blockquote>
+<div>Pass all arguments specified after <strong>–safe-tool-args</strong> to the “safe” execution
+tool.</div></blockquote>
+<p><strong>–gcc-tool-args</strong> <em>gcc tool args</em></p>
+<blockquote>
+<div>Pass all arguments specified after <strong>–gcc-tool-args</strong> to the invocation of
+<strong>gcc</strong>.</div></blockquote>
+<p><strong>–opt-args</strong> <em>opt args</em></p>
+<blockquote>
+<div>Pass all arguments specified after <strong>–opt-args</strong> to the invocation of <strong>opt</strong>.</div></blockquote>
+<p><strong>–disable-{dce,simplifycfg}</strong></p>
+<blockquote>
+<div>Do not run the specified passes to clean up and reduce the size of the test
+program. By default, <strong>bugpoint</strong> uses these passes internally when attempting to
+reduce test programs. If you’re trying to find a bug in one of these passes,
+<strong>bugpoint</strong> may crash.</div></blockquote>
+<p><strong>–enable-valgrind</strong></p>
+<blockquote>
+<div>Use valgrind to find faults in the optimization phase. This will allow
+bugpoint to find otherwise asymptomatic problems caused by memory
+mis-management.</div></blockquote>
+<p><strong>-find-bugs</strong></p>
+<blockquote>
+<div>Continually randomize the specified passes and run them on the test program
+until a bug is found or the user kills <strong>bugpoint</strong>.</div></blockquote>
+<p><strong>-help</strong></p>
+<blockquote>
+<div>Print a summary of command line options.</div></blockquote>
+<p><strong>–input</strong> <em>filename</em></p>
+<blockquote>
+<div>Open <em>filename</em> and redirect the standard input of the test program, whenever
+it runs, to come from that file.</div></blockquote>
+<p><strong>–load</strong> <em>plugin</em></p>
+<blockquote>
+<div><p>Load the dynamic object <em>plugin</em> into <strong>bugpoint</strong> itself. This object should
+register new optimization passes. Once loaded, the object will add new command
+line options to enable various optimizations. To see the new complete list of
+optimizations, use the <strong>-help</strong> and <strong>–load</strong> options together; for example:</p>
+<div class="highlight-bash"><div class="highlight"><pre>bugpoint --load myNewPass.so -help
+</pre></div>
+</div>
+</div></blockquote>
+<p><strong>–mlimit</strong> <em>megabytes</em></p>
+<blockquote>
+<div>Specifies an upper limit on memory usage of the optimization and codegen. Set
+to zero to disable the limit.</div></blockquote>
+<p><strong>–output</strong> <em>filename</em></p>
+<blockquote>
+<div>Whenever the test program produces output on its standard output stream, it
+should match the contents of <em>filename</em> (the “reference output”). If you
+do not use this option, <strong>bugpoint</strong> will attempt to generate a reference output
+by compiling the program with the “safe” backend and running it.</div></blockquote>
+<p><strong>–run-{int,jit,llc,custom}</strong></p>
+<blockquote>
+<div>Whenever the test program is compiled, <strong>bugpoint</strong> should generate code for it
+using the specified code generator. These options allow you to choose the
+interpreter, the JIT compiler, the static native code compiler, or a
+custom command (see <strong>–exec-command</strong>) respectively.</div></blockquote>
+<p><strong>–safe-{llc,custom}</strong></p>
+<blockquote>
+<div>When debugging a code generator, <strong>bugpoint</strong> should use the specified code
+generator as the “safe” code generator. This is a known-good code generator
+used to generate the “reference output” if it has not been provided, and to
+compile portions of the program that as they are excluded from the testcase.
+These options allow you to choose the
+static native code compiler, or a custom command, (see <strong>–exec-command</strong>)
+respectively. The interpreter and the JIT backends cannot currently
+be used as the “safe” backends.</div></blockquote>
+<p><strong>–exec-command</strong> <em>command</em></p>
+<blockquote>
+<div>This option defines the command to use with the <strong>–run-custom</strong> and
+<strong>–safe-custom</strong> options to execute the bitcode testcase. This can
+be useful for cross-compilation.</div></blockquote>
+<p><strong>–compile-command</strong> <em>command</em></p>
+<blockquote>
+<div><p>This option defines the command to use with the <strong>–compile-custom</strong>
+option to compile the bitcode testcase. The command should exit with a
+failure exit code if the file is “interesting” and should exit with a
+success exit code (i.e. 0) otherwise (this is the same as if it crashed on
+“interesting” inputs).</p>
+<p>This can be useful for
+testing compiler output without running any link or execute stages. To
+generate a reduced unit test, you may add CHECK directives to the
+testcase and pass the name of an executable compile-command script in this form:</p>
+<div class="highlight-sh"><div class="highlight"><pre><span class="c">#!/bin/sh</span>
+llc <span class="s2">"$@"</span>
+not FileCheck <span class="o">[</span>bugpoint input file<span class="o">]</span>.ll < bugpoint-test-program.s
+</pre></div>
+</div>
+<p>This script will “fail” as long as FileCheck passes. So the result
+will be the minimum bitcode that passes FileCheck.</p>
+</div></blockquote>
+<p><strong>–safe-path</strong> <em>path</em></p>
+<blockquote>
+<div>This option defines the path to the command to execute with the
+<strong>–safe-{int,jit,llc,custom}</strong>
+option.</div></blockquote>
+<p><strong>–verbose-errors</strong>=<em>{true,false}</em></p>
+<blockquote>
+<div>The default behavior of bugpoint is to print “<crash>” when it finds a reduced
+test that crashes compilation. This flag prints the output of the crashing
+program to stderr. This is useful to make sure it is the same error being
+tracked down and not a different error that happens to crash the compiler as
+well. Defaults to false.</div></blockquote>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong>bugpoint</strong> succeeds in finding a problem, it will exit with 0. Otherwise,
+if an error occurs, it will exit with a non-zero value.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>opt|opt</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol files"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/dsymutil.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/dsymutil.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/dsymutil.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/dsymutil.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,214 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>dsymutil - manipulate archived DWARF debug symbol files — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="bugpoint - automatic test case reduction tool" href="bugpoint.html" />
+ <link rel="prev" title="llvm-dwarfdump - dump and verify DWARF debug information" href="llvm-dwarfdump.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-dwarfdump.html" title="llvm-dwarfdump - dump and verify DWARF debug information"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="dsymutil-manipulate-archived-dwarf-debug-symbol-files">
+<h1>dsymutil - manipulate archived DWARF debug symbol files<a class="headerlink" href="#dsymutil-manipulate-archived-dwarf-debug-symbol-files" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<div class="line-block">
+<div class="line"><strong class="program">dsymutil</strong> [<em>options</em>] <em>executable</em></div>
+</div>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">dsymutil</strong> links the DWARF debug information found in the object files
+for an executable <em>executable</em> by using debug symbols information contained in
+its symbol table. By default, the linked debug information is placed in a
+<tt class="docutils literal"><span class="pre">.dSYM</span></tt> bundle with the same name as the executable.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption--arch">
+<tt class="descname">--arch</tt><tt class="descclassname">=<arch></tt><a class="headerlink" href="#cmdoption--arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Link DWARF debug information only for specified CPU architecture types.
+Architectures may be specified by name. When using this option, an error will
+be returned if any architectures can not be properly linked. This option can
+be specified multiple times, once for each desired architecture. All CPU
+architectures will be linked by default and any architectures that can’t be
+properly linked will cause <strong class="program">dsymutil</strong> to return an error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--dump-debug-map">
+<tt class="descname">--dump-debug-map</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--dump-debug-map" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the <em>executable</em>‘s debug-map (the list of the object files containing the
+debug information) in YAML format and exit. Not DWARF link will take place.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-f">
+<tt class="descname">-f</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--flat</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Produce a flat dSYM file. A <tt class="docutils literal"><span class="pre">.dwarf</span></tt> extension will be appended to the
+executable name unless the output file is specified using the -o option.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--no-odr">
+<tt class="descname">--no-odr</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--no-odr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not use ODR (One Definition Rule) for uniquing C++ types.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--no-output">
+<tt class="descname">--no-output</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--no-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do the link in memory, but do not emit the result file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--no-swiftmodule-timestamp">
+<tt class="descname">--no-swiftmodule-timestamp</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--no-swiftmodule-timestamp" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t check the timestamp for swiftmodule files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-j">
+<tt class="descname">-j</tt><tt class="descclassname"> <n></tt><tt class="descclassname">, </tt><tt class="descname">--num-threads</tt><tt class="descclassname">=<n></tt><a class="headerlink" href="#cmdoption-j" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specifies the maximum number (<tt class="docutils literal"><span class="pre">n</span></tt>) of simultaneous threads to use when
+linking multiple architectures.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> <filename></tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specifies an alternate <tt class="docutils literal"><span class="pre">path</span></tt> to place the dSYM bundle. The default dSYM
+bundle path is created by appending <tt class="docutils literal"><span class="pre">.dSYM</span></tt> to the executable name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--oso-prepend-path">
+<tt class="descname">--oso-prepend-path</tt><tt class="descclassname">=<path></tt><a class="headerlink" href="#cmdoption--oso-prepend-path" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specifies a <tt class="docutils literal"><span class="pre">path</span></tt> to prepend to all debug symbol object file paths.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-s">
+<tt class="descname">-s</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--symtab</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-s" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dumps the symbol table found in <em>executable</em> or object file(s) and exits.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-v">
+<tt class="descname">-v</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--verbose</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display verbose information when linking.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--version">
+<tt class="descname">--version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of the tool.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-y">
+<tt class="descname">-y</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-y" title="Permalink to this definition">¶</a></dt>
+<dd><p>Treat <em>executable</em> as a YAML debug-map rather than an executable.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">dsymutil</strong> returns 0 if the DWARF debug information was linked
+successfully. Otherwise, it returns 1.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage">llvm-dwarfdump(1)</em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-dwarfdump.html" title="llvm-dwarfdump - dump and verify DWARF debug information"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/index.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/index.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/index.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,152 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Command Guide — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="next" title="llvm-as - LLVM assembler" href="llvm-as.html" />
+ <link rel="prev" title="How To Cross-Compile Clang/LLVM using Clang/LLVM" href="../HowToCrossCompileLLVM.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-as.html" title="llvm-as - LLVM assembler"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-command-guide">
+<h1>LLVM Command Guide<a class="headerlink" href="#llvm-command-guide" title="Permalink to this headline">¶</a></h1>
+<p>The following documents are command descriptions for all of the LLVM tools.
+These pages describe how to use the LLVM commands and what their options are.
+Note that these pages do not describe all of the options available for all
+tools. To get a complete listing, pass the <tt class="docutils literal"><span class="pre">--help</span></tt> (general options) or
+<tt class="docutils literal"><span class="pre">--help-hidden</span></tt> (general and debugging options) arguments to the tool you are
+interested in.</p>
+<div class="section" id="basic-commands">
+<h2>Basic Commands<a class="headerlink" href="#basic-commands" title="Permalink to this headline">¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="llvm-as.html">llvm-as - LLVM assembler</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-dis.html">llvm-dis - LLVM disassembler</a></li>
+<li class="toctree-l1"><a class="reference internal" href="opt.html">opt - LLVM optimizer</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llc.html">llc - LLVM static compiler</a></li>
+<li class="toctree-l1"><a class="reference internal" href="lli.html">lli - directly execute programs from LLVM bitcode</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-link.html">llvm-link - LLVM bitcode linker</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-ar.html">llvm-ar - LLVM archiver</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-lib.html">llvm-lib - LLVM lib.exe compatible library tool</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-nm.html">llvm-nm - list LLVM bitcode and object file’s symbol table</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-config.html">llvm-config - Print LLVM compilation options</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-diff.html">llvm-diff - LLVM structural ‘diff’</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-cov.html">llvm-cov - emit coverage information</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-profdata.html">llvm-profdata - Profile data tool</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-stress.html">llvm-stress - generate random .ll files</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-symbolizer.html">llvm-symbolizer - convert addresses into source code locations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-dwarfdump.html">llvm-dwarfdump - dump and verify DWARF debug information</a></li>
+<li class="toctree-l1"><a class="reference internal" href="dsymutil.html">dsymutil - manipulate archived DWARF debug symbol files</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="debugging-tools">
+<h2>Debugging Tools<a class="headerlink" href="#debugging-tools" title="Permalink to this headline">¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="bugpoint.html">bugpoint - automatic test case reduction tool</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-extract.html">llvm-extract - extract a function from an LLVM module</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-bcanalyzer.html">llvm-bcanalyzer - LLVM bitcode analyzer</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="developer-tools">
+<h2>Developer Tools<a class="headerlink" href="#developer-tools" title="Permalink to this headline">¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="FileCheck.html">FileCheck - Flexible pattern matching file verifier</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tblgen.html">tblgen - Target Description To C++ Code Generator</a></li>
+<li class="toctree-l1"><a class="reference internal" href="lit.html">lit - LLVM Integrated Tester</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-build.html">llvm-build - LLVM Project Build Utility</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-pdbutil.html">llvm-pdbutil - PDB File forensics and diagnostics</a></li>
+<li class="toctree-l1"><a class="reference internal" href="llvm-readobj.html">llvm-readobj - LLVM Object Reader</a></li>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-as.html" title="llvm-as - LLVM assembler"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/lit.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/lit.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/lit.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/lit.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,581 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>lit - LLVM Integrated Tester — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-build - LLVM Project Build Utility" href="llvm-build.html" />
+ <link rel="prev" title="tblgen - Target Description To C++ Code Generator" href="tblgen.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-build.html" title="llvm-build - LLVM Project Build Utility"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="tblgen.html" title="tblgen - Target Description To C++ Code Generator"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="lit-llvm-integrated-tester">
+<h1>lit - LLVM Integrated Tester<a class="headerlink" href="#lit-llvm-integrated-tester" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">lit</strong> [<em>options</em>] [<em>tests</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">lit</strong> is a portable tool for executing LLVM and Clang style test
+suites, summarizing their results, and providing indication of failures.
+<strong class="program">lit</strong> is designed to be a lightweight testing tool with as simple a
+user interface as possible.</p>
+<p><strong class="program">lit</strong> should be run with one or more <em>tests</em> to run specified on the
+command line. Tests can be either individual test files or directories to
+search for tests (see <a class="reference internal" href="#test-discovery"><em>TEST DISCOVERY</em></a>).</p>
+<p>Each specified test will be executed (potentially in parallel) and once all
+tests have been run <strong class="program">lit</strong> will print summary information on the number
+of tests which passed or failed (see <a class="reference internal" href="#test-status-results"><em>TEST STATUS RESULTS</em></a>). The
+<strong class="program">lit</strong> program will execute with a non-zero exit code if any tests
+fail.</p>
+<p>By default <strong class="program">lit</strong> will use a succinct progress display and will only
+print summary information for test failures. See <a class="reference internal" href="#output-options"><em>OUTPUT OPTIONS</em></a> for
+options controlling the <strong class="program">lit</strong> progress display and output.</p>
+<p><strong class="program">lit</strong> also includes a number of options for controlling how tests are
+executed (specific features may depend on the particular test format). See
+<a class="reference internal" href="#execution-options"><em>EXECUTION OPTIONS</em></a> for more information.</p>
+<p>Finally, <strong class="program">lit</strong> also supports additional options for only running a
+subset of the options specified on the command line, see
+<a class="reference internal" href="#selection-options"><em>SELECTION OPTIONS</em></a> for more information.</p>
+<p>Users interested in the <strong class="program">lit</strong> architecture or designing a
+<strong class="program">lit</strong> testing implementation should see <a class="reference internal" href="#lit-infrastructure"><em>LIT INFRASTRUCTURE</em></a>.</p>
+</div>
+<div class="section" id="general-options">
+<h2>GENERAL OPTIONS<a class="headerlink" href="#general-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-h">
+<tt class="descname">-h</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-h" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the <strong class="program">lit</strong> help message.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-j">
+<tt class="descname">-j</tt><tt class="descclassname"> N</tt><tt class="descclassname">, </tt><tt class="descname">--threads</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-j" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run <tt class="docutils literal"><span class="pre">N</span></tt> tests in parallel. By default, this is automatically chosen to
+match the number of detected available CPUs.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--config-prefix">
+<tt class="descname">--config-prefix</tt><tt class="descclassname">=NAME</tt><a class="headerlink" href="#cmdoption--config-prefix" title="Permalink to this definition">¶</a></dt>
+<dd><p>Search for <tt class="file docutils literal"><em><span class="pre">NAME</span></em><span class="pre">.cfg</span></tt> and <tt class="file docutils literal"><em><span class="pre">NAME</span></em><span class="pre">.site.cfg</span></tt> when searching for
+test suites, instead of <tt class="file docutils literal"><span class="pre">lit.cfg</span></tt> and <tt class="file docutils literal"><span class="pre">lit.site.cfg</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-D">
+<tt class="descname">-D</tt><tt class="descclassname"> NAME[=VALUE]</tt><tt class="descclassname">, </tt><tt class="descname">--param</tt><tt class="descclassname"> NAME[=VALUE]</tt><a class="headerlink" href="#cmdoption-D" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add a user defined parameter <tt class="docutils literal"><span class="pre">NAME</span></tt> with the given <tt class="docutils literal"><span class="pre">VALUE</span></tt> (or the empty
+string if not given). The meaning and use of these parameters is test suite
+dependent.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="output-options">
+<span id="id1"></span><h2>OUTPUT OPTIONS<a class="headerlink" href="#output-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-q">
+<tt class="descname">-q</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--quiet</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-q" title="Permalink to this definition">¶</a></dt>
+<dd><p>Suppress any output except for test failures.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-s">
+<tt class="descname">-s</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--succinct</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-s" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show less output, for example don’t show information on tests that pass.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-v">
+<tt class="descname">-v</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--verbose</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show more information on test failures, for example the entire test output
+instead of just the test result.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-vv">
+<tt class="descname">-vv</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--echo-all-commands</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-vv" title="Permalink to this definition">¶</a></dt>
+<dd><p>Echo all commands to stdout, as they are being executed.
+This can be valuable for debugging test failures, as the last echoed command
+will be the one which has failed.
+This option implies <tt class="docutils literal"><span class="pre">--verbose</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-a">
+<tt class="descname">-a</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--show-all</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-a" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show more information about all tests, for example the entire test
+commandline and output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--no-progress-bar">
+<tt class="descname">--no-progress-bar</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--no-progress-bar" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not use curses based progress bar.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--show-unsupported">
+<tt class="descname">--show-unsupported</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--show-unsupported" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the names of unsupported tests.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--show-xfail">
+<tt class="descname">--show-xfail</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--show-xfail" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the names of tests that were expected to fail.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="execution-options">
+<span id="id2"></span><h2>EXECUTION OPTIONS<a class="headerlink" href="#execution-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption--path">
+<tt class="descname">--path</tt><tt class="descclassname">=PATH</tt><a class="headerlink" href="#cmdoption--path" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify an additional <tt class="docutils literal"><span class="pre">PATH</span></tt> to use when searching for executables in tests.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--vg">
+<tt class="descname">--vg</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--vg" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run individual tests under valgrind (using the memcheck tool). The
+<tt class="docutils literal"><span class="pre">--error-exitcode</span></tt> argument for valgrind is used so that valgrind failures
+will cause the program to exit with a non-zero status.</p>
+<p>When this option is enabled, <strong class="program">lit</strong> will also automatically provide a
+“<tt class="docutils literal"><span class="pre">valgrind</span></tt>” feature that can be used to conditionally disable (or expect
+failure in) certain tests.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--vg-arg">
+<tt class="descname">--vg-arg</tt><tt class="descclassname">=ARG</tt><a class="headerlink" href="#cmdoption--vg-arg" title="Permalink to this definition">¶</a></dt>
+<dd><p>When <a class="reference internal" href="#cmdoption--vg"><em class="xref std std-option">--vg</em></a> is used, specify an additional argument to pass to
+<strong class="program">valgrind</strong> itself.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--vg-leak">
+<tt class="descname">--vg-leak</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--vg-leak" title="Permalink to this definition">¶</a></dt>
+<dd><p>When <a class="reference internal" href="#cmdoption--vg"><em class="xref std std-option">--vg</em></a> is used, enable memory leak checks. When this option is
+enabled, <strong class="program">lit</strong> will also automatically provide a “<tt class="docutils literal"><span class="pre">vg_leak</span></tt>”
+feature that can be used to conditionally disable (or expect failure in)
+certain tests.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--time-tests">
+<tt class="descname">--time-tests</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--time-tests" title="Permalink to this definition">¶</a></dt>
+<dd><p>Track the wall time individual tests take to execute and includes the results
+in the summary output. This is useful for determining which tests in a test
+suite take the most time to execute. Note that this option is most useful
+with <tt class="docutils literal"><span class="pre">-j</span> <span class="pre">1</span></tt>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="selection-options">
+<span id="id3"></span><h2>SELECTION OPTIONS<a class="headerlink" href="#selection-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption--max-tests">
+<tt class="descname">--max-tests</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption--max-tests" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run at most <tt class="docutils literal"><span class="pre">N</span></tt> tests and then terminate.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--max-time">
+<tt class="descname">--max-time</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption--max-time" title="Permalink to this definition">¶</a></dt>
+<dd><p>Spend at most <tt class="docutils literal"><span class="pre">N</span></tt> seconds (approximately) running tests and then terminate.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--shuffle">
+<tt class="descname">--shuffle</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--shuffle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run the tests in a random order.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--num-shards">
+<tt class="descname">--num-shards</tt><tt class="descclassname">=M</tt><a class="headerlink" href="#cmdoption--num-shards" title="Permalink to this definition">¶</a></dt>
+<dd><p>Divide the set of selected tests into <tt class="docutils literal"><span class="pre">M</span></tt> equal-sized subsets or
+“shards”, and run only one of them. Must be used with the
+<tt class="docutils literal"><span class="pre">--run-shard=N</span></tt> option, which selects the shard to run. The environment
+variable <tt class="docutils literal"><span class="pre">LIT_NUM_SHARDS</span></tt> can also be used in place of this
+option. These two options provide a coarse mechanism for paritioning large
+testsuites, for parallel execution on separate machines (say in a large
+testing farm).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--run-shard">
+<tt class="descname">--run-shard</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption--run-shard" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which shard to run, assuming the <tt class="docutils literal"><span class="pre">--num-shards=M</span></tt> option was
+provided. The two options must be used together, and the value of <tt class="docutils literal"><span class="pre">N</span></tt>
+must be in the range <tt class="docutils literal"><span class="pre">1..M</span></tt>. The environment variable
+<tt class="docutils literal"><span class="pre">LIT_RUN_SHARD</span></tt> can also be used in place of this option.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--filter">
+<tt class="descname">--filter</tt><tt class="descclassname">=REGEXP</tt><a class="headerlink" href="#cmdoption--filter" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run only those tests whose name matches the regular expression specified in
+<tt class="docutils literal"><span class="pre">REGEXP</span></tt>. The environment variable <tt class="docutils literal"><span class="pre">LIT_FILTER</span></tt> can be also used in place
+of this option, which is especially useful in environments where the call
+to <tt class="docutils literal"><span class="pre">lit</span></tt> is issued indirectly.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="additional-options">
+<h2>ADDITIONAL OPTIONS<a class="headerlink" href="#additional-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption--debug">
+<tt class="descname">--debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run <strong class="program">lit</strong> in debug mode, for debugging configuration issues and
+<strong class="program">lit</strong> itself.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--show-suites">
+<tt class="descname">--show-suites</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--show-suites" title="Permalink to this definition">¶</a></dt>
+<dd><p>List the discovered test suites and exit.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--show-tests">
+<tt class="descname">--show-tests</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--show-tests" title="Permalink to this definition">¶</a></dt>
+<dd><p>List all of the discovered tests and exit.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">lit</strong> will exit with an exit code of 1 if there are any FAIL or XPASS
+results. Otherwise, it will exit with the status 0. Other exit codes are used
+for non-test related failures (for example a user error or an internal program
+error).</p>
+</div>
+<div class="section" id="test-discovery">
+<span id="id4"></span><h2>TEST DISCOVERY<a class="headerlink" href="#test-discovery" title="Permalink to this headline">¶</a></h2>
+<p>The inputs passed to <strong class="program">lit</strong> can be either individual tests, or entire
+directories or hierarchies of tests to run. When <strong class="program">lit</strong> starts up, the
+first thing it does is convert the inputs into a complete list of tests to run
+as part of <em>test discovery</em>.</p>
+<p>In the <strong class="program">lit</strong> model, every test must exist inside some <em>test suite</em>.
+<strong class="program">lit</strong> resolves the inputs specified on the command line to test suites
+by searching upwards from the input path until it finds a <tt class="file docutils literal"><span class="pre">lit.cfg</span></tt> or
+<tt class="file docutils literal"><span class="pre">lit.site.cfg</span></tt> file. These files serve as both a marker of test suites
+and as configuration files which <strong class="program">lit</strong> loads in order to understand
+how to find and run the tests inside the test suite.</p>
+<p>Once <strong class="program">lit</strong> has mapped the inputs into test suites it traverses the
+list of inputs adding tests for individual files and recursively searching for
+tests in directories.</p>
+<p>This behavior makes it easy to specify a subset of tests to run, while still
+allowing the test suite configuration to control exactly how tests are
+interpreted. In addition, <strong class="program">lit</strong> always identifies tests by the test
+suite they are in, and their relative path inside the test suite. For
+appropriately configured projects, this allows <strong class="program">lit</strong> to provide
+convenient and flexible support for out-of-tree builds.</p>
+</div>
+<div class="section" id="test-status-results">
+<span id="id5"></span><h2>TEST STATUS RESULTS<a class="headerlink" href="#test-status-results" title="Permalink to this headline">¶</a></h2>
+<p>Each test ultimately produces one of the following six results:</p>
+<p><strong>PASS</strong></p>
+<blockquote>
+<div>The test succeeded.</div></blockquote>
+<p><strong>XFAIL</strong></p>
+<blockquote>
+<div>The test failed, but that is expected. This is used for test formats which allow
+specifying that a test does not currently work, but wish to leave it in the test
+suite.</div></blockquote>
+<p><strong>XPASS</strong></p>
+<blockquote>
+<div>The test succeeded, but it was expected to fail. This is used for tests which
+were specified as expected to fail, but are now succeeding (generally because
+the feature they test was broken and has been fixed).</div></blockquote>
+<p><strong>FAIL</strong></p>
+<blockquote>
+<div>The test failed.</div></blockquote>
+<p><strong>UNRESOLVED</strong></p>
+<blockquote>
+<div>The test result could not be determined. For example, this occurs when the test
+could not be run, the test itself is invalid, or the test was interrupted.</div></blockquote>
+<p><strong>UNSUPPORTED</strong></p>
+<blockquote>
+<div>The test is not supported in this environment. This is used by test formats
+which can report unsupported tests.</div></blockquote>
+<p>Depending on the test format tests may produce additional information about
+their status (generally only for failures). See the <a class="reference internal" href="#output-options"><em>OUTPUT OPTIONS</em></a>
+section for more information.</p>
+</div>
+<div class="section" id="lit-infrastructure">
+<span id="id6"></span><h2>LIT INFRASTRUCTURE<a class="headerlink" href="#lit-infrastructure" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the <strong class="program">lit</strong> testing architecture for users interested in
+creating a new <strong class="program">lit</strong> testing implementation, or extending an existing one.</p>
+<p><strong class="program">lit</strong> proper is primarily an infrastructure for discovering and running
+arbitrary tests, and to expose a single convenient interface to these
+tests. <strong class="program">lit</strong> itself doesn’t know how to run tests, rather this logic is
+defined by <em>test suites</em>.</p>
+<div class="section" id="test-suites">
+<h3>TEST SUITES<a class="headerlink" href="#test-suites" title="Permalink to this headline">¶</a></h3>
+<p>As described in <a class="reference internal" href="#test-discovery"><em>TEST DISCOVERY</em></a>, tests are always located inside a <em>test
+suite</em>. Test suites serve to define the format of the tests they contain, the
+logic for finding those tests, and any additional information to run the tests.</p>
+<p><strong class="program">lit</strong> identifies test suites as directories containing <tt class="docutils literal"><span class="pre">lit.cfg</span></tt> or
+<tt class="docutils literal"><span class="pre">lit.site.cfg</span></tt> files (see also <a class="reference internal" href="#cmdoption--config-prefix"><em class="xref std std-option">--config-prefix</em></a>). Test suites are
+initially discovered by recursively searching up the directory hierarchy for
+all the input files passed on the command line. You can use
+<a class="reference internal" href="#cmdoption--show-suites"><em class="xref std std-option">--show-suites</em></a> to display the discovered test suites at startup.</p>
+<p>Once a test suite is discovered, its config file is loaded. Config files
+themselves are Python modules which will be executed. When the config file is
+executed, two important global variables are predefined:</p>
+<p><strong>lit_config</strong></p>
+<blockquote>
+<div>The global <strong>lit</strong> configuration object (a <em>LitConfig</em> instance), which defines
+the builtin test formats, global configuration parameters, and other helper
+routines for implementing test configurations.</div></blockquote>
+<p><strong>config</strong></p>
+<blockquote>
+<div><p>This is the config object (a <em>TestingConfig</em> instance) for the test suite,
+which the config file is expected to populate. The following variables are also
+available on the <em>config</em> object, some of which must be set by the config and
+others are optional or predefined:</p>
+<p><strong>name</strong> <em>[required]</em> The name of the test suite, for use in reports and
+diagnostics.</p>
+<p><strong>test_format</strong> <em>[required]</em> The test format object which will be used to
+discover and run tests in the test suite. Generally this will be a builtin test
+format available from the <em>lit.formats</em> module.</p>
+<p><strong>test_source_root</strong> The filesystem path to the test suite root. For out-of-dir
+builds this is the directory that will be scanned for tests.</p>
+<p><strong>test_exec_root</strong> For out-of-dir builds, the path to the test suite root inside
+the object directory. This is where tests will be run and temporary output files
+placed.</p>
+<p><strong>environment</strong> A dictionary representing the environment to use when executing
+tests in the suite.</p>
+<p><strong>suffixes</strong> For <strong>lit</strong> test formats which scan directories for tests, this
+variable is a list of suffixes to identify test files. Used by: <em>ShTest</em>.</p>
+<p><strong>substitutions</strong> For <strong>lit</strong> test formats which substitute variables into a test
+script, the list of substitutions to perform. Used by: <em>ShTest</em>.</p>
+<p><strong>unsupported</strong> Mark an unsupported directory, all tests within it will be
+reported as unsupported. Used by: <em>ShTest</em>.</p>
+<p><strong>parent</strong> The parent configuration, this is the config object for the directory
+containing the test suite, or None.</p>
+<p><strong>root</strong> The root configuration. This is the top-most <strong class="program">lit</strong> configuration in
+the project.</p>
+<p><strong>pipefail</strong> Normally a test using a shell pipe fails if any of the commands
+on the pipe fail. If this is not desired, setting this variable to false
+makes the test fail only if the last command in the pipe fails.</p>
+<p><strong>available_features</strong> A set of features that can be used in <cite>XFAIL</cite>,
+<cite>REQUIRES</cite>, and <cite>UNSUPPORTED</cite> directives.</p>
+</div></blockquote>
+</div>
+<div class="section" id="id7">
+<h3>TEST DISCOVERY<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
+<p>Once test suites are located, <strong class="program">lit</strong> recursively traverses the source
+directory (following <em>test_source_root</em>) looking for tests. When <strong class="program">lit</strong>
+enters a sub-directory, it first checks to see if a nested test suite is
+defined in that directory. If so, it loads that test suite recursively,
+otherwise it instantiates a local test config for the directory (see
+<a class="reference internal" href="#local-configuration-files"><em>LOCAL CONFIGURATION FILES</em></a>).</p>
+<p>Tests are identified by the test suite they are contained within, and the
+relative path inside that suite. Note that the relative path may not refer to
+an actual file on disk; some test formats (such as <em>GoogleTest</em>) define
+“virtual tests” which have a path that contains both the path to the actual
+test file and a subpath to identify the virtual test.</p>
+</div>
+<div class="section" id="local-configuration-files">
+<span id="id8"></span><h3>LOCAL CONFIGURATION FILES<a class="headerlink" href="#local-configuration-files" title="Permalink to this headline">¶</a></h3>
+<p>When <strong class="program">lit</strong> loads a subdirectory in a test suite, it instantiates a
+local test configuration by cloning the configuration for the parent directory
+— the root of this configuration chain will always be a test suite. Once the
+test configuration is cloned <strong class="program">lit</strong> checks for a <em>lit.local.cfg</em> file
+in the subdirectory. If present, this file will be loaded and can be used to
+specialize the configuration for each individual directory. This facility can
+be used to define subdirectories of optional tests, or to change other
+configuration parameters — for example, to change the test format, or the
+suffixes which identify test files.</p>
+</div>
+<div class="section" id="pre-defined-substitutions">
+<h3>PRE-DEFINED SUBSTITUTIONS<a class="headerlink" href="#pre-defined-substitutions" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">lit</strong> provides various patterns that can be used with the RUN command.
+These are defined in TestRunner.py. The base set of substitutions are:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="16%" />
+<col width="84%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Macro</th>
+<th class="head">Substitution</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>%s</td>
+<td>source path (path to the file currently being run)</td>
+</tr>
+<tr class="row-odd"><td>%S</td>
+<td>source dir (directory of the file currently being run)</td>
+</tr>
+<tr class="row-even"><td>%p</td>
+<td>same as %S</td>
+</tr>
+<tr class="row-odd"><td>%{pathsep}</td>
+<td>path separator</td>
+</tr>
+<tr class="row-even"><td>%t</td>
+<td>temporary file name unique to the test</td>
+</tr>
+<tr class="row-odd"><td>%T</td>
+<td>temporary directory unique to the test</td>
+</tr>
+<tr class="row-even"><td>%%</td>
+<td>%</td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+<p>Other substitutions are provided that are variations on this base set and
+further substitution patterns can be defined by each test module. See the
+modules <a class="reference internal" href="#local-configuration-files"><em>LOCAL CONFIGURATION FILES</em></a>.</p>
+<p>More detailed information on substitutions can be found in the
+<a class="reference internal" href="../TestingGuide.html"><em>LLVM Testing Infrastructure Guide</em></a>.</p>
+</div>
+<div class="section" id="test-run-output-format">
+<h3>TEST RUN OUTPUT FORMAT<a class="headerlink" href="#test-run-output-format" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">lit</strong> output for a test run conforms to the following schema, in
+both short and verbose modes (although in short mode no PASS lines will be
+shown). This schema has been chosen to be relatively easy to reliably parse by
+a machine (for example in buildbot log scraping), and for other tools to
+generate.</p>
+<p>Each test result is expected to appear on a line that matches:</p>
+<div class="highlight-none"><div class="highlight"><pre><result code>: <test name> (<progress info>)
+</pre></div>
+</div>
+<p>where <tt class="docutils literal"><span class="pre"><result-code></span></tt> is a standard test result such as PASS, FAIL, XFAIL,
+XPASS, UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and
+REGRESSED are also allowed.</p>
+<p>The <tt class="docutils literal"><span class="pre"><test</span> <span class="pre">name></span></tt> field can consist of an arbitrary string containing no
+newline.</p>
+<p>The <tt class="docutils literal"><span class="pre"><progress</span> <span class="pre">info></span></tt> field can be used to report progress information such
+as (1/300) or can be empty, but even when empty the parentheses are required.</p>
+<p>Each test result may include additional (multiline) log information in the
+following format:</p>
+<div class="highlight-none"><div class="highlight"><pre><log delineator> TEST '(<test name>)' <trailing delineator>
+... log message ...
+<log delineator>
+</pre></div>
+</div>
+<p>where <tt class="docutils literal"><span class="pre"><test</span> <span class="pre">name></span></tt> should be the name of a preceding reported test, <tt class="docutils literal"><span class="pre"><log</span>
+<span class="pre">delineator></span></tt> is a string of “*” characters <em>at least</em> four characters long
+(the recommended length is 20), and <tt class="docutils literal"><span class="pre"><trailing</span> <span class="pre">delineator></span></tt> is an arbitrary
+(unparsed) string.</p>
+<p>The following is an example of a test run output which consists of four tests A,
+B, C, and D, and a log message for the failing test C:</p>
+<div class="highlight-none"><div class="highlight"><pre>PASS: A (1 of 4)
+PASS: B (2 of 4)
+FAIL: C (3 of 4)
+******************** TEST 'C' FAILED ********************
+Test 'C' failed as a result of exit code 1.
+********************
+PASS: D (4 of 4)
+</pre></div>
+</div>
+</div>
+<div class="section" id="lit-example-tests">
+<h3>LIT EXAMPLE TESTS<a class="headerlink" href="#lit-example-tests" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">lit</strong> distribution contains several example implementations of
+test suites in the <em>ExampleTests</em> directory.</p>
+</div>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>valgrind(1)</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-build.html" title="llvm-build - LLVM Project Build Utility"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="tblgen.html" title="tblgen - Target Description To C++ Code Generator"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llc.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llc.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llc.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llc.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,326 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llc - LLVM static compiler — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="lli - directly execute programs from LLVM bitcode" href="lli.html" />
+ <link rel="prev" title="opt - LLVM optimizer" href="opt.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="lli.html" title="lli - directly execute programs from LLVM bitcode"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="opt.html" title="opt - LLVM optimizer"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llc-llvm-static-compiler">
+<h1>llc - LLVM static compiler<a class="headerlink" href="#llc-llvm-static-compiler" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llc</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llc</strong> command compiles LLVM source inputs into assembly language
+for a specified architecture. The assembly language output can then be passed
+through a native assembler and linker to generate a native executable.</p>
+<p>The choice of architecture for the output assembly code is automatically
+determined from the input file, unless the <a class="reference internal" href="lli.html#cmdoption-march"><em class="xref std std-option">-march</em></a> option is used to
+override the default.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p>If <tt class="docutils literal"><span class="pre">filename</span></tt> is “<tt class="docutils literal"><span class="pre">-</span></tt>” or omitted, <strong class="program">llc</strong> reads from standard input.
+Otherwise, it will from <tt class="docutils literal"><span class="pre">filename</span></tt>. Inputs can be in either the LLVM assembly
+language format (<tt class="docutils literal"><span class="pre">.ll</span></tt>) or the LLVM bitcode format (<tt class="docutils literal"><span class="pre">.bc</span></tt>).</p>
+<p>If the <a class="reference internal" href="opt.html#cmdoption-o"><em class="xref std std-option">-o</em></a> option is omitted, then <strong class="program">llc</strong> will send its output
+to standard output if the input is from standard input. If the <a class="reference internal" href="opt.html#cmdoption-o"><em class="xref std std-option">-o</em></a>
+option specifies “<tt class="docutils literal"><span class="pre">-</span></tt>”, then the output will also be sent to standard output.</p>
+<p>If no <a class="reference internal" href="opt.html#cmdoption-o"><em class="xref std std-option">-o</em></a> option is specified and an input file other than “<tt class="docutils literal"><span class="pre">-</span></tt>” is
+specified, then <strong class="program">llc</strong> creates the output filename by taking the input
+filename, removing any existing <tt class="docutils literal"><span class="pre">.bc</span></tt> extension, and adding a <tt class="docutils literal"><span class="pre">.s</span></tt> suffix.</p>
+<p>Other <strong class="program">llc</strong> options are described below.</p>
+<div class="section" id="end-user-options">
+<h3>End-user Options<a class="headerlink" href="#end-user-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-O">
+<tt class="descname">-O</tt><tt class="descclassname">=uint</tt><a class="headerlink" href="#cmdoption-O" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate code at different optimization levels. These correspond to the
+<tt class="docutils literal"><span class="pre">-O0</span></tt>, <tt class="docutils literal"><span class="pre">-O1</span></tt>, <tt class="docutils literal"><span class="pre">-O2</span></tt>, and <tt class="docutils literal"><span class="pre">-O3</span></tt> optimization levels used by
+<strong class="program">clang</strong>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mtriple">
+<tt class="descname">-mtriple</tt><tt class="descclassname">=<target triple></tt><a class="headerlink" href="#cmdoption-mtriple" title="Permalink to this definition">¶</a></dt>
+<dd><p>Override the target triple specified in the input file with the specified
+string.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-march">
+<tt class="descname">-march</tt><tt class="descclassname">=<arch></tt><a class="headerlink" href="#cmdoption-march" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the architecture for which to generate assembly, overriding the target
+encoded in the input file. See the output of <tt class="docutils literal"><span class="pre">llc</span> <span class="pre">-help</span></tt> for a list of
+valid architectures. By default this is inferred from the target triple or
+autodetected to the current architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mcpu">
+<tt class="descname">-mcpu</tt><tt class="descclassname">=<cpuname></tt><a class="headerlink" href="#cmdoption-mcpu" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a specific chip in the current architecture to generate code for.
+By default this is inferred from the target triple and autodetected to
+the current architecture. For a list of available CPUs, use:</p>
+<div class="highlight-none"><div class="highlight"><pre>llvm-as < /dev/null | llc -march=xyz -mcpu=help
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-filetype">
+<tt class="descname">-filetype</tt><tt class="descclassname">=<output file type></tt><a class="headerlink" href="#cmdoption-filetype" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify what kind of output <tt class="docutils literal"><span class="pre">llc</span></tt> should generated. Options are: <tt class="docutils literal"><span class="pre">asm</span></tt>
+for textual assembly ( <tt class="docutils literal"><span class="pre">'.s'</span></tt>), <tt class="docutils literal"><span class="pre">obj</span></tt> for native object files (<tt class="docutils literal"><span class="pre">'.o'</span></tt>)
+and <tt class="docutils literal"><span class="pre">null</span></tt> for not emitting anything (for performance testing).</p>
+<p>Note that not all targets support all options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mattr">
+<tt class="descname">-mattr</tt><tt class="descclassname">=a1,+a2,-a3,...</tt><a class="headerlink" href="#cmdoption-mattr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Override or control specific attributes of the target, such as whether SIMD
+operations are enabled or not. The default set of attributes is set by the
+current CPU. For a list of available attributes, use:</p>
+<div class="highlight-none"><div class="highlight"><pre>llvm-as < /dev/null | llc -march=xyz -mattr=help
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--disable-fp-elim">
+<tt class="descname">--disable-fp-elim</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--disable-fp-elim" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable frame pointer elimination optimization.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--disable-excess-fp-precision">
+<tt class="descname">--disable-excess-fp-precision</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--disable-excess-fp-precision" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable optimizations that may produce excess precision for floating point.
+Note that this option can dramatically slow down code on some systems
+(e.g. X86).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--enable-no-infs-fp-math">
+<tt class="descname">--enable-no-infs-fp-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--enable-no-infs-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations that assume no Inf values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--enable-no-nans-fp-math">
+<tt class="descname">--enable-no-nans-fp-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--enable-no-nans-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations that assume no NAN values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--enable-unsafe-fp-math">
+<tt class="descname">--enable-unsafe-fp-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--enable-unsafe-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations that make unsafe assumptions about IEEE math (e.g. that
+addition is associative) or may not work for all input ranges. These
+optimizations allow the code generator to make use of some instructions which
+would otherwise not be usable (such as <tt class="docutils literal"><span class="pre">fsin</span></tt> on X86).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--stats">
+<tt class="descname">--stats</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print statistics recorded by code-generation passes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--time-passes">
+<tt class="descname">--time-passes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--time-passes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Record the amount of time needed for each pass and print a report to standard
+error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--load">
+<tt class="descname">--load</tt><tt class="descclassname">=<dso_path></tt><a class="headerlink" href="#cmdoption--load" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dynamically load <tt class="docutils literal"><span class="pre">dso_path</span></tt> (a path to a dynamically shared object) that
+implements an LLVM target. This will permit the target name to be used with
+the <a class="reference internal" href="lli.html#cmdoption-march"><em class="xref std std-option">-march</em></a> option so that code can be generated for that target.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-meabi">
+<tt class="descname">-meabi</tt><tt class="descclassname">=[default|gnu|4|5]</tt><a class="headerlink" href="#cmdoption-meabi" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify which EABI version should conform to. Valid EABI versions are <em>gnu</em>,
+<em>4</em> and <em>5</em>. Default value (<em>default</em>) depends on the triple.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-stack-size-section">
+<tt class="descname">-stack-size-section</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-stack-size-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>Emit the .stack_sizes section which contains stack size metadata. The section
+contains an array of pairs of function symbol references (8 byte) and stack
+sizes (unsigned LEB128). The stack size values only include the space allocated
+in the function prologue. Functions with dynamic stack allocations are not
+included.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="tuning-configuration-options">
+<h3>Tuning/Configuration Options<a class="headerlink" href="#tuning-configuration-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption--print-machineinstrs">
+<tt class="descname">--print-machineinstrs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--print-machineinstrs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print generated machine code between compilation phases (useful for debugging).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--regalloc">
+<tt class="descname">--regalloc</tt><tt class="descclassname">=<allocator></tt><a class="headerlink" href="#cmdoption--regalloc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the register allocator to use.
+Valid register allocators are:</p>
+<p><em>basic</em></p>
+<blockquote>
+<div>Basic register allocator.</div></blockquote>
+<p><em>fast</em></p>
+<blockquote>
+<div>Fast register allocator. It is the default for unoptimized code.</div></blockquote>
+<p><em>greedy</em></p>
+<blockquote>
+<div>Greedy register allocator. It is the default for optimized code.</div></blockquote>
+<p><em>pbqp</em></p>
+<blockquote>
+<div>Register allocator based on ‘Partitioned Boolean Quadratic Programming’.</div></blockquote>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--spiller">
+<tt class="descname">--spiller</tt><tt class="descclassname">=<spiller></tt><a class="headerlink" href="#cmdoption--spiller" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the spiller to use for register allocators that support it. Currently
+this option is used only by the linear scan register allocator. The default
+<tt class="docutils literal"><span class="pre">spiller</span></tt> is <em>local</em>. Valid spillers are:</p>
+<p><em>simple</em></p>
+<blockquote>
+<div>Simple spiller</div></blockquote>
+<p><em>local</em></p>
+<blockquote>
+<div>Local spiller</div></blockquote>
+</dd></dl>
+
+</div>
+<div class="section" id="intel-ia-32-specific-options">
+<h3>Intel IA-32-specific Options<a class="headerlink" href="#intel-ia-32-specific-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption--x86-asm-syntax">
+<tt class="descname">--x86-asm-syntax</tt><tt class="descclassname">=[att|intel]</tt><a class="headerlink" href="#cmdoption--x86-asm-syntax" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify whether to emit assembly code in AT&T syntax (the default) or Intel
+syntax.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">llc</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>lli</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="lli.html" title="lli - directly execute programs from LLVM bitcode"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="opt.html" title="opt - LLVM optimizer"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/lli.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/lli.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/lli.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/lli.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,354 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>lli - directly execute programs from LLVM bitcode — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-link - LLVM bitcode linker" href="llvm-link.html" />
+ <link rel="prev" title="llc - LLVM static compiler" href="llc.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-link.html" title="llvm-link - LLVM bitcode linker"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llc.html" title="llc - LLVM static compiler"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="lli-directly-execute-programs-from-llvm-bitcode">
+<h1>lli - directly execute programs from LLVM bitcode<a class="headerlink" href="#lli-directly-execute-programs-from-llvm-bitcode" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">lli</strong> [<em>options</em>] [<em>filename</em>] [<em>program args</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">lli</strong> directly executes programs in LLVM bitcode format. It takes a program
+in LLVM bitcode format and executes it using a just-in-time compiler or an
+interpreter.</p>
+<p><strong class="program">lli</strong> is <em>not</em> an emulator. It will not execute IR of different architectures
+and it can only interpret (or JIT-compile) for the host architecture.</p>
+<p>The JIT compiler takes the same arguments as other tools, like <strong class="program">llc</strong>,
+but they don’t necessarily work for the interpreter.</p>
+<p>If <cite>filename</cite> is not specified, then <strong class="program">lli</strong> reads the LLVM bitcode for the
+program from standard input.</p>
+<p>The optional <em>args</em> specified on the command line are passed to the program as
+arguments.</p>
+</div>
+<div class="section" id="general-options">
+<h2>GENERAL OPTIONS<a class="headerlink" href="#general-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-fake-argv0">
+<tt class="descname">-fake-argv0</tt><tt class="descclassname">=executable</tt><a class="headerlink" href="#cmdoption-fake-argv0" title="Permalink to this definition">¶</a></dt>
+<dd><p>Override the <tt class="docutils literal"><span class="pre">argv[0]</span></tt> value passed into the executing program.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-force-interpreter">
+<tt class="descname">-force-interpreter</tt><tt class="descclassname">={false,true}</tt><a class="headerlink" href="#cmdoption-force-interpreter" title="Permalink to this definition">¶</a></dt>
+<dd><p>If set to true, use the interpreter even if a just-in-time compiler is available
+for this architecture. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-load">
+<tt class="descname">-load</tt><tt class="descclassname">=pluginfilename</tt><a class="headerlink" href="#cmdoption-load" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">lli</strong> to load the plugin (shared object) named <em>pluginfilename</em> and use
+it for optimization.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-stats">
+<tt class="descname">-stats</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print statistics from the code-generation passes. This is only meaningful for
+the just-in-time compiler, at present.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-time-passes">
+<tt class="descname">-time-passes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-time-passes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Record the amount of time needed for each code-generation pass and print it to
+standard error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-version">
+<tt class="descname">-version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print out the version of <strong class="program">lli</strong> and exit without doing anything else.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="target-options">
+<h2>TARGET OPTIONS<a class="headerlink" href="#target-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-mtriple">
+<tt class="descname">-mtriple</tt><tt class="descclassname">=target triple</tt><a class="headerlink" href="#cmdoption-mtriple" title="Permalink to this definition">¶</a></dt>
+<dd><p>Override the target triple specified in the input bitcode file with the
+specified string. This may result in a crash if you pick an
+architecture which is not compatible with the current system.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-march">
+<tt class="descname">-march</tt><tt class="descclassname">=arch</tt><a class="headerlink" href="#cmdoption-march" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the architecture for which to generate assembly, overriding the target
+encoded in the bitcode file. See the output of <strong>llc -help</strong> for a list of
+valid architectures. By default this is inferred from the target triple or
+autodetected to the current architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mcpu">
+<tt class="descname">-mcpu</tt><tt class="descclassname">=cpuname</tt><a class="headerlink" href="#cmdoption-mcpu" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a specific chip in the current architecture to generate code for.
+By default this is inferred from the target triple and autodetected to
+the current architecture. For a list of available CPUs, use:
+<strong>llvm-as < /dev/null | llc -march=xyz -mcpu=help</strong></p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mattr">
+<tt class="descname">-mattr</tt><tt class="descclassname">=a1,+a2,-a3,...</tt><a class="headerlink" href="#cmdoption-mattr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Override or control specific attributes of the target, such as whether SIMD
+operations are enabled or not. The default set of attributes is set by the
+current CPU. For a list of available attributes, use:
+<strong>llvm-as < /dev/null | llc -march=xyz -mattr=help</strong></p>
+</dd></dl>
+
+</div>
+<div class="section" id="floating-point-options">
+<h2>FLOATING POINT OPTIONS<a class="headerlink" href="#floating-point-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-disable-excess-fp-precision">
+<tt class="descname">-disable-excess-fp-precision</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-disable-excess-fp-precision" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable optimizations that may increase floating point precision.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-enable-no-infs-fp-math">
+<tt class="descname">-enable-no-infs-fp-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-enable-no-infs-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations that assume no Inf values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-enable-no-nans-fp-math">
+<tt class="descname">-enable-no-nans-fp-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-enable-no-nans-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations that assume no NAN values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-enable-unsafe-fp-math">
+<tt class="descname">-enable-unsafe-fp-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-enable-unsafe-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">lli</strong> to enable optimizations that may decrease floating point
+precision.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-soft-float">
+<tt class="descname">-soft-float</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-soft-float" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">lli</strong> to generate software floating point library calls instead of
+equivalent hardware instructions.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="code-generation-options">
+<h2>CODE GENERATION OPTIONS<a class="headerlink" href="#code-generation-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-code-model">
+<tt class="descname">-code-model</tt><tt class="descclassname">=model</tt><a class="headerlink" href="#cmdoption-code-model" title="Permalink to this definition">¶</a></dt>
+<dd><p>Choose the code model from:</p>
+<div class="highlight-text"><div class="highlight"><pre>default: Target default code model
+small: Small code model
+kernel: Kernel code model
+medium: Medium code model
+large: Large code model
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-disable-post-RA-scheduler">
+<tt class="descname">-disable-post-RA-scheduler</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-disable-post-RA-scheduler" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable scheduling after register allocation.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-disable-spill-fusing">
+<tt class="descname">-disable-spill-fusing</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-disable-spill-fusing" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable fusing of spill code into instructions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-jit-enable-eh">
+<tt class="descname">-jit-enable-eh</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-jit-enable-eh" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exception handling should be enabled in the just-in-time compiler.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-join-liveintervals">
+<tt class="descname">-join-liveintervals</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-join-liveintervals" title="Permalink to this definition">¶</a></dt>
+<dd><p>Coalesce copies (default=true).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-nozero-initialized-in-bss">
+<tt class="descname">-nozero-initialized-in-bss</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-nozero-initialized-in-bss" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t place zero-initialized symbols into the BSS section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pre-RA-sched">
+<tt class="descname">-pre-RA-sched</tt><tt class="descclassname">=scheduler</tt><a class="headerlink" href="#cmdoption-pre-RA-sched" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruction schedulers available (before register allocation):</p>
+<div class="highlight-text"><div class="highlight"><pre>=default: Best scheduler for the target
+=none: No scheduling: breadth first sequencing
+=simple: Simple two pass scheduling: minimize critical path and maximize processor utilization
+=simple-noitin: Simple two pass scheduling: Same as simple except using generic latency
+=list-burr: Bottom-up register reduction list scheduling
+=list-tdrr: Top-down register reduction list scheduling
+=list-td: Top-down list scheduler -print-machineinstrs - Print generated machine code
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-regalloc">
+<tt class="descname">-regalloc</tt><tt class="descclassname">=allocator</tt><a class="headerlink" href="#cmdoption-regalloc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Register allocator to use (default=linearscan)</p>
+<div class="highlight-text"><div class="highlight"><pre>=bigblock: Big-block register allocator
+=linearscan: linear scan register allocator =local - local register allocator
+=simple: simple register allocator
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-relocation-model">
+<tt class="descname">-relocation-model</tt><tt class="descclassname">=model</tt><a class="headerlink" href="#cmdoption-relocation-model" title="Permalink to this definition">¶</a></dt>
+<dd><p>Choose relocation model from:</p>
+<div class="highlight-text"><div class="highlight"><pre>=default: Target default relocation model
+=static: Non-relocatable code =pic - Fully relocatable, position independent code
+=dynamic-no-pic: Relocatable external references, non-relocatable code
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-spiller">
+<tt class="descname">-spiller</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-spiller" title="Permalink to this definition">¶</a></dt>
+<dd><p>Spiller to use (default=local)</p>
+<div class="highlight-text"><div class="highlight"><pre>=simple: simple spiller
+=local: local spiller
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-x86-asm-syntax">
+<tt class="descname">-x86-asm-syntax</tt><tt class="descclassname">=syntax</tt><a class="headerlink" href="#cmdoption-x86-asm-syntax" title="Permalink to this definition">¶</a></dt>
+<dd><p>Choose style of code to emit from X86 backend:</p>
+<div class="highlight-text"><div class="highlight"><pre>=att: Emit AT&T-style assembly
+=intel: Emit Intel-style assembly
+</pre></div>
+</div>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">lli</strong> fails to load the program, it will exit with an exit code of 1.
+Otherwise, it will return the exit code of the program it executes.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llc</strong></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-link.html" title="llvm-link - LLVM bitcode linker"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llc.html" title="llc - LLVM static compiler"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-ar.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-ar.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-ar.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-ar.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,347 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-ar - LLVM archiver — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-lib - LLVM lib.exe compatible library tool" href="llvm-lib.html" />
+ <link rel="prev" title="llvm-link - LLVM bitcode linker" href="llvm-link.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-lib.html" title="llvm-lib - LLVM lib.exe compatible library tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-link.html" title="llvm-link - LLVM bitcode linker"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-ar-llvm-archiver">
+<h1>llvm-ar - LLVM archiver<a class="headerlink" href="#llvm-ar-llvm-archiver" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-ar</strong> [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong>llvm-ar</strong> command is similar to the common Unix utility, <tt class="docutils literal"><span class="pre">ar</span></tt>. It
+archives several files together into a single file. The intent for this is
+to produce archive libraries by LLVM bitcode that can be linked into an
+LLVM program. However, the archive can contain any kind of file. By default,
+<strong>llvm-ar</strong> generates a symbol table that makes linking faster because
+only the symbol table needs to be consulted, not each individual file member
+of the archive.</p>
+<p>The <strong>llvm-ar</strong> command can be used to <em>read</em> SVR4, GNU and BSD style archive
+files. However, right now it can only write in the GNU format. If an
+SVR4 or BSD style archive is used with the <tt class="docutils literal"><span class="pre">r</span></tt> (replace) or <tt class="docutils literal"><span class="pre">q</span></tt> (quick
+update) operations, the archive will be reconstructed in GNU format.</p>
+<p>Here’s where <strong>llvm-ar</strong> departs from previous <tt class="docutils literal"><span class="pre">ar</span></tt> implementations:</p>
+<p><em>Symbol Table</em></p>
+<blockquote>
+<div>Since <strong>llvm-ar</strong> supports bitcode files. The symbol table it creates
+is in GNU format and includes both native and bitcode files.</div></blockquote>
+<p><em>Long Paths</em></p>
+<blockquote>
+<div>Currently <strong>llvm-ar</strong> can read GNU and BSD long file names, but only writes
+archives with the GNU format.</div></blockquote>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p>The options to <strong>llvm-ar</strong> are compatible with other <tt class="docutils literal"><span class="pre">ar</span></tt> implementations.
+However, there are a few modifiers (<em>R</em>) that are not found in other <tt class="docutils literal"><span class="pre">ar</span></tt>
+implementations. The options to <strong>llvm-ar</strong> specify a single basic operation to
+perform on the archive, a variety of modifiers for that operation, the name of
+the archive file, and an optional list of file names. These options are used to
+determine how <strong>llvm-ar</strong> should process the archive file.</p>
+<p>The Operations and Modifiers are explained in the sections below. The minimal
+set of options is at least one operator and the name of the archive. Typically
+archive files end with a <tt class="docutils literal"><span class="pre">.a</span></tt> suffix, but this is not required. Following
+the <em>archive-name</em> comes a list of <em>files</em> that indicate the specific members
+of the archive to operate on. If the <em>files</em> option is not specified, it
+generally means either “none” or “all” members, depending on the operation.</p>
+<div class="section" id="operations">
+<h3>Operations<a class="headerlink" href="#operations" title="Permalink to this headline">¶</a></h3>
+<p>d</p>
+<blockquote>
+<div>Delete files from the archive. No modifiers are applicable to this operation.
+The <em>files</em> options specify which members should be removed from the
+archive. It is not an error if a specified file does not appear in the archive.
+If no <em>files</em> are specified, the archive is not modified.</div></blockquote>
+<p>m[abi]</p>
+<blockquote>
+<div>Move files from one location in the archive to another. The <em>a</em>, <em>b</em>, and
+<em>i</em> modifiers apply to this operation. The <em>files</em> will all be moved
+to the location given by the modifiers. If no modifiers are used, the files
+will be moved to the end of the archive. If no <em>files</em> are specified, the
+archive is not modified.</div></blockquote>
+<p>p</p>
+<blockquote>
+<div>Print files to the standard output. This operation simply prints the
+<em>files</em> indicated to the standard output. If no <em>files</em> are
+specified, the entire archive is printed. Printing bitcode files is
+ill-advised as they might confuse your terminal settings. The <em>p</em>
+operation never modifies the archive.</div></blockquote>
+<p>q</p>
+<blockquote>
+<div>Quickly append files to the end of the archive. This operation quickly adds the
+<em>files</em> to the archive without checking for duplicates that should be
+removed first. If no <em>files</em> are specified, the archive is not modified.
+Because of the way that <strong>llvm-ar</strong> constructs the archive file, its dubious
+whether the <em>q</em> operation is any faster than the <em>r</em> operation.</div></blockquote>
+<p>r[abu]</p>
+<blockquote>
+<div>Replace or insert file members. The <em>a</em>, <em>b</em>, and <em>u</em>
+modifiers apply to this operation. This operation will replace existing
+<em>files</em> or insert them at the end of the archive if they do not exist. If no
+<em>files</em> are specified, the archive is not modified.</div></blockquote>
+<p>t[v]</p>
+<blockquote>
+<div>Print the table of contents. Without any modifiers, this operation just prints
+the names of the members to the standard output. With the <em>v</em> modifier,
+<strong>llvm-ar</strong> also prints out the file type (B=bitcode, S=symbol
+table, blank=regular file), the permission mode, the owner and group, the
+size, and the date. If any <em>files</em> are specified, the listing is only for
+those files. If no <em>files</em> are specified, the table of contents for the
+whole archive is printed.</div></blockquote>
+<p>x[oP]</p>
+<blockquote>
+<div>Extract archive members back to files. The <em>o</em> modifier applies to this
+operation. This operation retrieves the indicated <em>files</em> from the archive
+and writes them back to the operating system’s file system. If no
+<em>files</em> are specified, the entire archive is extract.</div></blockquote>
+</div>
+<div class="section" id="modifiers-operation-specific">
+<h3>Modifiers (operation specific)<a class="headerlink" href="#modifiers-operation-specific" title="Permalink to this headline">¶</a></h3>
+<p>The modifiers below are specific to certain operations. See the Operations
+section (above) to determine which modifiers are applicable to which operations.</p>
+<p>[a]</p>
+<blockquote>
+<div>When inserting or moving member files, this option specifies the destination of
+the new files as being after the <em>relpos</em> member. If <em>relpos</em> is not found,
+the files are placed at the end of the archive.</div></blockquote>
+<p>[b]</p>
+<blockquote>
+<div>When inserting or moving member files, this option specifies the destination of
+the new files as being before the <em>relpos</em> member. If <em>relpos</em> is not
+found, the files are placed at the end of the archive. This modifier is
+identical to the <em>i</em> modifier.</div></blockquote>
+<p>[i]</p>
+<blockquote>
+<div>A synonym for the <em>b</em> option.</div></blockquote>
+<p>[o]</p>
+<blockquote>
+<div>When extracting files, this option will cause <strong>llvm-ar</strong> to preserve the
+original modification times of the files it writes.</div></blockquote>
+<p>[u]</p>
+<blockquote>
+<div>When replacing existing files in the archive, only replace those files that have
+a time stamp than the time stamp of the member in the archive.</div></blockquote>
+</div>
+<div class="section" id="modifiers-generic">
+<h3>Modifiers (generic)<a class="headerlink" href="#modifiers-generic" title="Permalink to this headline">¶</a></h3>
+<p>The modifiers below may be applied to any operation.</p>
+<p>[c]</p>
+<blockquote>
+<div>For all operations, <strong>llvm-ar</strong> will always create the archive if it doesn’t
+exist. Normally, <strong>llvm-ar</strong> will print a warning message indicating that the
+archive is being created. Using this modifier turns off that warning.</div></blockquote>
+<p>[s]</p>
+<blockquote>
+<div>This modifier requests that an archive index (or symbol table) be added to the
+archive. This is the default mode of operation. The symbol table will contain
+all the externally visible functions and global variables defined by all the
+bitcode files in the archive.</div></blockquote>
+<p>[S]</p>
+<blockquote>
+<div>This modifier is the opposite of the <em>s</em> modifier. It instructs <strong>llvm-ar</strong> to
+not build the symbol table. If both <em>s</em> and <em>S</em> are used, the last modifier to
+occur in the options will prevail.</div></blockquote>
+<p>[v]</p>
+<blockquote>
+<div>This modifier instructs <strong>llvm-ar</strong> to be verbose about what it is doing. Each
+editing operation taken against the archive will produce a line of output saying
+what is being done.</div></blockquote>
+</div>
+</div>
+<div class="section" id="standards">
+<h2>STANDARDS<a class="headerlink" href="#standards" title="Permalink to this headline">¶</a></h2>
+<p>The <strong>llvm-ar</strong> utility is intended to provide a superset of the IEEE Std 1003.2
+(POSIX.2) functionality for <tt class="docutils literal"><span class="pre">ar</span></tt>. <strong>llvm-ar</strong> can read both SVR4 and BSD4.4 (or
+Mac OS X) archives. If the <tt class="docutils literal"><span class="pre">f</span></tt> modifier is given to the <tt class="docutils literal"><span class="pre">x</span></tt> or <tt class="docutils literal"><span class="pre">r</span></tt> operations
+then <strong>llvm-ar</strong> will write SVR4 compatible archives. Without this modifier,
+<strong>llvm-ar</strong> will write BSD4.4 compatible archives that have long names
+immediately after the header and indicated using the “#1/ddd” notation for the
+name in the header.</p>
+</div>
+<div class="section" id="file-format">
+<h2>FILE FORMAT<a class="headerlink" href="#file-format" title="Permalink to this headline">¶</a></h2>
+<p>The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX
+archive files. In fact, except for the symbol table, the <tt class="docutils literal"><span class="pre">ar</span></tt> commands on those
+operating systems should be able to read LLVM archive files. The details of the
+file format follow.</p>
+<p>Each archive begins with the archive magic number which is the eight printable
+characters ”!<arch>n” where n represents the newline character (0x0A).
+Following the magic number, the file is composed of even length members that
+begin with an archive header and end with a n padding character if necessary
+(to make the length even). Each file member is composed of a header (defined
+below), an optional newline-terminated “long file name” and the contents of
+the file.</p>
+<p>The fields of the header are described in the items below. All fields of the
+header contain only ASCII characters, are left justified and are right padded
+with space characters.</p>
+<p>name - char[16]</p>
+<blockquote>
+<div>This field of the header provides the name of the archive member. If the name is
+longer than 15 characters or contains a slash (/) character, then this field
+contains <tt class="docutils literal"><span class="pre">#1/nnn</span></tt> where <tt class="docutils literal"><span class="pre">nnn</span></tt> provides the length of the name and the <tt class="docutils literal"><span class="pre">#1/</span></tt>
+is literal. In this case, the actual name of the file is provided in the <tt class="docutils literal"><span class="pre">nnn</span></tt>
+bytes immediately following the header. If the name is 15 characters or less, it
+is contained directly in this field and terminated with a slash (/) character.</div></blockquote>
+<p>date - char[12]</p>
+<blockquote>
+<div>This field provides the date of modification of the file in the form of a
+decimal encoded number that provides the number of seconds since the epoch
+(since 00:00:00 Jan 1, 1970) per Posix specifications.</div></blockquote>
+<p>uid - char[6]</p>
+<blockquote>
+<div>This field provides the user id of the file encoded as a decimal ASCII string.
+This field might not make much sense on non-Unix systems. On Unix, it is the
+same value as the st_uid field of the stat structure returned by the stat(2)
+operating system call.</div></blockquote>
+<p>gid - char[6]</p>
+<blockquote>
+<div>This field provides the group id of the file encoded as a decimal ASCII string.
+This field might not make much sense on non-Unix systems. On Unix, it is the
+same value as the st_gid field of the stat structure returned by the stat(2)
+operating system call.</div></blockquote>
+<p>mode - char[8]</p>
+<blockquote>
+<div>This field provides the access mode of the file encoded as an octal ASCII
+string. This field might not make much sense on non-Unix systems. On Unix, it
+is the same value as the st_mode field of the stat structure returned by the
+stat(2) operating system call.</div></blockquote>
+<p>size - char[10]</p>
+<blockquote>
+<div>This field provides the size of the file, in bytes, encoded as a decimal ASCII
+string.</div></blockquote>
+<p>fmag - char[2]</p>
+<blockquote>
+<div>This field is the archive file member magic number. Its content is always the
+two characters back tick (0x60) and newline (0x0A). This provides some measure
+utility in identifying archive files that have been corrupted.</div></blockquote>
+<p>offset - vbr encoded 32-bit integer</p>
+<blockquote>
+<div>The offset item provides the offset into the archive file where the bitcode
+member is stored that is associated with the symbol. The offset value is 0
+based at the start of the first “normal” file member. To derive the actual
+file offset of the member, you must add the number of bytes occupied by the file
+signature (8 bytes) and the symbol tables. The value of this item is encoded
+using variable bit rate encoding to reduce the size of the symbol table.
+Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
+if there are more bytes to follow. The remaining 7 bits in each byte carry bits
+from the value. The final byte does not have the high bit set.</div></blockquote>
+<p>length - vbr encoded 32-bit integer</p>
+<blockquote>
+<div>The length item provides the length of the symbol that follows. Like this
+<em>offset</em> item, the length is variable bit rate encoded.</div></blockquote>
+<p>symbol - character array</p>
+<blockquote>
+<div>The symbol item provides the text of the symbol that is associated with the
+<em>offset</em>. The symbol is not terminated by any character. Its length is provided
+by the <em>length</em> field. Note that is allowed (but unwise) to use non-printing
+characters (even 0x00) in the symbol. This allows for multiple encodings of
+symbol names.</div></blockquote>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong>llvm-ar</strong> succeeds, it will exit with 0. A usage error, results
+in an exit code of 1. A hard (file system typically) error results in an
+exit code of 2. Miscellaneous or unknown errors result in an
+exit code of 3.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>ar(1)</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-lib.html" title="llvm-lib - LLVM lib.exe compatible library tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-link.html" title="llvm-link - LLVM bitcode linker"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-as.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-as.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-as.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-as.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,148 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-as - LLVM assembler — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-dis - LLVM disassembler" href="llvm-dis.html" />
+ <link rel="prev" title="LLVM Command Guide" href="index.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-dis.html" title="llvm-dis - LLVM disassembler"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="LLVM Command Guide"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-as-llvm-assembler">
+<h1>llvm-as - LLVM assembler<a class="headerlink" href="#llvm-as-llvm-assembler" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-as</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-as</strong> is the LLVM assembler. It reads a file containing human-readable
+LLVM assembly language, translates it to LLVM bitcode, and writes the result
+into a file or to standard output.</p>
+<p>If <em>filename</em> is omitted or is <tt class="docutils literal"><span class="pre">-</span></tt>, then <strong>llvm-as</strong> reads its input from
+standard input.</p>
+<p>If an output file is not specified with the <strong>-o</strong> option, then
+<strong>llvm-as</strong> sends its output to a file or standard output by following
+these rules:</p>
+<ul class="simple">
+<li>If the input is standard input, then the output is standard output.</li>
+<li>If the input is a file that ends with <tt class="docutils literal"><span class="pre">.ll</span></tt>, then the output file is of the
+same name, except that the suffix is changed to <tt class="docutils literal"><span class="pre">.bc</span></tt>.</li>
+<li>If the input is a file that does not end with the <tt class="docutils literal"><span class="pre">.ll</span></tt> suffix, then the
+output file has the same name as the input file, except that the <tt class="docutils literal"><span class="pre">.bc</span></tt>
+suffix is appended.</li>
+</ul>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt><strong>-f</strong></dt>
+<dd>Enable binary output on terminals. Normally, <strong>llvm-as</strong> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+<strong>llvm-as</strong> will write raw bitcode regardless of the output device.</dd>
+<dt><strong>-help</strong></dt>
+<dd>Print a summary of command line options.</dd>
+<dt><strong>-o</strong> <em>filename</em></dt>
+<dd>Specify the output file name. If <em>filename</em> is <tt class="docutils literal"><span class="pre">-</span></tt>, then <strong>llvm-as</strong>
+sends its output to standard output.</dd>
+</dl>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong>llvm-as</strong> succeeds, it will exit with 0. Otherwise, if an error occurs, it
+will exit with a non-zero value.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>llvm-dis|llvm-dis, gccas|gccas</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-dis.html" title="llvm-dis - LLVM disassembler"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="LLVM Command Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-bcanalyzer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-bcanalyzer.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-bcanalyzer.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-bcanalyzer.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,354 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-bcanalyzer - LLVM bitcode analyzer — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="FileCheck - Flexible pattern matching file verifier" href="FileCheck.html" />
+ <link rel="prev" title="llvm-extract - extract a function from an LLVM module" href="llvm-extract.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-bcanalyzer-llvm-bitcode-analyzer">
+<h1>llvm-bcanalyzer - LLVM bitcode analyzer<a class="headerlink" href="#llvm-bcanalyzer-llvm-bitcode-analyzer" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-bcanalyzer</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-bcanalyzer</strong> command is a small utility for analyzing bitcode
+files. The tool reads a bitcode file (such as generated with the
+<strong class="program">llvm-as</strong> tool) and produces a statistical report on the contents of
+the bitcode file. The tool can also dump a low level but human readable
+version of the bitcode file. This tool is probably not of much interest or
+utility except for those working directly with the bitcode file format. Most
+LLVM users can just ignore this tool.</p>
+<p>If <em>filename</em> is omitted or is <tt class="docutils literal"><span class="pre">-</span></tt>, then <strong class="program">llvm-bcanalyzer</strong> reads its
+input from standard input. This is useful for combining the tool into a
+pipeline. Output is written to the standard output.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-llvm-bcanalyzer-nodetails">
+<tt class="descname">-nodetails</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-nodetails" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">llvm-bcanalyzer</strong> to abbreviate its output by writing out only
+a module level summary. The details for individual functions are not
+displayed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-bcanalyzer-dump">
+<tt class="descname">-dump</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-dump" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">llvm-bcanalyzer</strong> to dump the bitcode in a human readable
+format. This format is significantly different from LLVM assembly and
+provides details about the encoding of the bitcode file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-bcanalyzer-verify">
+<tt class="descname">-verify</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-verify" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">llvm-bcanalyzer</strong> to verify the module produced by reading the
+bitcode. This ensures that the statistics generated are based on a consistent
+module.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-bcanalyzer-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">llvm-bcanalyzer</strong> succeeds, it will exit with 0. Otherwise, if an
+error occurs, it will exit with a non-zero value, usually 1.</p>
+</div>
+<div class="section" id="summary-output-definitions">
+<h2>SUMMARY OUTPUT DEFINITIONS<a class="headerlink" href="#summary-output-definitions" title="Permalink to this headline">¶</a></h2>
+<p>The following items are always printed by llvm-bcanalyzer. They comprize the
+summary output.</p>
+<p><strong>Bitcode Analysis Of Module</strong></p>
+<blockquote>
+<div>This just provides the name of the module for which bitcode analysis is being
+generated.</div></blockquote>
+<p><strong>Bitcode Version Number</strong></p>
+<blockquote>
+<div>The bitcode version (not LLVM version) of the file read by the analyzer.</div></blockquote>
+<p><strong>File Size</strong></p>
+<blockquote>
+<div>The size, in bytes, of the entire bitcode file.</div></blockquote>
+<p><strong>Module Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the module block. Percentage is relative to File Size.</div></blockquote>
+<p><strong>Function Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the function blocks. Percentage is relative to File
+Size.</div></blockquote>
+<p><strong>Global Types Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the Global Types Pool. Percentage is relative to File
+Size. This is the size of the definitions of all types in the bitcode file.</div></blockquote>
+<p><strong>Constant Pool Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
+Size.</div></blockquote>
+<p><strong>Module Globals Bytes</strong></p>
+<blockquote>
+<div>Ths size, in bytes, of the Global Variable Definitions and their initializers.
+Percentage is relative to File Size.</div></blockquote>
+<p><strong>Instruction List Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the instruction lists in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.</div></blockquote>
+<p><strong>Compaction Table Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the compaction tables in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.</div></blockquote>
+<p><strong>Symbol Table Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the symbol tables in all the functions. Percentage is
+relative to File Size. Note that this value is also included in the Function
+Bytes.</div></blockquote>
+<p><strong>Dependent Libraries Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the list of dependent libraries in the module. Percentage
+is relative to File Size. Note that this value is also included in the Module
+Global Bytes.</div></blockquote>
+<p><strong>Number Of Bitcode Blocks</strong></p>
+<blockquote>
+<div>The total number of blocks of any kind in the bitcode file.</div></blockquote>
+<p><strong>Number Of Functions</strong></p>
+<blockquote>
+<div>The total number of function definitions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Types</strong></p>
+<blockquote>
+<div>The total number of types defined in the Global Types Pool.</div></blockquote>
+<p><strong>Number Of Constants</strong></p>
+<blockquote>
+<div>The total number of constants (of any type) defined in the Constant Pool.</div></blockquote>
+<p><strong>Number Of Basic Blocks</strong></p>
+<blockquote>
+<div>The total number of basic blocks defined in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Instructions</strong></p>
+<blockquote>
+<div>The total number of instructions defined in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Long Instructions</strong></p>
+<blockquote>
+<div>The total number of long instructions defined in all functions in the bitcode
+file. Long instructions are those taking greater than 4 bytes. Typically long
+instructions are GetElementPtr with several indices, PHI nodes, and calls to
+functions with large numbers of arguments.</div></blockquote>
+<p><strong>Number Of Operands</strong></p>
+<blockquote>
+<div>The total number of operands used in all instructions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Compaction Tables</strong></p>
+<blockquote>
+<div>The total number of compaction tables in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Symbol Tables</strong></p>
+<blockquote>
+<div>The total number of symbol tables in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Dependent Libs</strong></p>
+<blockquote>
+<div>The total number of dependent libraries found in the bitcode file.</div></blockquote>
+<p><strong>Total Instruction Size</strong></p>
+<blockquote>
+<div>The total size of the instructions in all functions in the bitcode file.</div></blockquote>
+<p><strong>Average Instruction Size</strong></p>
+<blockquote>
+<div>The average number of bytes per instruction across all functions in the bitcode
+file. This value is computed by dividing Total Instruction Size by Number Of
+Instructions.</div></blockquote>
+<p><strong>Maximum Type Slot Number</strong></p>
+<blockquote>
+<div>The maximum value used for a type’s slot number. Larger slot number values take
+more bytes to encode.</div></blockquote>
+<p><strong>Maximum Value Slot Number</strong></p>
+<blockquote>
+<div>The maximum value used for a value’s slot number. Larger slot number values take
+more bytes to encode.</div></blockquote>
+<p><strong>Bytes Per Value</strong></p>
+<blockquote>
+<div>The average size of a Value definition (of any type). This is computed by
+dividing File Size by the total number of values of any type.</div></blockquote>
+<p><strong>Bytes Per Global</strong></p>
+<blockquote>
+<div>The average size of a global definition (constants and global variables).</div></blockquote>
+<p><strong>Bytes Per Function</strong></p>
+<blockquote>
+<div>The average number of bytes per function definition. This is computed by
+dividing Function Bytes by Number Of Functions.</div></blockquote>
+<p><strong># of VBR 32-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 32-bit integers encoded using the Variable Bit Rate
+encoding scheme.</div></blockquote>
+<p><strong># of VBR 64-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 64-bit integers encoded using the Variable Bit Rate encoding
+scheme.</div></blockquote>
+<p><strong># of VBR Compressed Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes consumed by the 32-bit and 64-bit integers that use
+the Variable Bit Rate encoding scheme.</div></blockquote>
+<p><strong># of VBR Expanded Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes that would have been consumed by the 32-bit and 64-bit
+integers had they not been compressed with the Variable Bit Rage encoding
+scheme.</div></blockquote>
+<p><strong>Bytes Saved With VBR</strong></p>
+<blockquote>
+<div>The total number of bytes saved by using the Variable Bit Rate encoding scheme.
+The percentage is relative to # of VBR Expanded Bytes.</div></blockquote>
+</div>
+<div class="section" id="detailed-output-definitions">
+<h2>DETAILED OUTPUT DEFINITIONS<a class="headerlink" href="#detailed-output-definitions" title="Permalink to this headline">¶</a></h2>
+<p>The following definitions occur only if the -nodetails option was not given.
+The detailed output provides additional information on a per-function basis.</p>
+<p><strong>Type</strong></p>
+<blockquote>
+<div>The type signature of the function.</div></blockquote>
+<p><strong>Byte Size</strong></p>
+<blockquote>
+<div>The total number of bytes in the function’s block.</div></blockquote>
+<p><strong>Basic Blocks</strong></p>
+<blockquote>
+<div>The number of basic blocks defined by the function.</div></blockquote>
+<p><strong>Instructions</strong></p>
+<blockquote>
+<div>The number of instructions defined by the function.</div></blockquote>
+<p><strong>Long Instructions</strong></p>
+<blockquote>
+<div>The number of instructions using the long instruction format in the function.</div></blockquote>
+<p><strong>Operands</strong></p>
+<blockquote>
+<div>The number of operands used by all instructions in the function.</div></blockquote>
+<p><strong>Instruction Size</strong></p>
+<blockquote>
+<div>The number of bytes consumed by instructions in the function.</div></blockquote>
+<p><strong>Average Instruction Size</strong></p>
+<blockquote>
+<div>The average number of bytes consumed by the instructions in the function.
+This value is computed by dividing Instruction Size by Instructions.</div></blockquote>
+<p><strong>Bytes Per Instruction</strong></p>
+<blockquote>
+<div>The average number of bytes used by the function per instruction. This value
+is computed by dividing Byte Size by Instructions. Note that this is not the
+same as Average Instruction Size. It computes a number relative to the total
+function size not just the size of the instruction list.</div></blockquote>
+<p><strong>Number of VBR 32-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 32-bit integers found in this function (for any use).</div></blockquote>
+<p><strong>Number of VBR 64-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 64-bit integers found in this function (for any use).</div></blockquote>
+<p><strong>Number of VBR Compressed Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes in this function consumed by the 32-bit and 64-bit
+integers that use the Variable Bit Rate encoding scheme.</div></blockquote>
+<p><strong>Number of VBR Expanded Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes in this function that would have been consumed by
+the 32-bit and 64-bit integers had they not been compressed with the Variable
+Bit Rate encoding scheme.</div></blockquote>
+<p><strong>Bytes Saved With VBR</strong></p>
+<blockquote>
+<div>The total number of bytes saved in this function by using the Variable Bit
+Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.</div></blockquote>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="llvm-dis.html"><em>llvm-dis - LLVM disassembler</em></a>, <a class="reference internal" href="../BitCodeFormat.html"><em>LLVM Bitcode File Format</em></a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-build.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-build.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-build.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-build.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,165 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-build - LLVM Project Build Utility — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-pdbutil - PDB File forensics and diagnostics" href="llvm-pdbutil.html" />
+ <link rel="prev" title="lit - LLVM Integrated Tester" href="lit.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-build-llvm-project-build-utility">
+<h1>llvm-build - LLVM Project Build Utility<a class="headerlink" href="#llvm-build-llvm-project-build-utility" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-build</strong> [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-build</strong> is a tool for working with LLVM projects that use the LLVMBuild
+system for describing their components.</p>
+<p>At heart, <strong>llvm-build</strong> is responsible for loading, verifying, and manipulating
+the project’s component data. The tool is primarily designed for use in
+implementing build systems and tools which need access to the project structure
+information.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>-h</strong>, <strong>–help</strong></p>
+<blockquote>
+<div>Print the builtin program help.</div></blockquote>
+<p><strong>–source-root</strong>=<em>PATH</em></p>
+<blockquote>
+<div>If given, load the project at the given source root path. If this option is not
+given, the location of the project sources will be inferred from the location of
+the <strong>llvm-build</strong> script itself.</div></blockquote>
+<p><strong>–print-tree</strong></p>
+<blockquote>
+<div>Print the component tree for the project.</div></blockquote>
+<p><strong>–write-library-table</strong></p>
+<blockquote>
+<div>Write out the C++ fragment which defines the components, library names, and
+required libraries. This C++ fragment is built into llvm-config|llvm-config
+in order to provide clients with the list of required libraries for arbitrary
+component combinations.</div></blockquote>
+<p><strong>–write-llvmbuild</strong></p>
+<blockquote>
+<div>Write out new <em>LLVMBuild.txt</em> files based on the loaded components. This is
+useful for auto-upgrading the schema of the files. <strong>llvm-build</strong> will try to a
+limited extent to preserve the comments which were written in the original
+source file, although at this time it only preserves block comments that precede
+the section names in the <em>LLVMBuild</em> files.</div></blockquote>
+<p><strong>–write-cmake-fragment</strong></p>
+<blockquote>
+<div>Write out the LLVMBuild in the form of a CMake fragment, so it can easily be
+consumed by the CMake based build system. The exact contents and format of this
+file are closely tied to how LLVMBuild is integrated with CMake, see LLVM’s
+top-level CMakeLists.txt.</div></blockquote>
+<p><strong>–write-make-fragment</strong></p>
+<blockquote>
+<div>Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be
+consumed by a Make based build system. The exact contents and format of this
+file are closely tied to how LLVMBuild is integrated with the Makefiles, see
+LLVM’s Makefile.rules.</div></blockquote>
+<p><strong>–llvmbuild-source-root</strong>=<em>PATH</em></p>
+<blockquote>
+<div>If given, expect the <em>LLVMBuild</em> files for the project to be rooted at the
+given path, instead of inside the source tree itself. This option is primarily
+designed for use in conjunction with <strong>–write-llvmbuild</strong> to test changes to
+<em>LLVMBuild</em> schema.</div></blockquote>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-build</strong> exits with 0 if operation was successful. Otherwise, it will exist
+with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-config.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-config.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-config.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-config.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,197 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-config - Print LLVM compilation options — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-diff - LLVM structural âdiffâ" href="llvm-diff.html" />
+ <link rel="prev" title="llvm-nm - list LLVM bitcode and object fileâs symbol table" href="llvm-nm.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-config-print-llvm-compilation-options">
+<h1>llvm-config - Print LLVM compilation options<a class="headerlink" href="#llvm-config-print-llvm-compilation-options" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-config</strong> <em>option</em> [<em>components</em>...]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-config</strong> makes it easier to build applications that use LLVM. It can
+print the compiler flags, linker flags and object libraries needed to link
+against LLVM.</p>
+</div>
+<div class="section" id="examples">
+<h2>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<p>To link against the JIT:</p>
+<div class="highlight-sh"><div class="highlight"><pre>g++ <span class="sb">`</span>llvm-config --cxxflags<span class="sb">`</span> -o HowToUseJIT.o -c HowToUseJIT.cpp
+g++ <span class="sb">`</span>llvm-config --ldflags<span class="sb">`</span> -o HowToUseJIT HowToUseJIT.o <span class="se">\</span>
+ <span class="sb">`</span>llvm-config --libs engine bcreader scalaropts<span class="sb">`</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>–version</strong></p>
+<blockquote>
+<div>Print the version number of LLVM.</div></blockquote>
+<p><strong>-help</strong></p>
+<blockquote>
+<div>Print a summary of <strong>llvm-config</strong> arguments.</div></blockquote>
+<p><strong>–prefix</strong></p>
+<blockquote>
+<div>Print the installation prefix for LLVM.</div></blockquote>
+<p><strong>–src-root</strong></p>
+<blockquote>
+<div>Print the source root from which LLVM was built.</div></blockquote>
+<p><strong>–obj-root</strong></p>
+<blockquote>
+<div>Print the object root used to build LLVM.</div></blockquote>
+<p><strong>–bindir</strong></p>
+<blockquote>
+<div>Print the installation directory for LLVM binaries.</div></blockquote>
+<p><strong>–includedir</strong></p>
+<blockquote>
+<div>Print the installation directory for LLVM headers.</div></blockquote>
+<p><strong>–libdir</strong></p>
+<blockquote>
+<div>Print the installation directory for LLVM libraries.</div></blockquote>
+<p><strong>–cxxflags</strong></p>
+<blockquote>
+<div>Print the C++ compiler flags needed to use LLVM headers.</div></blockquote>
+<p><strong>–ldflags</strong></p>
+<blockquote>
+<div>Print the flags needed to link against LLVM libraries.</div></blockquote>
+<p><strong>–libs</strong></p>
+<blockquote>
+<div>Print all the libraries needed to link against the specified LLVM
+<em>components</em>, including any dependencies.</div></blockquote>
+<p><strong>–libnames</strong></p>
+<blockquote>
+<div>Similar to <strong>–libs</strong>, but prints the bare filenames of the libraries
+without <strong>-l</strong> or pathnames. Useful for linking against a not-yet-installed
+copy of LLVM.</div></blockquote>
+<p><strong>–libfiles</strong></p>
+<blockquote>
+<div>Similar to <strong>–libs</strong>, but print the full path to each library file. This is
+useful when creating makefile dependencies, to ensure that a tool is relinked if
+any library it uses changes.</div></blockquote>
+<p><strong>–components</strong></p>
+<blockquote>
+<div>Print all valid component names.</div></blockquote>
+<p><strong>–targets-built</strong></p>
+<blockquote>
+<div>Print the component names for all targets supported by this copy of LLVM.</div></blockquote>
+<p><strong>–build-mode</strong></p>
+<blockquote>
+<div>Print the build mode used when LLVM was built (e.g. Debug or Release)</div></blockquote>
+</div>
+<div class="section" id="components">
+<h2>COMPONENTS<a class="headerlink" href="#components" title="Permalink to this headline">¶</a></h2>
+<p>To print a list of all available components, run <strong>llvm-config
+–components</strong>. In most cases, components correspond directly to LLVM
+libraries. Useful “virtual” components include:</p>
+<p><strong>all</strong></p>
+<blockquote>
+<div>Includes all LLVM libraries. The default if no components are specified.</div></blockquote>
+<p><strong>backend</strong></p>
+<blockquote>
+<div>Includes either a native backend or the C backend.</div></blockquote>
+<p><strong>engine</strong></p>
+<blockquote>
+<div>Includes either a native JIT or the bitcode interpreter.</div></blockquote>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong>llvm-config</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-cov.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-cov.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-cov.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-cov.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,527 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-cov - emit coverage information — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-profdata - Profile data tool" href="llvm-profdata.html" />
+ <link rel="prev" title="llvm-diff - LLVM structural âdiffâ" href="llvm-diff.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-profdata.html" title="llvm-profdata - Profile data tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-cov-emit-coverage-information">
+<h1>llvm-cov - emit coverage information<a class="headerlink" href="#llvm-cov-emit-coverage-information" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-cov</strong> <em>command</em> [<em>args...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-cov</strong> tool shows code coverage information for
+programs that are instrumented to emit profile data. It can be used to
+work with <tt class="docutils literal"><span class="pre">gcov</span></tt>-style coverage or with <tt class="docutils literal"><span class="pre">clang</span></tt>‘s instrumentation
+based profiling.</p>
+<p>If the program is invoked with a base name of <tt class="docutils literal"><span class="pre">gcov</span></tt>, it will behave as if
+the <strong class="program">llvm-cov gcov</strong> command were called. Otherwise, a command should
+be provided.</p>
+</div>
+<div class="section" id="commands">
+<h2>COMMANDS<a class="headerlink" href="#commands" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference internal" href="#llvm-cov-gcov"><em>gcov</em></a></li>
+<li><a class="reference internal" href="#llvm-cov-show"><em>show</em></a></li>
+<li><a class="reference internal" href="#llvm-cov-report"><em>report</em></a></li>
+<li><a class="reference internal" href="#llvm-cov-export"><em>export</em></a></li>
+</ul>
+</div>
+<div class="section" id="gcov-command">
+<span id="llvm-cov-gcov"></span><h2>GCOV COMMAND<a class="headerlink" href="#gcov-command" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id1">
+<h3>SYNOPSIS<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-cov gcov</strong> [<em>options</em>] <em>SOURCEFILE</em></p>
+</div>
+<div class="section" id="id2">
+<h3>DESCRIPTION<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov gcov</strong> tool reads code coverage data files and displays
+the coverage information for a specified source file. It is compatible with the
+<tt class="docutils literal"><span class="pre">gcov</span></tt> tool from version 4.2 of <tt class="docutils literal"><span class="pre">GCC</span></tt> and may also be compatible with some
+later versions of <tt class="docutils literal"><span class="pre">gcov</span></tt>.</p>
+<p>To use <strong class="program">llvm-cov gcov</strong>, you must first build an instrumented version
+of your application that collects coverage data as it runs. Compile with the
+<tt class="docutils literal"><span class="pre">-fprofile-arcs</span></tt> and <tt class="docutils literal"><span class="pre">-ftest-coverage</span></tt> options to add the
+instrumentation. (Alternatively, you can use the <tt class="docutils literal"><span class="pre">--coverage</span></tt> option, which
+includes both of those other options.) You should compile with debugging
+information (<tt class="docutils literal"><span class="pre">-g</span></tt>) and without optimization (<tt class="docutils literal"><span class="pre">-O0</span></tt>); otherwise, the
+coverage data cannot be accurately mapped back to the source code.</p>
+<p>At the time you compile the instrumented code, a <tt class="docutils literal"><span class="pre">.gcno</span></tt> data file will be
+generated for each object file. These <tt class="docutils literal"><span class="pre">.gcno</span></tt> files contain half of the
+coverage data. The other half of the data comes from <tt class="docutils literal"><span class="pre">.gcda</span></tt> files that are
+generated when you run the instrumented program, with a separate <tt class="docutils literal"><span class="pre">.gcda</span></tt>
+file for each object file. Each time you run the program, the execution counts
+are summed into any existing <tt class="docutils literal"><span class="pre">.gcda</span></tt> files, so be sure to remove any old
+files if you do not want their contents to be included.</p>
+<p>By default, the <tt class="docutils literal"><span class="pre">.gcda</span></tt> files are written into the same directory as the
+object files, but you can override that by setting the <tt class="docutils literal"><span class="pre">GCOV_PREFIX</span></tt> and
+<tt class="docutils literal"><span class="pre">GCOV_PREFIX_STRIP</span></tt> environment variables. The <tt class="docutils literal"><span class="pre">GCOV_PREFIX_STRIP</span></tt>
+variable specifies a number of directory components to be removed from the
+start of the absolute path to the object file directory. After stripping those
+directories, the prefix from the <tt class="docutils literal"><span class="pre">GCOV_PREFIX</span></tt> variable is added. These
+environment variables allow you to run the instrumented program on a machine
+where the original object file directories are not accessible, but you will
+then need to copy the <tt class="docutils literal"><span class="pre">.gcda</span></tt> files back to the object file directories
+where <strong class="program">llvm-cov gcov</strong> expects to find them.</p>
+<p>Once you have generated the coverage data files, run <strong class="program">llvm-cov gcov</strong>
+for each main source file where you want to examine the coverage results. This
+should be run from the same directory where you previously ran the
+compiler. The results for the specified source file are written to a file named
+by appending a <tt class="docutils literal"><span class="pre">.gcov</span></tt> suffix. A separate output file is also created for
+each file included by the main source file, also with a <tt class="docutils literal"><span class="pre">.gcov</span></tt> suffix added.</p>
+<p>The basic content of an <tt class="docutils literal"><span class="pre">.gcov</span></tt> output file is a copy of the source file with
+an execution count and line number prepended to every line. The execution
+count is shown as <tt class="docutils literal"><span class="pre">-</span></tt> if a line does not contain any executable code. If
+a line contains code but that code was never executed, the count is displayed
+as <tt class="docutils literal"><span class="pre">#####</span></tt>.</p>
+</div>
+<div class="section" id="options">
+<h3>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-a">
+<tt class="descname">-a</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--all-blocks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-a" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all basic blocks. If there are multiple blocks for a single line of
+source code, this option causes llvm-cov to show the count for each block
+instead of just one count for the entire line.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-b">
+<tt class="descname">-b</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--branch-probabilities</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-b" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display conditional branch probabilities and a summary of branch information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-c">
+<tt class="descname">-c</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--branch-counts</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-c" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display branch counts instead of probabilities (requires -b).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-f">
+<tt class="descname">-f</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--function-summaries</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show a summary of coverage for each function instead of just one summary for
+an entire source file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov--help">
+<tt class="descname">--help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov--help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display available options (–help-hidden for more).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-l">
+<tt class="descname">-l</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--long-file-names</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-l" title="Permalink to this definition">¶</a></dt>
+<dd><p>For coverage output of files included from the main source file, add the
+main file name followed by <tt class="docutils literal"><span class="pre">##</span></tt> as a prefix to the output file names. This
+can be combined with the –preserve-paths option to use complete paths for
+both the main file and the included file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-n">
+<tt class="descname">-n</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--no-output</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-n" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not output any <tt class="docutils literal"><span class="pre">.gcov</span></tt> files. Summary information is still
+displayed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-o">
+<tt class="descname">-o</tt><tt class="descclassname">=<DIR|FILE></tt><tt class="descclassname">, </tt><tt class="descname">--object-directory</tt><tt class="descclassname">=<DIR></tt><tt class="descclassname">, </tt><tt class="descname">--object-file</tt><tt class="descclassname">=<FILE></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Find objects in DIR or based on FILE’s path. If you specify a particular
+object file, the coverage data files are expected to have the same base name
+with <tt class="docutils literal"><span class="pre">.gcno</span></tt> and <tt class="docutils literal"><span class="pre">.gcda</span></tt> extensions. If you specify a directory, the
+files are expected in that directory with the same base name as the source
+file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-p">
+<tt class="descname">-p</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--preserve-paths</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Preserve path components when naming the coverage output files. In addition
+to the source file name, include the directories from the path to that
+file. The directories are separate by <tt class="docutils literal"><span class="pre">#</span></tt> characters, with <tt class="docutils literal"><span class="pre">.</span></tt> directories
+removed and <tt class="docutils literal"><span class="pre">..</span></tt> directories replaced by <tt class="docutils literal"><span class="pre">^</span></tt> characters. When used with
+the –long-file-names option, this applies to both the main file name and the
+included file name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-u">
+<tt class="descname">-u</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--unconditional-branches</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-u" title="Permalink to this definition">¶</a></dt>
+<dd><p>Include unconditional branches in the output for the –branch-probabilities
+option.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-version">
+<tt class="descname">-version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-gcov-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of llvm-cov.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h3>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-cov gcov</strong> returns 1 if it cannot read input files. Otherwise,
+it exits with zero.</p>
+</div>
+</div>
+<div class="section" id="show-command">
+<span id="llvm-cov-show"></span><h2>SHOW COMMAND<a class="headerlink" href="#show-command" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id3">
+<h3>SYNOPSIS<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-cov show</strong> [<em>options</em>] -instr-profile <em>PROFILE</em> <em>BIN</em> [<em>-object BIN,...</em>] [[<em>-object BIN</em>]] [<em>SOURCES</em>]</p>
+</div>
+<div class="section" id="id4">
+<h3>DESCRIPTION<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov show</strong> command shows line by line coverage of the
+binaries <em>BIN</em>,... using the profile data <em>PROFILE</em>. It can optionally be
+filtered to only show the coverage for the files listed in <em>SOURCES</em>.</p>
+<p>To use <strong class="program">llvm-cov show</strong>, you need a program that is compiled with
+instrumentation to emit profile and coverage data. To build such a program with
+<tt class="docutils literal"><span class="pre">clang</span></tt> use the <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> and <tt class="docutils literal"><span class="pre">-fcoverage-mapping</span></tt>
+flags. If linking with the <tt class="docutils literal"><span class="pre">clang</span></tt> driver, pass <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt>
+to the link stage to make sure the necessary runtime libraries are linked in.</p>
+<p>The coverage information is stored in the built executable or library itself,
+and this is what you should pass to <strong class="program">llvm-cov show</strong> as a <em>BIN</em>
+argument. The profile data is generated by running this instrumented program
+normally. When the program exits it will write out a raw profile file,
+typically called <tt class="docutils literal"><span class="pre">default.profraw</span></tt>, which can be converted to a format that
+is suitable for the <em>PROFILE</em> argument using the <strong class="program">llvm-profdata merge</strong>
+tool.</p>
+</div>
+<div class="section" id="id5">
+<h3>OPTIONS<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-line-counts">
+<tt class="descname">-show-line-counts</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-show-line-counts" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the execution counts for each line. Defaults to true, unless another
+<tt class="docutils literal"><span class="pre">-show</span></tt> option is used.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-expansions">
+<tt class="descname">-show-expansions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-show-expansions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Expand inclusions, such as preprocessor macros or textual inclusions, inline
+in the display of the source file. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-instantiations">
+<tt class="descname">-show-instantiations</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-show-instantiations" title="Permalink to this definition">¶</a></dt>
+<dd><p>For source regions that are instantiated multiple times, such as templates in
+<tt class="docutils literal"><span class="pre">C++</span></tt>, show each instantiation separately as well as the combined summary.
+Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-regions">
+<tt class="descname">-show-regions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-show-regions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the execution counts for each region by displaying a caret that points to
+the character where the region starts. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-line-counts-or-regions">
+<tt class="descname">-show-line-counts-or-regions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-show-line-counts-or-regions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the execution counts for each line if there is only one region on the
+line, but show the individual regions if there are multiple on the line.
+Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-use-color">
+<tt class="descname">-use-color</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-use-color" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable or disable color output. By default this is autodetected.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-arch">
+<tt class="descname">-arch</tt><tt class="descclassname">=[*NAMES*]</tt><a class="headerlink" href="#cmdoption-llvm-cov-show-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a list of architectures such that the Nth entry in the list
+corresponds to the Nth specified binary. If the covered object is a universal
+binary, this specifies the architecture to use. It is an error to specify an
+architecture that is not included in the universal binary or to use an
+architecture that does not match a non-universal binary.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-name">
+<tt class="descname">-name</tt><tt class="descclassname">=<NAME></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with the given name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-name-whitelist">
+<tt class="descname">-name-whitelist</tt><tt class="descclassname">=<FILE></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-name-whitelist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions listed in the given file. Each line in
+the file should start with <cite>whitelist_fun:</cite>, immediately followed by the name
+of the function to accept. This name can be a wildcard expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-name-regex">
+<tt class="descname">-name-regex</tt><tt class="descclassname">=<PATTERN></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-name-regex" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions that match the given regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-format">
+<tt class="descname">-format</tt><tt class="descclassname">=<FORMAT></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use the specified output format. The supported formats are: “text”, “html”.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-tab-size">
+<tt class="descname">-tab-size</tt><tt class="descclassname">=<TABSIZE></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-tab-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
+only supported for the html format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-output-dir">
+<tt class="descname">-output-dir</tt><tt class="descclassname">=PATH</tt><a class="headerlink" href="#cmdoption-llvm-cov-show-output-dir" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a directory to write coverage reports into. If the directory does not
+exist, it is created. When used in function view mode (i.e when -name or
+-name-regex are used to select specific functions), the report is written to
+PATH/functions.EXTENSION. When used in file view mode, a report for each file
+is written to PATH/REL_PATH_TO_FILE.EXTENSION.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-Xdemangler">
+<tt class="descname">-Xdemangler</tt><tt class="descclassname">=<TOOL>|<TOOL-OPTION></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-Xdemangler" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a symbol demangler. This can be used to make reports more
+human-readable. This option can be specified multiple times to supply
+arguments to the demangler (e.g <cite>-Xdemangler c++filt -Xdemangler -n</cite> for C++).
+The demangler is expected to read a newline-separated list of symbols from
+stdin and write a newline-separated list of the same length to stdout.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-num-threads">
+<tt class="descname">-num-threads</tt><tt class="descclassname">=N</tt><tt class="descclassname">, </tt><tt class="descname">-j</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-llvm-cov-show-num-threads" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use N threads to write file reports (only applicable when -output-dir is
+specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
+use. This is the default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-line-coverage-gt">
+<tt class="descname">-line-coverage-gt</tt><tt class="descclassname">=<N></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-line-coverage-gt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with line coverage greater than the
+given threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-line-coverage-lt">
+<tt class="descname">-line-coverage-lt</tt><tt class="descclassname">=<N></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-line-coverage-lt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with line coverage less than the given
+threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-region-coverage-gt">
+<tt class="descname">-region-coverage-gt</tt><tt class="descclassname">=<N></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-region-coverage-gt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with region coverage greater than the
+given threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-region-coverage-lt">
+<tt class="descname">-region-coverage-lt</tt><tt class="descclassname">=<N></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-region-coverage-lt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with region coverage less than the given
+threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-path-equivalence">
+<tt class="descname">-path-equivalence</tt><tt class="descclassname">=<from>,<to></tt><a class="headerlink" href="#cmdoption-llvm-cov-show-path-equivalence" title="Permalink to this definition">¶</a></dt>
+<dd><p>Map the paths in the coverage data to local source file paths. This allows you
+to generate the coverage data on one machine, and then use llvm-cov on a
+different machine where you have the same files on a different path.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="report-command">
+<span id="llvm-cov-report"></span><h2>REPORT COMMAND<a class="headerlink" href="#report-command" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id6">
+<h3>SYNOPSIS<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-cov report</strong> [<em>options</em>] -instr-profile <em>PROFILE</em> <em>BIN</em> [<em>-object BIN,...</em>] [[<em>-object BIN</em>]] [<em>SOURCES</em>]</p>
+</div>
+<div class="section" id="id7">
+<h3>DESCRIPTION<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov report</strong> command displays a summary of the coverage of
+the binaries <em>BIN</em>,... using the profile data <em>PROFILE</em>. It can optionally be
+filtered to only show the coverage for the files listed in <em>SOURCES</em>.</p>
+<p>If no source files are provided, a summary line is printed for each file in the
+coverage data. If any files are provided, summaries are shown for each function
+in the listed files instead.</p>
+<p>For information on compiling programs for coverage and generating profile data,
+see <a class="reference internal" href="#llvm-cov-show"><em>SHOW COMMAND</em></a>.</p>
+</div>
+<div class="section" id="id8">
+<h3>OPTIONS<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-use-color">
+<tt class="descname">-use-color</tt><tt class="descclassname">[=VALUE]</tt><a class="headerlink" href="#cmdoption-llvm-cov-report-use-color" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable or disable color output. By default this is autodetected.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-arch">
+<tt class="descname">-arch</tt><tt class="descclassname">=<name></tt><a class="headerlink" href="#cmdoption-llvm-cov-report-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>If the covered binary is a universal binary, select the architecture to use.
+It is an error to specify an architecture that is not included in the
+universal binary or to use an architecture that does not match a
+non-universal binary.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-show-functions">
+<tt class="descname">-show-functions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-report-show-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show coverage summaries for each function. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-show-instantiation-summary">
+<tt class="descname">-show-instantiation-summary</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-report-show-instantiation-summary" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show statistics for all function instantiations. Defaults to false.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="export-command">
+<span id="llvm-cov-export"></span><h2>EXPORT COMMAND<a class="headerlink" href="#export-command" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id9">
+<h3>SYNOPSIS<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-cov export</strong> [<em>options</em>] -instr-profile <em>PROFILE</em> <em>BIN</em> [<em>-object BIN,...</em>] [[<em>-object BIN</em>]]</p>
+</div>
+<div class="section" id="id10">
+<h3>DESCRIPTION<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov export</strong> command exports regions, functions, expansions,
+and summaries of the coverage of the binaries <em>BIN</em>,... using the profile data
+<em>PROFILE</em> as JSON.</p>
+<p>For information on compiling programs for coverage and generating profile data,
+see <a class="reference internal" href="#llvm-cov-show"><em>SHOW COMMAND</em></a>.</p>
+</div>
+<div class="section" id="id11">
+<h3>OPTIONS<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-cov-export-arch">
+<tt class="descname">-arch</tt><tt class="descclassname">=<name></tt><a class="headerlink" href="#cmdoption-llvm-cov-export-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>If the covered binary is a universal binary, select the architecture to use.
+It is an error to specify an architecture that is not included in the
+universal binary or to use an architecture that does not match a
+non-universal binary.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-export-summary-only">
+<tt class="descname">-summary-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-cov-export-summary-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Export only summary information for each file in the coverage data. This mode
+will not export coverage information for smaller units such as individual
+functions or regions. The result will be the same as produced by :program:
+<cite>llvm-cov report</cite> command, but presented in JSON format rather than text.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-profdata.html" title="llvm-profdata - Profile data tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-diff.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-diff.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-diff.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-diff.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,139 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-diff - LLVM structural âdiffâ — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-cov - emit coverage information" href="llvm-cov.html" />
+ <link rel="prev" title="llvm-config - Print LLVM compilation options" href="llvm-config.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-cov.html" title="llvm-cov - emit coverage information"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-config.html" title="llvm-config - Print LLVM compilation options"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-diff-llvm-structural-diff">
+<h1>llvm-diff - LLVM structural ‘diff’<a class="headerlink" href="#llvm-diff-llvm-structural-diff" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-diff</strong> [<em>options</em>] <em>module 1</em> <em>module 2</em> [<em>global name ...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-diff</strong> compares the structure of two LLVM modules, primarily
+focusing on differences in function definitions. Insignificant
+differences, such as changes in the ordering of globals or in the
+names of local values, are ignored.</p>
+<p>An input module will be interpreted as an assembly file if its name
+ends in ‘.ll’; otherwise it will be read in as a bitcode file.</p>
+<p>If a list of global names is given, just the values with those names
+are compared; otherwise, all global values are compared, and
+diagnostics are produced for globals which only appear in one module
+or the other.</p>
+<p><strong>llvm-diff</strong> compares two functions by comparing their basic blocks,
+beginning with the entry blocks. If the terminators seem to match,
+then the corresponding successors are compared; otherwise they are
+ignored. This algorithm is very sensitive to changes in control flow,
+which tend to stop any downstream changes from being detected.</p>
+<p><strong>llvm-diff</strong> is intended as a debugging tool for writers of LLVM
+passes and frontends. It does not have a stable output format.</p>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong>llvm-diff</strong> finds no differences between the modules, it will exit
+with 0 and produce no output. Otherwise it will exit with a non-zero
+value.</p>
+</div>
+<div class="section" id="bugs">
+<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2>
+<p>Many important differences, like changes in linkage or function
+attributes, are not diagnosed.</p>
+<p>Changes in memory behavior (for example, coalescing loads) can cause
+massive detected differences in blocks.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-cov.html" title="llvm-cov - emit coverage information"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-config.html" title="llvm-config - Print LLVM compilation options"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dis.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dis.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dis.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,143 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-dis - LLVM disassembler — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="opt - LLVM optimizer" href="opt.html" />
+ <link rel="prev" title="llvm-as - LLVM assembler" href="llvm-as.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="opt.html" title="opt - LLVM optimizer"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-as.html" title="llvm-as - LLVM assembler"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-dis-llvm-disassembler">
+<h1>llvm-dis - LLVM disassembler<a class="headerlink" href="#llvm-dis-llvm-disassembler" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-dis</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong>llvm-dis</strong> command is the LLVM disassembler. It takes an LLVM
+bitcode file and converts it into human-readable LLVM assembly language.</p>
+<p>If filename is omitted or specified as <tt class="docutils literal"><span class="pre">-</span></tt>, <strong>llvm-dis</strong> reads its
+input from standard input.</p>
+<p>If the input is being read from standard input, then <strong>llvm-dis</strong>
+will send its output to standard output by default. Otherwise, the
+output will be written to a file named after the input file, with
+a <tt class="docutils literal"><span class="pre">.ll</span></tt> suffix added (any existing <tt class="docutils literal"><span class="pre">.bc</span></tt> suffix will first be
+removed). You can override the choice of output file using the
+<strong>-o</strong> option.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>-f</strong></p>
+<blockquote>
+<div>Enable binary output on terminals. Normally, <strong>llvm-dis</strong> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+<strong>llvm-dis</strong> will write raw bitcode regardless of the output device.</div></blockquote>
+<p><strong>-help</strong></p>
+<blockquote>
+<div>Print a summary of command line options.</div></blockquote>
+<p><strong>-o</strong> <em>filename</em></p>
+<blockquote>
+<div>Specify the output file name. If <em>filename</em> is -, then the output is sent
+to standard output.</div></blockquote>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong>llvm-dis</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>llvm-as|llvm-as</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="opt.html" title="opt - LLVM optimizer"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-as.html" title="llvm-as - LLVM assembler"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dwarfdump.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dwarfdump.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dwarfdump.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-dwarfdump.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,278 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-dwarfdump - dump and verify DWARF debug information — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="dsymutil - manipulate archived DWARF debug symbol files" href="dsymutil.html" />
+ <link rel="prev" title="llvm-symbolizer - convert addresses into source code locations" href="llvm-symbolizer.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol files"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-dwarfdump-dump-and-verify-dwarf-debug-information">
+<h1>llvm-dwarfdump - dump and verify DWARF debug information<a class="headerlink" href="#llvm-dwarfdump-dump-and-verify-dwarf-debug-information" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-dwarfdump</strong> [<em>options</em>] [<em>filename ...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-dwarfdump</strong> parses DWARF sections in object files,
+archives, and <cite>.dSYM</cite> bundles and prints their contents in
+human-readable form. Only the .debug_info section is printed unless one of
+the section-specific options or <em class="xref std std-option">--all</em> is specified.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-a">
+<tt class="descname">-a</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--all</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-a" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disassemble all supported DWARF sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--arch">
+<tt class="descname">--arch</tt><tt class="descclassname">=<arch></tt><a class="headerlink" href="#cmdoption--arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump DWARF debug information for the specified CPU architecture.
+Architectures may be specified by name or by number. This
+option can be specified multiple times, once for each desired
+architecture. All CPU architectures will be printed by
+default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-c">
+<tt class="descname">-c</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--show-children</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-c" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show a debug info entry’s children when using
+the <em class="xref std std-option">--debug-info</em>, <em class="xref std std-option">--find</em>,
+and <em class="xref std std-option">--name</em> options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-f">
+<tt class="descname">-f</tt><tt class="descclassname"> <name></tt><tt class="descclassname">, </tt><tt class="descname">--find</tt><tt class="descclassname">=<name></tt><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Search for the exact text <name> in the accelerator tables
+and print the matching debug information entries.
+When there is no accelerator tables or the name of the DIE
+you are looking for is not found in the accelerator tables,
+try using the slower but more complete <em class="xref std std-option">--name</em> option.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-F">
+<tt class="descname">-F</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--show-form</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-F" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show DWARF form types after the DWARF attribute types.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-h">
+<tt class="descname">-h</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-h" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show help and usage for this command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-i">
+<tt class="descname">-i</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--ignore-case</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-i" title="Permalink to this definition">¶</a></dt>
+<dd><p>Ignore case distinctions in when searching entries by name
+or by regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-n">
+<tt class="descname">-n</tt><tt class="descclassname"> <pattern></tt><tt class="descclassname">, </tt><tt class="descname">--name</tt><tt class="descclassname">=<pattern></tt><a class="headerlink" href="#cmdoption-n" title="Permalink to this definition">¶</a></dt>
+<dd><p>Find and print all debug info entries whose name
+(<cite>DW_AT_name</cite> attribute) matches the exact text in
+<pattern>. Use the <em class="xref std std-option">--regex</em> option to have
+<pattern> become a regular expression for more flexible
+pattern matching.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--lookup">
+<tt class="descname">--lookup</tt><tt class="descclassname">=<address></tt><a class="headerlink" href="#cmdoption--lookup" title="Permalink to this definition">¶</a></dt>
+<dd><p>Lookup <address> in the debug information and print out the file,
+function, block, and line table details.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> <path></tt><tt class="descclassname">, </tt><tt class="descname">--out-file</tt><tt class="descclassname">=<path></tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Redirect output to a file specified by <path>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-p">
+<tt class="descname">-p</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--show-parents</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show a debug info entry’s parent objects when using the
+<em class="xref std std-option">--debug-info</em>, <em class="xref std std-option">--find</em>, and
+<em class="xref std std-option">--name</em> options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-r">
+<tt class="descname">-r</tt><tt class="descclassname"> <n></tt><tt class="descclassname">, </tt><tt class="descname">--recurse-depth</tt><tt class="descclassname">=<n></tt><a class="headerlink" href="#cmdoption-r" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only recurse to a maximum depth of <n> when dumping debug info
+entries.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--statistics">
+<tt class="descname">--statistics</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--statistics" title="Permalink to this definition">¶</a></dt>
+<dd><p>Collect debug info quality metrics and print the results
+as machine-readable single-line JSON output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-x">
+<tt class="descname">-x</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--regex</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-x" title="Permalink to this definition">¶</a></dt>
+<dd><p>Treat any <pattern> strings as regular expressions when searching
+instead of just as an exact string match.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-u">
+<tt class="descname">-u</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--uuid</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-u" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the UUID for each architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--diff">
+<tt class="descname">--diff</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--diff" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the output in a format that is more friendly for comparing
+DWARF output from two different files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-v">
+<tt class="descname">-v</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--verbose</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display verbose information when dumping. This can help to debug
+DWARF issues.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--verify">
+<tt class="descname">--verify</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--verify" title="Permalink to this definition">¶</a></dt>
+<dd><p>Verify the structure of the DWARF information by verifying the
+compile unit chains, DIE relationships graph, address
+ranges, and more.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--version">
+<tt class="descname">--version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of the tool.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--debug-abbrev">
+<tt class="descname">--debug-abbrev</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-aranges</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-cu-index</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-frame</tt><tt class="descclassname"> [=<offset>]</tt><tt class="descclassname">, </tt><tt class="descname">--debug-gnu-pubnames</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-gnu-pubtypes</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-info</tt><tt class="descclassname"> [=<offset>]</tt><tt class="descclassname">, </tt><tt class="descname">--debug-line</tt><tt class="descclassname"> [=<offset>]</tt><tt class="descclassname">, </tt><tt class="descname">--debug-loc</tt><tt class="descclassname"> [=<offset>]</tt><tt class="descclassname">, </tt><tt class="descname">--debug-macro</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-pubnames</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-pubtypes</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-ranges</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-str</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-str-offsets</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-tu-index</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--debug-types</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--eh-frame</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--gdb-index</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--apple-names</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--apple-types</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--apple-namespaces</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">--apple-objc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--debug-abbrev" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the specified DWARF section by name. Only the
+<cite>.debug_info</cite> section is shown by default. Some entries
+support adding an <cite>=<offset></cite> as a way to provide an
+optional offset of the exact entry to dump within the
+respective section. When an offset is provided, only the
+entry at that offset will be dumped, else the entire
+section will be dumped. Children of items at a specific
+offset can be dumped by also using the
+<em class="xref std std-option">--show-children</em> option where applicable.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-dwarfdump</strong> returns 0 if the input files were parsed and dumped
+successfully. Otherwise, it returns 1.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage">dsymutil(1)</em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol files"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-extract.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-extract.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-extract.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-extract.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,164 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-extract - extract a function from an LLVM module — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-bcanalyzer - LLVM bitcode analyzer" href="llvm-bcanalyzer.html" />
+ <link rel="prev" title="bugpoint - automatic test case reduction tool" href="bugpoint.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction tool"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-extract-extract-a-function-from-an-llvm-module">
+<h1>llvm-extract - extract a function from an LLVM module<a class="headerlink" href="#llvm-extract-extract-a-function-from-an-llvm-module" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-extract</strong> [<em>options</em>] <strong>–func</strong> <em>function-name</em> [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-extract</strong> command takes the name of a function and extracts
+it from the specified LLVM bitcode file. It is primarily used as a debugging
+tool to reduce test cases from larger programs that are triggering a bug.</p>
+<p>In addition to extracting the bitcode of the specified function,
+<strong class="program">llvm-extract</strong> will also remove unreachable global variables,
+prototypes, and unused types.</p>
+<p>The <strong class="program">llvm-extract</strong> command reads its input from standard input if
+filename is omitted or if filename is <tt class="docutils literal"><span class="pre">-</span></tt>. The output is always written to
+standard output, unless the <strong>-o</strong> option is specified (see below).</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>-f</strong></p>
+<blockquote>
+<div>Enable binary output on terminals. Normally, <strong class="program">llvm-extract</strong> will
+refuse to write raw bitcode output if the output stream is a terminal. With
+this option, <strong class="program">llvm-extract</strong> will write raw bitcode regardless of the
+output device.</div></blockquote>
+<p><strong>–func</strong> <em>function-name</em></p>
+<blockquote>
+<div>Extract the function named <em>function-name</em> from the LLVM bitcode. May be
+specified multiple times to extract multiple functions at once.</div></blockquote>
+<p><strong>–rfunc</strong> <em>function-regular-expr</em></p>
+<blockquote>
+<div>Extract the function(s) matching <em>function-regular-expr</em> from the LLVM bitcode.
+All functions matching the regular expression will be extracted. May be
+specified multiple times.</div></blockquote>
+<p><strong>–glob</strong> <em>global-name</em></p>
+<blockquote>
+<div>Extract the global variable named <em>global-name</em> from the LLVM bitcode. May be
+specified multiple times to extract multiple global variables at once.</div></blockquote>
+<p><strong>–rglob</strong> <em>glob-regular-expr</em></p>
+<blockquote>
+<div>Extract the global variable(s) matching <em>global-regular-expr</em> from the LLVM
+bitcode. All global variables matching the regular expression will be
+extracted. May be specified multiple times.</div></blockquote>
+<p><strong>-help</strong></p>
+<blockquote>
+<div>Print a summary of command line options.</div></blockquote>
+<p><strong>-o</strong> <em>filename</em></p>
+<blockquote>
+<div>Specify the output filename. If filename is “-” (the default), then
+<strong class="program">llvm-extract</strong> sends its output to standard output.</div></blockquote>
+<p><strong>-S</strong></p>
+<blockquote>
+<div>Write output in LLVM intermediate language (instead of bitcode).</div></blockquote>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">llvm-extract</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>bugpoint</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction tool"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-lib.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-lib.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-lib.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-lib.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,124 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-lib - LLVM lib.exe compatible library tool — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-nm - list LLVM bitcode and object fileâs symbol table" href="llvm-nm.html" />
+ <link rel="prev" title="llvm-ar - LLVM archiver" href="llvm-ar.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-ar.html" title="llvm-ar - LLVM archiver"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-lib-llvm-lib-exe-compatible-library-tool">
+<h1>llvm-lib - LLVM lib.exe compatible library tool<a class="headerlink" href="#llvm-lib-llvm-lib-exe-compatible-library-tool" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-lib</strong> [/libpath:<path>] [/out:<output>] [/llvmlibthin]
+[/ignore] [/machine] [/nologo] [files...]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong>llvm-lib</strong> command is intended to be a <tt class="docutils literal"><span class="pre">lib.exe</span></tt> compatible
+tool. See <a class="reference external" href="https://msdn.microsoft.com/en-us/library/7ykb2k5f">https://msdn.microsoft.com/en-us/library/7ykb2k5f</a> for the
+general description.</p>
+<p><strong>llvm-lib</strong> has the following extensions:</p>
+<ul class="simple">
+<li>Bitcode files in symbol tables.
+<strong>llvm-lib</strong> includes symbols from both bitcode files and regular
+object files in the symbol table.</li>
+<li>Creating thin archives.
+The /llvmlibthin option causes <strong>llvm-lib</strong> to create thin archive
+that contain only the symbol table and the header for the various
+members. These files are much smaller, but are not compatible with
+link.exe (lld can handle them).</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-ar.html" title="llvm-ar - LLVM archiver"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-link.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-link.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-link.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-link.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,163 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-link - LLVM bitcode linker — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-ar - LLVM archiver" href="llvm-ar.html" />
+ <link rel="prev" title="lli - directly execute programs from LLVM bitcode" href="lli.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-ar.html" title="llvm-ar - LLVM archiver"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="lli.html" title="lli - directly execute programs from LLVM bitcode"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-link-llvm-bitcode-linker">
+<h1>llvm-link - LLVM bitcode linker<a class="headerlink" href="#llvm-link-llvm-bitcode-linker" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-link</strong> [<em>options</em>] <em>filename ...</em></p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-link</strong> takes several LLVM bitcode files and links them together
+into a single LLVM bitcode file. It writes the output file to standard output,
+unless the <a class="reference internal" href="opt.html#cmdoption-o"><em class="xref std std-option">-o</em></a> option is used to specify a filename.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-f">
+<tt class="descname">-f</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable binary output on terminals. Normally, <strong class="program">llvm-link</strong> will refuse
+to write raw bitcode output if the output stream is a terminal. With this
+option, <strong class="program">llvm-link</strong> will write raw bitcode regardless of the output
+device.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> filename</tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. If <tt class="docutils literal"><span class="pre">filename</span></tt> is “<tt class="docutils literal"><span class="pre">-</span></tt>”, then
+<strong class="program">llvm-link</strong> will write its output to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-S">
+<tt class="descname">-S</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-S" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write output in LLVM intermediate language (instead of bitcode).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-d">
+<tt class="descname">-d</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-d" title="Permalink to this definition">¶</a></dt>
+<dd><p>If specified, <strong class="program">llvm-link</strong> prints a human-readable version of the
+output bitcode file to standard error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-v">
+<tt class="descname">-v</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt>
+<dd><p>Verbose mode. Print information about what <strong class="program">llvm-link</strong> is doing.
+This typically includes a message for each bitcode file linked in and for each
+library found.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">llvm-link</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-ar.html" title="llvm-ar - LLVM archiver"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="lli.html" title="lli - directly execute programs from LLVM bitcode"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-nm.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-nm.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-nm.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-nm.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,264 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-nm - list LLVM bitcode and object fileâs symbol table — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-config - Print LLVM compilation options" href="llvm-config.html" />
+ <link rel="prev" title="llvm-lib - LLVM lib.exe compatible library tool" href="llvm-lib.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-config.html" title="llvm-config - Print LLVM compilation options"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-lib.html" title="llvm-lib - LLVM lib.exe compatible library tool"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-nm-list-llvm-bitcode-and-object-file-s-symbol-table">
+<h1>llvm-nm - list LLVM bitcode and object file’s symbol table<a class="headerlink" href="#llvm-nm-list-llvm-bitcode-and-object-file-s-symbol-table" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-nm</strong> [<em>options</em>] [<em>filenames...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-nm</strong> utility lists the names of symbols from the LLVM bitcode
+files, object files, or <strong class="program">ar</strong> archives containing them, named on the
+command line. Each symbol is listed along with some simple information about
+its provenance. If no file name is specified, or <em>-</em> is used as a file name,
+<strong class="program">llvm-nm</strong> will process a file on its standard input stream.</p>
+<p><strong class="program">llvm-nm</strong>‘s default output format is the traditional BSD <strong class="program">nm</strong>
+output format. Each such output record consists of an (optional) 8-digit
+hexadecimal address, followed by a type code character, followed by a name, for
+each symbol. One record is printed per line; fields are separated by spaces.
+When the address is omitted, it is replaced by 8 spaces.</p>
+<p>Type code characters currently supported, and their meanings, are as follows:</p>
+<p>U</p>
+<blockquote>
+<div>Named object is referenced but undefined in this bitcode file</div></blockquote>
+<p>C</p>
+<blockquote>
+<div>Common (multiple definitions link together into one def)</div></blockquote>
+<p>W</p>
+<blockquote>
+<div>Weak reference (multiple definitions link together into zero or one definitions)</div></blockquote>
+<p>t</p>
+<blockquote>
+<div>Local function (text) object</div></blockquote>
+<p>T</p>
+<blockquote>
+<div>Global function (text) object</div></blockquote>
+<p>d</p>
+<blockquote>
+<div>Local data object</div></blockquote>
+<p>D</p>
+<blockquote>
+<div>Global data object</div></blockquote>
+<p>?</p>
+<blockquote>
+<div>Something unrecognizable</div></blockquote>
+<p>Because LLVM bitcode files typically contain objects that are not considered to
+have addresses until they are linked into an executable image or dynamically
+compiled “just-in-time”, <strong class="program">llvm-nm</strong> does not print an address for any
+symbol in an LLVM bitcode file, even symbols which are defined in the bitcode
+file.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-llvm-nm-B">
+<tt class="descname">-B</tt><tt class="descclassname"> (default)</tt><a class="headerlink" href="#cmdoption-llvm-nm-B" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use BSD output format. Alias for <cite>–format=bsd</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-P">
+<tt class="descname">-P</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm-P" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use POSIX.2 output format. Alias for <cite>–format=posix</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--debug-syms">
+<tt class="descname">--debug-syms</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-a</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--debug-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show all symbols, even debugger only.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--defined-only">
+<tt class="descname">--defined-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--defined-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print only symbols defined in this file (as opposed to
+symbols which may be referenced by objects in this file, but not
+defined in this file.)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--dynamic">
+<tt class="descname">--dynamic</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-D</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--dynamic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display dynamic symbols instead of normal symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--extern-only">
+<tt class="descname">--extern-only</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-g</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--extern-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print only symbols whose definitions are external; that is, accessible
+from other files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--format">
+<tt class="descname">--format</tt><tt class="descclassname">=format</tt><tt class="descclassname">, </tt><tt class="descname">-f</tt><tt class="descclassname"> format</tt><a class="headerlink" href="#cmdoption-llvm-nm--format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select an output format; <em>format</em> may be <em>sysv</em>, <em>posix</em>, or <em>bsd</em>. The default
+is <em>bsd</em>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command-line options and their meanings.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--no-sort">
+<tt class="descname">--no-sort</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-p</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--no-sort" title="Permalink to this definition">¶</a></dt>
+<dd><p>Shows symbols in order encountered.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--numeric-sort">
+<tt class="descname">--numeric-sort</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-n</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-v</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--numeric-sort" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sort symbols by address.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--print-file-name">
+<tt class="descname">--print-file-name</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-A</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-o</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--print-file-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Precede each symbol with the file it came from.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--print-size">
+<tt class="descname">--print-size</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-S</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--print-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show symbol size instead of address.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--size-sort">
+<tt class="descname">--size-sort</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--size-sort" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sort symbols by size.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--undefined-only">
+<tt class="descname">--undefined-only</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-u</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--undefined-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print only symbols referenced but not defined in this file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm--radix">
+<tt class="descname">--radix</tt><tt class="descclassname">=RADIX</tt><tt class="descclassname">, </tt><tt class="descname">-t</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-nm--radix" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the radix of the symbol address(es). Values accepted d(decimal),
+x(hexadecomal) and o(octal).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="bugs">
+<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2>
+<blockquote>
+<div><ul class="simple">
+<li><strong class="program">llvm-nm</strong> does not support the full set of arguments that GNU
+<strong class="program">nm</strong> does.</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-nm</strong> exits with an exit code of zero.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>llvm-dis, ar(1), nm(1)</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-config.html" title="llvm-config - Print LLVM compilation options"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-lib.html" title="llvm-lib - LLVM lib.exe compatible library tool"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-pdbutil.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-pdbutil.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-pdbutil.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-pdbutil.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,861 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-pdbutil - PDB File forensics and diagnostics — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-readobj - LLVM Object Reader" href="llvm-readobj.html" />
+ <link rel="prev" title="llvm-build - LLVM Project Build Utility" href="llvm-build.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-build.html" title="llvm-build - LLVM Project Build Utility"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-pdbutil-pdb-file-forensics-and-diagnostics">
+<h1>llvm-pdbutil - PDB File forensics and diagnostics<a class="headerlink" href="#llvm-pdbutil-pdb-file-forensics-and-diagnostics" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#synopsis" id="id12">Synopsis</a></li>
+<li><a class="reference internal" href="#description" id="id13">Description</a></li>
+<li><a class="reference internal" href="#subcommands" id="id14">Subcommands</a><ul>
+<li><a class="reference internal" href="#pretty" id="id15">pretty</a><ul>
+<li><a class="reference internal" href="#summary" id="id16">Summary</a></li>
+<li><a class="reference internal" href="#options" id="id17">Options</a><ul>
+<li><a class="reference internal" href="#filtering-and-sorting-options" id="id18">Filtering and Sorting Options</a></li>
+<li><a class="reference internal" href="#symbol-type-options" id="id19">Symbol Type Options</a></li>
+<li><a class="reference internal" href="#other-options" id="id20">Other Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dump" id="id21">dump</a><ul>
+<li><a class="reference internal" href="#id1" id="id22">Summary</a></li>
+<li><a class="reference internal" href="#id2" id="id23">Options</a><ul>
+<li><a class="reference internal" href="#msf-container-options" id="id24">MSF Container Options</a></li>
+<li><a class="reference internal" href="#module-file-options" id="id25">Module & File Options</a></li>
+<li><a class="reference internal" href="#symbol-options" id="id26">Symbol Options</a></li>
+<li><a class="reference internal" href="#type-record-options" id="id27">Type Record Options</a></li>
+<li><a class="reference internal" href="#miscellaneous-options" id="id28">Miscellaneous Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#bytes" id="id29">bytes</a><ul>
+<li><a class="reference internal" href="#id3" id="id30">Summary</a></li>
+<li><a class="reference internal" href="#id4" id="id31">Options</a><ul>
+<li><a class="reference internal" href="#msf-file-options" id="id32">MSF File Options</a></li>
+<li><a class="reference internal" href="#pdb-stream-options" id="id33">PDB Stream Options</a></li>
+<li><a class="reference internal" href="#dbi-stream-options" id="id34">DBI Stream Options</a></li>
+<li><a class="reference internal" href="#module-options" id="id35">Module Options</a></li>
+<li><a class="reference internal" href="#id5" id="id36">Type Record Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pdb2yaml" id="id37">pdb2yaml</a><ul>
+<li><a class="reference internal" href="#id6" id="id38">Summary</a></li>
+<li><a class="reference internal" href="#id7" id="id39">Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#yaml2pdb" id="id40">yaml2pdb</a><ul>
+<li><a class="reference internal" href="#id8" id="id41">Summary</a></li>
+<li><a class="reference internal" href="#id9" id="id42">Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#merge" id="id43">merge</a><ul>
+<li><a class="reference internal" href="#id10" id="id44">Summary</a></li>
+<li><a class="reference internal" href="#id11" id="id45">Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="synopsis">
+<h2><a class="toc-backref" href="#id12">Synopsis</a><a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-pdbutil</strong> [<em>subcommand</em>] [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<h2><a class="toc-backref" href="#id13">Description</a><a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>Display types, symbols, CodeView records, and other information from a
+PDB file, as well as manipulate and create PDB files. <strong class="program">llvm-pdbutil</strong>
+is normally used by FileCheck-based tests to test LLVM’s PDB reading and
+writing functionality, but can also be used for general PDB file investigation
+and forensics, or as a replacement for cvdump.</p>
+</div>
+<div class="section" id="subcommands">
+<h2><a class="toc-backref" href="#id14">Subcommands</a><a class="headerlink" href="#subcommands" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-pdbutil</strong> is separated into several subcommands each tailored to
+a different purpose. A brief summary of each command follows, with more detail
+in the sections that follow.</p>
+<blockquote>
+<div><ul class="simple">
+<li><a class="reference internal" href="#pretty-subcommand"><em>pretty</em></a> - Dump symbol and type information in a format that
+tries to look as much like the original source code as possible.</li>
+<li><a class="reference internal" href="#dump-subcommand"><em>dump</em></a> - Dump low level types and structures from the PDB
+file, including CodeView records, hash tables, PDB streams, etc.</li>
+<li><a class="reference internal" href="#bytes-subcommand"><em>bytes</em></a> - Dump data from the PDB file’s streams, records,
+types, symbols, etc as raw bytes.</li>
+<li><a class="reference internal" href="#yaml2pdb-subcommand"><em>yaml2pdb</em></a> - Given a yaml description of a PDB file, produce
+a valid PDB file that matches that description.</li>
+<li><a class="reference internal" href="#pdb2yaml-subcommand"><em>pdb2yaml</em></a> - For a given PDB file, produce a YAML
+description of some or all of the file in a way that the PDB can be
+reconstructed.</li>
+<li><a class="reference internal" href="#merge-subcommand"><em>merge</em></a> - Given two PDBs, produce a third PDB that is the
+result of merging the two input PDBs.</li>
+</ul>
+</div></blockquote>
+<div class="section" id="pretty">
+<span id="pretty-subcommand"></span><h3><a class="toc-backref" href="#id15">pretty</a><a class="headerlink" href="#pretty" title="Permalink to this headline">¶</a></h3>
+<div class="admonition important">
+<p class="first admonition-title">Important</p>
+<p class="last">The <strong>pretty</strong> subcommand is built on the Windows DIA SDK, and as such is not
+supported on non-Windows platforms.</p>
+</div>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> pretty [<em>options</em>] <input PDB file></p>
+<div class="section" id="summary">
+<h4><a class="toc-backref" href="#id16">Summary</a><a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h4>
+<p>The <em>pretty</em> subcommand displays a very high level representation of your
+program’s debug info. Since it is built on the Windows DIA SDK which is the
+standard API that Windows tools and debuggers query debug information, it
+presents a more authoritative view of how a debugger is going to interpret your
+debug information than a mode which displays low-level CodeView records.</p>
+</div>
+<div class="section" id="options">
+<h4><a class="toc-backref" href="#id17">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="filtering-and-sorting-options">
+<h5><a class="toc-backref" href="#id18">Filtering and Sorting Options</a><a class="headerlink" href="#filtering-and-sorting-options" title="Permalink to this headline">¶</a></h5>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last"><em>exclude</em> filters take priority over <em>include</em> filters. So if a filter
+matches both an include and an exclude rule, then it is excluded.</p>
+</div>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-exclude-compilands">
+<tt class="descname">-exclude-compilands</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-exclude-compilands" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping compilands, compiland source-file contributions, or per-compiland
+symbols, this option instructs <strong>llvm-pdbutil</strong> to omit any compilands that
+match the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-exclude-symbols">
+<tt class="descname">-exclude-symbols</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-exclude-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping global, public, or per-compiland symbols, this option instructs
+<strong>llvm-pdbutil</strong> to omit any symbols that match the specified regular
+expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-exclude-types">
+<tt class="descname">-exclude-types</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-exclude-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping types, this option instructs <strong>llvm-pdbutil</strong> to omit any types
+that match the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-include-compilands">
+<tt class="descname">-include-compilands</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-include-compilands" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping compilands, compiland source-file contributions, or per-compiland
+symbols, limit the initial search to only those compilands that match the
+specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-include-symbols">
+<tt class="descname">-include-symbols</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-include-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping global, public, or per-compiland symbols, limit the initial
+search to only those symbols that match the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-include-types">
+<tt class="descname">-include-types</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-include-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping types, limit the initial search to only those types that match
+the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-min-class-padding">
+<tt class="descname">-min-class-padding</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-min-class-padding" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only display types that have at least the specified amount of alignment
+padding, accounting for padding in base classes and aggregate field members.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-min-class-padding-imm">
+<tt class="descname">-min-class-padding-imm</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-min-class-padding-imm" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only display types that have at least the specified amount of alignment
+padding, ignoring padding in base classes and aggregate field members.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-min-type-size">
+<tt class="descname">-min-type-size</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-min-type-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only display types T where sizeof(T) is greater than or equal to the specified
+amount.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-no-compiler-generated">
+<tt class="descname">-no-compiler-generated</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-no-compiler-generated" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t show compiler generated types and symbols</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-no-enum-definitions">
+<tt class="descname">-no-enum-definitions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-no-enum-definitions" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping an enum, don’t show the full enum (e.g. the individual enumerator
+values).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-no-system-libs">
+<tt class="descname">-no-system-libs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-no-system-libs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t show symbols from system libraries</p>
+</dd></dl>
+
+</div>
+<div class="section" id="symbol-type-options">
+<h5><a class="toc-backref" href="#id19">Symbol Type Options</a><a class="headerlink" href="#symbol-type-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-all">
+<tt class="descname">-all</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Implies all other options in this category.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-class-definitions">
+<tt class="descname">-class-definitions</tt><tt class="descclassname">=<format></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-class-definitions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Displays class definitions in the specified format.</p>
+<div class="highlight-text"><div class="highlight"><pre>=all - Display all class members including data, constants, typedefs, functions, etc (default)
+=layout - Only display members that contribute to class size.
+=none - Don't display class definitions (e.g. only display the name and base list)
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-class-order">
+<tt class="descname">-class-order</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-class-order" title="Permalink to this definition">¶</a></dt>
+<dd><p>Displays classes in the specified order.</p>
+<div class="highlight-text"><div class="highlight"><pre>=none - Undefined / no particular sort order (default)
+=name - Sort classes by name
+=size - Sort classes by size
+=padding - Sort classes by amount of padding
+=padding-pct - Sort classes by percentage of space consumed by padding
+=padding-imm - Sort classes by amount of immediate padding
+=padding-pct-imm - Sort classes by percentage of space consumed by immediate padding
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-class-recurse-depth">
+<tt class="descname">-class-recurse-depth</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-class-recurse-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping class definitions, stop after recursing the specified number of times. The
+default is 0, which is no limit.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-classes">
+<tt class="descname">-classes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-classes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display classes</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-compilands">
+<tt class="descname">-compilands</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-compilands" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display compilands (e.g. object files)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-enums">
+<tt class="descname">-enums</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-enums" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display enums</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-externals">
+<tt class="descname">-externals</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-externals" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump external (e.g. exported) symbols</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-globals">
+<tt class="descname">-globals</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-globals" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump global symbols</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-lines">
+<tt class="descname">-lines</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-lines" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the mappings between source lines and code addresses.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-module-syms">
+<tt class="descname">-module-syms</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-module-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display symbols (variables, functions, etc) for each compiland</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-sym-types">
+<tt class="descname">-sym-types</tt><tt class="descclassname">=<types></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-sym-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>Type of symbols to dump when -globals, -externals, or -module-syms is
+specified. (default all)</p>
+<div class="highlight-text"><div class="highlight"><pre>=thunks - Display thunk symbols
+=data - Display data symbols
+=funcs - Display function symbols
+=all - Display all symbols (default)
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-symbol-order">
+<tt class="descname">-symbol-order</tt><tt class="descclassname">=<order></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-symbol-order" title="Permalink to this definition">¶</a></dt>
+<dd><p>For symbols dumped via the -module-syms, -globals, or -externals options, sort
+the results in specified order.</p>
+<div class="highlight-text"><div class="highlight"><pre>=none - Undefined / no particular sort order
+=name - Sort symbols by name
+=size - Sort symbols by size
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-typedefs">
+<tt class="descname">-typedefs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-typedefs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display typedef types</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-types">
+<tt class="descname">-types</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all types (implies -classes, -enums, -typedefs)</p>
+</dd></dl>
+
+</div>
+<div class="section" id="other-options">
+<h5><a class="toc-backref" href="#id20">Other Options</a><a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-color-output">
+<tt class="descname">-color-output</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-color-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Force color output on or off. By default, color if used if outputting to a
+terminal.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-load-address">
+<tt class="descname">-load-address</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-load-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>When displaying relative virtual addresses, assume the process is loaded at the
+given address and display what would be the absolute address.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+<div class="section" id="dump">
+<span id="dump-subcommand"></span><h3><a class="toc-backref" href="#id21">dump</a><a class="headerlink" href="#dump" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> dump [<em>options</em>] <input PDB file></p>
+<div class="section" id="id1">
+<h4><a class="toc-backref" href="#id22">Summary</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>The <strong>dump</strong> subcommand displays low level information about the structure of a
+PDB file. It is used heavily by LLVM’s testing infrastructure, but can also be
+used for PDB forensics. It serves a role similar to that of Microsoft’s
+<cite>cvdump</cite> tool.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The <strong>dump</strong> subcommand exposes internal details of the file format. As
+such, the reader should be familiar with <a class="reference internal" href="../PDB/index.html"><em>The PDB File Format</em></a> before using this
+command.</p>
+</div>
+</div>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id23">Options</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="msf-container-options">
+<h5><a class="toc-backref" href="#id24">MSF Container Options</a><a class="headerlink" href="#msf-container-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-streams">
+<tt class="descname">-streams</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-streams" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump a summary of all of the streams in the PDB file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-stream-blocks">
+<tt class="descname">-stream-blocks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-stream-blocks" title="Permalink to this definition">¶</a></dt>
+<dd><p>In conjunction with <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-streams"><em class="xref std std-option">-streams</em></a>, add information to the output about
+what blocks the specified stream occupies.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-summary">
+<tt class="descname">-summary</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-summary" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump MSF and PDB header information.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="module-file-options">
+<h5><a class="toc-backref" href="#id25">Module & File Options</a><a class="headerlink" href="#module-file-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-modi">
+<tt class="descname">-modi</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-modi" title="Permalink to this definition">¶</a></dt>
+<dd><p>For all options that dump information from each module/compiland, limit to
+the specified module.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-files">
+<tt class="descname">-files</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the source files that contribute to each displayed module.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-il">
+<tt class="descname">-il</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-il" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-l">
+<tt class="descname">-l</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-l" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump line information (DEBUG_S_LINES CodeView subsection)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-modules">
+<tt class="descname">-modules</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-modules" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump compiland information</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-xme">
+<tt class="descname">-xme</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-xme" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-xmi">
+<tt class="descname">-xmi</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-xmi" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)</p>
+</dd></dl>
+
+</div>
+<div class="section" id="symbol-options">
+<h5><a class="toc-backref" href="#id26">Symbol Options</a><a class="headerlink" href="#symbol-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-globals">
+<tt class="descname">-globals</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-globals" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump global symbol records</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-global-extras">
+<tt class="descname">-global-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-global-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump additional information about the globals, such as hash buckets and hash
+values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-publics">
+<tt class="descname">-publics</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-publics" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump public symbol records</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-public-extras">
+<tt class="descname">-public-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-public-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump additional information about the publics, such as hash buckets and hash
+values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-symbols">
+<tt class="descname">-symbols</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump symbols (functions, variables, etc) for each module dumped.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-sym-data">
+<tt class="descname">-sym-data</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-sym-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>For each symbol record dumped as a result of the <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-symbols"><em class="xref std std-option">-symbols</em></a> option,
+display the full bytes of the record in binary as well.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="type-record-options">
+<h5><a class="toc-backref" href="#id27">Type Record Options</a><a class="headerlink" href="#type-record-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-types">
+<tt class="descname">-types</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump CodeView type records from TPI stream</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-type-extras">
+<tt class="descname">-type-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-type-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump additional information from the TPI stream, such as hashes and the type
+index offsets array.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-type-data">
+<tt class="descname">-type-data</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-type-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>For each type record dumped, display the full bytes of the record in binary as
+well.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-type-index">
+<tt class="descname">-type-index</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-type-index" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only dump types with the specified type index.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-ids">
+<tt class="descname">-ids</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-ids" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump CodeView type records from IPI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-id-extras">
+<tt class="descname">-id-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-id-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump additional information from the IPI stream, such as hashes and the type
+index offsets array.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-id-data">
+<tt class="descname">-id-data</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-id-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>For each ID record dumped, display the full bytes of the record in binary as
+well.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-id-index">
+<tt class="descname">-id-index</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-id-index" title="Permalink to this definition">¶</a></dt>
+<dd><p>only dump ID records with the specified hexadecimal type index.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-dependents">
+<tt class="descname">-dependents</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-dependents" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used in conjunction with <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-type-index"><em class="xref std std-option">-type-index</em></a> or <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-id-index"><em class="xref std std-option">-id-index</em></a>,
+dumps the entire dependency graph for the specified index instead of just the
+single record with the specified index. For example, if type index 0x4000 is
+a function whose return type has index 0x3000, and you specify
+<cite>-dependents=0x4000</cite>, then this would dump both records (as well as any other
+dependents in the tree).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="miscellaneous-options">
+<h5><a class="toc-backref" href="#id28">Miscellaneous Options</a><a class="headerlink" href="#miscellaneous-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-all">
+<tt class="descname">-all</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Implies most other options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-section-contribs">
+<tt class="descname">-section-contribs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-section-contribs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump section contributions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-section-headers">
+<tt class="descname">-section-headers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-section-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump image section headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-section-map">
+<tt class="descname">-section-map</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-section-map" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump section map.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-string-table">
+<tt class="descname">-string-table</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-string-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump PDB string table.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+<div class="section" id="bytes">
+<span id="bytes-subcommand"></span><h3><a class="toc-backref" href="#id29">bytes</a><a class="headerlink" href="#bytes" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> bytes [<em>options</em>] <input PDB file></p>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id30">Summary</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>Like the <strong>dump</strong> subcommand, the <strong>bytes</strong> subcommand displays low level
+information about the structure of a PDB file, but it is used for even deeper
+forensics. The <strong>bytes</strong> subcommand finds various structures in a PDB file
+based on the command line options specified, and dumps them in hex. Someone
+working on support for emitting PDBs would use this heavily, for example, to
+compare one PDB against another PDB to ensure byte-for-byte compatibility. It
+is not enough to simply compare the bytes of an entire file, or an entire stream
+because it’s perfectly fine for the same structure to exist at different
+locations in two different PDBs, and “finding” the structure is half the battle.</p>
+</div>
+<div class="section" id="id4">
+<h4><a class="toc-backref" href="#id31">Options</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="msf-file-options">
+<h5><a class="toc-backref" href="#id32">MSF File Options</a><a class="headerlink" href="#msf-file-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-block-range">
+<tt class="descname">-block-range</tt><tt class="descclassname">=<start[-end]></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-block-range" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump binary data from specified range of MSF file blocks.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-byte-range">
+<tt class="descname">-byte-range</tt><tt class="descclassname">=<start[-end]></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-byte-range" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump binary data from specified range of bytes in the file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-fpm">
+<tt class="descname">-fpm</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-fpm" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the MSF free page map.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-stream-data">
+<tt class="descname">-stream-data</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-stream-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump binary data from the specified streams. Format is SN[:Start][@Size].
+For example, <cite>-stream-data=7:3@12</cite> dumps 12 bytes from stream 7, starting
+at offset 3 in the stream.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="pdb-stream-options">
+<h5><a class="toc-backref" href="#id33">PDB Stream Options</a><a class="headerlink" href="#pdb-stream-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-name-map">
+<tt class="descname">-name-map</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-name-map" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump bytes of PDB Name Map</p>
+</dd></dl>
+
+</div>
+<div class="section" id="dbi-stream-options">
+<h5><a class="toc-backref" href="#id34">DBI Stream Options</a><a class="headerlink" href="#dbi-stream-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-ec">
+<tt class="descname">-ec</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-ec" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the edit and continue map substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-files">
+<tt class="descname">-files</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the file info substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-modi">
+<tt class="descname">-modi</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-modi" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the modi substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-sc">
+<tt class="descname">-sc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-sc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump section contributions substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-sm">
+<tt class="descname">-sm</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-sm" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the section map from the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-type-server">
+<tt class="descname">-type-server</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-type-server" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the type server map from the DBI stream.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="module-options">
+<h5><a class="toc-backref" href="#id35">Module Options</a><a class="headerlink" href="#module-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-mod">
+<tt class="descname">-mod</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-mod" title="Permalink to this definition">¶</a></dt>
+<dd><p>Limit all options in this category to the specified module index. By default,
+options in this category will dump bytes from all modules.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-chunks">
+<tt class="descname">-chunks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-chunks" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the bytes of each module’s C13 debug subsection.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-split-chunks">
+<tt class="descname">-split-chunks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-split-chunks" title="Permalink to this definition">¶</a></dt>
+<dd><p>When specified with <a class="reference internal" href="#cmdoption-llvm-pdbutil-bytes-chunks"><em class="xref std std-option">-chunks</em></a>, split the C13 debug subsection into a
+separate chunk for each subsection type, and dump them separately.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-syms">
+<tt class="descname">-syms</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the symbol record substream from each module.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="id5">
+<h5><a class="toc-backref" href="#id36">Type Record Options</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-id">
+<tt class="descname">-id</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-id" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the record from the IPI stream with the given type index.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-type">
+<tt class="descname">-type</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-type" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the record from the TPI stream with the given type index.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+<div class="section" id="pdb2yaml">
+<span id="pdb2yaml-subcommand"></span><h3><a class="toc-backref" href="#id37">pdb2yaml</a><a class="headerlink" href="#pdb2yaml" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> pdb2yaml [<em>options</em>] <input PDB file></p>
+<div class="section" id="id6">
+<h4><a class="toc-backref" href="#id38">Summary</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+</div>
+<div class="section" id="id7">
+<h4><a class="toc-backref" href="#id39">Options</a><a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h4>
+</div>
+</div>
+<div class="section" id="yaml2pdb">
+<span id="yaml2pdb-subcommand"></span><h3><a class="toc-backref" href="#id40">yaml2pdb</a><a class="headerlink" href="#yaml2pdb" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> yaml2pdb [<em>options</em>] <input YAML file></p>
+<div class="section" id="id8">
+<h4><a class="toc-backref" href="#id41">Summary</a><a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h4>
+<p>Generate a PDB file from a YAML description. The YAML syntax is not described
+here. Instead, use <a class="reference internal" href="#pdb2yaml-subcommand"><em>llvm-pdbutil pdb2yaml</em></a> and
+examine the output for an example starting point.</p>
+</div>
+<div class="section" id="id9">
+<h4><a class="toc-backref" href="#id42">Options</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-yaml2pdb-pdb">
+<tt class="descname">-pdb</tt><tt class="descclassname">=<file-name></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-yaml2pdb-pdb" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Write the resulting PDB to the specified file.</p>
+</div>
+</div>
+<div class="section" id="merge">
+<span id="merge-subcommand"></span><h3><a class="toc-backref" href="#id43">merge</a><a class="headerlink" href="#merge" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> merge [<em>options</em>] <input PDB file 1> <input PDB file 2></p>
+<div class="section" id="id10">
+<h4><a class="toc-backref" href="#id44">Summary</a><a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h4>
+<p>Merge two PDB files into a single file.</p>
+</div>
+<div class="section" id="id11">
+<h4><a class="toc-backref" href="#id45">Options</a><a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h4>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-merge-pdb">
+<tt class="descname">-pdb</tt><tt class="descclassname">=<file-name></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-merge-pdb" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Write the resulting PDB to the specified file.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-build.html" title="llvm-build - LLVM Project Build Utility"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-profdata.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-profdata.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-profdata.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-profdata.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,330 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-profdata - Profile data tool — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-stress - generate random .ll files" href="llvm-stress.html" />
+ <link rel="prev" title="llvm-cov - emit coverage information" href="llvm-cov.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cov.html" title="llvm-cov - emit coverage information"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-profdata-profile-data-tool">
+<h1>llvm-profdata - Profile data tool<a class="headerlink" href="#llvm-profdata-profile-data-tool" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-profdata</strong> <em>command</em> [<em>args...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-profdata</strong> tool is a small utility for working with profile
+data files.</p>
+</div>
+<div class="section" id="commands">
+<h2>COMMANDS<a class="headerlink" href="#commands" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference internal" href="#profdata-merge"><em>merge</em></a></li>
+<li><a class="reference internal" href="#profdata-show"><em>show</em></a></li>
+</ul>
+</div>
+<div class="section" id="merge">
+<span id="profdata-merge"></span><h2>MERGE<a class="headerlink" href="#merge" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id1">
+<h3>SYNOPSIS<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata merge</strong> [<em>options</em>] [<em>filename...</em>]</p>
+</div>
+<div class="section" id="id2">
+<h3>DESCRIPTION<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata merge</strong> takes several profile data files
+generated by PGO instrumentation and merges them together into a single
+indexed profile data file.</p>
+<p>By default profile data is merged without modification. This means that the
+relative importance of each input file is proportional to the number of samples
+or counts it contains. In general, the input from a longer training run will be
+interpreted as relatively more important than a shorter run. Depending on the
+nature of the training runs it may be useful to adjust the weight given to each
+input file by using the <tt class="docutils literal"><span class="pre">-weighted-input</span></tt> option.</p>
+<p>Profiles passed in via <tt class="docutils literal"><span class="pre">-weighted-input</span></tt>, <tt class="docutils literal"><span class="pre">-input-files</span></tt>, or via positional
+arguments are processed once for each time they are seen.</p>
+</div>
+<div class="section" id="options">
+<h3>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-output">
+<tt class="descname">-output</tt><tt class="descclassname">=output</tt><tt class="descclassname">, </tt><tt class="descname">-o</tt><tt class="descclassname">=output</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. <em>Output</em> cannot be <tt class="docutils literal"><span class="pre">-</span></tt> as the resulting
+indexed profile data can’t be written to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-weighted-input">
+<tt class="descname">-weighted-input</tt><tt class="descclassname">=weight,filename</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-weighted-input" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify an input file name along with a weight. The profile counts of the
+supplied <tt class="docutils literal"><span class="pre">filename</span></tt> will be scaled (multiplied) by the supplied
+<tt class="docutils literal"><span class="pre">weight</span></tt>, where where <tt class="docutils literal"><span class="pre">weight</span></tt> is a decimal integer >= 1.
+Input files specified without using this option are assigned a default
+weight of 1. Examples are shown below.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-input-files">
+<tt class="descname">-input-files</tt><tt class="descclassname">=path</tt><tt class="descclassname">, </tt><tt class="descname">-f</tt><tt class="descclassname">=path</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-input-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a file which contains a list of files to merge. The entries in this
+file are newline-separated. Lines starting with ‘#’ are skipped. Entries may
+be of the form <filename> or <weight>,<filename>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-instr">
+<tt class="descname">-instr</tt><tt class="descclassname"> (default)</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-instr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is an instrumentation-based profile.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-sample">
+<tt class="descname">-sample</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-sample" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is a sample-based profile.</p>
+<p>The format of the generated file can be generated in one of three ways:</p>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-binary">
+<tt class="descname">-binary</tt><tt class="descclassname"> (default)</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-binary" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Emit the profile using a binary encoding. For instrumentation-based profile
+the output format is the indexed binary format.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-text">
+<tt class="descname">-text</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-text" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Emit the profile in text mode. This option can also be used with both
+sample-based and instrumentation-based profile. When this option is used
+the profile will be dumped in the text format that is parsable by the profile
+reader.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-gcc">
+<tt class="descname">-gcc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-gcc" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Emit the profile using GCC’s gcov format (Not yet supported).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-sparse">
+<tt class="descname">-sparse</tt><tt class="descclassname">[=true|false]</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-sparse" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not emit function records with 0 execution count. Can only be used in
+conjunction with -instr. Defaults to false, since it can inhibit compiler
+optimization during PGO.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-num-threads">
+<tt class="descname">-num-threads</tt><tt class="descclassname">=N</tt><tt class="descclassname">, </tt><tt class="descname">-j</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-num-threads" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
+an appropriate number of threads to use. This is the default.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="examples">
+<h3>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="basic-usage">
+<h4>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h4>
+<p>Merge three profiles:</p>
+<div class="highlight-python"><pre>llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata</pre>
+</div>
+</div>
+<div class="section" id="weighted-input">
+<h4>Weighted Input<a class="headerlink" href="#weighted-input" title="Permalink to this headline">¶</a></h4>
+<p>The input file <cite>foo.profdata</cite> is especially important, multiply its counts by 10:</p>
+<div class="highlight-python"><pre>llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata</pre>
+</div>
+<p>Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):</p>
+<div class="highlight-python"><pre>llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata</pre>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="show">
+<span id="profdata-show"></span><h2>SHOW<a class="headerlink" href="#show" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id3">
+<h3>SYNOPSIS<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata show</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="id4">
+<h3>DESCRIPTION<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata show</strong> takes a profile data file and displays the
+information about the profile counters for this file and
+for any of the specified function(s).</p>
+<p>If <em>filename</em> is omitted or is <tt class="docutils literal"><span class="pre">-</span></tt>, then <strong>llvm-profdata show</strong> reads its
+input from standard input.</p>
+</div>
+<div class="section" id="id5">
+<h3>OPTIONS<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-all-functions">
+<tt class="descname">-all-functions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-all-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print details for every function.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-counts">
+<tt class="descname">-counts</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-counts" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the counter values for the displayed functions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-function">
+<tt class="descname">-function</tt><tt class="descclassname">=string</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-function" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print details for a function if the function’s name contains the given string.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-output">
+<tt class="descname">-output</tt><tt class="descclassname">=output</tt><tt class="descclassname">, </tt><tt class="descname">-o</tt><tt class="descclassname">=output</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. If <em>output</em> is <tt class="docutils literal"><span class="pre">-</span></tt> or it isn’t specified,
+then the output is sent to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-instr">
+<tt class="descname">-instr</tt><tt class="descclassname"> (default)</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-instr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is an instrumentation-based profile.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-text">
+<tt class="descname">-text</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-text" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruct the profile dumper to show profile counts in the text format of the
+instrumentation-based profile data representation. By default, the profile
+information is dumped in a more human readable form (also in text) with
+annotations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-topn">
+<tt class="descname">-topn</tt><tt class="descclassname">=n</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-topn" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruct the profile dumper to show the top <tt class="docutils literal"><span class="pre">n</span></tt> functions with the
+hottest basic blocks in the summary section. By default, the topn functions
+are not dumped.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-sample">
+<tt class="descname">-sample</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-sample" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is a sample-based profile.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-memop-sizes">
+<tt class="descname">-memop-sizes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-memop-sizes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the profiled sizes of the memory intrinsic calls for shown functions.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-profdata</strong> returns 1 if the command is omitted or is invalid,
+if it cannot read input files, or if there is a mismatch between their data.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cov.html" title="llvm-cov - emit coverage information"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-readobj.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-readobj.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-readobj.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-readobj.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,218 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-readobj - LLVM Object Reader — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="Getting Started with the LLVM System" href="../GettingStarted.html" />
+ <link rel="prev" title="llvm-pdbutil - PDB File forensics and diagnostics" href="llvm-pdbutil.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../GettingStarted.html" title="Getting Started with the LLVM System"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-readobj-llvm-object-reader">
+<h1>llvm-readobj - LLVM Object Reader<a class="headerlink" href="#llvm-readobj-llvm-object-reader" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-readobj</strong> [<em>options</em>] [<em>input...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-readobj</strong> tool displays low-level format-specific information
+about one or more object files. The tool and its output is primarily designed
+for use in FileCheck-based tests.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p>If <tt class="docutils literal"><span class="pre">input</span></tt> is “<tt class="docutils literal"><span class="pre">-</span></tt>” or omitted, <strong class="program">llvm-readobj</strong> reads from standard
+input. Otherwise, it will read from the specified <tt class="docutils literal"><span class="pre">filenames</span></tt>.</p>
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-version">
+<tt class="descname">-version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of this program</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-file-headers">
+<tt class="descname">-file-headers</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-h</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-file-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display file headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-sections">
+<tt class="descname">-sections</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-s</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-data">
+<tt class="descname">-section-data</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-sd</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-section-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-sections</span></tt>, display section data for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-relocations">
+<tt class="descname">-section-relocations</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-sr</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-section-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-sections</span></tt>, display relocations for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-symbols">
+<tt class="descname">-section-symbols</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-st</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-section-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-sections</span></tt>, display symbols for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-relocations">
+<tt class="descname">-relocations</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-r</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the relocation entries in the file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-symbols">
+<tt class="descname">-symbols</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-t</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dyn-symbols">
+<tt class="descname">-dyn-symbols</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-dyn-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic symbol table (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-unwind">
+<tt class="descname">-unwind</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-u</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-unwind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display unwind information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-expand-relocs">
+<tt class="descname">-expand-relocs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-expand-relocs" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-relocations</span></tt>, display each relocation in an expanded
+multi-line format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dynamic-table">
+<tt class="descname">-dynamic-table</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-dynamic-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ELF .dynamic section table (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-needed-libs">
+<tt class="descname">-needed-libs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-needed-libs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the needed libraries (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-program-headers">
+<tt class="descname">-program-headers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-program-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ELF program headers (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-elf-section-groups">
+<tt class="descname">-elf-section-groups</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-g</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-elf-section-groups" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display section groups (only for ELF object files).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-readobj</strong> returns 0.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../GettingStarted.html" title="Getting Started with the LLVM System"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-stress.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-stress.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-stress.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-stress.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,136 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-stress - generate random .ll files — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-symbolizer - convert addresses into source code locations" href="llvm-symbolizer.html" />
+ <link rel="prev" title="llvm-profdata - Profile data tool" href="llvm-profdata.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-profdata.html" title="llvm-profdata - Profile data tool"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-stress-generate-random-ll-files">
+<h1>llvm-stress - generate random .ll files<a class="headerlink" href="#llvm-stress-generate-random-ll-files" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-stress</strong> [-size=filesize] [-seed=initialseed] [-o=outfile]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-stress</strong> tool is used to generate random <tt class="docutils literal"><span class="pre">.ll</span></tt> files that
+can be used to test different components of LLVM.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> filename</tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-size">
+<tt class="descname">-size</tt><tt class="descclassname"> size</tt><a class="headerlink" href="#cmdoption-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the size of the generated <tt class="docutils literal"><span class="pre">.ll</span></tt> file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-seed">
+<tt class="descname">-seed</tt><tt class="descclassname"> seed</tt><a class="headerlink" href="#cmdoption-seed" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the seed to be used for the randomly generated instructions.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-stress</strong> returns 0.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-profdata.html" title="llvm-profdata - Profile data tool"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/llvm-symbolizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/llvm-symbolizer.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/llvm-symbolizer.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/llvm-symbolizer.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,235 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>llvm-symbolizer - convert addresses into source code locations — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-dwarfdump - dump and verify DWARF debug information" href="llvm-dwarfdump.html" />
+ <link rel="prev" title="llvm-stress - generate random .ll files" href="llvm-stress.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-dwarfdump.html" title="llvm-dwarfdump - dump and verify DWARF debug information"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-symbolizer-convert-addresses-into-source-code-locations">
+<h1>llvm-symbolizer - convert addresses into source code locations<a class="headerlink" href="#llvm-symbolizer-convert-addresses-into-source-code-locations" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> [options]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> reads object file names and addresses from standard
+input and prints corresponding source code locations to standard output.
+If object file is specified in command line, <strong class="program">llvm-symbolizer</strong>
+processes only addresses from standard input, the rest is output verbatim.
+This program uses debug info sections and symbol table in the object files.</p>
+</div>
+<div class="section" id="example">
+<h2>EXAMPLE<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat addr.txt
+<span class="go">a.out 0x4004f4</span>
+<span class="go">/tmp/b.out 0x400528</span>
+<span class="go">/tmp/c.so 0x710</span>
+<span class="go">/tmp/mach_universal_binary:i386 0x1f84</span>
+<span class="go">/tmp/mach_universal_binary:x86_64 0x100000f24</span>
+<span class="gp">$</span> llvm-symbolizer < addr.txt
+<span class="go">main</span>
+<span class="go">/tmp/a.cc:4</span>
+
+<span class="go">f(int, int)</span>
+<span class="go">/tmp/b.cc:11</span>
+
+<span class="go">h_inlined_into_g</span>
+<span class="go">/tmp/header.h:2</span>
+<span class="go">g_inlined_into_f</span>
+<span class="go">/tmp/header.h:7</span>
+<span class="go">f_inlined_into_main</span>
+<span class="go">/tmp/source.cc:3</span>
+<span class="go">main</span>
+<span class="go">/tmp/source.cc:8</span>
+
+<span class="go">_main</span>
+<span class="go">/tmp/source_i386.cc:8</span>
+
+<span class="go">_main</span>
+<span class="go">/tmp/source_x86_64.cc:8</span>
+<span class="gp">$</span> cat addr2.txt
+<span class="go">0x4004f4</span>
+<span class="go">0x401000</span>
+<span class="gp">$</span> llvm-symbolizer -obj<span class="o">=</span>a.out < addr2.txt
+<span class="go">main</span>
+<span class="go">/tmp/a.cc:4</span>
+
+<span class="go">foo(int)</span>
+<span class="go">/tmp/a.cc:12</span>
+<span class="gp">$</span>cat addr.txt
+<span class="go">0x40054d</span>
+<span class="gp">$</span>llvm-symbolizer -inlining -print-address -pretty-print -obj<span class="o">=</span>addr.exe < addr.txt
+<span class="go">0x40054d: inc at /tmp/x.c:3:3</span>
+<span class="go"> (inlined by) main at /tmp/x.c:9:0</span>
+<span class="gp">$</span>llvm-symbolizer -inlining -pretty-print -obj<span class="o">=</span>addr.exe < addr.txt
+<span class="go">inc at /tmp/x.c:3:3</span>
+<span class="go"> (inlined by) main at /tmp/x.c:9:0</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-obj">
+<tt class="descname">-obj</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-obj" title="Permalink to this definition">¶</a></dt>
+<dd><p>Path to object file to be symbolized.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-functions">
+<tt class="descname">-functions</tt><tt class="descclassname">=[none|short|linkage]</tt><a class="headerlink" href="#cmdoption-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the way function names are printed (omit function name,
+print short function name, or print full linkage name, respectively).
+Defaults to <tt class="docutils literal"><span class="pre">linkage</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-use-symbol-table">
+<tt class="descname">-use-symbol-table</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-use-symbol-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Prefer function names stored in symbol table to function names
+in debug info sections. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-demangle">
+<tt class="descname">-demangle</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print demangled function names. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-inlining">
+<tt class="descname">-inlining</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-inlining" title="Permalink to this definition">¶</a></dt>
+<dd><p>If a source code location is in an inlined function, prints all the
+inlnied frames. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-default-arch">
+<tt class="descname">-default-arch</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-default-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>If a binary contains object files for multiple architectures (e.g. it is a
+Mach-O universal binary), symbolize the object file for a given architecture.
+You can also specify architecture by writing <tt class="docutils literal"><span class="pre">binary_name:arch_name</span></tt> in the
+input (see example above). If architecture is not specified in either way,
+address will not be symbolized. Defaults to empty string.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dsym-hint">
+<tt class="descname">-dsym-hint</tt><tt class="descclassname">=<path/to/file.dSYM></tt><a class="headerlink" href="#cmdoption-dsym-hint" title="Permalink to this definition">¶</a></dt>
+<dd><p>(Darwin-only flag). If the debug info for a binary isn’t present in the default
+location, look for the debug info at the .dSYM path provided via the
+<tt class="docutils literal"><span class="pre">-dsym-hint</span></tt> flag. This flag can be used multiple times.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-print-address">
+<tt class="descname">-print-address</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-print-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print address before the source code location. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pretty-print">
+<tt class="descname">-pretty-print</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pretty-print" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print human readable output. If <tt class="docutils literal"><span class="pre">-inlining</span></tt> is specified, enclosing scope is
+prefixed by (inlined by). Refer to listed examples.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> returns 0. Other exit codes imply internal program error.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-dwarfdump.html" title="llvm-dwarfdump - dump and verify DWARF debug information"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/opt.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/opt.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/opt.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/opt.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,241 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>opt - LLVM optimizer — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llc - LLVM static compiler" href="llc.html" />
+ <link rel="prev" title="llvm-dis - LLVM disassembler" href="llvm-dis.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llc.html" title="llc - LLVM static compiler"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-dis.html" title="llvm-dis - LLVM disassembler"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="opt-llvm-optimizer">
+<h1>opt - LLVM optimizer<a class="headerlink" href="#opt-llvm-optimizer" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">opt</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">opt</strong> command is the modular LLVM optimizer and analyzer. It
+takes LLVM source files as input, runs the specified optimizations or analyses
+on it, and then outputs the optimized file or the analysis results. The
+function of <strong class="program">opt</strong> depends on whether the <cite>-analyze</cite> option is
+given.</p>
+<p>When <cite>-analyze</cite> is specified, <strong class="program">opt</strong> performs various analyses
+of the input source. It will usually print the results on standard output, but
+in a few cases, it will print output to standard error or generate a file with
+the analysis output, which is usually done when the output is meant for another
+program.</p>
+<p>While <cite>-analyze</cite> is <em>not</em> given, <strong class="program">opt</strong> attempts to produce an
+optimized output file. The optimizations available via <strong class="program">opt</strong> depend
+upon what libraries were linked into it as well as any additional libraries
+that have been loaded with the <a class="reference internal" href="#cmdoption-load"><em class="xref std std-option">-load</em></a> option. Use the <a class="reference internal" href="#cmdoption-help"><em class="xref std std-option">-help</em></a>
+option to determine what optimizations you can use.</p>
+<p>If <tt class="docutils literal"><span class="pre">filename</span></tt> is omitted from the command line or is “<tt class="docutils literal"><span class="pre">-</span></tt>”, <strong class="program">opt</strong>
+reads its input from standard input. Inputs can be in either the LLVM assembly
+language format (<tt class="docutils literal"><span class="pre">.ll</span></tt>) or the LLVM bitcode format (<tt class="docutils literal"><span class="pre">.bc</span></tt>).</p>
+<p>If an output filename is not specified with the <a class="reference internal" href="#cmdoption-o"><em class="xref std std-option">-o</em></a> option,
+<strong class="program">opt</strong> writes its output to the standard output.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-f">
+<tt class="descname">-f</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable binary output on terminals. Normally, <strong class="program">opt</strong> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+<strong class="program">opt</strong> will write raw bitcode regardless of the output device.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> <filename></tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-S">
+<tt class="descname">-S</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-S" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write output in LLVM intermediate language (instead of bitcode).</p>
+</dd></dl>
+
+<dl class="option">
+<dt>
+<tt class="descname">-{passname}</tt></dt>
+<dd><p><strong class="program">opt</strong> provides the ability to run any of LLVM’s optimization or
+analysis passes in any order. The <a class="reference internal" href="#cmdoption-help"><em class="xref std std-option">-help</em></a> option lists all the passes
+available. The order in which the options occur on the command line are the
+order in which they are executed (within pass constraints).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-disable-inlining">
+<tt class="descname">-disable-inlining</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-disable-inlining" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option simply removes the inlining pass from the standard list.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-disable-opt">
+<tt class="descname">-disable-opt</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-disable-opt" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option is only meaningful when <cite>-std-link-opts</cite> is given. It
+disables most passes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-strip-debug">
+<tt class="descname">-strip-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-strip-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option causes opt to strip debug information from the module before
+applying other optimizations. It is essentially the same as <cite>-strip</cite>
+but it ensures that stripping of debug information is done first.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-verify-each">
+<tt class="descname">-verify-each</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-verify-each" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option causes opt to add a verify pass after every pass otherwise
+specified on the command line (including <cite>-verify</cite>). This is useful
+for cases where it is suspected that a pass is creating an invalid module but
+it is not clear which pass is doing it.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-stats">
+<tt class="descname">-stats</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print statistics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-time-passes">
+<tt class="descname">-time-passes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-time-passes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Record the amount of time needed for each pass and print it to standard
+error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-debug">
+<tt class="descname">-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>If this is a debug build, this option will enable debug printouts from passes
+which use the <tt class="docutils literal"><span class="pre">DEBUG()</span></tt> macro. See the <a class="reference external" href="../ProgrammersManual.html">LLVM Programmer’s Manual</a>, section <tt class="docutils literal"><span class="pre">#DEBUG</span></tt> for more information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-load">
+<tt class="descname">-load</tt><tt class="descclassname">=<plugin></tt><a class="headerlink" href="#cmdoption-load" title="Permalink to this definition">¶</a></dt>
+<dd><p>Load the dynamic object <tt class="docutils literal"><span class="pre">plugin</span></tt>. This object should register new
+optimization or analysis passes. Once loaded, the object will add new command
+line options to enable various optimizations or analyses. To see the new
+complete list of optimizations, use the <a class="reference internal" href="#cmdoption-help"><em class="xref std std-option">-help</em></a> and <a class="reference internal" href="#cmdoption-load"><em class="xref std std-option">-load</em></a>
+options together. For example:</p>
+<div class="highlight-sh"><div class="highlight"><pre>opt -load<span class="o">=</span>plugin.so -help
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-p">
+<tt class="descname">-p</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print module after each transformation.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">opt</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llc.html" title="llc - LLVM static compiler"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-dis.html" title="llvm-dis - LLVM disassembler"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandGuide/tblgen.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandGuide/tblgen.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandGuide/tblgen.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandGuide/tblgen.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,272 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>tblgen - Target Description To C++ Code Generator — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="lit - LLVM Integrated Tester" href="lit.html" />
+ <link rel="prev" title="FileCheck - Flexible pattern matching file verifier" href="FileCheck.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tblgen-target-description-to-c-code-generator">
+<h1>tblgen - Target Description To C++ Code Generator<a class="headerlink" href="#tblgen-target-description-to-c-code-generator" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">tblgen</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">tblgen</strong> translates from target description (<tt class="docutils literal"><span class="pre">.td</span></tt>) files into C++
+code that can be included in the definition of an LLVM target library. Most
+users of LLVM will not need to use this program. It is only for assisting with
+writing an LLVM target backend.</p>
+<p>The input and output of <strong class="program">tblgen</strong> is beyond the scope of this short
+introduction; please see the <a class="reference internal" href="../TableGen/index.html"><em>introduction to TableGen</em></a>.</p>
+<p>The <em>filename</em> argument specifies the name of a Target Description (<tt class="docutils literal"><span class="pre">.td</span></tt>)
+file to read as input.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-tblgen-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-o">
+<tt class="descname">-o</tt><tt class="descclassname"> filename</tt><a class="headerlink" href="#cmdoption-tblgen-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. If <tt class="docutils literal"><span class="pre">filename</span></tt> is <tt class="docutils literal"><span class="pre">-</span></tt>, then
+<strong class="program">tblgen</strong> sends its output to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-I">
+<tt class="descname">-I</tt><tt class="descclassname"> directory</tt><a class="headerlink" href="#cmdoption-tblgen-I" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify where to find other target description files for inclusion. The
+<tt class="docutils literal"><span class="pre">directory</span></tt> value should be a full or partial path to a directory that
+contains target description files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-asmparsernum">
+<tt class="descname">-asmparsernum</tt><tt class="descclassname"> N</tt><a class="headerlink" href="#cmdoption-tblgen-asmparsernum" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make -gen-asm-parser emit assembly writer number <tt class="docutils literal"><span class="pre">N</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-asmwriternum">
+<tt class="descname">-asmwriternum</tt><tt class="descclassname"> N</tt><a class="headerlink" href="#cmdoption-tblgen-asmwriternum" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make -gen-asm-writer emit assembly writer number <tt class="docutils literal"><span class="pre">N</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-class">
+<tt class="descname">-class</tt><tt class="descclassname"> className</tt><a class="headerlink" href="#cmdoption-tblgen-class" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the enumeration list for this class.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-print-records">
+<tt class="descname">-print-records</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-print-records" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print all records to standard output (default).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-print-enums">
+<tt class="descname">-print-enums</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-print-enums" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print enumeration values for a class.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-print-sets">
+<tt class="descname">-print-sets</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-print-sets" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print expanded sets for testing DAG exprs.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-emitter">
+<tt class="descname">-gen-emitter</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-emitter" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate machine code emitter.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-register-info">
+<tt class="descname">-gen-register-info</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-register-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate registers and register classes info.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-instr-info">
+<tt class="descname">-gen-instr-info</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-instr-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate instruction descriptions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-asm-writer">
+<tt class="descname">-gen-asm-writer</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-asm-writer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate the assembly writer.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-disassembler">
+<tt class="descname">-gen-disassembler</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-disassembler" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate disassembler.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-pseudo-lowering">
+<tt class="descname">-gen-pseudo-lowering</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-pseudo-lowering" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate pseudo instruction lowering.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-dag-isel">
+<tt class="descname">-gen-dag-isel</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-dag-isel" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate a DAG (Directed Acycle Graph) instruction selector.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-asm-matcher">
+<tt class="descname">-gen-asm-matcher</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-asm-matcher" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate assembly instruction matcher.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-dfa-packetizer">
+<tt class="descname">-gen-dfa-packetizer</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-dfa-packetizer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate DFA Packetizer for VLIW targets.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-fast-isel">
+<tt class="descname">-gen-fast-isel</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-fast-isel" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate a “fast” instruction selector.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-subtarget">
+<tt class="descname">-gen-subtarget</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-subtarget" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate subtarget enumerations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-intrinsic">
+<tt class="descname">-gen-intrinsic</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-intrinsic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate intrinsic information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-tgt-intrinsic">
+<tt class="descname">-gen-tgt-intrinsic</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-tgt-intrinsic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate target intrinsic information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-enhanced-disassembly-info">
+<tt class="descname">-gen-enhanced-disassembly-info</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-enhanced-disassembly-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate enhanced disassembly info.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-version">
+<tt class="descname">-version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the version number of this program.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">tblgen</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CommandLine.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CommandLine.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CommandLine.html (added)
+++ www-releases/trunk/6.0.1/docs/CommandLine.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,1553 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>CommandLine 2.0 Library Manual — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="Architecture & Platform Information for Compiler Writers" href="CompilerWriterInfo.html" />
+ <link rel="prev" title="LLVM Coding Standards" href="CodingStandards.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodingStandards.html" title="LLVM Coding Standards"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="commandline-2-0-library-manual">
+<h1>CommandLine 2.0 Library Manual<a class="headerlink" href="#commandline-2-0-library-manual" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id8">Introduction</a></li>
+<li><a class="reference internal" href="#quick-start-guide" id="id9">Quick Start Guide</a><ul>
+<li><a class="reference internal" href="#boolean-arguments" id="id10">Boolean Arguments</a></li>
+<li><a class="reference internal" href="#argument-aliases" id="id11">Argument Aliases</a></li>
+<li><a class="reference internal" href="#selecting-an-alternative-from-a-set-of-possibilities" id="id12">Selecting an alternative from a set of possibilities</a></li>
+<li><a class="reference internal" href="#named-alternatives" id="id13">Named Alternatives</a></li>
+<li><a class="reference internal" href="#parsing-a-list-of-options" id="id14">Parsing a list of options</a></li>
+<li><a class="reference internal" href="#collecting-options-as-a-set-of-flags" id="id15">Collecting options as a set of flags</a></li>
+<li><a class="reference internal" href="#adding-freeform-text-to-help-output" id="id16">Adding freeform text to help output</a></li>
+<li><a class="reference internal" href="#grouping-options-into-categories" id="id17">Grouping options into categories</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reference-guide" id="id18">Reference Guide</a><ul>
+<li><a class="reference internal" href="#positional-options" id="id19">Positional Arguments</a><ul>
+<li><a class="reference internal" href="#specifying-positional-options-with-hyphens" id="id20">Specifying positional options with hyphens</a></li>
+<li><a class="reference internal" href="#determining-absolute-position-with-getposition" id="id21">Determining absolute position with getPosition()</a></li>
+<li><a class="reference internal" href="#the-cl-consumeafter-modifier" id="id22">The <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> modifier</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#internal-vs-external-storage" id="id23">Internal vs External Storage</a></li>
+<li><a class="reference internal" href="#option-attributes" id="id24">Option Attributes</a></li>
+<li><a class="reference internal" href="#option-modifiers" id="id25">Option Modifiers</a><ul>
+<li><a class="reference internal" href="#hiding-an-option-from-help-output" id="id26">Hiding an option from <tt class="docutils literal"><span class="pre">-help</span></tt> output</a></li>
+<li><a class="reference internal" href="#controlling-the-number-of-occurrences-required-and-allowed" id="id27">Controlling the number of occurrences required and allowed</a></li>
+<li><a class="reference internal" href="#controlling-whether-or-not-a-value-must-be-specified" id="id28">Controlling whether or not a value must be specified</a></li>
+<li><a class="reference internal" href="#controlling-other-formatting-options" id="id29">Controlling other formatting options</a></li>
+<li><a class="reference internal" href="#miscellaneous-option-modifiers" id="id30">Miscellaneous option modifiers</a></li>
+<li><a class="reference internal" href="#response-files" id="id31">Response files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#top-level-classes-and-functions" id="id32">Top-Level Classes and Functions</a><ul>
+<li><a class="reference internal" href="#the-cl-getregisteredoptions-function" id="id33">The <tt class="docutils literal"><span class="pre">cl::getRegisteredOptions</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-parsecommandlineoptions-function" id="id34">The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-parseenvironmentoptions-function" id="id35">The <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-setversionprinter-function" id="id36">The <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-opt-class" id="id37">The <tt class="docutils literal"><span class="pre">cl::opt</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-list-class" id="id38">The <tt class="docutils literal"><span class="pre">cl::list</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-bits-class" id="id39">The <tt class="docutils literal"><span class="pre">cl::bits</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-alias-class" id="id40">The <tt class="docutils literal"><span class="pre">cl::alias</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-extrahelp-class" id="id41">The <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-optioncategory-class" id="id42">The <tt class="docutils literal"><span class="pre">cl::OptionCategory</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#builtin-parsers" id="id43">Builtin parsers</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#extending-the-library" id="id44">Extension Guide</a><ul>
+<li><a class="reference internal" href="#writing-a-custom-parser" id="id45">Writing a custom parser</a></li>
+<li><a class="reference internal" href="#exploiting-external-storage" id="id46">Exploiting external storage</a></li>
+<li><a class="reference internal" href="#dynamically-adding-command-line-options" id="id47">Dynamically adding command line options</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the CommandLine argument processing library. It will
+show you how to use it, and what it can do. The CommandLine library uses a
+declarative approach to specifying the command line options that your program
+takes. By default, these options declarations implicitly hold the value parsed
+for the option declared (of course this <a class="reference internal" href="#can-be-changed">can be changed</a>).</p>
+<p>Although there are a <strong>lot</strong> of command line argument parsing libraries out
+there in many different languages, none of them fit well with what I needed. By
+looking at the features and problems of other libraries, I designed the
+CommandLine library to have the following features:</p>
+<ol class="arabic simple">
+<li>Speed: The CommandLine library is very quick and uses little resources. The
+parsing time of the library is directly proportional to the number of
+arguments parsed, not the number of options recognized. Additionally,
+command line argument values are captured transparently into user defined
+global variables, which can be accessed like any other variable (and with the
+same performance).</li>
+<li>Type Safe: As a user of CommandLine, you don’t have to worry about
+remembering the type of arguments that you want (is it an int? a string? a
+bool? an enum?) and keep casting it around. Not only does this help prevent
+error prone constructs, it also leads to dramatically cleaner source code.</li>
+<li>No subclasses required: To use CommandLine, you instantiate variables that
+correspond to the arguments that you would like to capture, you don’t
+subclass a parser. This means that you don’t have to write <strong>any</strong>
+boilerplate code.</li>
+<li>Globally accessible: Libraries can specify command line arguments that are
+automatically enabled in any tool that links to the library. This is
+possible because the application doesn’t have to keep a list of arguments to
+pass to the parser. This also makes supporting <a class="reference internal" href="#dynamically-loaded-options">dynamically loaded options</a>
+trivial.</li>
+<li>Cleaner: CommandLine supports enum and other types directly, meaning that
+there is less error and more security built into the library. You don’t have
+to worry about whether your integral command line argument accidentally got
+assigned a value that is not valid for your enum type.</li>
+<li>Powerful: The CommandLine library supports many different types of arguments,
+from simple <a class="reference internal" href="#boolean-flags">boolean flags</a> to <a class="reference internal" href="#scalars-arguments">scalars arguments</a> (<a class="reference internal" href="#strings">strings</a>,
+<a class="reference internal" href="#integers">integers</a>, <a class="reference internal" href="#enums">enums</a>, <a class="reference internal" href="#doubles">doubles</a>), to <a class="reference internal" href="#lists-of-arguments">lists of arguments</a>. This is
+possible because CommandLine is...</li>
+<li>Extensible: It is very simple to add a new argument type to CommandLine.
+Simply specify the parser that you want to use with the command line option
+when you declare it. <a class="reference internal" href="#custom-parsers">Custom parsers</a> are no problem.</li>
+<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
+that you, the user, have to do. For example, it automatically provides a
+<tt class="docutils literal"><span class="pre">-help</span></tt> option that shows the available command line options for your tool.
+Additionally, it does most of the basic correctness checking for you.</li>
+<li>Capable: The CommandLine library can handle lots of different forms of
+options often found in real programs. For example, <a class="reference internal" href="#positional">positional</a> arguments,
+<tt class="docutils literal"><span class="pre">ls</span></tt> style <a class="reference internal" href="#grouping">grouping</a> options (to allow processing ‘<tt class="docutils literal"><span class="pre">ls</span> <span class="pre">-lad</span></tt>‘
+naturally), <tt class="docutils literal"><span class="pre">ld</span></tt> style <a class="reference internal" href="#prefix">prefix</a> options (to parse ‘<tt class="docutils literal"><span class="pre">-lmalloc</span>
+<span class="pre">-L/usr/lib</span></tt>‘), and interpreter style options.</li>
+</ol>
+<p>This document will hopefully let you jump in and start using CommandLine in your
+utility quickly and painlessly. Additionally it should be a simple reference
+manual to figure out how stuff works.</p>
+</div>
+<div class="section" id="quick-start-guide">
+<h2><a class="toc-backref" href="#id9">Quick Start Guide</a><a class="headerlink" href="#quick-start-guide" title="Permalink to this headline">¶</a></h2>
+<p>This section of the manual runs through a simple CommandLine’ification of a
+basic compiler tool. This is intended to show you how to jump into using the
+CommandLine library in your own program, and show you some of the cool things it
+can do.</p>
+<p>To start out, you need to include the CommandLine header file into your program:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Support/CommandLine.h"</span>
+</pre></div>
+</div>
+<p>Additionally, you need to add this as the first line of your main program:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">ParseCommandLineOptions</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">);</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>... which actually parses the arguments and fills in the variable declarations.</p>
+<p>Now that you are ready to support command line arguments, we need to tell the
+system which ones we want, and what type of arguments they are. The CommandLine
+library uses a declarative syntax to model command line arguments with the
+global variable declarations that capture the parsed values. This means that
+for every command line option that you would like to support, there should be a
+global variable declaration to capture the result. For example, in a compiler,
+we would like to support the Unix-standard ‘<tt class="docutils literal"><span class="pre">-o</span> <span class="pre"><filename></span></tt>‘ option to specify
+where to put the output. With the CommandLine library, this is represented like
+this:</p>
+<div class="highlight-c++" id="here"><span id="scalars-arguments"></span><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">OutputFilename</span><span class="p">(</span><span class="s">"o"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Specify output filename"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">value_desc</span><span class="p">(</span><span class="s">"filename"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This declares a global variable “<tt class="docutils literal"><span class="pre">OutputFilename</span></tt>” that is used to capture the
+result of the “<tt class="docutils literal"><span class="pre">o</span></tt>” argument (first parameter). We specify that this is a
+simple scalar option by using the “<tt class="docutils literal"><span class="pre">cl::opt</span></tt>” template (as opposed to the
+“<tt class="docutils literal"><span class="pre">cl::list</span></tt>” template), and tell the CommandLine library that the data
+type that we are parsing is a string.</p>
+<p>The second and third parameters (which are optional) are used to specify what to
+output for the “<tt class="docutils literal"><span class="pre">-help</span></tt>” option. In this case, we get a line that looks like
+this:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options]
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename</pre>
+</div>
+<p>Because we specified that the command line option should parse using the
+<tt class="docutils literal"><span class="pre">string</span></tt> data type, the variable declared is automatically usable as a real
+string in all contexts that a normal C++ string object may be used. For
+example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+<span class="n">std</span><span class="o">::</span><span class="n">ofstream</span> <span class="n">Output</span><span class="p">(</span><span class="n">OutputFilename</span><span class="p">.</span><span class="n">c_str</span><span class="p">());</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">Output</span><span class="p">.</span><span class="n">good</span><span class="p">())</span> <span class="p">...</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>There are many different options that you can use to customize the command line
+option handling library, but the above example shows the general interface to
+these options. The options can be specified in any order, and are specified
+with helper functions like <a class="reference internal" href="#cl-desc">cl::desc(...)</a>, so there are no positional
+dependencies to remember. The available options are discussed in detail in the
+<a class="reference internal" href="#reference-guide">Reference Guide</a>.</p>
+<p>Continuing the example, we would like to have our compiler take an input
+filename as well as an output filename, but we do not want the input filename to
+be specified with a hyphen (ie, not <tt class="docutils literal"><span class="pre">-filename.c</span></tt>). To support this style of
+argument, the CommandLine library allows for <a class="reference internal" href="#positional">positional</a> arguments to be
+specified for the program. These positional arguments are filled with command
+line parameters that are not in option form. We use this feature like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="s">"-"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This declaration indicates that the first positional argument should be treated
+as the input filename. Here we use the <a class="reference internal" href="#cl-init">cl::init</a> option to specify an initial
+value for the command line option, which is used if the option is not specified
+(if you do not specify a <a class="reference internal" href="#cl-init">cl::init</a> modifier for an option, then the default
+constructor for the data type is used to initialize the value). Command line
+options default to being optional, so if we would like to require that the user
+always specify an input filename, we would add the <a class="reference internal" href="#cl-required">cl::Required</a> flag, and we
+could eliminate the <a class="reference internal" href="#cl-init">cl::init</a> modifier, like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Required</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Again, the CommandLine library does not require the options to be specified in
+any particular order, so the above declaration is equivalent to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">Required</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>By simply adding the <a class="reference internal" href="#cl-required">cl::Required</a> flag, the CommandLine library will
+automatically issue an error if the argument is not specified, which shifts all
+of the command line option verification code out of your application into the
+library. This is just one example of how using flags can alter the default
+behaviour of the library, on a per-option basis. By adding one of the
+declarations above, the <tt class="docutils literal"><span class="pre">-help</span></tt> option synopsis is now extended to:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename</pre>
+</div>
+<p>... indicating that an input filename is expected.</p>
+<div class="section" id="boolean-arguments">
+<h3><a class="toc-backref" href="#id10">Boolean Arguments</a><a class="headerlink" href="#boolean-arguments" title="Permalink to this headline">¶</a></h3>
+<p>In addition to input and output filenames, we would like the compiler example to
+support three boolean flags: “<tt class="docutils literal"><span class="pre">-f</span></tt>” to force writing binary output to a
+terminal, “<tt class="docutils literal"><span class="pre">--quiet</span></tt>” to enable quiet mode, and “<tt class="docutils literal"><span class="pre">-q</span></tt>” for backwards
+compatibility with some of our users. We can support these by declaring options
+of boolean type like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Force</span> <span class="p">(</span><span class="s">"f"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Enable binary output on terminals"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet</span> <span class="p">(</span><span class="s">"quiet"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Don't print informational messages"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet2</span><span class="p">(</span><span class="s">"q"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Don't print informational messages"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Hidden</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This does what you would expect: it declares three boolean variables
+(“<tt class="docutils literal"><span class="pre">Force</span></tt>”, “<tt class="docutils literal"><span class="pre">Quiet</span></tt>”, and “<tt class="docutils literal"><span class="pre">Quiet2</span></tt>”) to recognize these options. Note
+that the “<tt class="docutils literal"><span class="pre">-q</span></tt>” option is specified with the “<a class="reference internal" href="#cl-hidden">cl::Hidden</a>” flag. This
+modifier prevents it from being shown by the standard “<tt class="docutils literal"><span class="pre">-help</span></tt>” output (note
+that it is still shown in the “<tt class="docutils literal"><span class="pre">-help-hidden</span></tt>” output).</p>
+<p>The CommandLine library uses a <a class="reference internal" href="#different-parser">different parser</a> for different data types.
+For example, in the string case, the argument passed to the option is copied
+literally into the content of the string variable... we obviously cannot do that
+in the boolean case, however, so we must use a smarter parser. In the case of
+the boolean parser, it allows no options (in which case it assigns the value of
+true to the variable), or it allows the values “<tt class="docutils literal"><span class="pre">true</span></tt>” or “<tt class="docutils literal"><span class="pre">false</span></tt>” to be
+specified, allowing any of the following inputs:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">compiler</span> <span class="o">-</span><span class="n">f</span> <span class="c"># No value, 'Force' == true</span>
+<span class="n">compiler</span> <span class="o">-</span><span class="n">f</span><span class="o">=</span><span class="n">true</span> <span class="c"># Value specified, 'Force' == true</span>
+<span class="n">compiler</span> <span class="o">-</span><span class="n">f</span><span class="o">=</span><span class="n">TRUE</span> <span class="c"># Value specified, 'Force' == true</span>
+<span class="n">compiler</span> <span class="o">-</span><span class="n">f</span><span class="o">=</span><span class="n">FALSE</span> <span class="c"># Value specified, 'Force' == false</span>
+</pre></div>
+</div>
+<p>... you get the idea. The <a class="reference internal" href="#bool-parser">bool parser</a> just turns the string values into
+boolean values, and rejects things like ‘<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-f=foo</span></tt>‘. Similarly, the
+<a class="reference internal" href="#float">float</a>, <a class="reference internal" href="#double">double</a>, and <a class="reference internal" href="#int">int</a> parsers work like you would expect, using the
+‘<tt class="docutils literal"><span class="pre">strtol</span></tt>‘ and ‘<tt class="docutils literal"><span class="pre">strtod</span></tt>‘ C library calls to parse the string value into the
+specified data type.</p>
+<p>With the declarations above, “<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-help</span></tt>” emits this:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ -f - Enable binary output on terminals
+ -o - Override output filename
+ -quiet - Don't print informational messages
+ -help - display available options (-help-hidden for more)</pre>
+</div>
+<p>and “<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-help-hidden</span></tt>” prints this:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ -f - Enable binary output on terminals
+ -o - Override output filename
+ -q - Don't print informational messages
+ -quiet - Don't print informational messages
+ -help - display available options (-help-hidden for more)</pre>
+</div>
+<p>This brief example has shown you how to use the ‘<a class="reference internal" href="#cl-opt">cl::opt</a>‘ class to parse
+simple scalar command line arguments. In addition to simple scalar arguments,
+the CommandLine library also provides primitives to support CommandLine option
+<a class="reference internal" href="#aliases">aliases</a>, and <a class="reference internal" href="#lists">lists</a> of options.</p>
+</div>
+<div class="section" id="argument-aliases">
+<span id="aliases"></span><h3><a class="toc-backref" href="#id11">Argument Aliases</a><a class="headerlink" href="#argument-aliases" title="Permalink to this headline">¶</a></h3>
+<p>So far, the example works well, except for the fact that we need to check the
+quiet condition like this now:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">Quiet</span> <span class="o">&&</span> <span class="o">!</span><span class="n">Quiet2</span><span class="p">)</span> <span class="n">printInformationalMessage</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>... which is a real pain! Instead of defining two values for the same
+condition, we can use the “<a class="reference internal" href="#cl-alias">cl::alias</a>” class to make the “<tt class="docutils literal"><span class="pre">-q</span></tt>” option an
+<strong>alias</strong> for the “<tt class="docutils literal"><span class="pre">-quiet</span></tt>” option, instead of providing a value itself:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Force</span> <span class="p">(</span><span class="s">"f"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Overwrite output files"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet</span> <span class="p">(</span><span class="s">"quiet"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Don't print informational messages"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">alias</span> <span class="n">QuietA</span><span class="p">(</span><span class="s">"q"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Alias for -quiet"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">aliasopt</span><span class="p">(</span><span class="n">Quiet</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>The third line (which is the only one we modified from above) defines a “<tt class="docutils literal"><span class="pre">-q</span></tt>”
+alias that updates the “<tt class="docutils literal"><span class="pre">Quiet</span></tt>” variable (as specified by the <a class="reference internal" href="#cl-aliasopt">cl::aliasopt</a>
+modifier) whenever it is specified. Because aliases do not hold state, the only
+thing the program has to query is the <tt class="docutils literal"><span class="pre">Quiet</span></tt> variable now. Another nice
+feature of aliases is that they automatically hide themselves from the <tt class="docutils literal"><span class="pre">-help</span></tt>
+output (although, again, they are still visible in the <tt class="docutils literal"><span class="pre">-help-hidden</span> <span class="pre">output</span></tt>).</p>
+<p>Now the application code can simply use:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">Quiet</span><span class="p">)</span> <span class="n">printInformationalMessage</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>... which is much nicer! The “<a class="reference internal" href="#cl-alias">cl::alias</a>” can be used to specify an
+alternative name for any variable type, and has many uses.</p>
+</div>
+<div class="section" id="selecting-an-alternative-from-a-set-of-possibilities">
+<span id="unnamed-alternatives-using-the-generic-parser"></span><h3><a class="toc-backref" href="#id12">Selecting an alternative from a set of possibilities</a><a class="headerlink" href="#selecting-an-alternative-from-a-set-of-possibilities" title="Permalink to this headline">¶</a></h3>
+<p>So far we have seen how the CommandLine library handles builtin types like
+<tt class="docutils literal"><span class="pre">std::string</span></tt>, <tt class="docutils literal"><span class="pre">bool</span></tt> and <tt class="docutils literal"><span class="pre">int</span></tt>, but how does it handle things it doesn’t
+know about, like enums or ‘<tt class="docutils literal"><span class="pre">int*</span></tt>‘s?</p>
+<p>The answer is that it uses a table-driven generic parser (unless you specify
+your own parser, as described in the <a class="reference internal" href="#extension-guide">Extension Guide</a>). This parser maps
+literal strings to whatever type is required, and requires you to tell it what
+this mapping should be.</p>
+<p>Let’s say that we would like to add four optimization levels to our optimizer,
+using the standard flags “<tt class="docutils literal"><span class="pre">-g</span></tt>”, “<tt class="docutils literal"><span class="pre">-O0</span></tt>”, “<tt class="docutils literal"><span class="pre">-O1</span></tt>”, and “<tt class="docutils literal"><span class="pre">-O2</span></tt>”. We
+could easily implement this with boolean options like above, but there are
+several problems with this strategy:</p>
+<ol class="arabic simple">
+<li>A user could specify more than one of the options at a time, for example,
+“<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-O3</span> <span class="pre">-O2</span></tt>”. The CommandLine library would not be able to catch
+this erroneous input for us.</li>
+<li>We would have to test 4 different variables to see which ones are set.</li>
+<li>This doesn’t map to the numeric levels that we want... so we cannot easily
+see if some level >= “<tt class="docutils literal"><span class="pre">-O1</span></tt>” is enabled.</li>
+</ol>
+<p>To cope with these problems, we can use an enum value, and have the CommandLine
+library fill it in with the appropriate level directly, which is used like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">OptLevel</span> <span class="p">{</span>
+ <span class="n">g</span><span class="p">,</span> <span class="n">O1</span><span class="p">,</span> <span class="n">O2</span><span class="p">,</span> <span class="n">O3</span>
+<span class="p">};</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">OptLevel</span><span class="o">></span> <span class="n">OptimizationLevel</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Choose optimization level:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">g</span> <span class="p">,</span> <span class="s">"No optimizations, enable debugging"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O1</span><span class="p">,</span> <span class="s">"Enable trivial optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O2</span><span class="p">,</span> <span class="s">"Enable default optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O3</span><span class="p">,</span> <span class="s">"Enable expensive optimizations"</span><span class="p">)));</span>
+
+<span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">OptimizationLevel</span> <span class="o">>=</span> <span class="n">O2</span><span class="p">)</span> <span class="n">doPartialRedundancyElimination</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>This declaration defines a variable “<tt class="docutils literal"><span class="pre">OptimizationLevel</span></tt>” of the
+“<tt class="docutils literal"><span class="pre">OptLevel</span></tt>” enum type. This variable can be assigned any of the values that
+are listed in the declaration. The CommandLine library enforces that
+the user can only specify one of the options, and it ensure that only valid enum
+values can be specified. The “<tt class="docutils literal"><span class="pre">clEnumVal</span></tt>” macros ensure that the command
+line arguments matched the enum values. With this option added, our help output
+now is:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages</pre>
+</div>
+<p>In this case, it is sort of awkward that flag names correspond directly to enum
+names, because we probably don’t want a enum definition named “<tt class="docutils literal"><span class="pre">g</span></tt>” in our
+program. Because of this, we can alternatively write this example like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">OptLevel</span> <span class="p">{</span>
+ <span class="n">Debug</span><span class="p">,</span> <span class="n">O1</span><span class="p">,</span> <span class="n">O2</span><span class="p">,</span> <span class="n">O3</span>
+<span class="p">};</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">OptLevel</span><span class="o">></span> <span class="n">OptimizationLevel</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Choose optimization level:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">Debug</span><span class="p">,</span> <span class="s">"g"</span><span class="p">,</span> <span class="s">"No optimizations, enable debugging"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O1</span> <span class="p">,</span> <span class="s">"Enable trivial optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O2</span> <span class="p">,</span> <span class="s">"Enable default optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O3</span> <span class="p">,</span> <span class="s">"Enable expensive optimizations"</span><span class="p">)));</span>
+
+<span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">OptimizationLevel</span> <span class="o">==</span> <span class="n">Debug</span><span class="p">)</span> <span class="n">outputDebugInfo</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>By using the “<tt class="docutils literal"><span class="pre">clEnumValN</span></tt>” macro instead of “<tt class="docutils literal"><span class="pre">clEnumVal</span></tt>”, we can directly
+specify the name that the flag should get. In general a direct mapping is nice,
+but sometimes you can’t or don’t want to preserve the mapping, which is when you
+would use it.</p>
+</div>
+<div class="section" id="named-alternatives">
+<h3><a class="toc-backref" href="#id13">Named Alternatives</a><a class="headerlink" href="#named-alternatives" title="Permalink to this headline">¶</a></h3>
+<p>Another useful argument form is a named alternative style. We shall use this
+style in our compiler to specify different debug levels that can be used.
+Instead of each debug level being its own switch, we want to support the
+following options, of which only one can be specified at a time:
+“<tt class="docutils literal"><span class="pre">--debug-level=none</span></tt>”, “<tt class="docutils literal"><span class="pre">--debug-level=quick</span></tt>”,
+“<tt class="docutils literal"><span class="pre">--debug-level=detailed</span></tt>”. To do this, we use the exact same format as our
+optimization level flags, but we also specify an option name. For this case,
+the code looks like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">DebugLev</span> <span class="p">{</span>
+ <span class="n">nodebuginfo</span><span class="p">,</span> <span class="n">quick</span><span class="p">,</span> <span class="n">detailed</span>
+<span class="p">};</span>
+
+<span class="c1">// Enable Debug Options to be specified on the command line</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">DebugLev</span><span class="o">></span> <span class="n">DebugLevel</span><span class="p">(</span><span class="s">"debug_level"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Set the debugging level:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">nodebuginfo</span><span class="p">,</span> <span class="s">"none"</span><span class="p">,</span> <span class="s">"disable debug information"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">quick</span><span class="p">,</span> <span class="s">"enable quick debug information"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">detailed</span><span class="p">,</span> <span class="s">"enable detailed debug information"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>This definition defines an enumerated command line variable of type “<tt class="docutils literal"><span class="pre">enum</span>
+<span class="pre">DebugLev</span></tt>”, which works exactly the same way as before. The difference here is
+just the interface exposed to the user of your program and the help output by
+the “<tt class="docutils literal"><span class="pre">-help</span></tt>” option:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations
+ -debug_level - Set the debugging level:
+ =none - disable debug information
+ =quick - enable quick debug information
+ =detailed - enable detailed debug information
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages</pre>
+</div>
+<p>Again, the only structural difference between the debug level declaration and
+the optimization level declaration is that the debug level declaration includes
+an option name (<tt class="docutils literal"><span class="pre">"debug_level"</span></tt>), which automatically changes how the library
+processes the argument. The CommandLine library supports both forms so that you
+can choose the form most appropriate for your application.</p>
+</div>
+<div class="section" id="parsing-a-list-of-options">
+<span id="lists"></span><h3><a class="toc-backref" href="#id14">Parsing a list of options</a><a class="headerlink" href="#parsing-a-list-of-options" title="Permalink to this headline">¶</a></h3>
+<p>Now that we have the standard run-of-the-mill argument types out of the way,
+lets get a little wild and crazy. Lets say that we want our optimizer to accept
+a <strong>list</strong> of optimizations to perform, allowing duplicates. For example, we
+might want to run: “<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-dce</span> <span class="pre">-constprop</span> <span class="pre">-inline</span> <span class="pre">-dce</span> <span class="pre">-strip</span></tt>”. In this
+case, the order of the arguments and the number of appearances is very
+important. This is what the “<tt class="docutils literal"><span class="pre">cl::list</span></tt>” template is for. First, start by
+defining an enum of the optimizations that you would like to perform:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">Opts</span> <span class="p">{</span>
+ <span class="c1">// 'inline' is a C++ keyword, so name it 'inlining'</span>
+ <span class="n">dce</span><span class="p">,</span> <span class="n">constprop</span><span class="p">,</span> <span class="n">inlining</span><span class="p">,</span> <span class="n">strip</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Then define your “<tt class="docutils literal"><span class="pre">cl::list</span></tt>” variable:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">Opts</span><span class="o">></span> <span class="n">OptimizationList</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Available Optimizations:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">dce</span> <span class="p">,</span> <span class="s">"Dead Code Elimination"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">constprop</span> <span class="p">,</span> <span class="s">"Constant Propagation"</span><span class="p">),</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">inlining</span><span class="p">,</span> <span class="s">"inline"</span><span class="p">,</span> <span class="s">"Procedure Integration"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">strip</span> <span class="p">,</span> <span class="s">"Strip Symbols"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>This defines a variable that is conceptually of the type
+“<tt class="docutils literal"><span class="pre">std::vector<enum</span> <span class="pre">Opts></span></tt>”. Thus, you can access it with standard vector
+methods:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">OptimizationList</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">OptimizationList</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>... to iterate through the list of options specified.</p>
+<p>Note that the “<tt class="docutils literal"><span class="pre">cl::list</span></tt>” template is completely general and may be used with
+any data types or other arguments that you can use with the “<tt class="docutils literal"><span class="pre">cl::opt</span></tt>”
+template. One especially useful way to use a list is to capture all of the
+positional arguments together if there may be more than one specified. In the
+case of a linker, for example, the linker takes several ‘<tt class="docutils literal"><span class="pre">.o</span></tt>‘ files, and
+needs to capture them into a list. This is naturally specified as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilenames</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<Input files>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">OneOrMore</span><span class="p">);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>This variable works just like a “<tt class="docutils literal"><span class="pre">vector<string></span></tt>” object. As such, accessing
+the list is simple, just like above. In this example, we used the
+<a class="reference internal" href="#cl-oneormore">cl::OneOrMore</a> modifier to inform the CommandLine library that it is an error
+if the user does not specify any <tt class="docutils literal"><span class="pre">.o</span></tt> files on our command line. Again, this
+just reduces the amount of checking we have to do.</p>
+</div>
+<div class="section" id="collecting-options-as-a-set-of-flags">
+<h3><a class="toc-backref" href="#id15">Collecting options as a set of flags</a><a class="headerlink" href="#collecting-options-as-a-set-of-flags" title="Permalink to this headline">¶</a></h3>
+<p>Instead of collecting sets of options in a list, it is also possible to gather
+information for enum values in a <strong>bit vector</strong>. The representation used by the
+<a class="reference internal" href="#cl-bits">cl::bits</a> class is an <tt class="docutils literal"><span class="pre">unsigned</span></tt> integer. An enum value is represented by a
+0/1 in the enum’s ordinal value bit position. 1 indicating that the enum was
+specified, 0 otherwise. As each specified value is parsed, the resulting enum’s
+bit is set in the option’s bit vector:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">bits</span> <span class="o">|=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="p">(</span><span class="kt">unsigned</span><span class="p">)</span><span class="k">enum</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Options that are specified multiple times are redundant. Any instances after
+the first are discarded.</p>
+<p>Reworking the above list example, we could replace <a class="reference internal" href="#cl-list">cl::list</a> with <a class="reference internal" href="#cl-bits">cl::bits</a>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">bits</span><span class="o"><</span><span class="n">Opts</span><span class="o">></span> <span class="n">OptimizationBits</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Available Optimizations:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">dce</span> <span class="p">,</span> <span class="s">"Dead Code Elimination"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">constprop</span> <span class="p">,</span> <span class="s">"Constant Propagation"</span><span class="p">),</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">inlining</span><span class="p">,</span> <span class="s">"inline"</span><span class="p">,</span> <span class="s">"Procedure Integration"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">strip</span> <span class="p">,</span> <span class="s">"Strip Symbols"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>To test to see if <tt class="docutils literal"><span class="pre">constprop</span></tt> was specified, we can use the <tt class="docutils literal"><span class="pre">cl:bits::isSet</span></tt>
+function:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">OptimizationBits</span><span class="p">.</span><span class="n">isSet</span><span class="p">(</span><span class="n">constprop</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It’s also possible to get the raw bit vector using the <tt class="docutils literal"><span class="pre">cl::bits::getBits</span></tt>
+function:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">unsigned</span> <span class="n">bits</span> <span class="o">=</span> <span class="n">OptimizationBits</span><span class="p">.</span><span class="n">getBits</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>Finally, if external storage is used, then the location specified must be of
+<strong>type</strong> <tt class="docutils literal"><span class="pre">unsigned</span></tt>. In all other ways a <a class="reference internal" href="#cl-bits">cl::bits</a> option is equivalent to a
+<a class="reference internal" href="#cl-list">cl::list</a> option.</p>
+</div>
+<div class="section" id="adding-freeform-text-to-help-output">
+<span id="additional-extra-text"></span><h3><a class="toc-backref" href="#id16">Adding freeform text to help output</a><a class="headerlink" href="#adding-freeform-text-to-help-output" title="Permalink to this headline">¶</a></h3>
+<p>As our program grows and becomes more mature, we may decide to put summary
+information about what it does into the help output. The help output is styled
+to look similar to a Unix <tt class="docutils literal"><span class="pre">man</span></tt> page, providing concise information about a
+program. Unix <tt class="docutils literal"><span class="pre">man</span></tt> pages, however often have a description about what the
+program does. To add this to your CommandLine program, simply pass a third
+argument to the <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a> call in main. This additional
+argument is then printed as the overview information for your program, allowing
+you to include any additional information that you want. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">ParseCommandLineOptions</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">,</span> <span class="s">" CommandLine compiler example</span><span class="se">\n\n</span><span class="s">"</span>
+ <span class="s">" This program blah blah blah...</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>would yield the help output:</p>
+<div class="highlight-python"><pre>**OVERVIEW: CommandLine compiler example
+
+ This program blah blah blah...**
+
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ ...
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename</pre>
+</div>
+</div>
+<div class="section" id="grouping-options-into-categories">
+<span id="id1"></span><h3><a class="toc-backref" href="#id17">Grouping options into categories</a><a class="headerlink" href="#grouping-options-into-categories" title="Permalink to this headline">¶</a></h3>
+<p>If our program has a large number of options it may become difficult for users
+of our tool to navigate the output of <tt class="docutils literal"><span class="pre">-help</span></tt>. To alleviate this problem we
+can put our options into categories. This can be done by declaring option
+categories (<a class="reference internal" href="#cl-optioncategory">cl::OptionCategory</a> objects) and then placing our options into
+these categories using the <a class="reference internal" href="#cl-cat">cl::cat</a> option attribute. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">OptionCategory</span> <span class="n">StageSelectionCat</span><span class="p">(</span><span class="s">"Stage Selection Options"</span><span class="p">,</span>
+ <span class="s">"These control which stages are run."</span><span class="p">);</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Preprocessor</span><span class="p">(</span><span class="s">"E"</span><span class="p">,</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Run preprocessor stage."</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">cat</span><span class="p">(</span><span class="n">StageSelectionCat</span><span class="p">));</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">NoLink</span><span class="p">(</span><span class="s">"c"</span><span class="p">,</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Run all stages except linking."</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">cat</span><span class="p">(</span><span class="n">StageSelectionCat</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>The output of <tt class="docutils literal"><span class="pre">-help</span></tt> will become categorized if an option category is
+declared. The output looks something like</p>
+<div class="highlight-python"><pre>OVERVIEW: This is a small program to demo the LLVM CommandLine API
+USAGE: Sample [options]
+
+OPTIONS:
+
+ General options:
+
+ -help - Display available options (-help-hidden for more)
+ -help-list - Display list of available options (-help-list-hidden for more)
+
+
+ Stage Selection Options:
+ These control which stages are run.
+
+ -E - Run preprocessor stage.
+ -c - Run all stages except linking.</pre>
+</div>
+<p>In addition to the behaviour of <tt class="docutils literal"><span class="pre">-help</span></tt> changing when an option category is
+declared, the command line option <tt class="docutils literal"><span class="pre">-help-list</span></tt> becomes visible which will
+print the command line options as uncategorized list.</p>
+<p>Note that Options that are not explicitly categorized will be placed in the
+<tt class="docutils literal"><span class="pre">cl::GeneralCategory</span></tt> category.</p>
+</div>
+</div>
+<div class="section" id="reference-guide">
+<span id="id2"></span><h2><a class="toc-backref" href="#id18">Reference Guide</a><a class="headerlink" href="#reference-guide" title="Permalink to this headline">¶</a></h2>
+<p>Now that you know the basics of how to use the CommandLine library, this section
+will give you the detailed information you need to tune how command line options
+work, as well as information on more “advanced” command line option processing
+capabilities.</p>
+<div class="section" id="positional-options">
+<span id="positional-arguments-section"></span><span id="positional-arguments"></span><span id="positional-argument"></span><span id="positional"></span><span id="id3"></span><h3><a class="toc-backref" href="#id19">Positional Arguments</a><a class="headerlink" href="#positional-options" title="Permalink to this headline">¶</a></h3>
+<p>Positional arguments are those arguments that are not named, and are not
+specified with a hyphen. Positional arguments should be used when an option is
+specified by its position alone. For example, the standard Unix <tt class="docutils literal"><span class="pre">grep</span></tt> tool
+takes a regular expression argument, and an optional filename to search through
+(which defaults to standard input if a filename is not specified). Using the
+CommandLine library, this would be specified as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Regex</span> <span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<regular expression>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Required</span><span class="p">);</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Filename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="s">"-"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>Given these two option declarations, the <tt class="docutils literal"><span class="pre">-help</span></tt> output for our grep
+replacement would look like this:</p>
+<div class="highlight-python"><pre>USAGE: spiffygrep [options] <regular expression> <input file>
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)</pre>
+</div>
+<p>... and the resultant program could be used just like the standard <tt class="docutils literal"><span class="pre">grep</span></tt>
+tool.</p>
+<p>Positional arguments are sorted by their order of construction. This means that
+command line options will be ordered according to how they are listed in a .cpp
+file, but will not have an ordering defined if the positional arguments are
+defined in multiple .cpp files. The fix for this problem is simply to define
+all of your positional arguments in one .cpp file.</p>
+<div class="section" id="specifying-positional-options-with-hyphens">
+<h4><a class="toc-backref" href="#id20">Specifying positional options with hyphens</a><a class="headerlink" href="#specifying-positional-options-with-hyphens" title="Permalink to this headline">¶</a></h4>
+<p>Sometimes you may want to specify a value to your positional argument that
+starts with a hyphen (for example, searching for ‘<tt class="docutils literal"><span class="pre">-foo</span></tt>‘ in a file). At
+first, you will have trouble doing this, because it will try to find an argument
+named ‘<tt class="docutils literal"><span class="pre">-foo</span></tt>‘, and will fail (and single quotes will not save you). Note
+that the system <tt class="docutils literal"><span class="pre">grep</span></tt> has the same problem:</p>
+<div class="highlight-python"><pre>$ spiffygrep '-foo' test.txt
+Unknown command line argument '-foo'. Try: spiffygrep -help'
+
+$ grep '-foo' test.txt
+grep: illegal option -- f
+grep: illegal option -- o
+grep: illegal option -- o
+Usage: grep -hblcnsviw pattern file . . .</pre>
+</div>
+<p>The solution for this problem is the same for both your tool and the system
+version: use the ‘<tt class="docutils literal"><span class="pre">--</span></tt>‘ marker. When the user specifies ‘<tt class="docutils literal"><span class="pre">--</span></tt>‘ on the
+command line, it is telling the program that all options after the ‘<tt class="docutils literal"><span class="pre">--</span></tt>‘
+should be treated as positional arguments, not options. Thus, we can use it
+like this:</p>
+<div class="highlight-python"><pre>$ spiffygrep -- -foo test.txt
+ ...output...</pre>
+</div>
+</div>
+<div class="section" id="determining-absolute-position-with-getposition">
+<h4><a class="toc-backref" href="#id21">Determining absolute position with getPosition()</a><a class="headerlink" href="#determining-absolute-position-with-getposition" title="Permalink to this headline">¶</a></h4>
+<p>Sometimes an option can affect or modify the meaning of another option. For
+example, consider <tt class="docutils literal"><span class="pre">gcc</span></tt>‘s <tt class="docutils literal"><span class="pre">-x</span> <span class="pre">LANG</span></tt> option. This tells <tt class="docutils literal"><span class="pre">gcc</span></tt> to ignore the
+suffix of subsequent positional arguments and force the file to be interpreted
+as if it contained source code in language <tt class="docutils literal"><span class="pre">LANG</span></tt>. In order to handle this
+properly, you need to know the absolute position of each argument, especially
+those in lists, so their interaction(s) can be applied correctly. This is also
+useful for options like <tt class="docutils literal"><span class="pre">-llibname</span></tt> which is actually a positional argument
+that starts with a dash.</p>
+<p>So, generally, the problem is that you have two <tt class="docutils literal"><span class="pre">cl::list</span></tt> variables that
+interact in some way. To ensure the correct interaction, you can use the
+<tt class="docutils literal"><span class="pre">cl::list::getPosition(optnum)</span></tt> method. This method returns the absolute
+position (as found on the command line) of the <tt class="docutils literal"><span class="pre">optnum</span></tt> item in the
+<tt class="docutils literal"><span class="pre">cl::list</span></tt>.</p>
+<p>The idiom for usage is like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">Files</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">OneOrMore</span><span class="p">);</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">Libraries</span><span class="p">(</span><span class="s">"l"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">ZeroOrMore</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="n">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>::</span><span class="n">iterator</span> <span class="n">fileIt</span> <span class="o">=</span> <span class="n">Files</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>::</span><span class="n">iterator</span> <span class="n">libIt</span> <span class="o">=</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+ <span class="kt">unsigned</span> <span class="n">libPos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">filePos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">while</span> <span class="p">(</span> <span class="mi">1</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span> <span class="n">libIt</span> <span class="o">!=</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">end</span><span class="p">()</span> <span class="p">)</span>
+ <span class="n">libPos</span> <span class="o">=</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">getPosition</span><span class="p">(</span> <span class="n">libIt</span> <span class="o">-</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">begin</span><span class="p">()</span> <span class="p">);</span>
+ <span class="k">else</span>
+ <span class="n">libPos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span> <span class="n">fileIt</span> <span class="o">!=</span> <span class="n">Files</span><span class="p">.</span><span class="n">end</span><span class="p">()</span> <span class="p">)</span>
+ <span class="n">filePos</span> <span class="o">=</span> <span class="n">Files</span><span class="p">.</span><span class="n">getPosition</span><span class="p">(</span> <span class="n">fileIt</span> <span class="o">-</span> <span class="n">Files</span><span class="p">.</span><span class="n">begin</span><span class="p">()</span> <span class="p">);</span>
+ <span class="k">else</span>
+ <span class="n">filePos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="k">if</span> <span class="p">(</span> <span class="n">filePos</span> <span class="o">!=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="p">(</span><span class="n">libPos</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="n">filePos</span> <span class="o"><</span> <span class="n">libPos</span><span class="p">)</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Source File Is next</span>
+ <span class="o">++</span><span class="n">fileIt</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">else</span> <span class="k">if</span> <span class="p">(</span> <span class="n">libPos</span> <span class="o">!=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="p">(</span><span class="n">filePos</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="n">libPos</span> <span class="o"><</span> <span class="n">filePos</span><span class="p">)</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Library is next</span>
+ <span class="o">++</span><span class="n">libIt</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">else</span>
+ <span class="k">break</span><span class="p">;</span> <span class="c1">// we're done with the list</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that, for compatibility reasons, the <tt class="docutils literal"><span class="pre">cl::opt</span></tt> also supports an
+<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">getPosition()</span></tt> option that will provide the absolute position of
+that option. You can apply the same approach as above with a <tt class="docutils literal"><span class="pre">cl::opt</span></tt> and a
+<tt class="docutils literal"><span class="pre">cl::list</span></tt> option as you can with two lists.</p>
+</div>
+<div class="section" id="the-cl-consumeafter-modifier">
+<span id="this-section-for-more-information"></span><span id="cl-consumeafter"></span><span id="interpreter-style-options"></span><h4><a class="toc-backref" href="#id22">The <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> modifier</a><a class="headerlink" href="#the-cl-consumeafter-modifier" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> <a class="reference internal" href="#formatting-option">formatting option</a> is used to construct programs that
+use “interpreter style” option processing. With this style of option
+processing, all arguments specified after the last positional argument are
+treated as special interpreter arguments that are not interpreted by the command
+line argument.</p>
+<p>As a concrete example, lets say we are developing a replacement for the standard
+Unix Bourne shell (<tt class="docutils literal"><span class="pre">/bin/sh</span></tt>). To run <tt class="docutils literal"><span class="pre">/bin/sh</span></tt>, first you specify options
+to the shell itself (like <tt class="docutils literal"><span class="pre">-x</span></tt> which turns on trace output), then you specify
+the name of the script to run, then you specify arguments to the script. These
+arguments to the script are parsed by the Bourne shell command line option
+processor, but are not interpreted as options to the shell itself. Using the
+CommandLine library, we would specify this as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Script</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input script>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="s">"-"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Argv</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">ConsumeAfter</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<program arguments>..."</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Trace</span><span class="p">(</span><span class="s">"x"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Enable trace output"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>which automatically provides the help output:</p>
+<div class="highlight-python"><pre>USAGE: spiffysh [options] <input script> <program arguments>...
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ -x - Enable trace output</pre>
+</div>
+<p>At runtime, if we run our new shell replacement as <tt class="docutils literal"><span class="pre">`spiffysh</span> <span class="pre">-x</span> <span class="pre">test.sh</span> <span class="pre">-a</span> <span class="pre">-x</span>
+<span class="pre">-y</span> <span class="pre">bar</span></tt>‘, the <tt class="docutils literal"><span class="pre">Trace</span></tt> variable will be set to true, the <tt class="docutils literal"><span class="pre">Script</span></tt> variable
+will be set to “<tt class="docutils literal"><span class="pre">test.sh</span></tt>”, and the <tt class="docutils literal"><span class="pre">Argv</span></tt> list will contain <tt class="docutils literal"><span class="pre">["-a",</span> <span class="pre">"-x",</span>
+<span class="pre">"-y",</span> <span class="pre">"bar"]</span></tt>, because they were specified after the last positional argument
+(which is the script name).</p>
+<p>There are several limitations to when <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> options can be
+specified. For example, only one <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> can be specified per
+program, there must be at least one <a class="reference internal" href="#positional-argument">positional argument</a> specified, there must
+not be any <a class="reference internal" href="#cl-list">cl::list</a> positional arguments, and the <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> option
+should be a <a class="reference internal" href="#cl-list">cl::list</a> option.</p>
+</div>
+</div>
+<div class="section" id="internal-vs-external-storage">
+<span id="can-be-changed"></span><span id="id4"></span><h3><a class="toc-backref" href="#id23">Internal vs External Storage</a><a class="headerlink" href="#internal-vs-external-storage" title="Permalink to this headline">¶</a></h3>
+<p>By default, all command line options automatically hold the value that they
+parse from the command line. This is very convenient in the common case,
+especially when combined with the ability to define command line options in the
+files that use them. This is called the internal storage model.</p>
+<p>Sometimes, however, it is nice to separate the command line option processing
+code from the storage of the value parsed. For example, lets say that we have a
+‘<tt class="docutils literal"><span class="pre">-debug</span></tt>‘ option that we would like to use to enable debug information across
+the entire body of our program. In this case, the boolean value controlling the
+debug code should be globally accessible (in a header file, for example) yet the
+command line option processing code should not be exposed to all of these
+clients (requiring lots of .cpp files to <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">CommandLine.h</span></tt>).</p>
+<p>To do this, set up your .h file with your option, like this for example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// DebugFlag.h - Get access to the '-debug' command line option</span>
+<span class="c1">//</span>
+
+<span class="c1">// DebugFlag - This boolean is set to true if the '-debug' command line option</span>
+<span class="c1">// is specified. This should probably not be referenced directly, instead, use</span>
+<span class="c1">// the DEBUG macro below.</span>
+<span class="c1">//</span>
+<span class="k">extern</span> <span class="kt">bool</span> <span class="n">DebugFlag</span><span class="p">;</span>
+
+<span class="cp">// DEBUG macro - This macro should be used by code to emit debug information.</span>
+<span class="cp">// In the '-debug' option is specified on the command line, and if this is a</span>
+<span class="cp">// debug build, then the code specified as the option to the macro will be</span>
+<span class="cp">// executed. Otherwise it will not be.</span>
+<span class="cp">#ifdef NDEBUG</span>
+<span class="cp">#define DEBUG(X)</span>
+<span class="cp">#else</span>
+<span class="cp">#define DEBUG(X) do { if (DebugFlag) { X; } } while (0)</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>This allows clients to blissfully use the <tt class="docutils literal"><span class="pre">DEBUG()</span></tt> macro, or the
+<tt class="docutils literal"><span class="pre">DebugFlag</span></tt> explicitly if they want to. Now we just need to be able to set
+the <tt class="docutils literal"><span class="pre">DebugFlag</span></tt> boolean when the option is set. To do this, we pass an
+additional argument to our command line argument processor, and we specify where
+to fill in with the <a class="reference internal" href="#cl-location">cl::location</a> attribute:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">DebugFlag</span><span class="p">;</span> <span class="c1">// the actual value</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="p">,</span> <span class="kc">true</span><span class="o">></span> <span class="c1">// The parser</span>
+<span class="n">Debug</span><span class="p">(</span><span class="s">"debug"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Enable debug output"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Hidden</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">location</span><span class="p">(</span><span class="n">DebugFlag</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>In the above example, we specify “<tt class="docutils literal"><span class="pre">true</span></tt>” as the second argument to the
+<a class="reference internal" href="#cl-opt">cl::opt</a> template, indicating that the template should not maintain a copy of
+the value itself. In addition to this, we specify the <a class="reference internal" href="#cl-location">cl::location</a>
+attribute, so that <tt class="docutils literal"><span class="pre">DebugFlag</span></tt> is automatically set.</p>
+</div>
+<div class="section" id="option-attributes">
+<h3><a class="toc-backref" href="#id24">Option Attributes</a><a class="headerlink" href="#option-attributes" title="Permalink to this headline">¶</a></h3>
+<p>This section describes the basic attributes that you can specify on options.</p>
+<ul>
+<li><p class="first">The option name attribute (which is required for all options, except
+<a class="reference internal" href="#positional-options">positional options</a>) specifies what the option name is. This option is
+specified in simple double quotes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet</span><span class="p">(</span><span class="s">"quiet"</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+</ul>
+<ul class="simple" id="cl-desc">
+<li>The <strong>cl::desc</strong> attribute specifies a description for the option to be
+shown in the <tt class="docutils literal"><span class="pre">-help</span></tt> output for the program. This attribute supports
+multi-line descriptions with lines separated by ‘n’.</li>
+</ul>
+<ul class="simple" id="cl-value-desc">
+<li>The <strong>cl::value_desc</strong> attribute specifies a string that can be used to
+fine tune the <tt class="docutils literal"><span class="pre">-help</span></tt> output for a command line option. Look <a class="reference internal" href="#here">here</a> for an
+example.</li>
+</ul>
+<ul id="cl-init">
+<li><p class="first">The <strong>cl::init</strong> attribute specifies an initial value for a <a class="reference internal" href="#scalar">scalar</a>
+option. If this attribute is not specified then the command line option value
+defaults to the value created by the default constructor for the
+type.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">If you specify both <strong>cl::init</strong> and <strong>cl::location</strong> for an option, you
+must specify <strong>cl::location</strong> first, so that when the command-line parser
+sees <strong>cl::init</strong>, it knows where to put the initial value. (You will get an
+error at runtime if you don’t put them in the right order.)</p>
+</div>
+</li>
+</ul>
+<ul class="simple" id="cl-location">
+<li>The <strong>cl::location</strong> attribute where to store the value for a parsed command
+line option if using external storage. See the section on <a class="reference internal" href="#internal-vs-external-storage">Internal vs
+External Storage</a> for more information.</li>
+</ul>
+<ul class="simple" id="cl-aliasopt">
+<li>The <strong>cl::aliasopt</strong> attribute specifies which option a <a class="reference internal" href="#cl-alias">cl::alias</a> option is
+an alias for.</li>
+</ul>
+<ul id="cl-values">
+<li><p class="first">The <strong>cl::values</strong> attribute specifies the string-to-value mapping to be used
+by the generic parser. It takes a list of (option, value, description)
+triplets that specify the option name, the value mapped to, and the
+description shown in the <tt class="docutils literal"><span class="pre">-help</span></tt> for the tool. Because the generic parser
+is used most frequently with enum values, two macros are often useful:</p>
+<ol class="arabic simple">
+<li>The <strong>clEnumVal</strong> macro is used as a nice simple way to specify a triplet
+for an enum. This macro automatically makes the option name be the same as
+the enum name. The first option to the macro is the enum, the second is
+the description for the command line option.</li>
+<li>The <strong>clEnumValN</strong> macro is used to specify macro options where the option
+name doesn’t equal the enum name. For this macro, the first argument is
+the enum value, the second is the flag name, and the second is the
+description.</li>
+</ol>
+<p>You will get a compile time error if you try to use cl::values with a parser
+that does not support it.</p>
+</li>
+</ul>
+<ul class="simple" id="cl-multi-val">
+<li>The <strong>cl::multi_val</strong> attribute specifies that this option takes has multiple
+values (example: <tt class="docutils literal"><span class="pre">-sectalign</span> <span class="pre">segname</span> <span class="pre">sectname</span> <span class="pre">sectvalue</span></tt>). This attribute
+takes one unsigned argument - the number of values for the option. This
+attribute is valid only on <tt class="docutils literal"><span class="pre">cl::list</span></tt> options (and will fail with compile
+error if you try to use it with other option types). It is allowed to use all
+of the usual modifiers on multi-valued options (besides
+<tt class="docutils literal"><span class="pre">cl::ValueDisallowed</span></tt>, obviously).</li>
+</ul>
+<ul class="simple" id="cl-cat">
+<li>The <strong>cl::cat</strong> attribute specifies the option category that the option
+belongs to. The category should be a <a class="reference internal" href="#cl-optioncategory">cl::OptionCategory</a> object.</li>
+</ul>
+</div>
+<div class="section" id="option-modifiers">
+<h3><a class="toc-backref" href="#id25">Option Modifiers</a><a class="headerlink" href="#option-modifiers" title="Permalink to this headline">¶</a></h3>
+<p>Option modifiers are the flags and expressions that you pass into the
+constructors for <a class="reference internal" href="#cl-opt">cl::opt</a> and <a class="reference internal" href="#cl-list">cl::list</a>. These modifiers give you the
+ability to tweak how options are parsed and how <tt class="docutils literal"><span class="pre">-help</span></tt> output is generated to
+fit your application well.</p>
+<p>These options fall into five main categories:</p>
+<ol class="arabic simple">
+<li>Hiding an option from <tt class="docutils literal"><span class="pre">-help</span></tt> output</li>
+<li>Controlling the number of occurrences required and allowed</li>
+<li>Controlling whether or not a value must be specified</li>
+<li>Controlling other formatting options</li>
+<li>Miscellaneous option modifiers</li>
+</ol>
+<p>It is not possible to specify two options from the same category (you’ll get a
+runtime error) to a single option, except for options in the miscellaneous
+category. The CommandLine library specifies defaults for all of these settings
+that are the most useful in practice and the most common, which mean that you
+usually shouldn’t have to worry about these.</p>
+<div class="section" id="hiding-an-option-from-help-output">
+<h4><a class="toc-backref" href="#id26">Hiding an option from <tt class="docutils literal"><span class="pre">-help</span></tt> output</a><a class="headerlink" href="#hiding-an-option-from-help-output" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::NotHidden</span></tt>, <tt class="docutils literal"><span class="pre">cl::Hidden</span></tt>, and <tt class="docutils literal"><span class="pre">cl::ReallyHidden</span></tt> modifiers are
+used to control whether or not an option appears in the <tt class="docutils literal"><span class="pre">-help</span></tt> and
+<tt class="docutils literal"><span class="pre">-help-hidden</span></tt> output for the compiled program:</p>
+<ul class="simple" id="cl-nothidden">
+<li>The <strong>cl::NotHidden</strong> modifier (which is the default for <a class="reference internal" href="#cl-opt">cl::opt</a> and
+<a class="reference internal" href="#cl-list">cl::list</a> options) indicates the option is to appear in both help
+listings.</li>
+</ul>
+<ul class="simple" id="cl-hidden">
+<li>The <strong>cl::Hidden</strong> modifier (which is the default for <a class="reference internal" href="#cl-alias">cl::alias</a> options)
+indicates that the option should not appear in the <tt class="docutils literal"><span class="pre">-help</span></tt> output, but
+should appear in the <tt class="docutils literal"><span class="pre">-help-hidden</span></tt> output.</li>
+</ul>
+<ul class="simple" id="cl-reallyhidden">
+<li>The <strong>cl::ReallyHidden</strong> modifier indicates that the option should not appear
+in any help output.</li>
+</ul>
+</div>
+<div class="section" id="controlling-the-number-of-occurrences-required-and-allowed">
+<h4><a class="toc-backref" href="#id27">Controlling the number of occurrences required and allowed</a><a class="headerlink" href="#controlling-the-number-of-occurrences-required-and-allowed" title="Permalink to this headline">¶</a></h4>
+<p>This group of options is used to control how many time an option is allowed (or
+required) to be specified on the command line of your program. Specifying a
+value for this setting allows the CommandLine library to do error checking for
+you.</p>
+<p>The allowed values for this option group are:</p>
+<ul class="simple" id="cl-optional">
+<li>The <strong>cl::Optional</strong> modifier (which is the default for the <a class="reference internal" href="#cl-opt">cl::opt</a> and
+<a class="reference internal" href="#cl-alias">cl::alias</a> classes) indicates that your program will allow either zero or
+one occurrence of the option to be specified.</li>
+</ul>
+<ul class="simple" id="cl-zeroormore">
+<li>The <strong>cl::ZeroOrMore</strong> modifier (which is the default for the <a class="reference internal" href="#cl-list">cl::list</a>
+class) indicates that your program will allow the option to be specified zero
+or more times.</li>
+</ul>
+<ul class="simple" id="cl-required">
+<li>The <strong>cl::Required</strong> modifier indicates that the specified option must be
+specified exactly one time.</li>
+</ul>
+<ul class="simple" id="cl-oneormore">
+<li>The <strong>cl::OneOrMore</strong> modifier indicates that the option must be specified at
+least one time.</li>
+<li>The <strong>cl::ConsumeAfter</strong> modifier is described in the <a class="reference internal" href="#positional-arguments-section">Positional arguments
+section</a>.</li>
+</ul>
+<p>If an option is not specified, then the value of the option is equal to the
+value specified by the <a class="reference internal" href="#cl-init">cl::init</a> attribute. If the <tt class="docutils literal"><span class="pre">cl::init</span></tt> attribute is
+not specified, the option value is initialized with the default constructor for
+the data type.</p>
+<p>If an option is specified multiple times for an option of the <a class="reference internal" href="#cl-opt">cl::opt</a> class,
+only the last value will be retained.</p>
+</div>
+<div class="section" id="controlling-whether-or-not-a-value-must-be-specified">
+<h4><a class="toc-backref" href="#id28">Controlling whether or not a value must be specified</a><a class="headerlink" href="#controlling-whether-or-not-a-value-must-be-specified" title="Permalink to this headline">¶</a></h4>
+<p>This group of options is used to control whether or not the option allows a
+value to be present. In the case of the CommandLine library, a value is either
+specified with an equal sign (e.g. ‘<tt class="docutils literal"><span class="pre">-index-depth=17</span></tt>‘) or as a trailing
+string (e.g. ‘<tt class="docutils literal"><span class="pre">-o</span> <span class="pre">a.out</span></tt>‘).</p>
+<p>The allowed values for this option group are:</p>
+<ul class="simple" id="cl-valueoptional">
+<li>The <strong>cl::ValueOptional</strong> modifier (which is the default for <tt class="docutils literal"><span class="pre">bool</span></tt> typed
+options) specifies that it is acceptable to have a value, or not. A boolean
+argument can be enabled just by appearing on the command line, or it can have
+an explicit ‘<tt class="docutils literal"><span class="pre">-foo=true</span></tt>‘. If an option is specified with this mode, it is
+illegal for the value to be provided without the equal sign. Therefore
+‘<tt class="docutils literal"><span class="pre">-foo</span> <span class="pre">true</span></tt>‘ is illegal. To get this behavior, you must use
+the <a class="reference internal" href="#cl-valuerequired">cl::ValueRequired</a> modifier.</li>
+</ul>
+<ul class="simple" id="cl-valuerequired">
+<li>The <strong>cl::ValueRequired</strong> modifier (which is the default for all other types
+except for <a class="reference internal" href="#unnamed-alternatives-using-the-generic-parser">unnamed alternatives using the generic parser</a>) specifies that a
+value must be provided. This mode informs the command line library that if an
+option is not provides with an equal sign, that the next argument provided
+must be the value. This allows things like ‘<tt class="docutils literal"><span class="pre">-o</span> <span class="pre">a.out</span></tt>‘ to work.</li>
+</ul>
+<ul class="simple" id="cl-valuedisallowed">
+<li>The <strong>cl::ValueDisallowed</strong> modifier (which is the default for <a class="reference internal" href="#unnamed-alternatives-using-the-generic-parser">unnamed
+alternatives using the generic parser</a>) indicates that it is a runtime error
+for the user to specify a value. This can be provided to disallow users from
+providing options to boolean options (like ‘<tt class="docutils literal"><span class="pre">-foo=true</span></tt>‘).</li>
+</ul>
+<p>In general, the default values for this option group work just like you would
+want them to. As mentioned above, you can specify the <a class="reference internal" href="#cl-valuedisallowed">cl::ValueDisallowed</a>
+modifier to a boolean argument to restrict your command line parser. These
+options are mostly useful when <a class="reference internal" href="#extending-the-library">extending the library</a>.</p>
+</div>
+<div class="section" id="controlling-other-formatting-options">
+<span id="formatting-option"></span><h4><a class="toc-backref" href="#id29">Controlling other formatting options</a><a class="headerlink" href="#controlling-other-formatting-options" title="Permalink to this headline">¶</a></h4>
+<p>The formatting option group is used to specify that the command line option has
+special abilities and is otherwise different from other command line arguments.
+As usual, you can only specify one of these arguments at most.</p>
+<ul class="simple" id="cl-normalformatting">
+<li>The <strong>cl::NormalFormatting</strong> modifier (which is the default all options)
+specifies that this option is “normal”.</li>
+</ul>
+<ul class="simple" id="cl-positional">
+<li>The <strong>cl::Positional</strong> modifier specifies that this is a positional argument
+that does not have a command line option associated with it. See the
+<a class="reference internal" href="#positional-arguments">Positional Arguments</a> section for more information.</li>
+<li>The <strong>cl::ConsumeAfter</strong> modifier specifies that this option is used to
+capture “interpreter style” arguments. See <a class="reference internal" href="#this-section-for-more-information">this section for more
+information</a>.</li>
+</ul>
+<ul class="simple" id="cl-prefix">
+<span id="prefix"></span><li>The <strong>cl::Prefix</strong> modifier specifies that this option prefixes its value.
+With ‘Prefix’ options, the equal sign does not separate the value from the
+option name specified. Instead, the value is everything after the prefix,
+including any equal sign if present. This is useful for processing odd
+arguments like <tt class="docutils literal"><span class="pre">-lmalloc</span></tt> and <tt class="docutils literal"><span class="pre">-L/usr/lib</span></tt> in a linker tool or
+<tt class="docutils literal"><span class="pre">-DNAME=value</span></tt> in a compiler tool. Here, the ‘<tt class="docutils literal"><span class="pre">l</span></tt>‘, ‘<tt class="docutils literal"><span class="pre">D</span></tt>‘ and ‘<tt class="docutils literal"><span class="pre">L</span></tt>‘
+options are normal string (or list) options, that have the <strong>cl::Prefix</strong>
+modifier added to allow the CommandLine library to recognize them. Note that
+<strong>cl::Prefix</strong> options must not have the <strong>cl::ValueDisallowed</strong> modifier
+specified.</li>
+</ul>
+<ul class="simple" id="cl-grouping">
+<span id="grouping"></span><li>The <strong>cl::Grouping</strong> modifier is used to implement Unix-style tools (like
+<tt class="docutils literal"><span class="pre">ls</span></tt>) that have lots of single letter arguments, but only require a single
+dash. For example, the ‘<tt class="docutils literal"><span class="pre">ls</span> <span class="pre">-labF</span></tt>‘ command actually enables four different
+options, all of which are single letters. Note that <strong>cl::Grouping</strong> options
+cannot have values.</li>
+</ul>
+<p>The CommandLine library does not restrict how you use the <strong>cl::Prefix</strong> or
+<strong>cl::Grouping</strong> modifiers, but it is possible to specify ambiguous argument
+settings. Thus, it is possible to have multiple letter options that are prefix
+or grouping options, and they will still work as designed.</p>
+<p>To do this, the CommandLine library uses a greedy algorithm to parse the input
+option into (potentially multiple) prefix and grouping options. The strategy
+basically looks like this:</p>
+<div class="highlight-python"><pre>parse(string OrigInput) {
+
+1. string input = OrigInput;
+2. if (isOption(input)) return getOption(input).parse(); // Normal option
+3. while (!isOption(input) && !input.empty()) input.pop_back(); // Remove the last letter
+4. if (input.empty()) return error(); // No matching option
+5. if (getOption(input).isPrefix())
+ return getOption(input).parse(input);
+6. while (!input.empty()) { // Must be grouping options
+ getOption(input).parse();
+ OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());
+ input = OrigInput;
+ while (!isOption(input) && !input.empty()) input.pop_back();
+ }
+7. if (!OrigInput.empty()) error();
+
+}</pre>
+</div>
+</div>
+<div class="section" id="miscellaneous-option-modifiers">
+<h4><a class="toc-backref" href="#id30">Miscellaneous option modifiers</a><a class="headerlink" href="#miscellaneous-option-modifiers" title="Permalink to this headline">¶</a></h4>
+<p>The miscellaneous option modifiers are the only flags where you can specify more
+than one flag from the set: they are not mutually exclusive. These flags
+specify boolean properties that modify the option.</p>
+<ul class="simple" id="cl-commaseparated">
+<li>The <strong>cl::CommaSeparated</strong> modifier indicates that any commas specified for an
+option’s value should be used to split the value up into multiple values for
+the option. For example, these two options are equivalent when
+<tt class="docutils literal"><span class="pre">cl::CommaSeparated</span></tt> is specified: “<tt class="docutils literal"><span class="pre">-foo=a</span> <span class="pre">-foo=b</span> <span class="pre">-foo=c</span></tt>” and
+“<tt class="docutils literal"><span class="pre">-foo=a,b,c</span></tt>”. This option only makes sense to be used in a case where the
+option is allowed to accept one or more values (i.e. it is a <a class="reference internal" href="#cl-list">cl::list</a>
+option).</li>
+</ul>
+<ul class="simple" id="cl-positionaleatsargs">
+<li>The <strong>cl::PositionalEatsArgs</strong> modifier (which only applies to positional
+arguments, and only makes sense for lists) indicates that positional argument
+should consume any strings after it (including strings that start with a “-”)
+up until another recognized positional argument. For example, if you have two
+“eating” positional arguments, “<tt class="docutils literal"><span class="pre">pos1</span></tt>” and “<tt class="docutils literal"><span class="pre">pos2</span></tt>”, the string “<tt class="docutils literal"><span class="pre">-pos1</span>
+<span class="pre">-foo</span> <span class="pre">-bar</span> <span class="pre">baz</span> <span class="pre">-pos2</span> <span class="pre">-bork</span></tt>” would cause the “<tt class="docutils literal"><span class="pre">-foo</span> <span class="pre">-bar</span> <span class="pre">-baz</span></tt>” strings to
+be applied to the “<tt class="docutils literal"><span class="pre">-pos1</span></tt>” option and the “<tt class="docutils literal"><span class="pre">-bork</span></tt>” string to be applied
+to the “<tt class="docutils literal"><span class="pre">-pos2</span></tt>” option.</li>
+</ul>
+<ul class="simple" id="cl-sink">
+<li>The <strong>cl::Sink</strong> modifier is used to handle unknown options. If there is at
+least one option with <tt class="docutils literal"><span class="pre">cl::Sink</span></tt> modifier specified, the parser passes
+unrecognized option strings to it as values instead of signaling an error. As
+with <tt class="docutils literal"><span class="pre">cl::CommaSeparated</span></tt>, this modifier only makes sense with a <a class="reference internal" href="#cl-list">cl::list</a>
+option.</li>
+</ul>
+<p>So far, these are the only three miscellaneous option modifiers.</p>
+</div>
+<div class="section" id="response-files">
+<span id="id5"></span><h4><a class="toc-backref" href="#id31">Response files</a><a class="headerlink" href="#response-files" title="Permalink to this headline">¶</a></h4>
+<p>Some systems, such as certain variants of Microsoft Windows and some older
+Unices have a relatively low limit on command-line length. It is therefore
+customary to use the so-called ‘response files’ to circumvent this
+restriction. These files are mentioned on the command-line (using the “@file”)
+syntax. The program reads these files and inserts the contents into argv,
+thereby working around the command-line length limits.</p>
+</div>
+</div>
+<div class="section" id="top-level-classes-and-functions">
+<h3><a class="toc-backref" href="#id32">Top-Level Classes and Functions</a><a class="headerlink" href="#top-level-classes-and-functions" title="Permalink to this headline">¶</a></h3>
+<p>Despite all of the built-in flexibility, the CommandLine option library really
+only consists of one function <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>) and three main
+classes: <a class="reference internal" href="#cl-opt">cl::opt</a>, <a class="reference internal" href="#cl-list">cl::list</a>, and <a class="reference internal" href="#cl-alias">cl::alias</a>. This section describes
+these three classes in detail.</p>
+<div class="section" id="the-cl-getregisteredoptions-function">
+<span id="cl-getregisteredoptions"></span><h4><a class="toc-backref" href="#id33">The <tt class="docutils literal"><span class="pre">cl::getRegisteredOptions</span></tt> function</a><a class="headerlink" href="#the-cl-getregisteredoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::getRegisteredOptions</span></tt> function is designed to give a programmer
+access to declared non-positional command line options so that how they appear
+in <tt class="docutils literal"><span class="pre">-help</span></tt> can be modified prior to calling <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>.
+Note this method should not be called during any static initialisation because
+it cannot be guaranteed that all options will have been initialised. Hence it
+should be called from <tt class="docutils literal"><span class="pre">main</span></tt>.</p>
+<p>This function can be used to gain access to options declared in libraries that
+the tool writter may not have direct access to.</p>
+<p>The function retrieves a <a class="reference internal" href="ProgrammersManual.html#dss-stringmap"><em>StringMap</em></a> that maps the option
+string (e.g. <tt class="docutils literal"><span class="pre">-help</span></tt>) to an <tt class="docutils literal"><span class="pre">Option*</span></tt>.</p>
+<p>Here is an example of how the function could be used:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">OptionCategory</span> <span class="n">AnotherCategory</span><span class="p">(</span><span class="s">"Some options"</span><span class="p">);</span>
+
+ <span class="n">StringMap</span><span class="o"><</span><span class="n">cl</span><span class="o">::</span><span class="n">Option</span><span class="o">*></span> <span class="o">&</span><span class="n">Map</span> <span class="o">=</span> <span class="n">cl</span><span class="o">::</span><span class="n">getRegisteredOptions</span><span class="p">();</span>
+
+ <span class="c1">//Unhide useful option and put it in a different category</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"print-all-options"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"print-all-options"</span><span class="p">]</span><span class="o">-></span><span class="n">setHiddenFlag</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">NotHidden</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"print-all-options"</span><span class="p">]</span><span class="o">-></span><span class="n">setCategory</span><span class="p">(</span><span class="n">AnotherCategory</span><span class="p">);</span>
+
+ <span class="c1">//Hide an option we don't want to see</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"enable-no-infs-fp-math"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"enable-no-infs-fp-math"</span><span class="p">]</span><span class="o">-></span><span class="n">setHiddenFlag</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Hidden</span><span class="p">);</span>
+
+ <span class="c1">//Change --version to --show-version</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"version"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"version"</span><span class="p">]</span><span class="o">-></span><span class="n">setArgStr</span><span class="p">(</span><span class="s">"show-version"</span><span class="p">);</span>
+
+ <span class="c1">//Change --help description</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"help"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"help"</span><span class="p">]</span><span class="o">-></span><span class="n">setDescription</span><span class="p">(</span><span class="s">"Shows help"</span><span class="p">);</span>
+
+ <span class="n">cl</span><span class="o">::</span><span class="n">ParseCommandLineOptions</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</span><span class="p">,</span> <span class="s">"This is a small program to demo the LLVM CommandLine API"</span><span class="p">);</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-cl-parsecommandlineoptions-function">
+<span id="cl-parsecommandlineoptions"></span><h4><a class="toc-backref" href="#id34">The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function</a><a class="headerlink" href="#the-cl-parsecommandlineoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function is designed to be called directly
+from <tt class="docutils literal"><span class="pre">main</span></tt>, and is used to fill in the values of all of the command line
+option variables once <tt class="docutils literal"><span class="pre">argc</span></tt> and <tt class="docutils literal"><span class="pre">argv</span></tt> are available.</p>
+<p>The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function requires two parameters (<tt class="docutils literal"><span class="pre">argc</span></tt>
+and <tt class="docutils literal"><span class="pre">argv</span></tt>), but may also take an optional third parameter which holds
+<a class="reference internal" href="#additional-extra-text">additional extra text</a> to emit when the <tt class="docutils literal"><span class="pre">-help</span></tt> option is invoked.</p>
+</div>
+<div class="section" id="the-cl-parseenvironmentoptions-function">
+<span id="cl-parseenvironmentoptions"></span><h4><a class="toc-backref" href="#id35">The <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> function</a><a class="headerlink" href="#the-cl-parseenvironmentoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> function has mostly the same effects as
+<a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>, except that it is designed to take values for
+options from an environment variable, for those cases in which reading the
+command line is not convenient or desired. It fills in the values of all the
+command line option variables just like <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a> does.</p>
+<p>It takes four parameters: the name of the program (since <tt class="docutils literal"><span class="pre">argv</span></tt> may not be
+available, it can’t just look in <tt class="docutils literal"><span class="pre">argv[0]</span></tt>), the name of the environment
+variable to examine, and the optional <a class="reference internal" href="#additional-extra-text">additional extra text</a> to emit when the
+<tt class="docutils literal"><span class="pre">-help</span></tt> option is invoked.</p>
+<p><tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> will break the environment variable’s value up
+into words and then process them using <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>.
+<strong>Note:</strong> Currently <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> does not support quoting, so
+an environment variable containing <tt class="docutils literal"><span class="pre">-option</span> <span class="pre">"foo</span> <span class="pre">bar"</span></tt> will be parsed as three
+words, <tt class="docutils literal"><span class="pre">-option</span></tt>, <tt class="docutils literal"><span class="pre">"foo</span></tt>, and <tt class="docutils literal"><span class="pre">bar"</span></tt>, which is different from what you
+would get from the shell with the same input.</p>
+</div>
+<div class="section" id="the-cl-setversionprinter-function">
+<h4><a class="toc-backref" href="#id36">The <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> function</a><a class="headerlink" href="#the-cl-setversionprinter-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> function is designed to be called directly from
+<tt class="docutils literal"><span class="pre">main</span></tt> and <em>before</em> <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt>. Its use is optional. It
+simply arranges for a function to be called in response to the <tt class="docutils literal"><span class="pre">--version</span></tt>
+option instead of having the <tt class="docutils literal"><span class="pre">CommandLine</span></tt> library print out the usual version
+string for LLVM. This is useful for programs that are not part of LLVM but wish
+to use the <tt class="docutils literal"><span class="pre">CommandLine</span></tt> facilities. Such programs should just define a small
+function that takes no arguments and returns <tt class="docutils literal"><span class="pre">void</span></tt> and that prints out
+whatever version information is appropriate for the program. Pass the address of
+that function to <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> to arrange for it to be called when
+the <tt class="docutils literal"><span class="pre">--version</span></tt> option is given by the user.</p>
+</div>
+<div class="section" id="the-cl-opt-class">
+<span id="scalar"></span><span id="cl-opt"></span><h4><a class="toc-backref" href="#id37">The <tt class="docutils literal"><span class="pre">cl::opt</span></tt> class</a><a class="headerlink" href="#the-cl-opt-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::opt</span></tt> class is the class used to represent scalar command line
+options, and is the one used most of the time. It is a templated class which
+can take up to three arguments (all except for the first have default values
+though):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">DataType</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">ExternalStorage</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
+ <span class="k">class</span> <span class="nc">ParserClass</span> <span class="o">=</span> <span class="n">parser</span><span class="o"><</span><span class="n">DataType</span><span class="o">></span> <span class="o">></span>
+ <span class="k">class</span> <span class="nc">opt</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The first template argument specifies what underlying data type the command line
+argument is, and is used to select a default parser implementation. The second
+template argument is used to specify whether the option should contain the
+storage for the option (the default) or whether external storage should be used
+to contain the value parsed for the option (see <a class="reference internal" href="#internal-vs-external-storage">Internal vs External Storage</a>
+for more information).</p>
+<p>The third template argument specifies which parser to use. The default value
+selects an instantiation of the <tt class="docutils literal"><span class="pre">parser</span></tt> class based on the underlying data
+type of the option. In general, this default works well for most applications,
+so this option is only used when using a <a class="reference internal" href="#custom-parser">custom parser</a>.</p>
+</div>
+<div class="section" id="the-cl-list-class">
+<span id="cl-list"></span><span id="lists-of-arguments"></span><h4><a class="toc-backref" href="#id38">The <tt class="docutils literal"><span class="pre">cl::list</span></tt> class</a><a class="headerlink" href="#the-cl-list-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::list</span></tt> class is the class used to represent a list of command line
+options. It too is a templated class which can take up to three arguments:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">DataType</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Storage</span> <span class="o">=</span> <span class="kt">bool</span><span class="p">,</span>
+ <span class="k">class</span> <span class="nc">ParserClass</span> <span class="o">=</span> <span class="n">parser</span><span class="o"><</span><span class="n">DataType</span><span class="o">></span> <span class="o">></span>
+ <span class="k">class</span> <span class="nc">list</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This class works the exact same as the <a class="reference internal" href="#cl-opt">cl::opt</a> class, except that the second
+argument is the <strong>type</strong> of the external storage, not a boolean value. For this
+class, the marker type ‘<tt class="docutils literal"><span class="pre">bool</span></tt>‘ is used to indicate that internal storage
+should be used.</p>
+</div>
+<div class="section" id="the-cl-bits-class">
+<span id="cl-bits"></span><h4><a class="toc-backref" href="#id39">The <tt class="docutils literal"><span class="pre">cl::bits</span></tt> class</a><a class="headerlink" href="#the-cl-bits-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::bits</span></tt> class is the class used to represent a list of command line
+options in the form of a bit vector. It is also a templated class which can
+take up to three arguments:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">DataType</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Storage</span> <span class="o">=</span> <span class="kt">bool</span><span class="p">,</span>
+ <span class="k">class</span> <span class="nc">ParserClass</span> <span class="o">=</span> <span class="n">parser</span><span class="o"><</span><span class="n">DataType</span><span class="o">></span> <span class="o">></span>
+ <span class="k">class</span> <span class="nc">bits</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This class works the exact same as the <a class="reference internal" href="#cl-list">cl::list</a> class, except that the second
+argument must be of <strong>type</strong> <tt class="docutils literal"><span class="pre">unsigned</span></tt> if external storage is used.</p>
+</div>
+<div class="section" id="the-cl-alias-class">
+<span id="cl-alias"></span><h4><a class="toc-backref" href="#id40">The <tt class="docutils literal"><span class="pre">cl::alias</span></tt> class</a><a class="headerlink" href="#the-cl-alias-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::alias</span></tt> class is a nontemplated class that is used to form aliases for
+other arguments.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">alias</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The <a class="reference internal" href="#cl-aliasopt">cl::aliasopt</a> attribute should be used to specify which option this is an
+alias for. Alias arguments default to being <a class="reference internal" href="#cl-hidden">cl::Hidden</a>, and use the aliased
+options parser to do the conversion from string to data.</p>
+</div>
+<div class="section" id="the-cl-extrahelp-class">
+<span id="cl-extrahelp"></span><h4><a class="toc-backref" href="#id41">The <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt> class</a><a class="headerlink" href="#the-cl-extrahelp-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt> class is a nontemplated class that allows extra help text
+to be printed out for the <tt class="docutils literal"><span class="pre">-help</span></tt> option.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">struct</span> <span class="n">extrahelp</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>To use the extrahelp, simply construct one with a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt> parameter to
+the constructor. The text passed to the constructor will be printed at the
+bottom of the help message, verbatim. Note that multiple <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt>
+<strong>can</strong> be used, but this practice is discouraged. If your tool needs to print
+additional help information, put all that help into a single <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt>
+instance.</p>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">extrahelp</span><span class="p">(</span><span class="s">"</span><span class="se">\n</span><span class="s">ADDITIONAL HELP:</span><span class="se">\n\n</span><span class="s"> This is the extra help</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-cl-optioncategory-class">
+<span id="cl-optioncategory"></span><h4><a class="toc-backref" href="#id42">The <tt class="docutils literal"><span class="pre">cl::OptionCategory</span></tt> class</a><a class="headerlink" href="#the-cl-optioncategory-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::OptionCategory</span></tt> class is a simple class for declaring
+option categories.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">OptionCategory</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>An option category must have a name and optionally a description which are
+passed to the constructor as <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt>.</p>
+<p>Note that declaring an option category and associating it with an option before
+parsing options (e.g. statically) will change the output of <tt class="docutils literal"><span class="pre">-help</span></tt> from
+uncategorized to categorized. If an option category is declared but not
+associated with an option then it will be hidden from the output of <tt class="docutils literal"><span class="pre">-help</span></tt>
+but will be shown in the output of <tt class="docutils literal"><span class="pre">-help-hidden</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="builtin-parsers">
+<span id="discussed-previously"></span><span id="different-parser"></span><h3><a class="toc-backref" href="#id43">Builtin parsers</a><a class="headerlink" href="#builtin-parsers" title="Permalink to this headline">¶</a></h3>
+<p>Parsers control how the string value taken from the command line is translated
+into a typed value, suitable for use in a C++ program. By default, the
+CommandLine library uses an instance of <tt class="docutils literal"><span class="pre">parser<type></span></tt> if the command line
+option specifies that it uses values of type ‘<tt class="docutils literal"><span class="pre">type</span></tt>‘. Because of this,
+custom option processing is specified with specializations of the ‘<tt class="docutils literal"><span class="pre">parser</span></tt>‘
+class.</p>
+<p>The CommandLine library provides the following builtin parser specializations,
+which are sufficient for most applications. It can, however, also be extended to
+work with new data types and new ways of interpreting the same data. See the
+<a class="reference internal" href="#writing-a-custom-parser">Writing a Custom Parser</a> for more details on this type of library extension.</p>
+<ul class="simple" id="cl-parser">
+<span id="enums"></span><li>The generic <tt class="docutils literal"><span class="pre">parser<t></span></tt> parser can be used to map strings values to any data
+type, through the use of the <a class="reference internal" href="#cl-values">cl::values</a> property, which specifies the
+mapping information. The most common use of this parser is for parsing enum
+values, which allows you to use the CommandLine library for all of the error
+checking to make sure that only valid enum values are specified (as opposed to
+accepting arbitrary strings). Despite this, however, the generic parser class
+can be used for any data type.</li>
+</ul>
+<ul class="simple" id="bool-parser">
+<span id="boolean-flags"></span><li>The <strong>parser<bool> specialization</strong> is used to convert boolean strings to a
+boolean value. Currently accepted strings are “<tt class="docutils literal"><span class="pre">true</span></tt>”, “<tt class="docutils literal"><span class="pre">TRUE</span></tt>”,
+“<tt class="docutils literal"><span class="pre">True</span></tt>”, “<tt class="docutils literal"><span class="pre">1</span></tt>”, “<tt class="docutils literal"><span class="pre">false</span></tt>”, “<tt class="docutils literal"><span class="pre">FALSE</span></tt>”, “<tt class="docutils literal"><span class="pre">False</span></tt>”, and “<tt class="docutils literal"><span class="pre">0</span></tt>”.</li>
+<li>The <strong>parser<boolOrDefault> specialization</strong> is used for cases where the value
+is boolean, but we also need to know whether the option was specified at all.
+boolOrDefault is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE.
+This parser accepts the same strings as <strong>``parser<bool>``</strong>.</li>
+</ul>
+<ul class="simple" id="strings">
+<li>The <strong>parser<string> specialization</strong> simply stores the parsed string into the
+string value specified. No conversion or modification of the data is
+performed.</li>
+</ul>
+<ul class="simple" id="int">
+<span id="integers"></span><li>The <strong>parser<int> specialization</strong> uses the C <tt class="docutils literal"><span class="pre">strtol</span></tt> function to parse the
+string input. As such, it will accept a decimal number (with an optional ‘+’
+or ‘-‘ prefix) which must start with a non-zero digit. It accepts octal
+numbers, which are identified with a ‘<tt class="docutils literal"><span class="pre">0</span></tt>‘ prefix digit, and hexadecimal
+numbers with a prefix of ‘<tt class="docutils literal"><span class="pre">0x</span></tt>‘ or ‘<tt class="docutils literal"><span class="pre">0X</span></tt>‘.</li>
+</ul>
+<ul class="simple" id="double">
+<span id="float"></span><span id="doubles"></span><li>The <strong>parser<double></strong> and <strong>parser<float> specializations</strong> use the standard
+C <tt class="docutils literal"><span class="pre">strtod</span></tt> function to convert floating point strings into floating point
+values. As such, a broad range of string formats is supported, including
+exponential notation (ex: <tt class="docutils literal"><span class="pre">1.7e15</span></tt>) and properly supports locales.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="extending-the-library">
+<span id="extension-guide"></span><span id="id6"></span><h2><a class="toc-backref" href="#id44">Extension Guide</a><a class="headerlink" href="#extending-the-library" title="Permalink to this headline">¶</a></h2>
+<p>Although the CommandLine library has a lot of functionality built into it
+already (as discussed previously), one of its true strengths lie in its
+extensibility. This section discusses how the CommandLine library works under
+the covers and illustrates how to do some simple, common, extensions.</p>
+<div class="section" id="writing-a-custom-parser">
+<span id="custom-parser"></span><span id="custom-parsers"></span><span id="id7"></span><h3><a class="toc-backref" href="#id45">Writing a custom parser</a><a class="headerlink" href="#writing-a-custom-parser" title="Permalink to this headline">¶</a></h3>
+<p>One of the simplest and most common extensions is the use of a custom parser.
+As <a class="reference internal" href="#discussed-previously">discussed previously</a>, parsers are the portion of the CommandLine library
+that turns string input from the user into a particular parsed data type,
+validating the input in the process.</p>
+<p>There are two ways to use a new parser:</p>
+<ol class="arabic">
+<li><p class="first">Specialize the <a class="reference internal" href="#cl-parser">cl::parser</a> template for your custom data type.</p>
+<p>This approach has the advantage that users of your custom data type will
+automatically use your custom parser whenever they define an option with a
+value type of your data type. The disadvantage of this approach is that it
+doesn’t work if your fundamental data type is something that is already
+supported.</p>
+</li>
+<li><p class="first">Write an independent class, using it explicitly from options that need it.</p>
+<p>This approach works well in situations where you would line to parse an
+option using special syntax for a not-very-special data-type. The drawback
+of this approach is that users of your parser have to be aware that they are
+using your parser instead of the builtin ones.</p>
+</li>
+</ol>
+<p>To guide the discussion, we will discuss a custom parser that accepts file
+sizes, specified with an optional unit after the numeric size. For example, we
+would like to parse “102kb”, “41M”, “1G” into the appropriate integer value. In
+this case, the underlying data type we want to parse into is ‘<tt class="docutils literal"><span class="pre">unsigned</span></tt>‘. We
+choose approach #2 above because we don’t want to make this the default for all
+<tt class="docutils literal"><span class="pre">unsigned</span></tt> options.</p>
+<p>To start out, we declare our new <tt class="docutils literal"><span class="pre">FileSizeParser</span></tt> class:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">FileSizeParser</span> <span class="o">:</span> <span class="k">public</span> <span class="n">cl</span><span class="o">::</span><span class="n">parser</span><span class="o"><</span><span class="kt">unsigned</span><span class="o">></span> <span class="p">{</span>
+ <span class="c1">// parse - Return true on error.</span>
+ <span class="kt">bool</span> <span class="n">parse</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Option</span> <span class="o">&</span><span class="n">O</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">ArgName</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">ArgValue</span><span class="p">,</span>
+ <span class="kt">unsigned</span> <span class="o">&</span><span class="n">Val</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Our new class inherits from the <tt class="docutils literal"><span class="pre">cl::parser</span></tt> template class to fill in
+the default, boiler plate code for us. We give it the data type that we parse
+into, the last argument to the <tt class="docutils literal"><span class="pre">parse</span></tt> method, so that clients of our custom
+parser know what object type to pass in to the parse method. (Here we declare
+that we parse into ‘<tt class="docutils literal"><span class="pre">unsigned</span></tt>‘ variables.)</p>
+<p>For most purposes, the only method that must be implemented in a custom parser
+is the <tt class="docutils literal"><span class="pre">parse</span></tt> method. The <tt class="docutils literal"><span class="pre">parse</span></tt> method is called whenever the option is
+invoked, passing in the option itself, the option name, the string to parse, and
+a reference to a return value. If the string to parse is not well-formed, the
+parser should output an error message and return true. Otherwise it should
+return false and set ‘<tt class="docutils literal"><span class="pre">Val</span></tt>‘ to the parsed value. In our example, we
+implement <tt class="docutils literal"><span class="pre">parse</span></tt> as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">FileSizeParser</span><span class="o">::</span><span class="n">parse</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Option</span> <span class="o">&</span><span class="n">O</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">ArgName</span><span class="p">,</span>
+ <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">Arg</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="o">&</span><span class="n">Val</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">ArgStart</span> <span class="o">=</span> <span class="n">Arg</span><span class="p">.</span><span class="n">c_str</span><span class="p">();</span>
+ <span class="kt">char</span> <span class="o">*</span><span class="n">End</span><span class="p">;</span>
+
+ <span class="c1">// Parse integer part, leaving 'End' pointing to the first non-integer char</span>
+ <span class="n">Val</span> <span class="o">=</span> <span class="p">(</span><span class="kt">unsigned</span><span class="p">)</span><span class="n">strtol</span><span class="p">(</span><span class="n">ArgStart</span><span class="p">,</span> <span class="o">&</span><span class="n">End</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+
+ <span class="k">while</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="o">*</span><span class="n">End</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="mi">0</span><span class="o">:</span> <span class="k">return</span> <span class="kc">false</span><span class="p">;</span> <span class="c1">// No error</span>
+ <span class="k">case</span> <span class="sc">'i'</span><span class="o">:</span> <span class="c1">// Ignore the 'i' in KiB if people use that</span>
+ <span class="k">case</span> <span class="sc">'b'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'B'</span><span class="o">:</span> <span class="c1">// Ignore B suffix</span>
+ <span class="k">break</span><span class="p">;</span>
+
+ <span class="k">case</span> <span class="sc">'g'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'G'</span><span class="o">:</span> <span class="n">Val</span> <span class="o">*=</span> <span class="mi">1024</span><span class="o">*</span><span class="mi">1024</span><span class="o">*</span><span class="mi">1024</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="sc">'m'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'M'</span><span class="o">:</span> <span class="n">Val</span> <span class="o">*=</span> <span class="mi">1024</span><span class="o">*</span><span class="mi">1024</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="sc">'k'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'K'</span><span class="o">:</span> <span class="n">Val</span> <span class="o">*=</span> <span class="mi">1024</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+
+ <span class="k">default</span><span class="o">:</span>
+ <span class="c1">// Print an error message if unrecognized character!</span>
+ <span class="k">return</span> <span class="n">O</span><span class="p">.</span><span class="n">error</span><span class="p">(</span><span class="s">"'"</span> <span class="o">+</span> <span class="n">Arg</span> <span class="o">+</span> <span class="s">"' value invalid for file size argument!"</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This function implements a very simple parser for the kinds of strings we are
+interested in. Although it has some holes (it allows “<tt class="docutils literal"><span class="pre">123KKK</span></tt>” for example),
+it is good enough for this example. Note that we use the option itself to print
+out the error message (the <tt class="docutils literal"><span class="pre">error</span></tt> method always returns true) in order to get
+a nice error message (shown below). Now that we have our parser class, we can
+use it like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">unsigned</span><span class="p">,</span> <span class="kc">false</span><span class="p">,</span> <span class="n">FileSizeParser</span><span class="o">></span>
+<span class="n">MFS</span><span class="p">(</span><span class="s">"max-file-size"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Maximum file size to accept"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">value_desc</span><span class="p">(</span><span class="s">"size"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>Which adds this to the output of our program:</p>
+<div class="highlight-python"><pre>OPTIONS:
+ -help - display available options (-help-hidden for more)
+ ...
+ -max-file-size=<size> - Maximum file size to accept</pre>
+</div>
+<p>And we can test that our parse works correctly now (the test program just prints
+out the max-file-size argument value):</p>
+<div class="highlight-python"><pre>$ ./test
+MFS: 0
+$ ./test -max-file-size=123MB
+MFS: 128974848
+$ ./test -max-file-size=3G
+MFS: 3221225472
+$ ./test -max-file-size=dog
+-max-file-size option: 'dog' value invalid for file size argument!</pre>
+</div>
+<p>It looks like it works. The error message that we get is nice and helpful, and
+we seem to accept reasonable file sizes. This wraps up the “custom parser”
+tutorial.</p>
+</div>
+<div class="section" id="exploiting-external-storage">
+<h3><a class="toc-backref" href="#id46">Exploiting external storage</a><a class="headerlink" href="#exploiting-external-storage" title="Permalink to this headline">¶</a></h3>
+<p>Several of the LLVM libraries define static <tt class="docutils literal"><span class="pre">cl::opt</span></tt> instances that will
+automatically be included in any program that links with that library. This is
+a feature. However, sometimes it is necessary to know the value of the command
+line option outside of the library. In these cases the library does or should
+provide an external storage location that is accessible to users of the
+library. Examples of this include the <tt class="docutils literal"><span class="pre">llvm::DebugFlag</span></tt> exported by the
+<tt class="docutils literal"><span class="pre">lib/Support/Debug.cpp</span></tt> file and the <tt class="docutils literal"><span class="pre">llvm::TimePassesIsEnabled</span></tt> flag
+exported by the <tt class="docutils literal"><span class="pre">lib/VMCore/PassManager.cpp</span></tt> file.</p>
+</div>
+<div class="section" id="dynamically-adding-command-line-options">
+<span id="dynamically-loaded-options"></span><h3><a class="toc-backref" href="#id47">Dynamically adding command line options</a><a class="headerlink" href="#dynamically-adding-command-line-options" title="Permalink to this headline">¶</a></h3>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodingStandards.html" title="LLVM Coding Standards"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CompileCudaWithLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CompileCudaWithLLVM.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CompileCudaWithLLVM.html (added)
+++ www-releases/trunk/6.0.1/docs/CompileCudaWithLLVM.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,611 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Compiling CUDA with clang — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="Reporting Guide" href="ReportingGuide.html" />
+ <link rel="prev" title="LLVM Community Code of Conduct" href="CodeOfConduct.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="ReportingGuide.html" title="Reporting Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodeOfConduct.html" title="LLVM Community Code of Conduct"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="compiling-cuda-with-clang">
+<h1>Compiling CUDA with clang<a class="headerlink" href="#compiling-cuda-with-clang" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#compiling-cuda-code" id="id2">Compiling CUDA Code</a><ul>
+<li><a class="reference internal" href="#prerequisites" id="id3">Prerequisites</a></li>
+<li><a class="reference internal" href="#invoking-clang" id="id4">Invoking clang</a></li>
+<li><a class="reference internal" href="#flags-that-control-numerical-code" id="id5">Flags that control numerical code</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#standard-library-support" id="id6">Standard library support</a><ul>
+<li><a class="reference internal" href="#math-h-and-cmath" id="id7"><tt class="docutils literal"><span class="pre"><math.h></span></tt> and <tt class="docutils literal"><span class="pre"><cmath></span></tt></a></li>
+<li><a class="reference internal" href="#std-complex" id="id8"><tt class="docutils literal"><span class="pre"><std::complex></span></tt></a></li>
+<li><a class="reference internal" href="#algorithm" id="id9"><tt class="docutils literal"><span class="pre"><algorithm></span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#detecting-clang-vs-nvcc-from-code" id="id10">Detecting clang vs NVCC from code</a></li>
+<li><a class="reference internal" href="#dialect-differences-between-clang-and-nvcc" id="id11">Dialect Differences Between clang and nvcc</a><ul>
+<li><a class="reference internal" href="#compilation-models" id="id12">Compilation Models</a></li>
+<li><a class="reference internal" href="#overloading-based-on-host-and-device-attributes" id="id13">Overloading Based on <tt class="docutils literal"><span class="pre">__host__</span></tt> and <tt class="docutils literal"><span class="pre">__device__</span></tt> Attributes</a></li>
+<li><a class="reference internal" href="#using-a-different-class-on-host-device" id="id14">Using a Different Class on Host/Device</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#optimizations" id="id15">Optimizations</a></li>
+<li><a class="reference internal" href="#publication" id="id16">Publication</a></li>
+<li><a class="reference internal" href="#obtaining-help" id="id17">Obtaining Help</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes how to compile CUDA code with clang, and gives some
+details about LLVM and clang’s CUDA implementations.</p>
+<p>This document assumes a basic familiarity with CUDA. Information about CUDA
+programming can be found in the
+<a class="reference external" href="http://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html">CUDA programming guide</a>.</p>
+</div>
+<div class="section" id="compiling-cuda-code">
+<h2><a class="toc-backref" href="#id2">Compiling CUDA Code</a><a class="headerlink" href="#compiling-cuda-code" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="prerequisites">
+<h3><a class="toc-backref" href="#id3">Prerequisites</a><a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h3>
+<p>CUDA is supported in llvm 3.9, but it’s still in active development, so we
+recommend you <a class="reference external" href="http://llvm.org/docs/GettingStarted.html">compile clang/LLVM from HEAD</a>.</p>
+<p>Before you build CUDA code, you’ll need to have installed the appropriate
+driver for your nvidia GPU and the CUDA SDK. See <a class="reference external" href="https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html">NVIDIA’s CUDA installation
+guide</a>
+for details. Note that clang <a class="reference external" href="https://llvm.org/bugs/show_bug.cgi?id=26966">does not support</a> the CUDA toolkit as installed
+by many Linux package managers; you probably need to install nvidia’s package.</p>
+<p>You will need CUDA 7.0, 7.5, or 8.0 to compile with clang.</p>
+<p>CUDA compilation is supported on Linux, on MacOS as of 2016-11-18, and on
+Windows as of 2017-01-05.</p>
+</div>
+<div class="section" id="invoking-clang">
+<h3><a class="toc-backref" href="#id4">Invoking clang</a><a class="headerlink" href="#invoking-clang" title="Permalink to this headline">¶</a></h3>
+<p>Invoking clang for CUDA compilation works similarly to compiling regular C++.
+You just need to be aware of a few additional flags.</p>
+<p>You can use <a class="reference external" href="https://gist.github.com/855e277884eb6b388cd2f00d956c2fd4">this</a>
+program as a toy example. Save it as <tt class="docutils literal"><span class="pre">axpy.cu</span></tt>. (Clang detects that you’re
+compiling CUDA code by noticing that your filename ends with <tt class="docutils literal"><span class="pre">.cu</span></tt>.
+Alternatively, you can pass <tt class="docutils literal"><span class="pre">-x</span> <span class="pre">cuda</span></tt>.)</p>
+<p>To build and run, run the following commands, filling in the parts in angle
+brackets as described below:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ axpy.cu -o axpy --cuda-gpu-arch<span class="o">=</span><GPU arch> <span class="se">\</span>
+<span class="go"> -L<CUDA install path>/<lib64 or lib> \</span>
+<span class="go"> -lcudart_static -ldl -lrt -pthread</span>
+<span class="gp">$</span> ./axpy
+<span class="go">y[0] = 2</span>
+<span class="go">y[1] = 4</span>
+<span class="go">y[2] = 6</span>
+<span class="go">y[3] = 8</span>
+</pre></div>
+</div>
+<p>On MacOS, replace <cite>-lcudart_static</cite> with <cite>-lcudart</cite>; otherwise, you may get
+“CUDA driver version is insufficient for CUDA runtime version” errors when you
+run your program.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre"><CUDA</span> <span class="pre">install</span> <span class="pre">path></span></tt> – the directory where you installed CUDA SDK.
+Typically, <tt class="docutils literal"><span class="pre">/usr/local/cuda</span></tt>.</p>
+<p>Pass e.g. <tt class="docutils literal"><span class="pre">-L/usr/local/cuda/lib64</span></tt> if compiling in 64-bit mode; otherwise,
+pass e.g. <tt class="docutils literal"><span class="pre">-L/usr/local/cuda/lib</span></tt>. (In CUDA, the device code and host code
+always have the same pointer widths, so if you’re compiling 64-bit code for
+the host, you’re also compiling 64-bit code for the device.)</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre"><GPU</span> <span class="pre">arch></span></tt> – the <a class="reference external" href="https://developer.nvidia.com/cuda-gpus">compute capability</a> of your GPU. For example, if you
+want to run your program on a GPU with compute capability of 3.5, specify
+<tt class="docutils literal"><span class="pre">--cuda-gpu-arch=sm_35</span></tt>.</p>
+<p>Note: You cannot pass <tt class="docutils literal"><span class="pre">compute_XX</span></tt> as an argument to <tt class="docutils literal"><span class="pre">--cuda-gpu-arch</span></tt>;
+only <tt class="docutils literal"><span class="pre">sm_XX</span></tt> is currently supported. However, clang always includes PTX in
+its binaries, so e.g. a binary compiled with <tt class="docutils literal"><span class="pre">--cuda-gpu-arch=sm_30</span></tt> would be
+forwards-compatible with e.g. <tt class="docutils literal"><span class="pre">sm_35</span></tt> GPUs.</p>
+<p>You can pass <tt class="docutils literal"><span class="pre">--cuda-gpu-arch</span></tt> multiple times to compile for multiple archs.</p>
+</li>
+</ul>
+<p>The <cite>-L</cite> and <cite>-l</cite> flags only need to be passed when linking. When compiling,
+you may also need to pass <tt class="docutils literal"><span class="pre">--cuda-path=/path/to/cuda</span></tt> if you didn’t install
+the CUDA SDK into <tt class="docutils literal"><span class="pre">/usr/local/cuda</span></tt>, <tt class="docutils literal"><span class="pre">/usr/local/cuda-7.0</span></tt>, or
+<tt class="docutils literal"><span class="pre">/usr/local/cuda-7.5</span></tt>.</p>
+</div>
+<div class="section" id="flags-that-control-numerical-code">
+<h3><a class="toc-backref" href="#id5">Flags that control numerical code</a><a class="headerlink" href="#flags-that-control-numerical-code" title="Permalink to this headline">¶</a></h3>
+<p>If you’re using GPUs, you probably care about making numerical code run fast.
+GPU hardware allows for more control over numerical operations than most CPUs,
+but this results in more compiler options for you to juggle.</p>
+<p>Flags you may wish to tweak include:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-ffp-contract={on,off,fast}</span></tt> (defaults to <tt class="docutils literal"><span class="pre">fast</span></tt> on host and device when
+compiling CUDA) Controls whether the compiler emits fused multiply-add
+operations.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">off</span></tt>: never emit fma operations, and prevent ptxas from fusing multiply
+and add instructions.</li>
+<li><tt class="docutils literal"><span class="pre">on</span></tt>: fuse multiplies and adds within a single statement, but never
+across statements (C11 semantics). Prevent ptxas from fusing other
+multiplies and adds.</li>
+<li><tt class="docutils literal"><span class="pre">fast</span></tt>: fuse multiplies and adds wherever profitable, even across
+statements. Doesn’t prevent ptxas from fusing additional multiplies and
+adds.</li>
+</ul>
+<p>Fused multiply-add instructions can be much faster than the unfused
+equivalents, but because the intermediate result in an fma is not rounded,
+this flag can affect numerical code.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-fcuda-flush-denormals-to-zero</span></tt> (default: off) When this is enabled,
+floating point operations may flush <a class="reference external" href="https://en.wikipedia.org/wiki/Denormal_number">denormal</a> inputs and/or outputs to 0.
+Operations on denormal numbers are often much slower than the same operations
+on normal numbers.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-fcuda-approx-transcendentals</span></tt> (default: off) When this is enabled, the
+compiler may emit calls to faster, approximate versions of transcendental
+functions, instead of using the slower, fully IEEE-compliant versions. For
+example, this flag allows clang to emit the ptx <tt class="docutils literal"><span class="pre">sin.approx.f32</span></tt>
+instruction.</p>
+<p>This is implied by <tt class="docutils literal"><span class="pre">-ffast-math</span></tt>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="standard-library-support">
+<h2><a class="toc-backref" href="#id6">Standard library support</a><a class="headerlink" href="#standard-library-support" title="Permalink to this headline">¶</a></h2>
+<p>In clang and nvcc, most of the C++ standard library is not supported on the
+device side.</p>
+<div class="section" id="math-h-and-cmath">
+<h3><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre"><math.h></span></tt> and <tt class="docutils literal"><span class="pre"><cmath></span></tt></a><a class="headerlink" href="#math-h-and-cmath" title="Permalink to this headline">¶</a></h3>
+<p>In clang, <tt class="docutils literal"><span class="pre">math.h</span></tt> and <tt class="docutils literal"><span class="pre">cmath</span></tt> are available and <a class="reference external" href="https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/math_h.cu">pass</a>
+<a class="reference external" href="https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/cmath.cu">tests</a>
+adapted from libc++’s test suite.</p>
+<p>In nvcc <tt class="docutils literal"><span class="pre">math.h</span></tt> and <tt class="docutils literal"><span class="pre">cmath</span></tt> are mostly available. Versions of <tt class="docutils literal"><span class="pre">::foof</span></tt>
+in namespace std (e.g. <tt class="docutils literal"><span class="pre">std::sinf</span></tt>) are not available, and where the standard
+calls for overloads that take integral arguments, these are usually not
+available.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <math.h></span>
+<span class="cp">#include <cmath.h></span>
+
+<span class="c1">// clang is OK with everything in this function.</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">sin</span><span class="p">(</span><span class="mf">0.</span><span class="p">);</span> <span class="c1">// nvcc - ok</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">sin</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> <span class="c1">// nvcc - error, because no std::sin(int) override is available.</span>
+ <span class="n">sin</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> <span class="c1">// nvcc - same as above.</span>
+
+ <span class="n">sinf</span><span class="p">(</span><span class="mf">0.</span><span class="p">);</span> <span class="c1">// nvcc - ok</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">sinf</span><span class="p">(</span><span class="mf">0.</span><span class="p">);</span> <span class="c1">// nvcc - no such function</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="std-complex">
+<h3><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre"><std::complex></span></tt></a><a class="headerlink" href="#std-complex" title="Permalink to this headline">¶</a></h3>
+<p>nvcc does not officially support <tt class="docutils literal"><span class="pre">std::complex</span></tt>. It’s an error to use
+<tt class="docutils literal"><span class="pre">std::complex</span></tt> in <tt class="docutils literal"><span class="pre">__device__</span></tt> code, but it often works in <tt class="docutils literal"><span class="pre">__host__</span>
+<span class="pre">__device__</span></tt> code due to nvcc’s interpretation of the “wrong-side rule” (see
+below). However, we have heard from implementers that it’s possible to get
+into situations where nvcc will omit a call to an <tt class="docutils literal"><span class="pre">std::complex</span></tt> function,
+especially when compiling without optimizations.</p>
+<p>As of 2016-11-16, clang supports <tt class="docutils literal"><span class="pre">std::complex</span></tt> without these caveats. It is
+tested with libstdc++ 4.8.5 and newer, but is known to work only with libc++
+newer than 2016-11-16.</p>
+</div>
+<div class="section" id="algorithm">
+<h3><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre"><algorithm></span></tt></a><a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h3>
+<p>In C++14, many useful functions from <tt class="docutils literal"><span class="pre"><algorithm></span></tt> (notably, <tt class="docutils literal"><span class="pre">std::min</span></tt> and
+<tt class="docutils literal"><span class="pre">std::max</span></tt>) become constexpr. You can therefore use these in device code,
+when compiling with clang.</p>
+</div>
+</div>
+<div class="section" id="detecting-clang-vs-nvcc-from-code">
+<h2><a class="toc-backref" href="#id10">Detecting clang vs NVCC from code</a><a class="headerlink" href="#detecting-clang-vs-nvcc-from-code" title="Permalink to this headline">¶</a></h2>
+<p>Although clang’s CUDA implementation is largely compatible with NVCC’s, you may
+still want to detect when you’re compiling CUDA code specifically with clang.</p>
+<p>This is tricky, because NVCC may invoke clang as part of its own compilation
+process! For example, NVCC uses the host compiler’s preprocessor when
+compiling for device code, and that host compiler may in fact be clang.</p>
+<p>When clang is actually compiling CUDA code – rather than being used as a
+subtool of NVCC’s – it defines the <tt class="docutils literal"><span class="pre">__CUDA__</span></tt> macro. <tt class="docutils literal"><span class="pre">__CUDA_ARCH__</span></tt> is
+defined only in device mode (but will be defined if NVCC is using clang as a
+preprocessor). So you can use the following incantations to detect clang CUDA
+compilation, in host and device modes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(__clang__) && defined(__CUDA__) && !defined(__CUDA_ARCH__)</span>
+<span class="cp">// clang compiling CUDA code, host mode.</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if defined(__clang__) && defined(__CUDA__) && defined(__CUDA_ARCH__)</span>
+<span class="cp">// clang compiling CUDA code, device mode.</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>Both clang and nvcc define <tt class="docutils literal"><span class="pre">__CUDACC__</span></tt> during CUDA compilation. You can
+detect NVCC specifically by looking for <tt class="docutils literal"><span class="pre">__NVCC__</span></tt>.</p>
+</div>
+<div class="section" id="dialect-differences-between-clang-and-nvcc">
+<h2><a class="toc-backref" href="#id11">Dialect Differences Between clang and nvcc</a><a class="headerlink" href="#dialect-differences-between-clang-and-nvcc" title="Permalink to this headline">¶</a></h2>
+<p>There is no formal CUDA spec, and clang and nvcc speak slightly different
+dialects of the language. Below, we describe some of the differences.</p>
+<p>This section is painful; hopefully you can skip this section and live your life
+blissfully unaware.</p>
+<div class="section" id="compilation-models">
+<h3><a class="toc-backref" href="#id12">Compilation Models</a><a class="headerlink" href="#compilation-models" title="Permalink to this headline">¶</a></h3>
+<p>Most of the differences between clang and nvcc stem from the different
+compilation models used by clang and nvcc. nvcc uses <em>split compilation</em>,
+which works roughly as follows:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Run a preprocessor over the input <tt class="docutils literal"><span class="pre">.cu</span></tt> file to split it into two source
+files: <tt class="docutils literal"><span class="pre">H</span></tt>, containing source code for the host, and <tt class="docutils literal"><span class="pre">D</span></tt>, containing
+source code for the device.</li>
+<li>For each GPU architecture <tt class="docutils literal"><span class="pre">arch</span></tt> that we’re compiling for, do:<ul>
+<li>Compile <tt class="docutils literal"><span class="pre">D</span></tt> using nvcc proper. The result of this is a <tt class="docutils literal"><span class="pre">ptx</span></tt> file for
+<tt class="docutils literal"><span class="pre">P_arch</span></tt>.</li>
+<li>Optionally, invoke <tt class="docutils literal"><span class="pre">ptxas</span></tt>, the PTX assembler, to generate a file,
+<tt class="docutils literal"><span class="pre">S_arch</span></tt>, containing GPU machine code (SASS) for <tt class="docutils literal"><span class="pre">arch</span></tt>.</li>
+</ul>
+</li>
+<li>Invoke <tt class="docutils literal"><span class="pre">fatbin</span></tt> to combine all <tt class="docutils literal"><span class="pre">P_arch</span></tt> and <tt class="docutils literal"><span class="pre">S_arch</span></tt> files into a
+single “fat binary” file, <tt class="docutils literal"><span class="pre">F</span></tt>.</li>
+<li>Compile <tt class="docutils literal"><span class="pre">H</span></tt> using an external host compiler (gcc, clang, or whatever you
+like). <tt class="docutils literal"><span class="pre">F</span></tt> is packaged up into a header file which is force-included into
+<tt class="docutils literal"><span class="pre">H</span></tt>; nvcc generates code that calls into this header to e.g. launch
+kernels.</li>
+</ul>
+</div></blockquote>
+<p>clang uses <em>merged parsing</em>. This is similar to split compilation, except all
+of the host and device code is present and must be semantically-correct in both
+compilation steps.</p>
+<blockquote>
+<div><ul>
+<li><p class="first">For each GPU architecture <tt class="docutils literal"><span class="pre">arch</span></tt> that we’re compiling for, do:</p>
+<ul>
+<li><p class="first">Compile the input <tt class="docutils literal"><span class="pre">.cu</span></tt> file for device, using clang. <tt class="docutils literal"><span class="pre">__host__</span></tt> code
+is parsed and must be semantically correct, even though we’re not
+generating code for the host at this time.</p>
+<p>The output of this step is a <tt class="docutils literal"><span class="pre">ptx</span></tt> file <tt class="docutils literal"><span class="pre">P_arch</span></tt>.</p>
+</li>
+<li><p class="first">Invoke <tt class="docutils literal"><span class="pre">ptxas</span></tt> to generate a SASS file, <tt class="docutils literal"><span class="pre">S_arch</span></tt>. Note that, unlike
+nvcc, clang always generates SASS code.</p>
+</li>
+</ul>
+</li>
+<li><p class="first">Invoke <tt class="docutils literal"><span class="pre">fatbin</span></tt> to combine all <tt class="docutils literal"><span class="pre">P_arch</span></tt> and <tt class="docutils literal"><span class="pre">S_arch</span></tt> files into a
+single fat binary file, <tt class="docutils literal"><span class="pre">F</span></tt>.</p>
+</li>
+<li><p class="first">Compile <tt class="docutils literal"><span class="pre">H</span></tt> using clang. <tt class="docutils literal"><span class="pre">__device__</span></tt> code is parsed and must be
+semantically correct, even though we’re not generating code for the device
+at this time.</p>
+<p><tt class="docutils literal"><span class="pre">F</span></tt> is passed to this compilation, and clang includes it in a special ELF
+section, where it can be found by tools like <tt class="docutils literal"><span class="pre">cuobjdump</span></tt>.</p>
+</li>
+</ul>
+</div></blockquote>
+<p>(You may ask at this point, why does clang need to parse the input file
+multiple times? Why not parse it just once, and then use the AST to generate
+code for the host and each device architecture?</p>
+<p>Unfortunately this can’t work because we have to define different macros during
+host compilation and during device compilation for each GPU architecture.)</p>
+<p>clang’s approach allows it to be highly robust to C++ edge cases, as it doesn’t
+need to decide at an early stage which declarations to keep and which to throw
+away. But it has some consequences you should be aware of.</p>
+</div>
+<div class="section" id="overloading-based-on-host-and-device-attributes">
+<h3><a class="toc-backref" href="#id13">Overloading Based on <tt class="docutils literal"><span class="pre">__host__</span></tt> and <tt class="docutils literal"><span class="pre">__device__</span></tt> Attributes</a><a class="headerlink" href="#overloading-based-on-host-and-device-attributes" title="Permalink to this headline">¶</a></h3>
+<p>Let “H”, “D”, and “HD” stand for “<tt class="docutils literal"><span class="pre">__host__</span></tt> functions”, “<tt class="docutils literal"><span class="pre">__device__</span></tt>
+functions”, and “<tt class="docutils literal"><span class="pre">__host__</span> <span class="pre">__device__</span></tt> functions”, respectively. Functions
+with no attributes behave the same as H.</p>
+<p>nvcc does not allow you to create H and D functions with the same signature:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// nvcc: error - function "foo" has already been defined</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>However, nvcc allows you to “overload” H and D functions with different
+signatures:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// nvcc: no error</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>In clang, the <tt class="docutils literal"><span class="pre">__host__</span></tt> and <tt class="docutils literal"><span class="pre">__device__</span></tt> attributes are part of a
+function’s signature, and so it’s legal to have H and D functions with
+(otherwise) the same signature:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// clang: no error</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>HD functions cannot be overloaded by H or D functions with the same signature:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// nvcc: error - function "foo" has already been defined</span>
+<span class="c1">// clang: error - redefinition of 'foo'</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+
+<span class="c1">// nvcc: no error</span>
+<span class="c1">// clang: no error</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>When resolving an overloaded function, clang considers the host/device
+attributes of the caller and callee. These are used as a tiebreaker during
+overload resolution. See <a class="reference external" href="http://clang.llvm.org/doxygen/SemaCUDA_8cpp.html">IdentifyCUDAPreference</a> for the full set of rules,
+but at a high level they are:</p>
+<blockquote>
+<div><ul>
+<li><p class="first">D functions prefer to call other Ds. HDs are given lower priority.</p>
+</li>
+<li><p class="first">Similarly, H functions prefer to call other Hs, or <tt class="docutils literal"><span class="pre">__global__</span></tt> functions
+(with equal priority). HDs are given lower priority.</p>
+</li>
+<li><p class="first">HD functions prefer to call other HDs.</p>
+<p>When compiling for device, HDs will call Ds with lower priority than HD, and
+will call Hs with still lower priority. If it’s forced to call an H, the
+program is malformed if we emit code for this HD function. We call this the
+“wrong-side rule”, see example below.</p>
+<p>The rules are symmetrical when compiling for host.</p>
+</li>
+</ul>
+</div></blockquote>
+<p>Some examples:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">();</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">();</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">();</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">();</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">test_host</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// calls H overload</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// calls H overload</span>
+<span class="p">}</span>
+
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">test_device</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// calls D overload</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// calls HD overload</span>
+<span class="p">}</span>
+
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">test_hd</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// calls H overload when compiling for host, otherwise D overload</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// always calls HD overload</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Wrong-side rule example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__host__</span> <span class="kt">void</span> <span class="n">host_only</span><span class="p">();</span>
+
+<span class="c1">// We don't codegen inline functions unless they're referenced by a</span>
+<span class="c1">// non-inline function. inline_hd1() is called only from the host side, so</span>
+<span class="c1">// does not generate an error. inline_hd2() is called from the device side,</span>
+<span class="c1">// so it generates an error.</span>
+<span class="kr">inline</span> <span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">inline_hd1</span><span class="p">()</span> <span class="p">{</span> <span class="n">host_only</span><span class="p">();</span> <span class="p">}</span> <span class="c1">// no error</span>
+<span class="kr">inline</span> <span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">inline_hd2</span><span class="p">()</span> <span class="p">{</span> <span class="n">host_only</span><span class="p">();</span> <span class="p">}</span> <span class="c1">// error</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">host_fn</span><span class="p">()</span> <span class="p">{</span> <span class="n">inline_hd1</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">device_fn</span><span class="p">()</span> <span class="p">{</span> <span class="n">inline_hd2</span><span class="p">();</span> <span class="p">}</span>
+
+<span class="c1">// This function is not inline, so it's always codegen'ed on both the host</span>
+<span class="c1">// and the device. Therefore, it generates an error.</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">not_inline_hd</span><span class="p">()</span> <span class="p">{</span> <span class="n">host_only</span><span class="p">();</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>For the purposes of the wrong-side rule, templated functions also behave like
+<tt class="docutils literal"><span class="pre">inline</span></tt> functions: They aren’t codegen’ed unless they’re instantiated
+(usually as part of the process of invoking them).</p>
+<p>clang’s behavior with respect to the wrong-side rule matches nvcc’s, except
+nvcc only emits a warning for <tt class="docutils literal"><span class="pre">not_inline_hd</span></tt>; device code is allowed to call
+<tt class="docutils literal"><span class="pre">not_inline_hd</span></tt>. In its generated code, nvcc may omit <tt class="docutils literal"><span class="pre">not_inline_hd</span></tt>‘s
+call to <tt class="docutils literal"><span class="pre">host_only</span></tt> entirely, or it may try to generate code for
+<tt class="docutils literal"><span class="pre">host_only</span></tt> on the device. What you get seems to depend on whether or not
+the compiler chooses to inline <tt class="docutils literal"><span class="pre">host_only</span></tt>.</p>
+<p>Member functions, including constructors, may be overloaded using H and D
+attributes. However, destructors cannot be overloaded.</p>
+</div>
+<div class="section" id="using-a-different-class-on-host-device">
+<h3><a class="toc-backref" href="#id14">Using a Different Class on Host/Device</a><a class="headerlink" href="#using-a-different-class-on-host-device" title="Permalink to this headline">¶</a></h3>
+<p>Occasionally you may want to have a class with different host/device versions.</p>
+<p>If all of the class’s members are the same on the host and device, you can just
+provide overloads for the class’s member functions.</p>
+<p>However, if you want your class to have different members on host/device, you
+won’t be able to provide working H and D overloads in both classes. In this
+case, clang is likely to be unhappy with you.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#ifdef __CUDA_ARCH__</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span> <span class="cm">/* use device_only */</span> <span class="p">}</span>
+ <span class="kt">int</span> <span class="n">device_only</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="cp">#else</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span> <span class="cm">/* use host_only */</span> <span class="p">}</span>
+ <span class="kt">double</span> <span class="n">host_only</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">S</span> <span class="n">s</span><span class="p">;</span>
+ <span class="c1">// clang generates an error here, because during host compilation, we</span>
+ <span class="c1">// have ifdef'ed away the __device__ overload of S::foo(). The __device__</span>
+ <span class="c1">// overload must be present *even during host compilation*.</span>
+ <span class="n">S</span><span class="p">.</span><span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>We posit that you don’t really want to have classes with different members on H
+and D. For example, if you were to pass one of these as a parameter to a
+kernel, it would have a different layout on H and D, so would not work
+properly.</p>
+<p>To make code like this compatible with clang, we recommend you separate it out
+into two classes. If you need to write code that works on both host and
+device, consider writing an overloaded wrapper function that returns different
+types on host and device.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">HostS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">DeviceS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+
+<span class="n">__host__</span> <span class="n">HostS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">HostS</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">__device__</span> <span class="n">DeviceS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">DeviceS</span><span class="p">();</span> <span class="p">}</span>
+
+<span class="c1">// Now host and device code can call MakeStruct().</span>
+</pre></div>
+</div>
+<p>Unfortunately, this idiom isn’t compatible with nvcc, because it doesn’t allow
+you to overload based on the H/D attributes. Here’s an idiom that works with
+both clang and nvcc:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">HostS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">DeviceS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+
+<span class="cp">#ifdef __NVCC__</span>
+<span class="cp"> #ifndef __CUDA_ARCH__</span>
+ <span class="n">__host__</span> <span class="n">HostS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">HostS</span><span class="p">();</span> <span class="p">}</span>
+<span class="cp"> #else</span>
+ <span class="n">__device__</span> <span class="n">DeviceS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">DeviceS</span><span class="p">();</span> <span class="p">}</span>
+<span class="cp"> #endif</span>
+<span class="cp">#else</span>
+ <span class="n">__host__</span> <span class="n">HostS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">HostS</span><span class="p">();</span> <span class="p">}</span>
+ <span class="n">__device__</span> <span class="n">DeviceS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">DeviceS</span><span class="p">();</span> <span class="p">}</span>
+<span class="cp">#endif</span>
+
+<span class="c1">// Now host and device code can call MakeStruct().</span>
+</pre></div>
+</div>
+<p>Hopefully you don’t have to do this sort of thing often.</p>
+</div>
+</div>
+<div class="section" id="optimizations">
+<h2><a class="toc-backref" href="#id15">Optimizations</a><a class="headerlink" href="#optimizations" title="Permalink to this headline">¶</a></h2>
+<p>Modern CPUs and GPUs are architecturally quite different, so code that’s fast
+on a CPU isn’t necessarily fast on a GPU. We’ve made a number of changes to
+LLVM to make it generate good GPU code. Among these changes are:</p>
+<ul>
+<li><p class="first"><a class="reference external" href="https://goo.gl/4Rb9As">Straight-line scalar optimizations</a> – These
+reduce redundancy within straight-line code.</p>
+</li>
+<li><p class="first"><a class="reference external" href="http://llvm.org/docs/doxygen/html/SpeculativeExecution_8cpp_source.html">Aggressive speculative execution</a>
+– This is mainly for promoting straight-line scalar optimizations, which are
+most effective on code along dominator paths.</p>
+</li>
+<li><p class="first"><a class="reference external" href="http://llvm.org/doxygen/NVPTXInferAddressSpaces_8cpp_source.html">Memory space inference</a> –
+In PTX, we can operate on pointers that are in a paricular “address space”
+(global, shared, constant, or local), or we can operate on pointers in the
+“generic” address space, which can point to anything. Operations in a
+non-generic address space are faster, but pointers in CUDA are not explicitly
+annotated with their address space, so it’s up to LLVM to infer it where
+possible.</p>
+</li>
+<li><p class="first"><a class="reference external" href="http://llvm.org/docs/doxygen/html/BypassSlowDivision_8cpp_source.html">Bypassing 64-bit divides</a> –
+This was an existing optimization that we enabled for the PTX backend.</p>
+<p>64-bit integer divides are much slower than 32-bit ones on NVIDIA GPUs.
+Many of the 64-bit divides in our benchmarks have a divisor and dividend
+which fit in 32-bits at runtime. This optimization provides a fast path for
+this common case.</p>
+</li>
+<li><p class="first">Aggressive loop unrooling and function inlining – Loop unrolling and
+function inlining need to be more aggressive for GPUs than for CPUs because
+control flow transfer in GPU is more expensive. More aggressive unrolling and
+inlining also promote other optimizations, such as constant propagation and
+SROA, which sometimes speed up code by over 10x.</p>
+<p>(Programmers can force unrolling and inline using clang’s <a class="reference external" href="http://clang.llvm.org/docs/AttributeReference.html#pragma-unroll-pragma-nounroll">loop unrolling pragmas</a>
+and <tt class="docutils literal"><span class="pre">__attribute__((always_inline))</span></tt>.)</p>
+</li>
+</ul>
+</div>
+<div class="section" id="publication">
+<h2><a class="toc-backref" href="#id16">Publication</a><a class="headerlink" href="#publication" title="Permalink to this headline">¶</a></h2>
+<p>The team at Google published a paper in CGO 2016 detailing the optimizations
+they’d made to clang/LLVM. Note that “gpucc” is no longer a meaningful name:
+The relevant tools are now just vanilla clang/LLVM.</p>
+<div class="line-block">
+<div class="line"><a class="reference external" href="http://dl.acm.org/citation.cfm?id=2854041">gpucc: An Open-Source GPGPU Compiler</a></div>
+<div class="line">Jingyue Wu, Artem Belevich, Eli Bendersky, Mark Heffernan, Chris Leary, Jacques Pienaar, Bjarke Roune, Rob Springer, Xuetian Weng, Robert Hundt</div>
+<div class="line"><em>Proceedings of the 2016 International Symposium on Code Generation and Optimization (CGO 2016)</em></div>
+<div class="line"><br /></div>
+<div class="line"><a class="reference external" href="http://wujingyue.com/docs/gpucc-talk.pdf">Slides from the CGO talk</a></div>
+<div class="line"><br /></div>
+<div class="line"><a class="reference external" href="http://wujingyue.com/docs/gpucc-tutorial.pdf">Tutorial given at CGO</a></div>
+</div>
+</div>
+<div class="section" id="obtaining-help">
+<h2><a class="toc-backref" href="#id17">Obtaining Help</a><a class="headerlink" href="#obtaining-help" title="Permalink to this headline">¶</a></h2>
+<p>To obtain help on LLVM in general and its CUDA support, see <a class="reference external" href="http://llvm.org/docs/#mailing-lists">the LLVM
+community</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="ReportingGuide.html" title="Reporting Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodeOfConduct.html" title="LLVM Community Code of Conduct"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CompilerWriterInfo.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CompilerWriterInfo.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CompilerWriterInfo.html (added)
+++ www-releases/trunk/6.0.1/docs/CompilerWriterInfo.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,290 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Architecture & Platform Information for Compiler Writers — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="Extending LLVM: Adding instructions, intrinsics, types, etc." href="ExtendingLLVM.html" />
+ <link rel="prev" title="CommandLine 2.0 Library Manual" href="CommandLine.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CommandLine.html" title="CommandLine 2.0 Library Manual"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="architecture-platform-information-for-compiler-writers">
+<h1>Architecture & Platform Information for Compiler Writers<a class="headerlink" href="#architecture-platform-information-for-compiler-writers" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#hardware" id="id1">Hardware</a><ul>
+<li><a class="reference internal" href="#aarch64-arm" id="id2">AArch64 & ARM</a></li>
+<li><a class="reference internal" href="#itanium-ia64" id="id3">Itanium (ia64)</a></li>
+<li><a class="reference internal" href="#lanai" id="id4">Lanai</a></li>
+<li><a class="reference internal" href="#mips" id="id5">MIPS</a></li>
+<li><a class="reference internal" href="#powerpc" id="id6">PowerPC</a><ul>
+<li><a class="reference internal" href="#ibm-official-manuals-and-docs" id="id7">IBM - Official manuals and docs</a></li>
+<li><a class="reference internal" href="#other-documents-collections-notes" id="id8">Other documents, collections, notes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#amdgpu" id="id9">AMDGPU</a></li>
+<li><a class="reference internal" href="#risc-v" id="id10">RISC-V</a></li>
+<li><a class="reference internal" href="#sparc" id="id11">SPARC</a></li>
+<li><a class="reference internal" href="#systemz" id="id12">SystemZ</a></li>
+<li><a class="reference internal" href="#x86" id="id13">X86</a></li>
+<li><a class="reference internal" href="#xcore" id="id14">XCore</a></li>
+<li><a class="reference internal" href="#hexagon" id="id15">Hexagon</a></li>
+<li><a class="reference internal" href="#other-relevant-lists" id="id16">Other relevant lists</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#abi" id="id17">ABI</a><ul>
+<li><a class="reference internal" href="#linux" id="id18">Linux</a></li>
+<li><a class="reference internal" href="#os-x" id="id19">OS X</a></li>
+<li><a class="reference internal" href="#windows" id="id20">Windows</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nvptx" id="id21">NVPTX</a></li>
+<li><a class="reference internal" href="#miscellaneous-resources" id="id22">Miscellaneous Resources</a></li>
+</ul>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document is a work-in-progress. Additions and clarifications are
+welcome.</p>
+</div>
+<div class="section" id="hardware">
+<h2><a class="toc-backref" href="#id1">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="aarch64-arm">
+<h3><a class="toc-backref" href="#id2">AArch64 & ARM</a><a class="headerlink" href="#aarch64-arm" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.h/index.html">ARMv8-A Architecture Reference Manual</a> (authentication required, free sign-up). This document covers both AArch64 and ARM instructions</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ddi0403e.b/index.html">ARMv7-M Architecture Reference Manual</a> (authentication required, free sign-up). This covers the Thumb2-only microcontrollers</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ddi0419c/index.html">ARMv6-M Architecture Reference Manual</a> (authentication required, free sign-up). This covers the Thumb1-only microcontrollers</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf">ARM C Language Extensions</a></li>
+<li>AArch32 <a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0045d/IHI0045D_ABI_addenda.pdf">ABI Addenda and Errata</a></li>
+</ul>
+</div>
+<div class="section" id="itanium-ia64">
+<h3><a class="toc-backref" href="#id3">Itanium (ia64)</a><a class="headerlink" href="#itanium-ia64" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a></li>
+</ul>
+</div>
+<div class="section" id="lanai">
+<h3><a class="toc-backref" href="#id4">Lanai</a><a class="headerlink" href="#lanai" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://g.co/lanai/isa">Lanai Instruction Set Architecture</a></li>
+</ul>
+</div>
+<div class="section" id="mips">
+<h3><a class="toc-backref" href="#id5">MIPS</a><a class="headerlink" href="#mips" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://imgtec.com/mips/architectures/">MIPS Processor Architecture</a></li>
+<li><a class="reference external" href="http://techpubs.sgi.com/library/manuals/4000/007-4658-001/pdf/007-4658-001.pdf">MIPS 64-bit ELF Object File Specification</a></li>
+</ul>
+</div>
+<div class="section" id="powerpc">
+<h3><a class="toc-backref" href="#id6">PowerPC</a><a class="headerlink" href="#powerpc" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="ibm-official-manuals-and-docs">
+<h4><a class="toc-backref" href="#id7">IBM - Official manuals and docs</a><a class="headerlink" href="#ibm-official-manuals-and-docs" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><a class="reference external" href="https://www.power.org/technology-introduction/standards-specifications">Power Instruction Set Architecture, Versions 2.03 through 2.06 (authentication required, free sign-up)</a></li>
+<li><a class="reference external" href="http://www.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6">PowerPC Compiler Writer’s Guide</a></li>
+<li><a class="reference external" href="http://www.ibm.com/developerworks/linux/library/l-powarch/">Intro to PowerPC Architecture</a></li>
+<li><a class="reference external" href="http://www.ibm.com/chips/techlib/techlib.nsf/products/PowerPC">PowerPC Processor Manuals (embedded)</a></li>
+<li><a class="reference external" href="https://www.power.org/documentation/?document_company=105&document_category=all&publish_year=all&grid_order=DESC&grid_sort=title">Various IBM specifications and white papers</a></li>
+<li><a class="reference external" href="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixassem/alangref/alangreftfrm.htm">IBM AIX/5L for POWER Assembly Reference</a></li>
+</ul>
+</div>
+<div class="section" id="other-documents-collections-notes">
+<h4><a class="toc-backref" href="#id8">Other documents, collections, notes</a><a class="headerlink" href="#other-documents-collections-notes" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><a class="reference external" href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li>
+<li><a class="reference external" href="http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html">PowerPC64 alignment of long doubles (from GCC)</a></li>
+<li><a class="reference external" href="http://sources.redhat.com/ml/binutils/2002-04/msg00573.html">Long branch stubs for powerpc64-linux (from binutils)</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="amdgpu">
+<h3><a class="toc-backref" href="#id9">AMDGPU</a><a class="headerlink" href="#amdgpu" title="Permalink to this headline">¶</a></h3>
+<p>Refer to <a class="reference internal" href="AMDGPUUsage.html"><em>User Guide for AMDGPU Backend</em></a> for additional documentation.</p>
+</div>
+<div class="section" id="risc-v">
+<h3><a class="toc-backref" href="#id10">RISC-V</a><a class="headerlink" href="#risc-v" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://riscv.org/specifications/">RISC-V User-Level ISA Specification</a></li>
+</ul>
+</div>
+<div class="section" id="sparc">
+<h3><a class="toc-backref" href="#id11">SPARC</a><a class="headerlink" href="#sparc" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://sparc.org/standards">SPARC standards</a></li>
+<li><a class="reference external" href="http://sparc.org/standards/64.psabi.1.35.ps.Z">SPARC V9 ABI</a></li>
+<li><a class="reference external" href="http://sparc.org/standards/psABI3rd.pdf">SPARC V8 ABI</a></li>
+</ul>
+</div>
+<div class="section" id="systemz">
+<h3><a class="toc-backref" href="#id12">SystemZ</a><a class="headerlink" href="#systemz" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://www-01.ibm.com/support/docview.wss?uid=isg2b9de5f05a9d57819852571c500428f9a">z/Architecture Principles of Operation (registration required, free sign-up)</a></li>
+</ul>
+</div>
+<div class="section" id="x86">
+<h3><a class="toc-backref" href="#id13">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.amd.com/resources/developer-guides-manuals/">AMD processor manuals</a></li>
+<li><a class="reference external" href="http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html">Intel 64 and IA-32 manuals</a></li>
+<li><a class="reference external" href="http://www.intel.com/design/itanium/documentation.htm?iid=ipp_srvr_proc_itanium2+techdocs">Intel Itanium documentation</a></li>
+<li><a class="reference external" href="https://github.com/hjl-tools/x86-psABI/wiki/X86-psABI">X86 and X86-64 SysV psABI</a></li>
+<li><a class="reference external" href="http://www.agner.org/optimize/calling_conventions.pdf">Calling conventions for different C++ compilers and operating systems</a></li>
+</ul>
+</div>
+<div class="section" id="xcore">
+<h3><a class="toc-backref" href="#id14">XCore</a><a class="headerlink" href="#xcore" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://www.xmos.com/en/download/public/The-XMOS-XS1-Architecture%28X7879A%29.pdf">The XMOS XS1 Architecture (ISA)</a></li>
+<li><a class="reference external" href="https://www.xmos.com/download/public/Tools-Development-Guide%28X9114A%29.pdf">Tools Development Guide (includes ABI)</a></li>
+</ul>
+</div>
+<div class="section" id="hexagon">
+<h3><a class="toc-backref" href="#id15">Hexagon</a><a class="headerlink" href="#hexagon" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://developer.qualcomm.com/software/hexagon-dsp-sdk/tools">Hexagon Programmer’s Reference Manuals and Hexagon ABI Specification (registration required, free sign-up)</a></li>
+</ul>
+</div>
+<div class="section" id="other-relevant-lists">
+<h3><a class="toc-backref" href="#id16">Other relevant lists</a><a class="headerlink" href="#other-relevant-lists" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://gcc.gnu.org/readings.html">GCC reading list</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="abi">
+<h2><a class="toc-backref" href="#id17">ABI</a><a class="headerlink" href="#abi" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://www.sco.com/developers/gabi/latest/contents.html">System V Application Binary Interface</a></li>
+<li><a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/">Itanium C++ ABI</a></li>
+</ul>
+<div class="section" id="linux">
+<h3><a class="toc-backref" href="#id18">Linux</a><a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://github.com/hjl-tools/linux-abi/wiki/Linux-Extensions-to-gABI">Linux extensions to gabi</a></li>
+<li><a class="reference external" href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI Supplement</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055a/IHI0055A_aapcs64.pdf">Procedure Call Standard for the AArch64 Architecture</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0044e/IHI0044E_aaelf.pdf">ELF for the ARM Architecture</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0056a/IHI0056A_aaelf64.pdf">ELF for the ARM 64-bit Architecture (AArch64)</a></li>
+<li><a class="reference external" href="http://legacy.redhat.com/pub/redhat/linux/7.1/es/os/s390x/doc/lzsabi0.pdf">System z ELF ABI Supplement</a></li>
+</ul>
+</div>
+<div class="section" id="os-x">
+<h3><a class="toc-backref" href="#id19">OS X</a><a class="headerlink" href="#os-x" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O Runtime Architecture</a></li>
+<li><a class="reference external" href="http://www.unsanity.org/archives/000044.php">Notes on Mach-O ABI</a></li>
+</ul>
+</div>
+<div class="section" id="windows">
+<h3><a class="toc-backref" href="#id20">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://www.microsoft.com/whdc/system/platform/firmware/pecoff.mspx">Microsoft PE/COFF Specification</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="nvptx">
+<h2><a class="toc-backref" href="#id21">NVPTX</a><a class="headerlink" href="#nvptx" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://docs.nvidia.com/cuda/index.html">CUDA Documentation</a> includes the PTX
+ISA and Driver API documentation</li>
+</ul>
+</div>
+<div class="section" id="miscellaneous-resources">
+<h2><a class="toc-backref" href="#id22">Miscellaneous Resources</a><a class="headerlink" href="#miscellaneous-resources" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://www.nondot.org/sabre/os/articles/ExecutableFileFormats/">Executable File Format library</a></li>
+<li><a class="reference external" href="http://gcc.gnu.org/projects/prefetch.html">GCC prefetch project</a> page has a
+good survey of the prefetching capabilities of a variety of modern
+processors.</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CommandLine.html" title="CommandLine 2.0 Library Manual"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/Coroutines.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/Coroutines.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/Coroutines.html (added)
+++ www-releases/trunk/6.0.1/docs/Coroutines.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,1230 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Coroutines in LLVM — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="Global Instruction Selection" href="GlobalISel.html" />
+ <link rel="prev" title="Machine IR (MIR) Format Reference Manual" href="MIRLangRef.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GlobalISel.html" title="Global Instruction Selection"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="coroutines-in-llvm">
+<h1>Coroutines in LLVM<a class="headerlink" href="#coroutines-in-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id45">Introduction</a></li>
+<li><a class="reference internal" href="#coroutines-by-example" id="id46">Coroutines by Example</a><ul>
+<li><a class="reference internal" href="#coroutine-representation" id="id47">Coroutine Representation</a></li>
+<li><a class="reference internal" href="#coroutine-transformation" id="id48">Coroutine Transformation</a></li>
+<li><a class="reference internal" href="#avoiding-heap-allocations" id="id49">Avoiding Heap Allocations</a></li>
+<li><a class="reference internal" href="#multiple-suspend-points" id="id50">Multiple Suspend Points</a></li>
+<li><a class="reference internal" href="#distinct-save-and-suspend" id="id51">Distinct Save and Suspend</a></li>
+<li><a class="reference internal" href="#coroutine-promise" id="id52">Coroutine Promise</a></li>
+<li><a class="reference internal" href="#final-suspend" id="id53">Final Suspend</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#intrinsics" id="id54">Intrinsics</a><ul>
+<li><a class="reference internal" href="#coroutine-manipulation-intrinsics" id="id55">Coroutine Manipulation Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-coro-destroy-intrinsic" id="id56">‘llvm.coro.destroy’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-resume-intrinsic" id="id57">‘llvm.coro.resume’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-done-intrinsic" id="id58">‘llvm.coro.done’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-promise-intrinsic" id="id59">‘llvm.coro.promise’ Intrinsic</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#coroutine-structure-intrinsics" id="id60">Coroutine Structure Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-coro-size-intrinsic" id="id61">‘llvm.coro.size’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-begin-intrinsic" id="id62">‘llvm.coro.begin’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-free-intrinsic" id="id63">‘llvm.coro.free’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-alloc-intrinsic" id="id64">‘llvm.coro.alloc’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-frame-intrinsic" id="id65">‘llvm.coro.frame’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-id-intrinsic" id="id66">‘llvm.coro.id’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-end-intrinsic" id="id67">‘llvm.coro.end’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-suspend-intrinsic" id="id68">‘llvm.coro.suspend’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-save-intrinsic" id="id69">‘llvm.coro.save’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-param-intrinsic" id="id70">‘llvm.coro.param’ Intrinsic</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#coroutine-transformation-passes" id="id71">Coroutine Transformation Passes</a><ul>
+<li><a class="reference internal" href="#coroearly" id="id72">CoroEarly</a></li>
+<li><a class="reference internal" href="#corosplit" id="id73">CoroSplit</a></li>
+<li><a class="reference internal" href="#coroelide" id="id74">CoroElide</a></li>
+<li><a class="reference internal" href="#corocleanup" id="id75">CoroCleanup</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#areas-requiring-attention" id="id76">Areas Requiring Attention</a></li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This is a work in progress. Compatibility across LLVM releases is not
+guaranteed.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id45">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p id="coroutine-handle">LLVM coroutines are functions that have one or more <a class="reference internal" href="#suspend-points">suspend points</a>.
+When a suspend point is reached, the execution of a coroutine is suspended and
+control is returned back to its caller. A suspended coroutine can be resumed
+to continue execution from the last suspend point or it can be destroyed.</p>
+<p>In the following example, we call function <cite>f</cite> (which may or may not be a
+coroutine itself) that returns a handle to a suspended coroutine
+(<strong>coroutine handle</strong>) that is used by <cite>main</cite> to resume the coroutine twice and
+then destroy it:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@f</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.destroy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p id="coroutine-frame">In addition to the function stack frame which exists when a coroutine is
+executing, there is an additional region of storage that contains objects that
+keep the coroutine state when a coroutine is suspended. This region of storage
+is called <strong>coroutine frame</strong>. It is created when a coroutine is called and
+destroyed when a coroutine runs to completion or destroyed by a call to
+the <a class="reference internal" href="#coro-destroy">coro.destroy</a> intrinsic.</p>
+<p>An LLVM coroutine is represented as an LLVM function that has calls to
+<a class="reference internal" href="#coroutine-intrinsics">coroutine intrinsics</a> defining the structure of the coroutine.
+After lowering, a coroutine is split into several
+functions that represent three different ways of how control can enter the
+coroutine:</p>
+<ol class="arabic simple">
+<li>a ramp function, which represents an initial invocation of the coroutine that
+creates the coroutine frame and executes the coroutine code until it
+encounters a suspend point or reaches the end of the function;</li>
+<li>a coroutine resume function that is invoked when the coroutine is resumed;</li>
+<li>a coroutine destroy function that is invoked when the coroutine is destroyed.</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Splitting out resume and destroy functions are just one of the
+possible ways of lowering the coroutine. We chose it for initial
+implementation as it matches closely the mental model and results in
+reasonably nice code.</p>
+</div>
+</div>
+<div class="section" id="coroutines-by-example">
+<h2><a class="toc-backref" href="#id46">Coroutines by Example</a><a class="headerlink" href="#coroutines-by-example" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="coroutine-representation">
+<h3><a class="toc-backref" href="#id47">Coroutine Representation</a><a class="headerlink" href="#coroutine-representation" title="Permalink to this headline">¶</a></h3>
+<p>Let’s look at an example of an LLVM coroutine with the behavior sketched
+by the following pseudo-code.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span><span class="p">(;;)</span> <span class="p">{</span>
+ <span class="n">print</span><span class="p">(</span><span class="n">n</span><span class="o">++</span><span class="p">);</span>
+ <span class="o"><</span><span class="n">suspend</span><span class="o">></span> <span class="c1">// returns a coroutine handle on first suspend</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This coroutine calls some function <cite>print</cite> with value <cite>n</cite> as an argument and
+suspends execution. Every time this coroutine resumes, it calls <cite>print</cite> again with an argument one bigger than the last time. This coroutine never completes by itself and must be destroyed explicitly. If we use this coroutine with
+a <cite>main</cite> shown in the previous section. It will call <cite>print</cite> with values 4, 5
+and 6 after which the coroutine will be destroyed.</p>
+<p>The LLVM IR for this coroutine looks like this:</p>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %size = call i32 @llvm.coro.size.i32()
+ %alloc = call i8* @malloc(i32 %size)
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+ br label %loop
+loop:
+ %n.val = phi i32 [ %n, %entry ], [ %inc, %loop ]
+ %inc = add nsw i32 %n.val, 1
+ call void @print(i32 %n.val)
+ %0 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %0, label %suspend [i8 0, label %loop
+ i8 1, label %cleanup]
+cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+ call void @free(i8* %mem)
+ br label %suspend
+suspend:
+ %unused = call i1 @llvm.coro.end(i8* %hdl, i1 false)
+ ret i8* %hdl
+}</pre>
+</div>
+<p>The <cite>entry</cite> block establishes the coroutine frame. The <a class="reference internal" href="#coro-size">coro.size</a> intrinsic is
+lowered to a constant representing the size required for the coroutine frame.
+The <a class="reference internal" href="#coro-begin">coro.begin</a> intrinsic initializes the coroutine frame and returns the
+coroutine handle. The second parameter of <cite>coro.begin</cite> is given a block of memory
+to be used if the coroutine frame needs to be allocated dynamically.
+The <a class="reference internal" href="#coro-id">coro.id</a> intrinsic serves as coroutine identity useful in cases when the
+<a class="reference internal" href="#coro-begin">coro.begin</a> intrinsic get duplicated by optimization passes such as
+jump-threading.</p>
+<p>The <cite>cleanup</cite> block destroys the coroutine frame. The <a class="reference internal" href="#coro-free">coro.free</a> intrinsic,
+given the coroutine handle, returns a pointer of the memory block to be freed or
+<cite>null</cite> if the coroutine frame was not allocated dynamically. The <cite>cleanup</cite>
+block is entered when coroutine runs to completion by itself or destroyed via
+call to the <a class="reference internal" href="#coro-destroy">coro.destroy</a> intrinsic.</p>
+<p>The <cite>suspend</cite> block contains code to be executed when coroutine runs to
+completion or suspended. The <a class="reference internal" href="#coro-end">coro.end</a> intrinsic marks the point where
+a coroutine needs to return control back to the caller if it is not an initial
+invocation of the coroutine.</p>
+<p>The <cite>loop</cite> blocks represents the body of the coroutine. The <a class="reference internal" href="#coro-suspend">coro.suspend</a>
+intrinsic in combination with the following switch indicates what happens to
+control flow when a coroutine is suspended (default case), resumed (case 0) or
+destroyed (case 1).</p>
+</div>
+<div class="section" id="coroutine-transformation">
+<h3><a class="toc-backref" href="#id48">Coroutine Transformation</a><a class="headerlink" href="#coroutine-transformation" title="Permalink to this headline">¶</a></h3>
+<p>One of the steps of coroutine lowering is building the coroutine frame. The
+def-use chains are analyzed to determine which objects need be kept alive across
+suspend points. In the coroutine shown in the previous section, use of virtual register
+<cite>%n.val</cite> is separated from the definition by a suspend point, therefore, it
+cannot reside on the stack frame since the latter goes away once the coroutine
+is suspended and control is returned back to the caller. An i32 slot is
+allocated in the coroutine frame and <cite>%n.val</cite> is spilled and reloaded from that
+slot as needed.</p>
+<p>We also store addresses of the resume and destroy functions so that the
+<cite>coro.resume</cite> and <cite>coro.destroy</cite> intrinsics can resume and destroy the coroutine
+when its identity cannot be determined statically at compile time. For our
+example, the coroutine frame will be:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%f.frame</span> <span class="p">=</span> <span class="k">type</span> <span class="p">{</span> <span class="kt">void</span> <span class="p">(</span><span class="nv">%f.frame</span><span class="p">*)*,</span> <span class="kt">void</span> <span class="p">(</span><span class="nv">%f.frame</span><span class="p">*)*,</span> <span class="k">i32</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>After resume and destroy parts are outlined, function <cite>f</cite> will contain only the
+code responsible for creation and initialization of the coroutine frame and
+execution of the coroutine until a suspend point is reached:</p>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %alloc = call noalias i8* @malloc(i32 24)
+ %0 = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+ %frame = bitcast i8* %0 to %f.frame*
+ %1 = getelementptr %f.frame, %f.frame* %frame, i32 0, i32 0
+ store void (%f.frame*)* @f.resume, void (%f.frame*)** %1
+ %2 = getelementptr %f.frame, %f.frame* %frame, i32 0, i32 1
+ store void (%f.frame*)* @f.destroy, void (%f.frame*)** %2
+
+ %inc = add nsw i32 %n, 1
+ %inc.spill.addr = getelementptr inbounds %f.Frame, %f.Frame* %FramePtr, i32 0, i32 2
+ store i32 %inc, i32* %inc.spill.addr
+ call void @print(i32 %n)
+
+ ret i8* %frame
+}</pre>
+</div>
+<p>Outlined resume part of the coroutine will reside in function <cite>f.resume</cite>:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">internal</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@f.resume</span><span class="p">(</span><span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.resume</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%inc.spill.addr</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%f.frame</span><span class="p">,</span> <span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.resume</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span>
+ <span class="nv">%inc.spill</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%inc.spill.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="nv">%inc</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%n.val</span><span class="p">,</span> <span class="m">1</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%inc</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%inc.spill.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%inc</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Whereas function <cite>f.destroy</cite> will contain the cleanup code for the coroutine:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">internal</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@f.destroy</span><span class="p">(</span><span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.destroy</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.destroy</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@free</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%0</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="avoiding-heap-allocations">
+<h3><a class="toc-backref" href="#id49">Avoiding Heap Allocations</a><a class="headerlink" href="#avoiding-heap-allocations" title="Permalink to this headline">¶</a></h3>
+<p>A particular coroutine usage pattern, which is illustrated by the <cite>main</cite>
+function in the overview section, where a coroutine is created, manipulated and
+destroyed by the same calling function, is common for coroutines implementing
+RAII idiom and is suitable for allocation elision optimization which avoid
+dynamic allocation by storing the coroutine frame as a static <cite>alloca</cite> in its
+caller.</p>
+<p>In the entry block, we will call <a class="reference internal" href="#coro-alloc">coro.alloc</a> intrinsic that will return <cite>true</cite>
+when dynamic allocation is required, and <cite>false</cite> if dynamic allocation is
+elided.</p>
+<div class="highlight-llvm"><pre>entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %need.dyn.alloc = call i1 @llvm.coro.alloc(token %id)
+ br i1 %need.dyn.alloc, label %dyn.alloc, label %coro.begin
+dyn.alloc:
+ %size = call i32 @llvm.coro.size.i32()
+ %alloc = call i8* @CustomAlloc(i32 %size)
+ br label %coro.begin
+coro.begin:
+ %phi = phi i8* [ null, %entry ], [ %alloc, %dyn.alloc ]
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %phi)</pre>
+</div>
+<p>In the cleanup block, we will make freeing the coroutine frame conditional on
+<a class="reference internal" href="#coro-free">coro.free</a> intrinsic. If allocation is elided, <a class="reference internal" href="#coro-free">coro.free</a> returns <cite>null</cite>
+thus skipping the deallocation code:</p>
+<div class="highlight-llvm"><pre>cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+ %need.dyn.free = icmp ne i8* %mem, null
+ br i1 %need.dyn.free, label %dyn.free, label %if.end
+dyn.free:
+ call void @CustomFree(i8* %mem)
+ br label %if.end
+if.end:
+ ...</pre>
+</div>
+<p>With allocations and deallocations represented as described as above, after
+coroutine heap allocation elision optimization, the resulting main will be:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">5</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">6</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="multiple-suspend-points">
+<h3><a class="toc-backref" href="#id50">Multiple Suspend Points</a><a class="headerlink" href="#multiple-suspend-points" title="Permalink to this headline">¶</a></h3>
+<p>Let’s consider the coroutine that has more than one suspend point:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span><span class="p">(;;)</span> <span class="p">{</span>
+ <span class="n">print</span><span class="p">(</span><span class="n">n</span><span class="o">++</span><span class="p">);</span>
+ <span class="o"><</span><span class="n">suspend</span><span class="o">></span>
+ <span class="n">print</span><span class="p">(</span><span class="o">-</span><span class="n">n</span><span class="p">);</span>
+ <span class="o"><</span><span class="n">suspend</span><span class="o">></span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Matching LLVM code would look like (with the rest of the code remaining the same
+as the code in the previous section):</p>
+<div class="highlight-llvm"><pre>loop:
+ %n.addr = phi i32 [ %n, %entry ], [ %inc, %loop.resume ]
+ call void @print(i32 %n.addr) #4
+ %2 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %2, label %suspend [i8 0, label %loop.resume
+ i8 1, label %cleanup]
+loop.resume:
+ %inc = add nsw i32 %n.addr, 1
+ %sub = xor i32 %n.addr, -1
+ call void @print(i32 %sub)
+ %3 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %3, label %suspend [i8 0, label %loop
+ i8 1, label %cleanup]</pre>
+</div>
+<p>In this case, the coroutine frame would include a suspend index that will
+indicate at which suspend point the coroutine needs to resume. The resume
+function will use an index to jump to an appropriate basic block and will look
+as follows:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">internal</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@f.Resume</span><span class="p">(</span><span class="nv">%f.Frame</span><span class="p">*</span> <span class="nv">%FramePtr</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry.Resume:</span>
+ <span class="nv">%index.addr</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="k">inbounds</span> <span class="nv">%f.Frame</span><span class="p">,</span> <span class="nv">%f.Frame</span><span class="p">*</span> <span class="nv">%FramePtr</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span>
+ <span class="nv">%index</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i8</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%index.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">1</span>
+ <span class="nv">%switch</span> <span class="p">=</span> <span class="k">icmp</span> <span class="k">eq</span> <span class="k">i8</span> <span class="nv">%index</span><span class="p">,</span> <span class="m">0</span>
+ <span class="nv">%n.addr</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="k">inbounds</span> <span class="nv">%f.Frame</span><span class="p">,</span> <span class="nv">%f.Frame</span><span class="p">*</span> <span class="nv">%FramePtr</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">3</span>
+ <span class="nv">%n</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%n.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%switch</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop.resume</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop</span>
+
+<span class="nl">loop.resume:</span>
+ <span class="nv">%sub</span> <span class="p">=</span> <span class="k">xor</span> <span class="k">i32</span> <span class="nv">%n</span><span class="p">,</span> <span class="m">-1</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%sub</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%suspend</span>
+<span class="nl">loop:</span>
+ <span class="nv">%inc</span> <span class="p">=</span> <span class="k">add</span> <span class="k">nsw</span> <span class="k">i32</span> <span class="nv">%n</span><span class="p">,</span> <span class="m">1</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%inc</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%n.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%inc</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%suspend</span>
+
+<span class="nl">suspend:</span>
+ <span class="nv">%storemerge</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i8</span> <span class="p">[</span> <span class="m">0</span><span class="p">,</span> <span class="nv">%loop</span> <span class="p">],</span> <span class="p">[</span> <span class="m">1</span><span class="p">,</span> <span class="nv">%loop.resume</span> <span class="p">]</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="nv">%storemerge</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%index.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">1</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If different cleanup code needs to get executed for different suspend points,
+a similar switch will be in the <cite>f.destroy</cite> function.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Using suspend index in a coroutine state and having a switch in <cite>f.resume</cite> and
+<cite>f.destroy</cite> is one of the possible implementation strategies. We explored
+another option where a distinct <cite>f.resume1</cite>, <cite>f.resume2</cite>, etc. are created for
+every suspend point, and instead of storing an index, the resume and destroy
+function pointers are updated at every suspend. Early testing showed that the
+current approach is easier on the optimizer than the latter so it is a
+lowering strategy implemented at the moment.</p>
+</div>
+</div>
+<div class="section" id="distinct-save-and-suspend">
+<h3><a class="toc-backref" href="#id51">Distinct Save and Suspend</a><a class="headerlink" href="#distinct-save-and-suspend" title="Permalink to this headline">¶</a></h3>
+<p>In the previous example, setting a resume index (or some other state change that
+needs to happen to prepare a coroutine for resumption) happens at the same time as
+a suspension of a coroutine. However, in certain cases, it is necessary to control
+when coroutine is prepared for resumption and when it is suspended.</p>
+<p>In the following example, a coroutine represents some activity that is driven
+by completions of asynchronous operations <cite>async_op1</cite> and <cite>async_op2</cite> which get
+a coroutine handle as a parameter and resume the coroutine once async
+operation is finished.</p>
+<div class="highlight-text"><div class="highlight"><pre>void g() {
+ for (;;)
+ if (cond()) {
+ async_op1(<coroutine-handle>); // will resume once async_op1 completes
+ <suspend>
+ do_one();
+ }
+ else {
+ async_op2(<coroutine-handle>); // will resume once async_op2 completes
+ <suspend>
+ do_two();
+ }
+ }
+}
+</pre></div>
+</div>
+<p>In this case, coroutine should be ready for resumption prior to a call to
+<cite>async_op1</cite> and <cite>async_op2</cite>. The <a class="reference internal" href="#coro-save">coro.save</a> intrinsic is used to indicate a
+point when coroutine should be ready for resumption (namely, when a resume index
+should be stored in the coroutine frame, so that it can be resumed at the
+correct resume point):</p>
+<div class="highlight-llvm"><pre>if.true:
+ %save1 = call token @llvm.coro.save(i8* %hdl)
+ call void @async_op1(i8* %hdl)
+ %suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
+ switch i8 %suspend1, label %suspend [i8 0, label %resume1
+ i8 1, label %cleanup]
+if.false:
+ %save2 = call token @llvm.coro.save(i8* %hdl)
+ call void @async_op2(i8* %hdl)
+ %suspend2 = call i1 @llvm.coro.suspend(token %save2, i1 false)
+ switch i8 %suspend1, label %suspend [i8 0, label %resume2
+ i8 1, label %cleanup]</pre>
+</div>
+</div>
+<div class="section" id="coroutine-promise">
+<span id="id1"></span><h3><a class="toc-backref" href="#id52">Coroutine Promise</a><a class="headerlink" href="#coroutine-promise" title="Permalink to this headline">¶</a></h3>
+<p>A coroutine author or a frontend may designate a distinguished <cite>alloca</cite> that can
+be used to communicate with the coroutine. This distinguished alloca is called
+<strong>coroutine promise</strong> and is provided as the second parameter to the
+<a class="reference internal" href="#coro-id">coro.id</a> intrinsic.</p>
+<p>The following coroutine designates a 32 bit integer <cite>promise</cite> and uses it to
+store the current value produced by a coroutine.</p>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %promise = alloca i32
+ %pv = bitcast i32* %promise to i8*
+ %id = call token @llvm.coro.id(i32 0, i8* %pv, i8* null, i8* null)
+ %need.dyn.alloc = call i1 @llvm.coro.alloc(token %id)
+ br i1 %need.dyn.alloc, label %dyn.alloc, label %coro.begin
+dyn.alloc:
+ %size = call i32 @llvm.coro.size.i32()
+ %alloc = call i8* @malloc(i32 %size)
+ br label %coro.begin
+coro.begin:
+ %phi = phi i8* [ null, %entry ], [ %alloc, %dyn.alloc ]
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %phi)
+ br label %loop
+loop:
+ %n.val = phi i32 [ %n, %coro.begin ], [ %inc, %loop ]
+ %inc = add nsw i32 %n.val, 1
+ store i32 %n.val, i32* %promise
+ %0 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %0, label %suspend [i8 0, label %loop
+ i8 1, label %cleanup]
+cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+ call void @free(i8* %mem)
+ br label %suspend
+suspend:
+ %unused = call i1 @llvm.coro.end(i8* %hdl, i1 false)
+ ret i8* %hdl
+}</pre>
+</div>
+<p>A coroutine consumer can rely on the <a class="reference internal" href="#coro-promise">coro.promise</a> intrinsic to access the
+coroutine promise.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@f</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="nv">%promise.addr.raw</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.promise</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">,</span> <span class="k">i32</span> <span class="m">4</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="nv">%promise.addr</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%promise.addr.raw</span> <span class="k">to</span> <span class="k">i32</span><span class="p">*</span>
+ <span class="nv">%val0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%promise.addr</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%val0</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="nv">%val1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%promise.addr</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%val1</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="nv">%val2</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%promise.addr</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%val2</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.destroy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>After example in this section is compiled, result of the compilation will be:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">5</span><span class="p">)</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">6</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="final-suspend">
+<span id="final"></span><span id="id2"></span><h3><a class="toc-backref" href="#id53">Final Suspend</a><a class="headerlink" href="#final-suspend" title="Permalink to this headline">¶</a></h3>
+<p>A coroutine author or a frontend may designate a particular suspend to be final,
+by setting the second argument of the <a class="reference internal" href="#coro-suspend">coro.suspend</a> intrinsic to <cite>true</cite>.
+Such a suspend point has two properties:</p>
+<ul class="simple">
+<li>it is possible to check whether a suspended coroutine is at the final suspend
+point via <a class="reference internal" href="#coro-done">coro.done</a> intrinsic;</li>
+<li>a resumption of a coroutine stopped at the final suspend point leads to
+undefined behavior. The only possible action for a coroutine at a final
+suspend point is destroying it via <a class="reference internal" href="#coro-destroy">coro.destroy</a> intrinsic.</li>
+</ul>
+<p>From the user perspective, the final suspend point represents an idea of a
+coroutine reaching the end. From the compiler perspective, it is an optimization
+opportunity for reducing number of resume points (and therefore switch cases) in
+the resume function.</p>
+<p>The following is an example of a function that keeps resuming the coroutine
+until the final suspend point is reached after which point the coroutine is
+destroyed:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@f</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%while</span>
+<span class="nl">while:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="nv">%done</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.done</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%done</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%end</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%while</span>
+<span class="nl">end:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.destroy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Usually, final suspend point is a frontend injected suspend point that does not
+correspond to any explicitly authored suspend point of the high level language.
+For example, for a Python generator that has only one suspend point:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">coroutine</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
+ <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
+ <span class="k">yield</span> <span class="n">i</span>
+</pre></div>
+</div>
+<p>Python frontend would inject two more suspend points, so that the actual code
+looks like this:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span><span class="o">*</span> <span class="nf">coroutine</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">current_value</span><span class="p">;</span>
+ <span class="o"><</span><span class="n">designate</span> <span class="n">current_value</span> <span class="n">to</span> <span class="n">be</span> <span class="n">coroutine</span> <span class="n">promise</span><span class="o">></span>
+ <span class="o"><</span><span class="n">SUSPEND</span><span class="o">></span> <span class="c1">// injected suspend point, so that the coroutine starts suspended</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">current_value</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span> <span class="o"><</span><span class="n">SUSPEND</span><span class="o">></span><span class="p">;</span> <span class="c1">// corresponds to "yield i"</span>
+ <span class="p">}</span>
+ <span class="o"><</span><span class="n">SUSPEND</span> <span class="n">final</span><span class="o">=</span><span class="nb">true</span><span class="o">></span> <span class="c1">// injected final suspend point</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>and python iterator <cite>__next__</cite> would look like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__next__</span><span class="p">(</span><span class="kt">void</span><span class="o">*</span> <span class="n">hdl</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">coro</span><span class="p">.</span><span class="n">resume</span><span class="p">(</span><span class="n">hdl</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">coro</span><span class="p">.</span><span class="n">done</span><span class="p">(</span><span class="n">hdl</span><span class="p">))</span> <span class="k">throw</span> <span class="n">StopIteration</span><span class="p">();</span>
+ <span class="k">return</span> <span class="o">*</span><span class="p">(</span><span class="kt">int</span><span class="o">*</span><span class="p">)</span><span class="n">coro</span><span class="p">.</span><span class="n">promise</span><span class="p">(</span><span class="n">hdl</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="kc">false</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="intrinsics">
+<h2><a class="toc-backref" href="#id54">Intrinsics</a><a class="headerlink" href="#intrinsics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="coroutine-manipulation-intrinsics">
+<h3><a class="toc-backref" href="#id55">Coroutine Manipulation Intrinsics</a><a class="headerlink" href="#coroutine-manipulation-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>Intrinsics described in this section are used to manipulate an existing
+coroutine. They can be used in any function which happen to have a pointer
+to a <a class="reference internal" href="#coroutine-frame">coroutine frame</a> or a pointer to a <a class="reference internal" href="#coroutine-promise">coroutine promise</a>.</p>
+<div class="section" id="llvm-coro-destroy-intrinsic">
+<span id="coro-destroy"></span><h4><a class="toc-backref" href="#id56">‘llvm.coro.destroy’ Intrinsic</a><a class="headerlink" href="#llvm-coro-destroy-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="syntax">
+<h5>Syntax:<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-python"><pre>declare void @llvm.coro.destroy(i8* <handle>)</pre>
+</div>
+</div>
+<div class="section" id="overview">
+<h5>Overview:<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.destroy</span></tt>‘ intrinsic destroys a suspended
+coroutine.</p>
+</div>
+<div class="section" id="arguments">
+<h5>Arguments:<a class="headerlink" href="#arguments" title="Permalink to this headline">¶</a></h5>
+<p>The argument is a coroutine handle to a suspended coroutine.</p>
+</div>
+<div class="section" id="semantics">
+<h5>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h5>
+<p>When possible, the <cite>coro.destroy</cite> intrinsic is replaced with a direct call to
+the coroutine destroy function. Otherwise it is replaced with an indirect call
+based on the function pointer for the destroy function stored in the coroutine
+frame. Destroying a coroutine that is not suspended leads to undefined behavior.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-resume-intrinsic">
+<span id="coro-resume"></span><h4><a class="toc-backref" href="#id57">‘llvm.coro.resume’ Intrinsic</a><a class="headerlink" href="#llvm-coro-resume-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare void @llvm.coro.resume(i8* <handle>)</pre>
+</div>
+<div class="section" id="id3">
+<h5>Overview:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.resume</span></tt>‘ intrinsic resumes a suspended coroutine.</p>
+</div>
+<div class="section" id="id4">
+<h5>Arguments:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h5>
+<p>The argument is a handle to a suspended coroutine.</p>
+</div>
+<div class="section" id="id5">
+<h5>Semantics:<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
+<p>When possible, the <cite>coro.resume</cite> intrinsic is replaced with a direct call to the
+coroutine resume function. Otherwise it is replaced with an indirect call based
+on the function pointer for the resume function stored in the coroutine frame.
+Resuming a coroutine that is not suspended leads to undefined behavior.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-done-intrinsic">
+<span id="coro-done"></span><h4><a class="toc-backref" href="#id58">‘llvm.coro.done’ Intrinsic</a><a class="headerlink" href="#llvm-coro-done-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.done(i8* <handle>)</pre>
+</div>
+<div class="section" id="id6">
+<h5>Overview:<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.done</span></tt>‘ intrinsic checks whether a suspended coroutine is at
+the final suspend point or not.</p>
+</div>
+<div class="section" id="id7">
+<h5>Arguments:<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h5>
+<p>The argument is a handle to a suspended coroutine.</p>
+</div>
+<div class="section" id="id8">
+<h5>Semantics:<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
+<p>Using this intrinsic on a coroutine that does not have a <a class="reference internal" href="#final-suspend">final suspend</a> point
+or on a coroutine that is not suspended leads to undefined behavior.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-promise-intrinsic">
+<span id="coro-promise"></span><h4><a class="toc-backref" href="#id59">‘llvm.coro.promise’ Intrinsic</a><a class="headerlink" href="#llvm-coro-promise-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.promise(i8* <ptr>, i32 <alignment>, i1 <from>)</pre>
+</div>
+<div class="section" id="id9">
+<h5>Overview:<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.promise</span></tt>‘ intrinsic obtains a pointer to a
+<a class="reference internal" href="#coroutine-promise">coroutine promise</a> given a coroutine handle and vice versa.</p>
+</div>
+<div class="section" id="id10">
+<h5>Arguments:<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a handle to a coroutine if <cite>from</cite> is false. Otherwise,
+it is a pointer to a coroutine promise.</p>
+<p>The second argument is an alignment requirements of the promise.
+If a frontend designated <cite>%promise = alloca i32</cite> as a promise, the alignment
+argument to <cite>coro.promise</cite> should be the alignment of <cite>i32</cite> on the target
+platform. If a frontend designated <cite>%promise = alloca i32, align 16</cite> as a
+promise, the alignment argument should be 16.
+This argument only accepts constants.</p>
+<p>The third argument is a boolean indicating a direction of the transformation.
+If <cite>from</cite> is true, the intrinsic returns a coroutine handle given a pointer
+to a promise. If <cite>from</cite> is false, the intrinsics return a pointer to a promise
+from a coroutine handle. This argument only accepts constants.</p>
+</div>
+<div class="section" id="id11">
+<h5>Semantics:<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h5>
+<p>Using this intrinsic on a coroutine that does not have a coroutine promise
+leads to undefined behavior. It is possible to read and modify coroutine
+promise of the coroutine which is currently executing. The coroutine author and
+a coroutine user are responsible to makes sure there is no data races.</p>
+</div>
+<div class="section" id="example">
+<h5>Example:<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %promise = alloca i32
+ %pv = bitcast i32* %promise to i8*
+ ; the second argument to coro.id points to the coroutine promise.
+ %id = call token @llvm.coro.id(i32 0, i8* %pv, i8* null, i8* null)
+ ...
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+ ...
+ store i32 42, i32* %promise ; store something into the promise
+ ...
+ ret i8* %hdl
+}
+
+define i32 @main() {
+entry:
+ %hdl = call i8* @f(i32 4) ; starts the coroutine and returns its handle
+ %promise.addr.raw = call i8* @llvm.coro.promise(i8* %hdl, i32 4, i1 false)
+ %promise.addr = bitcast i8* %promise.addr.raw to i32*
+ %val = load i32, i32* %promise.addr ; load a value from the promise
+ call void @print(i32 %val)
+ call void @llvm.coro.destroy(i8* %hdl)
+ ret i32 0
+}</pre>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="coroutine-structure-intrinsics">
+<span id="coroutine-intrinsics"></span><h3><a class="toc-backref" href="#id60">Coroutine Structure Intrinsics</a><a class="headerlink" href="#coroutine-structure-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>Intrinsics described in this section are used within a coroutine to describe
+the coroutine structure. They should not be used outside of a coroutine.</p>
+<div class="section" id="llvm-coro-size-intrinsic">
+<span id="coro-size"></span><h4><a class="toc-backref" href="#id61">‘llvm.coro.size’ Intrinsic</a><a class="headerlink" href="#llvm-coro-size-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i32 @llvm.coro.size.i32()
+declare i64 @llvm.coro.size.i64()</pre>
+</div>
+<div class="section" id="id12">
+<h5>Overview:<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.size</span></tt>‘ intrinsic returns the number of bytes
+required to store a <a class="reference internal" href="#coroutine-frame">coroutine frame</a>.</p>
+</div>
+<div class="section" id="id13">
+<h5>Arguments:<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h5>
+<p>None</p>
+</div>
+<div class="section" id="id14">
+<h5>Semantics:<a class="headerlink" href="#id14" title="Permalink to this headline">¶</a></h5>
+<p>The <cite>coro.size</cite> intrinsic is lowered to a constant representing the size of
+the coroutine frame.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-begin-intrinsic">
+<span id="coro-begin"></span><h4><a class="toc-backref" href="#id62">‘llvm.coro.begin’ Intrinsic</a><a class="headerlink" href="#llvm-coro-begin-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.begin(token <id>, i8* <mem>)</pre>
+</div>
+<div class="section" id="id15">
+<h5>Overview:<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.begin</span></tt>‘ intrinsic returns an address of the coroutine frame.</p>
+</div>
+<div class="section" id="id16">
+<h5>Arguments:<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a token returned by a call to ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘
+identifying the coroutine.</p>
+<p>The second argument is a pointer to a block of memory where coroutine frame
+will be stored if it is allocated dynamically.</p>
+</div>
+<div class="section" id="id17">
+<h5>Semantics:<a class="headerlink" href="#id17" title="Permalink to this headline">¶</a></h5>
+<p>Depending on the alignment requirements of the objects in the coroutine frame
+and/or on the codegen compactness reasons the pointer returned from <cite>coro.begin</cite>
+may be at offset to the <cite>%mem</cite> argument. (This could be beneficial if
+instructions that express relative access to data can be more compactly encoded
+with small positive and negative offsets).</p>
+<p>A frontend should emit exactly one <cite>coro.begin</cite> intrinsic per coroutine.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-free-intrinsic">
+<span id="coro-free"></span><h4><a class="toc-backref" href="#id63">‘llvm.coro.free’ Intrinsic</a><a class="headerlink" href="#llvm-coro-free-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.free(token %id, i8* <frame>)</pre>
+</div>
+<div class="section" id="id18">
+<h5>Overview:<a class="headerlink" href="#id18" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.free</span></tt>‘ intrinsic returns a pointer to a block of memory where
+coroutine frame is stored or <cite>null</cite> if this instance of a coroutine did not use
+dynamically allocated memory for its coroutine frame.</p>
+</div>
+<div class="section" id="id19">
+<h5>Arguments:<a class="headerlink" href="#id19" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a token returned by a call to ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘
+identifying the coroutine.</p>
+<p>The second argument is a pointer to the coroutine frame. This should be the same
+pointer that was returned by prior <cite>coro.begin</cite> call.</p>
+</div>
+<div class="section" id="example-custom-deallocation-function">
+<h5>Example (custom deallocation function):<a class="headerlink" href="#example-custom-deallocation-function" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %frame)
+ %mem_not_null = icmp ne i8* %mem, null
+ br i1 %mem_not_null, label %if.then, label %if.end
+if.then:
+ call void @CustomFree(i8* %mem)
+ br label %if.end
+if.end:
+ ret void</pre>
+</div>
+</div>
+<div class="section" id="example-standard-deallocation-functions">
+<h5>Example (standard deallocation functions):<a class="headerlink" href="#example-standard-deallocation-functions" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %frame)
+ call void @free(i8* %mem)
+ ret void</pre>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-coro-alloc-intrinsic">
+<span id="coro-alloc"></span><h4><a class="toc-backref" href="#id64">‘llvm.coro.alloc’ Intrinsic</a><a class="headerlink" href="#llvm-coro-alloc-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.alloc(token <id>)</pre>
+</div>
+<div class="section" id="id20">
+<h5>Overview:<a class="headerlink" href="#id20" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.alloc</span></tt>‘ intrinsic returns <cite>true</cite> if dynamic allocation is
+required to obtain a memory for the coroutine frame and <cite>false</cite> otherwise.</p>
+</div>
+<div class="section" id="id21">
+<h5>Arguments:<a class="headerlink" href="#id21" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a token returned by a call to ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘
+identifying the coroutine.</p>
+</div>
+<div class="section" id="id22">
+<h5>Semantics:<a class="headerlink" href="#id22" title="Permalink to this headline">¶</a></h5>
+<p>A frontend should emit at most one <cite>coro.alloc</cite> intrinsic per coroutine.
+The intrinsic is used to suppress dynamic allocation of the coroutine frame
+when possible.</p>
+</div>
+<div class="section" id="id23">
+<h5>Example:<a class="headerlink" href="#id23" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %dyn.alloc.required = call i1 @llvm.coro.alloc(token %id)
+ br i1 %dyn.alloc.required, label %coro.alloc, label %coro.begin
+
+coro.alloc:
+ %frame.size = call i32 @llvm.coro.size()
+ %alloc = call i8* @MyAlloc(i32 %frame.size)
+ br label %coro.begin
+
+coro.begin:
+ %phi = phi i8* [ null, %entry ], [ %alloc, %coro.alloc ]
+ %frame = call i8* @llvm.coro.begin(token %id, i8* %phi)</pre>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-coro-frame-intrinsic">
+<span id="coro-frame"></span><h4><a class="toc-backref" href="#id65">‘llvm.coro.frame’ Intrinsic</a><a class="headerlink" href="#llvm-coro-frame-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.frame()</pre>
+</div>
+<div class="section" id="id24">
+<h5>Overview:<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.frame</span></tt>‘ intrinsic returns an address of the coroutine frame of
+the enclosing coroutine.</p>
+</div>
+<div class="section" id="id25">
+<h5>Arguments:<a class="headerlink" href="#id25" title="Permalink to this headline">¶</a></h5>
+<p>None</p>
+</div>
+<div class="section" id="id26">
+<h5>Semantics:<a class="headerlink" href="#id26" title="Permalink to this headline">¶</a></h5>
+<p>This intrinsic is lowered to refer to the <a class="reference internal" href="#coro-begin">coro.begin</a> instruction. This is
+a frontend convenience intrinsic that makes it easier to refer to the
+coroutine frame.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-id-intrinsic">
+<span id="coro-id"></span><h4><a class="toc-backref" href="#id66">‘llvm.coro.id’ Intrinsic</a><a class="headerlink" href="#llvm-coro-id-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare token @llvm.coro.id(i32 <align>, i8* <promise>, i8* <coroaddr>,
+ i8* <fnaddrs>)</pre>
+</div>
+<div class="section" id="id27">
+<h5>Overview:<a class="headerlink" href="#id27" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘ intrinsic returns a token identifying a coroutine.</p>
+</div>
+<div class="section" id="id28">
+<h5>Arguments:<a class="headerlink" href="#id28" title="Permalink to this headline">¶</a></h5>
+<p>The first argument provides information on the alignment of the memory returned
+by the allocation function and given to <cite>coro.begin</cite> by the first argument. If
+this argument is 0, the memory is assumed to be aligned to 2 * sizeof(i8*).
+This argument only accepts constants.</p>
+<p>The second argument, if not <cite>null</cite>, designates a particular alloca instruction
+to be a <a class="reference internal" href="#coroutine-promise">coroutine promise</a>.</p>
+<p>The third argument is <cite>null</cite> coming out of the frontend. The CoroEarly pass sets
+this argument to point to the function this coro.id belongs to.</p>
+<p>The fourth argument is <cite>null</cite> before coroutine is split, and later is replaced
+to point to a private global constant array containing function pointers to
+outlined resume and destroy parts of the coroutine.</p>
+</div>
+<div class="section" id="id29">
+<h5>Semantics:<a class="headerlink" href="#id29" title="Permalink to this headline">¶</a></h5>
+<p>The purpose of this intrinsic is to tie together <cite>coro.id</cite>, <cite>coro.alloc</cite> and
+<cite>coro.begin</cite> belonging to the same coroutine to prevent optimization passes from
+duplicating any of these instructions unless entire body of the coroutine is
+duplicated.</p>
+<p>A frontend should emit exactly one <cite>coro.id</cite> intrinsic per coroutine.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-end-intrinsic">
+<span id="coro-end"></span><h4><a class="toc-backref" href="#id67">‘llvm.coro.end’ Intrinsic</a><a class="headerlink" href="#llvm-coro-end-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.end(i8* <handle>, i1 <unwind>)</pre>
+</div>
+<div class="section" id="id30">
+<h5>Overview:<a class="headerlink" href="#id30" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.end</span></tt>‘ marks the point where execution of the resume part of
+the coroutine should end and control should return to the caller.</p>
+</div>
+<div class="section" id="id31">
+<h5>Arguments:<a class="headerlink" href="#id31" title="Permalink to this headline">¶</a></h5>
+<p>The first argument should refer to the coroutine handle of the enclosing
+coroutine. A frontend is allowed to supply null as the first parameter, in this
+case <cite>coro-early</cite> pass will replace the null with an appropriate coroutine
+handle value.</p>
+<p>The second argument should be <cite>true</cite> if this coro.end is in the block that is
+part of the unwind sequence leaving the coroutine body due to an exception and
+<cite>false</cite> otherwise.</p>
+</div>
+<div class="section" id="id32">
+<h5>Semantics:<a class="headerlink" href="#id32" title="Permalink to this headline">¶</a></h5>
+<p>The purpose of this intrinsic is to allow frontends to mark the cleanup and
+other code that is only relevant during the initial invocation of the coroutine
+and should not be present in resume and destroy parts.</p>
+<p>This intrinsic is lowered when a coroutine is split into
+the start, resume and destroy parts. In the start part, it is a no-op,
+in resume and destroy parts, it is replaced with <cite>ret void</cite> instruction and
+the rest of the block containing <cite>coro.end</cite> instruction is discarded.
+In landing pads it is replaced with an appropriate instruction to unwind to
+caller. The handling of coro.end differs depending on whether the target is
+using landingpad or WinEH exception model.</p>
+<p>For landingpad based exception model, it is expected that frontend uses the
+<a class="reference internal" href="#coro-end">coro.end</a> intrinsic as follows:</p>
+<div class="highlight-llvm"><pre>ehcleanup:
+ %InResumePart = call i1 @llvm.coro.end(i8* null, i1 true)
+ br i1 %InResumePart, label %eh.resume, label %cleanup.cont
+
+cleanup.cont:
+ ; rest of the cleanup
+
+eh.resume:
+ %exn = load i8*, i8** %exn.slot, align 8
+ %sel = load i32, i32* %ehselector.slot, align 4
+ %lpad.val = insertvalue { i8*, i32 } undef, i8* %exn, 0
+ %lpad.val29 = insertvalue { i8*, i32 } %lpad.val, i32 %sel, 1
+ resume { i8*, i32 } %lpad.val29</pre>
+</div>
+<p>The <cite>CoroSpit</cite> pass replaces <cite>coro.end</cite> with <tt class="docutils literal"><span class="pre">True</span></tt> in the resume functions,
+thus leading to immediate unwind to the caller, whereas in start function it
+is replaced with <tt class="docutils literal"><span class="pre">False</span></tt>, thus allowing to proceed to the rest of the cleanup
+code that is only needed during initial invocation of the coroutine.</p>
+<p>For Windows Exception handling model, a frontend should attach a funclet bundle
+referring to an enclosing cleanuppad as follows:</p>
+<div class="highlight-llvm"><pre>ehcleanup:
+ %tok = cleanuppad within none []
+ %unused = call i1 @llvm.coro.end(i8* null, i1 true) [ "funclet"(token %tok) ]
+ cleanupret from %tok unwind label %RestOfTheCleanup</pre>
+</div>
+<p>The <cite>CoroSplit</cite> pass, if the funclet bundle is present, will insert
+<tt class="docutils literal"><span class="pre">cleanupret</span> <span class="pre">from</span> <span class="pre">%tok</span> <span class="pre">unwind</span> <span class="pre">to</span> <span class="pre">caller</span></tt> before
+the <a class="reference internal" href="#coro-end">coro.end</a> intrinsic and will remove the rest of the block.</p>
+<p>The following table summarizes the handling of <a class="reference internal" href="#coro-end">coro.end</a> intrinsic.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="16%" />
+<col width="17%" />
+<col width="25%" />
+<col width="41%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td colspan="2"> </td>
+<td>In Start Function</td>
+<td>In Resume/Destroy Functions</td>
+</tr>
+<tr class="row-even"><td colspan="2">unwind=false</td>
+<td>nothing</td>
+<td><tt class="docutils literal"><span class="pre">ret</span> <span class="pre">void</span></tt></td>
+</tr>
+<tr class="row-odd"><td rowspan="2">unwind=true</td>
+<td>WinEH</td>
+<td>nothing</td>
+<td><tt class="docutils literal"><span class="pre">cleanupret</span> <span class="pre">unwind</span> <span class="pre">to</span> <span class="pre">caller</span></tt></td>
+</tr>
+<tr class="row-even"><td>Landingpad</td>
+<td>nothing</td>
+<td>nothing</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="llvm-coro-suspend-intrinsic">
+<span id="suspend-points"></span><span id="coro-suspend"></span><h4><a class="toc-backref" href="#id68">‘llvm.coro.suspend’ Intrinsic</a><a class="headerlink" href="#llvm-coro-suspend-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8 @llvm.coro.suspend(token <save>, i1 <final>)</pre>
+</div>
+<div class="section" id="id33">
+<h5>Overview:<a class="headerlink" href="#id33" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.suspend</span></tt>‘ marks the point where execution of the coroutine
+need to get suspended and control returned back to the caller.
+Conditional branches consuming the result of this intrinsic lead to basic blocks
+where coroutine should proceed when suspended (-1), resumed (0) or destroyed
+(1).</p>
+</div>
+<div class="section" id="id34">
+<h5>Arguments:<a class="headerlink" href="#id34" title="Permalink to this headline">¶</a></h5>
+<p>The first argument refers to a token of <cite>coro.save</cite> intrinsic that marks the
+point when coroutine state is prepared for suspension. If <cite>none</cite> token is passed,
+the intrinsic behaves as if there were a <cite>coro.save</cite> immediately preceding
+the <cite>coro.suspend</cite> intrinsic.</p>
+<p>The second argument indicates whether this suspension point is <a class="reference internal" href="#final">final</a>.
+The second argument only accepts constants. If more than one suspend point is
+designated as final, the resume and destroy branches should lead to the same
+basic blocks.</p>
+</div>
+<div class="section" id="example-normal-suspend-point">
+<h5>Example (normal suspend point):<a class="headerlink" href="#example-normal-suspend-point" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>%0 = call i8 @llvm.coro.suspend(token none, i1 false)
+switch i8 %0, label %suspend [i8 0, label %resume
+ i8 1, label %cleanup]</pre>
+</div>
+</div>
+<div class="section" id="example-final-suspend-point">
+<h5>Example (final suspend point):<a class="headerlink" href="#example-final-suspend-point" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>while.end:
+ %s.final = call i8 @llvm.coro.suspend(token none, i1 true)
+ switch i8 %s.final, label %suspend [i8 0, label %trap
+ i8 1, label %cleanup]
+trap:
+ call void @llvm.trap()
+ unreachable</pre>
+</div>
+</div>
+<div class="section" id="id35">
+<h5>Semantics:<a class="headerlink" href="#id35" title="Permalink to this headline">¶</a></h5>
+<p>If a coroutine that was suspended at the suspend point marked by this intrinsic
+is resumed via <a class="reference internal" href="#coro-resume">coro.resume</a> the control will transfer to the basic block
+of the 0-case. If it is resumed via <a class="reference internal" href="#coro-destroy">coro.destroy</a>, it will proceed to the
+basic block indicated by the 1-case. To suspend, coroutine proceed to the
+default label.</p>
+<p>If suspend intrinsic is marked as final, it can consider the <cite>true</cite> branch
+unreachable and can perform optimizations that can take advantage of that fact.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-save-intrinsic">
+<span id="coro-save"></span><h4><a class="toc-backref" href="#id69">‘llvm.coro.save’ Intrinsic</a><a class="headerlink" href="#llvm-coro-save-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare token @llvm.coro.save(i8* <handle>)</pre>
+</div>
+<div class="section" id="id36">
+<h5>Overview:<a class="headerlink" href="#id36" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.save</span></tt>‘ marks the point where a coroutine need to update its
+state to prepare for resumption to be considered suspended (and thus eligible
+for resumption).</p>
+</div>
+<div class="section" id="id37">
+<h5>Arguments:<a class="headerlink" href="#id37" title="Permalink to this headline">¶</a></h5>
+<p>The first argument points to a coroutine handle of the enclosing coroutine.</p>
+</div>
+<div class="section" id="id38">
+<h5>Semantics:<a class="headerlink" href="#id38" title="Permalink to this headline">¶</a></h5>
+<p>Whatever coroutine state changes are required to enable resumption of
+the coroutine from the corresponding suspend point should be done at the point
+of <cite>coro.save</cite> intrinsic.</p>
+</div>
+<div class="section" id="id39">
+<h5>Example:<a class="headerlink" href="#id39" title="Permalink to this headline">¶</a></h5>
+<p>Separate save and suspend points are necessary when a coroutine is used to
+represent an asynchronous control flow driven by callbacks representing
+completions of asynchronous operations.</p>
+<p>In such a case, a coroutine should be ready for resumption prior to a call to
+<cite>async_op</cite> function that may trigger resumption of a coroutine from the same or
+a different thread possibly prior to <cite>async_op</cite> call returning control back
+to the coroutine:</p>
+<div class="highlight-llvm"><pre>%save1 = call token @llvm.coro.save(i8* %hdl)
+call void @async_op1(i8* %hdl)
+%suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
+switch i8 %suspend1, label %suspend [i8 0, label %resume1
+ i8 1, label %cleanup]</pre>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-coro-param-intrinsic">
+<span id="coro-param"></span><h4><a class="toc-backref" href="#id70">‘llvm.coro.param’ Intrinsic</a><a class="headerlink" href="#llvm-coro-param-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.param(i8* <original>, i8* <copy>)</pre>
+</div>
+<div class="section" id="id40">
+<h5>Overview:<a class="headerlink" href="#id40" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.param</span></tt>‘ is used by a frontend to mark up the code used to
+construct and destruct copies of the parameters. If the optimizer discovers that
+a particular parameter copy is not used after any suspends, it can remove the
+construction and destruction of the copy by replacing corresponding coro.param
+with <cite>i1 false</cite> and replacing any use of the <cite>copy</cite> with the <cite>original</cite>.</p>
+</div>
+<div class="section" id="id41">
+<h5>Arguments:<a class="headerlink" href="#id41" title="Permalink to this headline">¶</a></h5>
+<p>The first argument points to an <cite>alloca</cite> storing the value of a parameter to a
+coroutine.</p>
+<p>The second argument points to an <cite>alloca</cite> storing the value of the copy of that
+parameter.</p>
+</div>
+<div class="section" id="id42">
+<h5>Semantics:<a class="headerlink" href="#id42" title="Permalink to this headline">¶</a></h5>
+<p>The optimizer is free to always replace this intrinsic with <cite>i1 true</cite>.</p>
+<p>The optimizer is also allowed to replace it with <cite>i1 false</cite> provided that the
+parameter copy is only used prior to control flow reaching any of the suspend
+points. The code that would be DCE’d if the <cite>coro.param</cite> is replaced with
+<cite>i1 false</cite> is not considered to be a use of the parameter copy.</p>
+<p>The frontend can emit this intrinsic if its language rules allow for this
+optimization.</p>
+</div>
+<div class="section" id="id43">
+<h5>Example:<a class="headerlink" href="#id43" title="Permalink to this headline">¶</a></h5>
+<p>Consider the following example. A coroutine takes two parameters <cite>a</cite> and <cite>b</cite>
+that has a destructor and a move constructor.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">A</span> <span class="p">{</span> <span class="o">~</span><span class="n">A</span><span class="p">();</span> <span class="n">A</span><span class="p">(</span><span class="n">A</span><span class="o">&&</span><span class="p">);</span> <span class="kt">bool</span> <span class="n">foo</span><span class="p">();</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">();</span> <span class="p">};</span>
+
+<span class="n">task</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">f</span><span class="p">(</span><span class="n">A</span> <span class="n">a</span><span class="p">,</span> <span class="n">A</span> <span class="n">b</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="n">foo</span><span class="p">())</span>
+ <span class="k">return</span> <span class="mi">42</span><span class="p">;</span>
+
+ <span class="n">a</span><span class="p">.</span><span class="n">bar</span><span class="p">();</span>
+ <span class="n">co_await</span> <span class="n">read_async</span><span class="p">();</span> <span class="c1">// introduces suspend point</span>
+ <span class="n">b</span><span class="p">.</span><span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that, uses of <cite>b</cite> is used after a suspend point and thus must be copied
+into a coroutine frame, whereas <cite>a</cite> does not have to, since it never used
+after suspend.</p>
+<p>A frontend can create parameter copies for <cite>a</cite> and <cite>b</cite> as follows:</p>
+<div class="highlight-text"><div class="highlight"><pre>task<int> f(A a', A b') {
+ a = alloca A;
+ b = alloca A;
+ // move parameters to its copies
+ if (coro.param(a', a)) A::A(a, A&& a');
+ if (coro.param(b', b)) A::A(b, A&& b');
+ ...
+ // destroy parameters copies
+ if (coro.param(a', a)) A::~A(a);
+ if (coro.param(b', b)) A::~A(b);
+}
+</pre></div>
+</div>
+<p>The optimizer can replace coro.param(a’,a) with <cite>i1 false</cite> and replace all uses
+of <cite>a</cite> with <cite>a’</cite>, since it is not used after suspend.</p>
+<p>The optimizer must replace coro.param(b’, b) with <cite>i1 true</cite>, since <cite>b</cite> is used
+after suspend and therefore, it has to reside in the coroutine frame.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="coroutine-transformation-passes">
+<h2><a class="toc-backref" href="#id71">Coroutine Transformation Passes</a><a class="headerlink" href="#coroutine-transformation-passes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="coroearly">
+<h3><a class="toc-backref" href="#id72">CoroEarly</a><a class="headerlink" href="#coroearly" title="Permalink to this headline">¶</a></h3>
+<p>The pass CoroEarly lowers coroutine intrinsics that hide the details of the
+structure of the coroutine frame, but, otherwise not needed to be preserved to
+help later coroutine passes. This pass lowers <a class="reference internal" href="#coro-frame">coro.frame</a>, <a class="reference internal" href="#coro-done">coro.done</a>,
+and <a class="reference internal" href="#coro-promise">coro.promise</a> intrinsics.</p>
+</div>
+<div class="section" id="corosplit">
+<span id="id44"></span><h3><a class="toc-backref" href="#id73">CoroSplit</a><a class="headerlink" href="#corosplit" title="Permalink to this headline">¶</a></h3>
+<p>The pass CoroSplit buides coroutine frame and outlines resume and destroy parts
+into separate functions.</p>
+</div>
+<div class="section" id="coroelide">
+<h3><a class="toc-backref" href="#id74">CoroElide</a><a class="headerlink" href="#coroelide" title="Permalink to this headline">¶</a></h3>
+<p>The pass CoroElide examines if the inlined coroutine is eligible for heap
+allocation elision optimization. If so, it replaces
+<cite>coro.begin</cite> intrinsic with an address of a coroutine frame placed on its caller
+and replaces <cite>coro.alloc</cite> and <cite>coro.free</cite> intrinsics with <cite>false</cite> and <cite>null</cite>
+respectively to remove the deallocation code.
+This pass also replaces <cite>coro.resume</cite> and <cite>coro.destroy</cite> intrinsics with direct
+calls to resume and destroy functions for a particular coroutine where possible.</p>
+</div>
+<div class="section" id="corocleanup">
+<h3><a class="toc-backref" href="#id75">CoroCleanup</a><a class="headerlink" href="#corocleanup" title="Permalink to this headline">¶</a></h3>
+<p>This pass runs late to lower all coroutine related intrinsics not replaced by
+earlier passes.</p>
+</div>
+</div>
+<div class="section" id="areas-requiring-attention">
+<h2><a class="toc-backref" href="#id76">Areas Requiring Attention</a><a class="headerlink" href="#areas-requiring-attention" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic simple">
+<li>A coroutine frame is bigger than it could be. Adding stack packing and stack
+coloring like optimization on the coroutine frame will result in tighter
+coroutine frames.</li>
+<li>Take advantage of the lifetime intrinsics for the data that goes into the
+coroutine frame. Leave lifetime intrinsics as is for the data that stays in
+allocas.</li>
+<li>The CoroElide optimization pass relies on coroutine ramp function to be
+inlined. It would be beneficial to split the ramp function further to
+increase the chance that it will get inlined into its caller.</li>
+<li>Design a convention that would make it possible to apply coroutine heap
+elision optimization across ABI boundaries.</li>
+<li>Cannot handle coroutines with <cite>inalloca</cite> parameters (used in x86 on Windows).</li>
+<li>Alignment is ignored by coro.begin and coro.free intrinsics.</li>
+<li>Make required changes to make sure that coroutine optimizations work with
+LTO.</li>
+<li>More tests, more tests, more tests</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GlobalISel.html" title="Global Instruction Selection"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/CoverageMappingFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/CoverageMappingFormat.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/CoverageMappingFormat.html (added)
+++ www-releases/trunk/6.0.1/docs/CoverageMappingFormat.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,664 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Code Coverage Mapping Format — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="Garbage Collection Safepoints in LLVM" href="Statepoints.html" />
+ <link rel="prev" title="Using ARM NEON instructions in big endian mode" href="BigEndianNEON.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Statepoints.html" title="Garbage Collection Safepoints in LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-code-coverage-mapping-format">
+<h1>LLVM Code Coverage Mapping Format<a class="headerlink" href="#llvm-code-coverage-mapping-format" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id11">Introduction</a></li>
+<li><a class="reference internal" href="#quick-start" id="id12">Quick Start</a></li>
+<li><a class="reference internal" href="#high-level-overview" id="id13">High Level Overview</a></li>
+<li><a class="reference internal" href="#advanced-concepts" id="id14">Advanced Concepts</a><ul>
+<li><a class="reference internal" href="#mapping-region" id="id15">Mapping Region</a><ul>
+<li><a class="reference internal" href="#source-range" id="id16">Source Range:</a></li>
+<li><a class="reference internal" href="#file-id" id="id17">File ID:</a></li>
+<li><a class="reference internal" href="#counter" id="id18">Counter:</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-ir-representation" id="id19">LLVM IR Representation</a><ul>
+<li><a class="reference internal" href="#coverage-mapping-header" id="id20">Coverage Mapping Header:</a></li>
+<li><a class="reference internal" href="#function-record" id="id21">Function record:</a></li>
+<li><a class="reference internal" href="#encoded-data" id="id22">Encoded data:</a><ul>
+<li><a class="reference internal" href="#dissecting-the-sample" id="id23">Dissecting the sample:</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#encoding" id="id24">Encoding</a><ul>
+<li><a class="reference internal" href="#types" id="id25">Types</a><ul>
+<li><a class="reference internal" href="#leb128" id="id26">LEB128</a></li>
+<li><a class="reference internal" href="#strings" id="id27">Strings</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#file-id-mapping" id="id28">File ID Mapping</a></li>
+<li><a class="reference internal" href="#id3" id="id29">Counter</a><ul>
+<li><a class="reference internal" href="#tag" id="id30">Tag:</a></li>
+<li><a class="reference internal" href="#data" id="id31">Data:</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#counter-expressions" id="id32">Counter Expressions</a></li>
+<li><a class="reference internal" href="#mapping-regions" id="id33">Mapping Regions</a><ul>
+<li><a class="reference internal" href="#sub-array-of-regions" id="id34">Sub-Array of Regions</a></li>
+<li><a class="reference internal" href="#id6" id="id35">Mapping Region</a></li>
+<li><a class="reference internal" href="#header" id="id36">Header</a><ul>
+<li><a class="reference internal" href="#id8" id="id37">Counter:</a></li>
+<li><a class="reference internal" href="#pseudo-counter" id="id38">Pseudo-Counter:</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id9" id="id39">Source Range</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id11">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>LLVM’s code coverage mapping format is used to provide code coverage
+analysis using LLVM’s and Clang’s instrumenation based profiling
+(Clang’s <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option).</p>
+<p>This document is aimed at those who use LLVM’s code coverage mapping to provide
+code coverage analysis for their own programs, and for those who would like
+to know how it works under the hood. A prior knowledge of how Clang’s profile
+guided optimization works is useful, but not required.</p>
+<p>We start by showing how to use LLVM and Clang for code coverage analysis,
+then we briefly describe LLVM’s code coverage mapping format and the
+way that Clang and LLVM’s code coverage tool work with this format. After
+the basics are down, more advanced features of the coverage mapping format
+are discussed - such as the data structures, LLVM IR representation and
+the binary encoding.</p>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id12">Quick Start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>Here’s a short story that describes how to generate code coverage overview
+for a sample source file called <em>test.c</em>.</p>
+<ul>
+<li><p class="first">First, compile an instrumented version of your program using Clang’s
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option with the additional <tt class="docutils literal"><span class="pre">-fcoverage-mapping</span></tt>
+option:</p>
+<p><tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-o</span> <span class="pre">test</span> <span class="pre">-fprofile-instr-generate</span> <span class="pre">-fcoverage-mapping</span> <span class="pre">test.c</span></tt></p>
+</li>
+<li><p class="first">Then, run the instrumented binary. The runtime will produce a file called
+<em>default.profraw</em> containing the raw profile instrumentation data:</p>
+<p><tt class="docutils literal"><span class="pre">./test</span></tt></p>
+</li>
+<li><p class="first">After that, merge the profile data using the <em>llvm-profdata</em> tool:</p>
+<p><tt class="docutils literal"><span class="pre">llvm-profdata</span> <span class="pre">merge</span> <span class="pre">-o</span> <span class="pre">test.profdata</span> <span class="pre">default.profraw</span></tt></p>
+</li>
+<li><p class="first">Finally, run LLVM’s code coverage tool (<em>llvm-cov</em>) to produce the code
+coverage overview for the sample source file:</p>
+<p><tt class="docutils literal"><span class="pre">llvm-cov</span> <span class="pre">show</span> <span class="pre">./test</span> <span class="pre">-instr-profile=test.profdata</span> <span class="pre">test.c</span></tt></p>
+</li>
+</ul>
+</div>
+<div class="section" id="high-level-overview">
+<h2><a class="toc-backref" href="#id13">High Level Overview</a><a class="headerlink" href="#high-level-overview" title="Permalink to this headline">¶</a></h2>
+<p>LLVM’s code coverage mapping format is designed to be a self contained
+data format, that can be embedded into the LLVM IR and object files.
+It’s described in this document as a <strong>mapping</strong> format because its goal is
+to store the data that is required for a code coverage tool to map between
+the specific source ranges in a file and the execution counts obtained
+after running the instrumented version of the program.</p>
+<p>The mapping data is used in two places in the code coverage process:</p>
+<ol class="arabic simple">
+<li>When clang compiles a source file with <tt class="docutils literal"><span class="pre">-fcoverage-mapping</span></tt>, it
+generates the mapping information that describes the mapping between the
+source ranges and the profiling instrumentation counters.
+This information gets embedded into the LLVM IR and conveniently
+ends up in the final executable file when the program is linked.</li>
+<li>It is also used by <em>llvm-cov</em> - the mapping information is extracted from an
+object file and is used to associate the execution counts (the values of the
+profile instrumentation counters), and the source ranges in a file.
+After that, the tool is able to generate various code coverage reports
+for the program.</li>
+</ol>
+<p>The coverage mapping format aims to be a “universal format” that would be
+suitable for usage by any frontend, and not just by Clang. It also aims to
+provide the frontend the possibility of generating the minimal coverage mapping
+data in order to reduce the size of the IR and object files - for example,
+instead of emitting mapping information for each statement in a function, the
+frontend is allowed to group the statements with the same execution count into
+regions of code, and emit the mapping information only for those regions.</p>
+</div>
+<div class="section" id="advanced-concepts">
+<h2><a class="toc-backref" href="#id14">Advanced Concepts</a><a class="headerlink" href="#advanced-concepts" title="Permalink to this headline">¶</a></h2>
+<p>The remainder of this guide is meant to give you insight into the way the
+coverage mapping format works.</p>
+<p>The coverage mapping format operates on a per-function level as the
+profile instrumentation counters are associated with a specific function.
+For each function that requires code coverage, the frontend has to create
+coverage mapping data that can map between the source code ranges and
+the profile instrumentation counters for that function.</p>
+<div class="section" id="mapping-region">
+<h3><a class="toc-backref" href="#id15">Mapping Region</a><a class="headerlink" href="#mapping-region" title="Permalink to this headline">¶</a></h3>
+<p>The function’s coverage mapping data contains an array of mapping regions.
+A mapping region stores the <a class="reference internal" href="#source-code-range">source code range</a> that is covered by this region,
+the <a class="reference internal" href="#coverage-file-id">file id</a>, the <a class="reference internal" href="#coverage-mapping-counter">coverage mapping counter</a> and
+the region’s kind.
+There are several kinds of mapping regions:</p>
+<ul>
+<li><p class="first">Code regions associate portions of source code and <a class="reference internal" href="#coverage-mapping-counters">coverage mapping
+counters</a>. They make up the majority of the mapping regions. They are used
+by the code coverage tool to compute the execution counts for lines,
+highlight the regions of code that were never executed, and to obtain
+the various code coverage statistics for a function.
+For example:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:40 to 9:2</span>
+<span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C1F5'>{ </span> <span class='c1'>// Code Region from 3:17 to 5:4</span>
+<span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span>
+<span style='background-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{ </span> <span class='c1'>// Code Region from 5:10 to 7:4</span>
+<span style='background-color:#F6D55D'> printf("\n"); </span>
+<span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</li>
+<li><p class="first">Skipped regions are used to represent source ranges that were skipped
+by Clang’s preprocessor. They don’t associate with
+<a class="reference internal" href="#coverage-mapping-counters">coverage mapping counters</a>, as the frontend knows that they are never
+executed. They are used by the code coverage tool to mark the skipped lines
+inside a function as non-code lines that don’t have execution counts.
+For example:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:12 to 6:2</span>
+<span style='background-color:#85C1F5'>#ifdef DEBUG </span> <span class='c1'>// Skipped Region from 2:1 to 4:2</span>
+<span style='background-color:#85C1F5'> printf("Hello world"); </span>
+<span style='background-color:#85C1F5'>#</span><span style='background-color:#4A789C'>endif </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</li>
+<li><p class="first">Expansion regions are used to represent Clang’s macro expansions. They
+have an additional property - <em>expanded file id</em>. This property can be
+used by the code coverage tool to find the mapping regions that are created
+as a result of this macro expansion, by checking if their file id matches the
+expanded file id. They don’t associate with <a class="reference internal" href="#coverage-mapping-counters">coverage mapping counters</a>,
+as the code coverage tool can determine the execution count for this region
+by looking up the execution count of the first region with a corresponding
+file id.
+For example:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int func(int x) </span><span style='background-color:#4A789C'>{ </span>
+<span style='background-color:#4A789C'> #define MAX(x,y) </span><span style='background-color:#85C1F5'>((x) > (y)? </span><span style='background-color:#F6D55D'>(x)</span><span style='background-color:#85C1F5'> : </span><span style='background-color:#F4BA70'>(y)</span><span style='background-color:#85C1F5'>)</span><span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> return </span><span style='background-color:#7FCA9F'>MAX</span><span style='background-color:#4A789C'>(x, 42); </span> <span class='c1'>// Expansion Region from 3:10 to 3:13</span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</li>
+</ul>
+<div class="section" id="source-range">
+<span id="source-code-range"></span><h4><a class="toc-backref" href="#id16">Source Range:</a><a class="headerlink" href="#source-range" title="Permalink to this headline">¶</a></h4>
+<p>The source range record contains the starting and ending location of a certain
+mapping region. Both locations include the line and the column numbers.</p>
+</div>
+<div class="section" id="file-id">
+<span id="coverage-file-id"></span><h4><a class="toc-backref" href="#id17">File ID:</a><a class="headerlink" href="#file-id" title="Permalink to this headline">¶</a></h4>
+<p>The file id an integer value that tells us
+in which source file or macro expansion is this region located.
+It enables Clang to produce mapping information for the code
+defined inside macros, like this example demonstrates:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>void func(const char *str) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:28 to 6:2 with file id 0</span>
+<span style='background-color:#4A789C'> #define PUT </span><span style='background-color:#85C1F5'>printf("%s\n", str)</span><span style='background-color:#4A789C'> </span> <span class='c1'>// 2 Code Regions from 2:15 to 2:34 with file ids 1 and 2</span>
+<span style='background-color:#4A789C'> if(*str) </span>
+<span style='background-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Expansion Region from 4:5 to 4:8 with file id 0 that expands a macro with file id 1</span>
+<span style='background-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Expansion Region from 5:3 to 5:6 with file id 0 that expands a macro with file id 2</span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</div>
+<div class="section" id="counter">
+<span id="coverage-mapping-counters"></span><span id="coverage-mapping-counter"></span><h4><a class="toc-backref" href="#id18">Counter:</a><a class="headerlink" href="#counter" title="Permalink to this headline">¶</a></h4>
+<p>A coverage mapping counter can represents a reference to the profile
+instrumentation counter. The execution count for a region with such counter
+is determined by looking up the value of the corresponding profile
+instrumentation counter.</p>
+<p>It can also represent a binary arithmetical expression that operates on
+coverage mapping counters or other expressions.
+The execution count for a region with an expression counter is determined by
+evaluating the expression’s arguments and then adding them together or
+subtracting them from one another.
+In the example below, a subtraction expression is used to compute the execution
+count for the compound statement that follows the <em>else</em> keyword:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Region's counter is a reference to the profile counter #0</span>
+<span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C1F5'>{ </span> <span class='c1'>// Region's counter is a reference to the profile counter #1</span>
+<span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span><span> </span>
+<span style='background-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{ </span> <span class='c1'>// Region's counter is an expression (reference to the profile counter #0 - reference to the profile counter #1)</span>
+<span style='background-color:#F6D55D'> printf("\n"); </span>
+<span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+<p>Finally, a coverage mapping counter can also represent an execution count of
+of zero. The zero counter is used to provide coverage mapping for
+unreachable statements and expressions, like in the example below:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{ </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'> </span><span style='background-color:#85C1F5'>printf("Hello world!\n")</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Unreachable region's counter is zero</span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+<p>The zero counters allow the code coverage tool to display proper line execution
+counts for the unreachable lines and highlight the unreachable code.
+Without them, the tool would think that those lines and regions were still
+executed, as it doesn’t possess the frontend’s knowledge.</p>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-ir-representation">
+<h2><a class="toc-backref" href="#id19">LLVM IR Representation</a><a class="headerlink" href="#llvm-ir-representation" title="Permalink to this headline">¶</a></h2>
+<p>The coverage mapping data is stored in the LLVM IR using a single global
+constant structure variable called <em>__llvm_coverage_mapping</em>
+with the <em>__llvm_covmap</em> section specifier.</p>
+<p>For example, letâs consider a C file and how it gets compiled to LLVM:</p>
+<div class="highlight-c" id="coverage-mapping-sample"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">42</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="kt">int</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">13</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The coverage mapping variable generated by Clang has 3 fields:</p>
+<ul class="simple">
+<li>Coverage mapping header.</li>
+<li>An array of function records.</li>
+<li>Coverage mapping data which is an array of bytes. Zero paddings are added at the end to force 8 byte alignment.</li>
+</ul>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@__llvm_coverage_mapping</span> <span class="p">=</span> <span class="k">internal</span> <span class="k">constant</span> <span class="p">{</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span> <span class="p">},</span> <span class="p">[</span><span class="m">2</span> <span class="k">x</span> <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}],</span> <span class="p">[</span><span class="m">40</span> <span class="k">x</span> <span class="k">i8</span><span class="p">]</span> <span class="p">}</span>
+<span class="p">{</span>
+ <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span> <span class="p">}</span> <span class="c">; Coverage map header</span>
+ <span class="p">{</span>
+ <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="c">; The number of function records</span>
+ <span class="k">i32</span> <span class="m">20</span><span class="p">,</span> <span class="c">; The length of the string that contains the encoded translation unit filenames</span>
+ <span class="k">i32</span> <span class="m">20</span><span class="p">,</span> <span class="c">; The length of the string that contains the encoded coverage mapping data</span>
+ <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="c">; Coverage mapping format version</span>
+ <span class="p">},</span>
+ <span class="p">[</span><span class="m">2</span> <span class="k">x</span> <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}]</span> <span class="p">[</span> <span class="c">; Function records</span>
+ <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span> <span class="p">{</span>
+ <span class="k">i64</span> <span class="m">0x5cf8c24cdb18bdac</span><span class="p">,</span> <span class="c">; Function's name MD5</span>
+ <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="c">; Function's encoded coverage mapping data string length</span>
+ <span class="k">i64</span> <span class="m">0</span> <span class="c">; Function's structural hash</span>
+ <span class="p">},</span>
+ <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span> <span class="p">{</span>
+ <span class="k">i64</span> <span class="m">0xe413754a191db537</span><span class="p">,</span> <span class="c">; Function's name MD5</span>
+ <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="c">; Function's encoded coverage mapping data string length</span>
+ <span class="k">i64</span> <span class="m">0</span> <span class="c">; Function's structural hash</span>
+ <span class="p">}],</span>
+ <span class="p">[</span><span class="m">40</span> <span class="k">x</span> <span class="k">i8</span><span class="p">]</span> <span class="k">c</span><span class="s">"..."</span> <span class="c">; Encoded data (dissected later)</span>
+<span class="p">},</span> <span class="k">section</span> <span class="s">"__llvm_covmap"</span><span class="p">,</span> <span class="k">align</span> <span class="m">8</span>
+</pre></div>
+</div>
+<p>The current version of the format is version 3. The only difference from version 2 is that a special encoding for column end locations was introduced to indicate gap regions.</p>
+<p>The function record layout has evolved since version 1. In version 1, the function record for <em>foo</em> is defined as follows:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*</span> <span class="k">getelementptr</span> <span class="k">inbounds</span> <span class="p">([</span><span class="m">3</span> <span class="k">x</span> <span class="k">i8</span><span class="p">]*</span> <span class="vg">@__profn_foo</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">),</span> <span class="c">; Function's name</span>
+ <span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="c">; Function's name length</span>
+ <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="c">; Function's encoded coverage mapping data string length</span>
+ <span class="k">i64</span> <span class="m">0</span> <span class="c">; Function's structural hash</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="section" id="coverage-mapping-header">
+<h3><a class="toc-backref" href="#id20">Coverage Mapping Header:</a><a class="headerlink" href="#coverage-mapping-header" title="Permalink to this headline">¶</a></h3>
+<p>The coverage mapping header has the following fields:</p>
+<ul class="simple">
+<li>The number of function records.</li>
+<li>The length of the string in the third field of <em>__llvm_coverage_mapping</em> that contains the encoded translation unit filenames.</li>
+<li>The length of the string in the third field of <em>__llvm_coverage_mapping</em> that contains the encoded coverage mapping data.</li>
+<li>The format version. The current version is 3 (encoded as a 2).</li>
+</ul>
+</div>
+<div class="section" id="function-record">
+<span id="function-records"></span><h3><a class="toc-backref" href="#id21">Function record:</a><a class="headerlink" href="#function-record" title="Permalink to this headline">¶</a></h3>
+<p>A function record is a structure of the following type:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>It contains function name’s MD5, the length of the encoded mapping data for that function, and function’s
+structural hash value.</p>
+</div>
+<div class="section" id="encoded-data">
+<h3><a class="toc-backref" href="#id22">Encoded data:</a><a class="headerlink" href="#encoded-data" title="Permalink to this headline">¶</a></h3>
+<p>The encoded data is stored in a single string that contains
+the encoded filenames used by this translation unit and the encoded coverage
+mapping data for each function in this translation unit.</p>
+<p>The encoded data has the following structure:</p>
+<p><tt class="docutils literal"><span class="pre">[filenames,</span> <span class="pre">coverageMappingDataForFunctionRecord0,</span> <span class="pre">coverageMappingDataForFunctionRecord1,</span> <span class="pre">...,</span> <span class="pre">padding]</span></tt></p>
+<p>If necessary, the encoded data is padded with zeroes so that the size
+of the data string is rounded up to the nearest multiple of 8 bytes.</p>
+<div class="section" id="dissecting-the-sample">
+<h4><a class="toc-backref" href="#id23">Dissecting the sample:</a><a class="headerlink" href="#dissecting-the-sample" title="Permalink to this headline">¶</a></h4>
+<p>Here’s an overview of the encoded data that was stored in the
+IR for the <a class="reference internal" href="#coverage-mapping-sample">coverage mapping sample</a> that was shown earlier:</p>
+<ul>
+<li><p class="first">The IR contains the following string constant that represents the encoded
+coverage mapping data for the sample translation unit:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">c</span><span class="s">"\01\12/Users/alex/test.c\01\00\00\01\01\01\0C\02\02\01\00\00\01\01\04\0C\02\02\00\00"</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">The string contains values that are encoded in the LEB128 format, which is
+used throughout for storing integers. It also contains a string value.</p>
+</li>
+<li><p class="first">The length of the substring that contains the encoded translation unit
+filenames is the value of the second field in the <em>__llvm_coverage_mapping</em>
+structure, which is 20, thus the filenames are encoded in this string:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">c</span><span class="s">"\01\12/Users/alex/test.c"</span>
+</pre></div>
+</div>
+<p>This string contains the following data:</p>
+<ul class="simple">
+<li>Its first byte has a value of <tt class="docutils literal"><span class="pre">0x01</span></tt>. It stores the number of filenames
+contained in this string.</li>
+<li>Its second byte stores the length of the first filename in this string.</li>
+<li>The remaining 18 bytes are used to store the first filename.</li>
+</ul>
+</li>
+<li><p class="first">The length of the substring that contains the encoded coverage mapping data
+for the first function is the value of the third field in the first
+structure in an array of <a class="reference internal" href="#function-records">function records</a> stored in the
+third field of the <em>__llvm_coverage_mapping</em> structure, which is the 9.
+Therefore, the coverage mapping for the first function record is encoded
+in this string:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">c</span><span class="s">"\01\00\00\01\01\01\0C\02\02"</span>
+</pre></div>
+</div>
+<p>This string consists of the following bytes:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="8%" />
+<col width="92%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The number of file ids used by this function. There is only one file id used by the mapping data in this function.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x00</span></tt></td>
+<td>An index into the filenames array which corresponds to the file “/Users/alex/test.c”.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x00</span></tt></td>
+<td>The number of counter expressions used by this function. This function doesn’t use any expressions.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The number of mapping regions that are stored in an array for the function’s file id #0.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The coverage mapping counter for the first region in this function. The value of 1 tells us that it’s a coverage
+mapping counter that is a reference to the profile instrumentation counter with an index of 0.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The starting line of the first mapping region in this function.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x0C</span></tt></td>
+<td>The starting column of the first mapping region in this function.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x02</span></tt></td>
+<td>The ending line of the first mapping region in this function.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x02</span></tt></td>
+<td>The ending column of the first mapping region in this function.</td>
+</tr>
+</tbody>
+</table>
+</li>
+<li><p class="first">The length of the substring that contains the encoded coverage mapping data
+for the second function record is also 9. It’s structured like the mapping data
+for the first function record.</p>
+</li>
+<li><p class="first">The two trailing bytes are zeroes and are used to pad the coverage mapping
+data to give it the 8 byte alignment.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="section" id="encoding">
+<h2><a class="toc-backref" href="#id24">Encoding</a><a class="headerlink" href="#encoding" title="Permalink to this headline">¶</a></h2>
+<p>The per-function coverage mapping data is encoded as a stream of bytes,
+with a simple structure. The structure consists of the encoding
+<a class="reference internal" href="#cvmtypes">types</a> like variable-length unsigned integers, that
+are used to encode <a class="reference internal" href="#file-id-mapping">File ID Mapping</a>, <a class="reference internal" href="#counter-expressions">Counter Expressions</a> and
+the <a class="reference internal" href="#mapping-regions">Mapping Regions</a>.</p>
+<p>The format of the structure follows:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">[file</span> <span class="pre">id</span> <span class="pre">mapping,</span> <span class="pre">counter</span> <span class="pre">expressions,</span> <span class="pre">mapping</span> <span class="pre">regions]</span></tt></div></blockquote>
+<p>The translation unit filenames are encoded using the same encoding
+<a class="reference internal" href="#cvmtypes">types</a> as the per-function coverage mapping data, with the
+following structure:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">[numFilenames</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">filename0</span> <span class="pre">:</span> <span class="pre">string,</span> <span class="pre">filename1</span> <span class="pre">:</span> <span class="pre">string,</span> <span class="pre">...]</span></tt></div></blockquote>
+<div class="section" id="types">
+<span id="cvmtypes"></span><h3><a class="toc-backref" href="#id25">Types</a><a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
+<p>This section describes the basic types that are used by the encoding format
+and can appear after <tt class="docutils literal"><span class="pre">:</span></tt> in the <tt class="docutils literal"><span class="pre">[foo</span> <span class="pre">:</span> <span class="pre">type]</span></tt> description.</p>
+<div class="section" id="leb128">
+<span id="id1"></span><h4><a class="toc-backref" href="#id26">LEB128</a><a class="headerlink" href="#leb128" title="Permalink to this headline">¶</a></h4>
+<p>LEB128 is an unsigned integer value that is encoded using DWARF’s LEB128
+encoding, optimizing for the case where values are small
+(1 byte for values less than 128).</p>
+</div>
+<div class="section" id="strings">
+<span id="coveragestrings"></span><h4><a class="toc-backref" href="#id27">Strings</a><a class="headerlink" href="#strings" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[length</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">characters...]</span></tt></p>
+<p>String values are encoded with a <a class="reference internal" href="#leb128">LEB value</a> for the length
+of the string and a sequence of bytes for its characters.</p>
+</div>
+</div>
+<div class="section" id="file-id-mapping">
+<span id="id2"></span><h3><a class="toc-backref" href="#id28">File ID Mapping</a><a class="headerlink" href="#file-id-mapping" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[numIndices</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">filenameIndex0</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">filenameIndex1</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">...]</span></tt></p>
+<p>File id mapping in a function’s coverage mapping stream
+contains the indices into the translation unit’s filenames array.</p>
+</div>
+<div class="section" id="id3">
+<h3><a class="toc-backref" href="#id29">Counter</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[value</span> <span class="pre">:</span> <span class="pre">LEB128]</span></tt></p>
+<p>A <a class="reference internal" href="#coverage-mapping-counter">coverage mapping counter</a> is stored in a single <a class="reference internal" href="#leb128">LEB value</a>.
+It is composed of two things — the <a class="reference internal" href="#counter-tag">tag</a>
+which is stored in the lowest 2 bits, and the <a class="reference internal" href="#counter-data">counter data</a> which is stored
+in the remaining bits.</p>
+<div class="section" id="tag">
+<span id="counter-tag"></span><h4><a class="toc-backref" href="#id30">Tag:</a><a class="headerlink" href="#tag" title="Permalink to this headline">¶</a></h4>
+<p>The counter’s tag encodes the counter’s kind
+and, if the counter is an expression, the expression’s kind.
+The possible tag values are:</p>
+<ul class="simple">
+<li>0 - The counter is zero.</li>
+<li>1 - The counter is a reference to the profile instrumentation counter.</li>
+<li>2 - The counter is a subtraction expression.</li>
+<li>3 - The counter is an addition expression.</li>
+</ul>
+</div>
+<div class="section" id="data">
+<span id="counter-data"></span><h4><a class="toc-backref" href="#id31">Data:</a><a class="headerlink" href="#data" title="Permalink to this headline">¶</a></h4>
+<p>The counter’s data is interpreted in the following manner:</p>
+<ul class="simple">
+<li>When the counter is a reference to the profile instrumentation counter,
+then the counter’s data is the id of the profile counter.</li>
+<li>When the counter is an expression, then the counter’s data
+is the index into the array of counter expressions.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="counter-expressions">
+<span id="id4"></span><h3><a class="toc-backref" href="#id32">Counter Expressions</a><a class="headerlink" href="#counter-expressions" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[numExpressions</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr0LHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr0RHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr1LHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr1RHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">...]</span></tt></p>
+<p>Counter expressions consist of two counters as they
+represent binary arithmetic operations.
+The expression’s kind is determined from the <a class="reference internal" href="#counter-tag">tag</a> of the
+counter that references this expression.</p>
+</div>
+<div class="section" id="mapping-regions">
+<span id="id5"></span><h3><a class="toc-backref" href="#id33">Mapping Regions</a><a class="headerlink" href="#mapping-regions" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[numRegionArrays</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">regionsForFile0,</span> <span class="pre">regionsForFile1,</span> <span class="pre">...]</span></tt></p>
+<p>The mapping regions are stored in an array of sub-arrays where every
+region in a particular sub-array has the same file id.</p>
+<p>The file id for a sub-array of regions is the index of that
+sub-array in the main array e.g. The first sub-array will have the file id
+of 0.</p>
+<div class="section" id="sub-array-of-regions">
+<h4><a class="toc-backref" href="#id34">Sub-Array of Regions</a><a class="headerlink" href="#sub-array-of-regions" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[numRegions</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">region0,</span> <span class="pre">region1,</span> <span class="pre">...]</span></tt></p>
+<p>The mapping regions for a specific file id are stored in an array that is
+sorted in an ascending order by the region’s starting location.</p>
+</div>
+<div class="section" id="id6">
+<h4><a class="toc-backref" href="#id35">Mapping Region</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[header,</span> <span class="pre">source</span> <span class="pre">range]</span></tt></p>
+<p>The mapping region record contains two sub-records —
+the <a class="reference internal" href="#header">header</a>, which stores the counter and/or the region’s kind,
+and the <a class="reference internal" href="#id9">source range</a> that contains the starting and ending
+location of this region.</p>
+</div>
+<div class="section" id="header">
+<span id="id7"></span><h4><a class="toc-backref" href="#id36">Header</a><a class="headerlink" href="#header" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[counter]</span></tt></p>
+<p>or</p>
+<p><tt class="docutils literal"><span class="pre">[pseudo-counter]</span></tt></p>
+<p>The header encodes the region’s counter and the region’s kind.</p>
+<p>The value of the counter’s tag distinguishes between the counters and
+pseudo-counters — if the tag is zero, than this header contains a
+pseudo-counter, otherwise this header contains an ordinary counter.</p>
+<div class="section" id="id8">
+<h5><a class="toc-backref" href="#id37">Counter:</a><a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
+<p>A mapping region whose header has a counter with a non-zero tag is
+a code region.</p>
+</div>
+<div class="section" id="pseudo-counter">
+<h5><a class="toc-backref" href="#id38">Pseudo-Counter:</a><a class="headerlink" href="#pseudo-counter" title="Permalink to this headline">¶</a></h5>
+<p><tt class="docutils literal"><span class="pre">[value</span> <span class="pre">:</span> <span class="pre">LEB128]</span></tt></p>
+<p>A pseudo-counter is stored in a single <a class="reference internal" href="#leb128">LEB value</a>, just like
+the ordinary counter. It has the following interpretation:</p>
+<ul>
+<li><p class="first">bits 0-1: tag, which is always 0.</p>
+</li>
+<li><p class="first">bit 2: expansionRegionTag. If this bit is set, then this mapping region
+is an expansion region.</p>
+</li>
+<li><p class="first">remaining bits: data. If this region is an expansion region, then the data
+contains the expanded file id of that region.</p>
+<p>Otherwise, the data contains the region’s kind. The possible region
+kind values are:</p>
+<ul class="simple">
+<li>0 - This mapping region is a code region with a counter of zero.</li>
+<li>2 - This mapping region is a skipped region.</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="id9">
+<span id="id10"></span><h4><a class="toc-backref" href="#id39">Source Range</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[deltaLineStart</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">columnStart</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">numLines</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">columnEnd</span> <span class="pre">:</span> <span class="pre">LEB128]</span></tt></p>
+<p>The source range record contains the following fields:</p>
+<ul>
+<li><p class="first"><em>deltaLineStart</em>: The difference between the starting line of the
+current mapping region and the starting line of the previous mapping region.</p>
+<p>If the current mapping region is the first region in the current
+sub-array, then it stores the starting line of that region.</p>
+</li>
+<li><p class="first"><em>columnStart</em>: The starting column of the mapping region.</p>
+</li>
+<li><p class="first"><em>numLines</em>: The difference between the ending line and the starting line
+of the current mapping region.</p>
+</li>
+<li><p class="first"><em>columnEnd</em>: The ending column of the mapping region. If the high bit is set,
+the current mapping region is a gap area. A count for a gap area is only used
+as the line execution count if there are no other regions on a line.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Statepoints.html" title="Garbage Collection Safepoints in LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.1/docs/DebuggingJITedCode.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.1/docs/DebuggingJITedCode.html?rev=336152&view=auto
==============================================================================
--- www-releases/trunk/6.0.1/docs/DebuggingJITedCode.html (added)
+++ www-releases/trunk/6.0.1/docs/DebuggingJITedCode.html Mon Jul 2 16:21:43 2018
@@ -0,0 +1,222 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Debugging JIT-ed Code With GDB — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 6 documentation" href="index.html" />
+ <link rel="next" title="The LLVM gold plugin" href="GoldPlugin.html" />
+ <link rel="prev" title="TableGen Deficiencies" href="TableGen/Deficiencies.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GoldPlugin.html" title="The LLVM gold plugin"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TableGen/Deficiencies.html" title="TableGen Deficiencies"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="debugging-jit-ed-code-with-gdb">
+<h1>Debugging JIT-ed Code With GDB<a class="headerlink" href="#debugging-jit-ed-code-with-gdb" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="background">
+<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2>
+<p>Without special runtime support, debugging dynamically generated code with
+GDB (as well as most debuggers) can be quite painful. Debuggers generally
+read debug information from the object file of the code, but for JITed
+code, there is no such file to look for.</p>
+<p>In order to communicate the necessary debug info to GDB, an interface for
+registering JITed code with debuggers has been designed and implemented for
+GDB and LLVM MCJIT. At a high level, whenever MCJIT generates new machine code,
+it does so in an in-memory object file that contains the debug information in
+DWARF format. MCJIT then adds this in-memory object file to a global list of
+dynamically generated object files and calls a special function
+(<tt class="docutils literal"><span class="pre">__jit_debug_register_code</span></tt>) marked noinline that GDB knows about. When
+GDB attaches to a process, it puts a breakpoint in this function and loads all
+of the object files in the global list. When MCJIT calls the registration
+function, GDB catches the breakpoint signal, loads the new object file from
+the inferior’s memory, and resumes the execution. In this way, GDB can get the
+necessary debug information.</p>
+</div>
+<div class="section" id="gdb-version">
+<h2>GDB Version<a class="headerlink" href="#gdb-version" title="Permalink to this headline">¶</a></h2>
+<p>In order to debug code JIT-ed by LLVM, you need GDB 7.0 or newer, which is
+available on most modern distributions of Linux. The version of GDB that
+Apple ships with Xcode has been frozen at 6.3 for a while. LLDB may be a
+better option for debugging JIT-ed code on Mac OS X.</p>
+</div>
+<div class="section" id="debugging-mcjit-ed-code">
+<h2>Debugging MCJIT-ed code<a class="headerlink" href="#debugging-mcjit-ed-code" title="Permalink to this headline">¶</a></h2>
+<p>The emerging MCJIT component of LLVM allows full debugging of JIT-ed code with
+GDB. This is due to MCJIT’s ability to use the MC emitter to provide full
+DWARF debugging information to GDB.</p>
+<p>Note that lli has to be passed the <tt class="docutils literal"><span class="pre">-use-mcjit</span></tt> flag to JIT the code with
+MCJIT instead of the old JIT.</p>
+<div class="section" id="example">
+<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>Consider the following C code (with line numbers added to make the example
+easier to follow):</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="mi">1</span> <span class="kt">int</span> <span class="n">compute_factorial</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span>
+<span class="mi">2</span> <span class="p">{</span>
+<span class="mi">3</span> <span class="k">if</span> <span class="p">(</span><span class="n">n</span> <span class="o"><=</span> <span class="mi">1</span><span class="p">)</span>
+<span class="mi">4</span> <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+<span class="mi">5</span>
+<span class="mi">6</span> <span class="kt">int</span> <span class="n">f</span> <span class="o">=</span> <span class="n">n</span><span class="p">;</span>
+<span class="mi">7</span> <span class="k">while</span> <span class="p">(</span><span class="o">--</span><span class="n">n</span> <span class="o">></span> <span class="mi">1</span><span class="p">)</span>
+<span class="mi">8</span> <span class="n">f</span> <span class="o">*=</span> <span class="n">n</span><span class="p">;</span>
+<span class="mi">9</span> <span class="k">return</span> <span class="n">f</span><span class="p">;</span>
+<span class="mi">10</span> <span class="p">}</span>
+<span class="mi">11</span>
+<span class="mi">12</span>
+<span class="mi">13</span> <span class="kt">int</span> <span class="n">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">**</span> <span class="n">argv</span><span class="p">)</span>
+<span class="mi">14</span> <span class="p">{</span>
+<span class="mi">15</span> <span class="k">if</span> <span class="p">(</span><span class="n">argc</span> <span class="o"><</span> <span class="mi">2</span><span class="p">)</span>
+<span class="mi">16</span> <span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
+<span class="mi">17</span> <span class="kt">char</span> <span class="n">firstletter</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">0</span><span class="p">];</span>
+<span class="mi">18</span> <span class="kt">int</span> <span class="n">result</span> <span class="o">=</span> <span class="n">compute_factorial</span><span class="p">(</span><span class="n">firstletter</span> <span class="o">-</span> <span class="sc">'0'</span><span class="p">);</span>
+<span class="mi">19</span>
+<span class="mi">20</span> <span class="c1">// Returned result is clipped at 255...</span>
+<span class="mi">21</span> <span class="k">return</span> <span class="n">result</span><span class="p">;</span>
+<span class="mi">22</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Here is a sample command line session that shows how to build and run this
+code via <tt class="docutils literal"><span class="pre">lli</span></tt> inside GDB:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ $BINPATH</span>/clang -cc1 -O0 -g -emit-llvm showdebug.c
+<span class="nv">$ </span>gdb --quiet --args <span class="nv">$BINPATH</span>/lli -use-mcjit showdebug.ll 5
+Reading symbols from <span class="nv">$BINPATH</span>/lli...done.
+<span class="o">(</span>gdb<span class="o">)</span> b showdebug.c:6
+No <span class="nb">source </span>file named showdebug.c.
+Make breakpoint pending on future shared library load? <span class="o">(</span>y or <span class="o">[</span>n<span class="o">])</span> y
+Breakpoint 1 <span class="o">(</span>showdebug.c:6<span class="o">)</span> pending.
+<span class="o">(</span>gdb<span class="o">)</span> r
+Starting program: <span class="nv">$BINPATH</span>/lli -use-mcjit showdebug.ll 5
+<span class="o">[</span>Thread debugging using libthread_db enabled<span class="o">]</span>
+
+Breakpoint 1, compute_factorial <span class="o">(</span><span class="nv">n</span><span class="o">=</span>5<span class="o">)</span> at showdebug.c:6
+6 int <span class="nv">f</span> <span class="o">=</span> n;
+<span class="o">(</span>gdb<span class="o">)</span> p n
+<span class="nv">$1</span> <span class="o">=</span> 5
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$2</span> <span class="o">=</span> 0
+<span class="o">(</span>gdb<span class="o">)</span> n
+7 <span class="k">while</span> <span class="o">(</span>--n > 1<span class="o">)</span>
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$3</span> <span class="o">=</span> 5
+<span class="o">(</span>gdb<span class="o">)</span> b showdebug.c:9
+Breakpoint 2 at 0x7ffff7ed404c: file showdebug.c, line 9.
+<span class="o">(</span>gdb<span class="o">)</span> c
+Continuing.
+
+Breakpoint 2, compute_factorial <span class="o">(</span><span class="nv">n</span><span class="o">=</span>1<span class="o">)</span> at showdebug.c:9
+9 <span class="k">return </span>f;
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$4</span> <span class="o">=</span> 120
+<span class="o">(</span>gdb<span class="o">)</span> bt
+<span class="c">#0 compute_factorial (n=1) at showdebug.c:9</span>
+<span class="c">#1 0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18</span>
+<span class="c">#2 0x3500000001652748 in ?? ()</span>
+<span class="c">#3 0x00000000016677e0 in ?? ()</span>
+<span class="c">#4 0x0000000000000002 in ?? ()</span>
+<span class="c">#5 0x0000000000d953b3 in llvm::MCJIT::runFunction (this=0x16151f0, F=0x1603020, ArgValues=...) at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/MCJIT/MCJIT.cpp:161</span>
+<span class="c">#6 0x0000000000dc8872 in llvm::ExecutionEngine::runFunctionAsMain (this=0x16151f0, Fn=0x1603020, argv=..., envp=0x7fffffffe040)</span>
+ at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/ExecutionEngine.cpp:397
+<span class="c">#7 0x000000000059c583 in main (argc=4, argv=0x7fffffffe018, envp=0x7fffffffe040) at /home/ebenders_test/llvm_svn_rw/tools/lli/lli.cpp:324</span>
+<span class="o">(</span>gdb<span class="o">)</span> finish
+Run till <span class="nb">exit </span>from <span class="c">#0 compute_factorial (n=1) at showdebug.c:9</span>
+0x00007ffff7ed40a9 in main <span class="o">(</span><span class="nv">argc</span><span class="o">=</span>2, <span class="nv">argv</span><span class="o">=</span>0x16677e0<span class="o">)</span> at showdebug.c:18
+18 int <span class="nv">result</span> <span class="o">=</span> compute_factorial<span class="o">(</span>firstletter - <span class="s1">'0'</span><span class="o">)</span>;
+Value returned is <span class="nv">$5</span> <span class="o">=</span> 120
+<span class="o">(</span>gdb<span class="o">)</span> p result
+<span class="nv">$6</span> <span class="o">=</span> 23406408
+<span class="o">(</span>gdb<span class="o">)</span> n
+21 <span class="k">return </span>result;
+<span class="o">(</span>gdb<span class="o">)</span> p result
+<span class="nv">$7</span> <span class="o">=</span> 120
+<span class="o">(</span>gdb<span class="o">)</span> c
+Continuing.
+
+Program exited with code 0170.
+<span class="o">(</span>gdb<span class="o">)</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GoldPlugin.html" title="The LLVM gold plugin"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TableGen/Deficiencies.html" title="TableGen Deficiencies"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-07-02.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list