[www-releases] r208244 - Add source, binaries, and documentation for 3.4.1 release
Tom Stellard
thomas.stellard at amd.com
Wed May 7 13:09:36 PDT 2014
Added: www-releases/trunk/3.4.1/docs/CommandLine.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/CommandLine.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/CommandLine.html (added)
+++ www-releases/trunk/3.4.1/docs/CommandLine.html Wed May 7 15:09:32 2014
@@ -0,0 +1,1562 @@
+
+
+<!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 3.4 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: '3.4',
+ 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 3.4 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>
+</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="nf">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="n">clEnumValEnd</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 (Note that the declaration list must be terminated
+with the “<tt class="docutils literal"><span class="pre">clEnumValEnd</span></tt>” argument!). 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="n">clEnumValEnd</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>
+ <span class="n">clEnumValEnd</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>
+ <span class="n">clEnumValEnd</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>
+ <span class="n">clEnumValEnd</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="nf">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="nf">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="c1">// DEBUG macro - This macro should be used by code to emit debug information.</span>
+<span class="c1">// In the '-debug' option is specified on the command line, and if this is a</span>
+<span class="c1">// debug build, then the code specified as the option to the macro will be</span>
+<span class="c1">// 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="nb">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 <strong>clEnumValEnd terminated</strong> 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. Response files are
+enabled by an optional fourth argument to <a class="reference internal" href="#cl-parseenvironmentoptions">cl::ParseEnvironmentOptions</a> and
+<a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>.</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="nf">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="n">Map</span><span class="p">;</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">getRegisteredOptions</span><span class="p">(</span><span class="n">Map</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, and a
+fourth boolean parameter that enables <a class="reference internal" href="#response-files">response files</a>.</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, 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, and the boolean switch that controls whether
+<a class="reference internal" href="#response-files">response files</a> should be read.</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="nb">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">basic_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="k">const</span> <span class="kt">char</span> <span class="o">*</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::basic_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="k">const</span> <span class="kt">char</span> <span class="o">*</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="k">return</span> <span class="nb">false</span><span class="p">;</span> <span class="c1">// No error</span>
+ <span class="k">case</span> <span class="sc">'i'</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="k">case</span> <span class="sc">'B'</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="k">case</span> <span class="sc">'G'</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="k">case</span> <span class="sc">'M'</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="k">case</span> <span class="sc">'K'</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="nl">default:</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="nb">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>
+<p id="dynamically-loaded-options">Dynamically adding command line options</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="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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/CompilerWriterInfo.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/CompilerWriterInfo.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/CompilerWriterInfo.html (added)
+++ www-releases/trunk/3.4.1/docs/CompilerWriterInfo.html Wed May 7 15:09:32 2014
@@ -0,0 +1,291 @@
+
+
+<!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 3.4 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: '3.4',
+ 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 3.4 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="id3">Hardware</a><ul>
+<li><a class="reference internal" href="#arm" id="id4">ARM</a></li>
+<li><a class="reference internal" href="#aarch64" id="id5">AArch64</a></li>
+<li><a class="reference internal" href="#itanium-ia64" id="id6">Itanium (ia64)</a></li>
+<li><a class="reference internal" href="#mips" id="id7">MIPS</a></li>
+<li><a class="reference internal" href="#powerpc" id="id8">PowerPC</a><ul>
+<li><a class="reference internal" href="#ibm-official-manuals-and-docs" id="id9">IBM - Official manuals and docs</a></li>
+<li><a class="reference internal" href="#other-documents-collections-notes" id="id10">Other documents, collections, notes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#r600" id="id11">R600</a></li>
+<li><a class="reference internal" href="#sparc" id="id12">SPARC</a></li>
+<li><a class="reference internal" href="#systemz" id="id13">SystemZ</a></li>
+<li><a class="reference internal" href="#x86" id="id14">X86</a><ul>
+<li><a class="reference internal" href="#amd-official-manuals-and-docs" id="id15">AMD - Official manuals and docs</a></li>
+<li><a class="reference internal" href="#intel-official-manuals-and-docs" id="id16">Intel - Official manuals and docs</a></li>
+<li><a class="reference internal" href="#other-x86-specific-information" id="id17">Other x86-specific information</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-relevant-lists" id="id18">Other relevant lists</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id2" id="id19">ABI</a><ul>
+<li><a class="reference internal" href="#linux" id="id20">Linux</a></li>
+<li><a class="reference internal" href="#os-x" id="id21">OS X</a></li>
+<li><a class="reference internal" href="#windows" id="id22">Windows</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nvptx" id="id23">NVPTX</a></li>
+<li><a class="reference internal" href="#miscellaneous-resources" id="id24">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="#id3">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="arm">
+<h3><a class="toc-backref" href="#id4">ARM</a><a class="headerlink" href="#arm" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://www.arm.com/documentation/">ARM documentation</a> (<a class="reference external" href="http://www.arm.com/documentation/ARMProcessor_Cores/">Processor Cores</a> Cores)</li>
+<li><a class="reference external" href="http://www.arm.com/products/DevTools/ABI.html">ABI</a></li>
+<li><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>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053a/IHI0053A_acle.pdf">ARM C Language Extensions</a></li>
+</ul>
+</div>
+<div class="section" id="aarch64">
+<h3><a class="toc-backref" href="#id5">AArch64</a><a class="headerlink" href="#aarch64" 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.genc010197a/index.html">ARMv8 Instruction Set Overview</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053a/IHI0053A_acle.pdf">ARM C Language Extensions</a></li>
+</ul>
+</div>
+<div class="section" id="itanium-ia64">
+<h3><a class="toc-backref" href="#id6">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="mips">
+<h3><a class="toc-backref" href="#id7">MIPS</a><a class="headerlink" href="#mips" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://imgtec.com/mips/mips-architectures.asp">MIPS Processor Architecture</a></li>
+</ul>
+</div>
+<div class="section" id="powerpc">
+<h3><a class="toc-backref" href="#id8">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="#id9">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="#id10">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="r600">
+<h3><a class="toc-backref" href="#id11">R600</a><a class="headerlink" href="#r600" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.amd.com/wordpress/media/2012/10/R600_Instruction_Set_Architecture.pdf">AMD R6xx shader ISA</a></li>
+<li><a class="reference external" href="http://developer.amd.com/wordpress/media/2012/10/R700-Family_Instruction_Set_Architecture.pdf">AMD R7xx shader ISA</a></li>
+<li><a class="reference external" href="http://developer.amd.com/wordpress/media/2012/10/AMD_Evergreen-Family_Instruction_Set_Architecture.pdf">AMD Evergreen shader ISA</a></li>
+<li><a class="reference external" href="http://developer.amd.com/wordpress/media/2012/10/AMD_HD_6900_Series_Instruction_Set_Architecture.pdf">AMD Cayman/Trinity shader ISA</a></li>
+<li><a class="reference external" href="http://developer.amd.com/wordpress/media/2012/12/AMD_Southern_Islands_Instruction_Set_Architecture.pdf">AMD Southern Islands Series ISA</a></li>
+<li><a class="reference external" href="http://developer.amd.com/download/AMD_Accelerated_Parallel_Processing_OpenCL_Programming_Guide.pdf">AMD GPU Programming Guide</a></li>
+<li><a class="reference external" href="http://developer.amd.com/tools/heterogeneous-computing/amd-accelerated-parallel-processing-app-sdk/documentation/">AMD Compute Resources</a></li>
+</ul>
+</div>
+<div class="section" id="sparc">
+<h3><a class="toc-backref" href="#id12">SPARC</a><a class="headerlink" href="#sparc" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://www.sparc.org/resource.htm">SPARC resources</a></li>
+<li><a class="reference external" href="http://www.sparc.org/standards.html">SPARC standards</a></li>
+</ul>
+</div>
+<div class="section" id="systemz">
+<h3><a class="toc-backref" href="#id13">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="#id14">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="amd-official-manuals-and-docs">
+<h4><a class="toc-backref" href="#id15">AMD - Official manuals and docs</a><a class="headerlink" href="#amd-official-manuals-and-docs" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><a class="reference external" href="http://www.amd.com/us-en/Processors/TechnicalResources/0,,30_182_739,00.html">AMD processor manuals</a></li>
+<li><a class="reference external" href="http://www.x86-64.org/documentation">X86-64 ABI</a></li>
+</ul>
+</div>
+<div class="section" id="intel-official-manuals-and-docs">
+<h4><a class="toc-backref" href="#id16">Intel - Official manuals and docs</a><a class="headerlink" href="#intel-official-manuals-and-docs" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<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>
+</ul>
+</div>
+<div class="section" id="other-x86-specific-information">
+<h4><a class="toc-backref" href="#id17">Other x86-specific information</a><a class="headerlink" href="#other-x86-specific-information" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<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>
+<div class="section" id="other-relevant-lists">
+<h3><a class="toc-backref" href="#id18">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="id2">
+<h2><a class="toc-backref" href="#id19">ABI</a><a class="headerlink" href="#id2" 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://mentorembedded.github.io/cxx-abi/">Itanium C++ ABI</a></li>
+</ul>
+<div class="section" id="linux">
+<h3><a class="toc-backref" href="#id20">Linux</a><a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<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="#id21">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="#id22">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="#id23">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="#id24">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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/DebuggingJITedCode.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/DebuggingJITedCode.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/DebuggingJITedCode.html (added)
+++ www-releases/trunk/3.4.1/docs/DebuggingJITedCode.html Wed May 7 15:09:32 2014
@@ -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 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="The LLVM gold plugin" href="GoldPlugin.html" />
+ <link rel="prev" title="TableGen Fundamentals" href="TableGenFundamentals.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="TableGenFundamentals.html" title="TableGen Fundamentals"
+ 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="TableGenFundamentals.html" title="TableGen Fundamentals"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/DeveloperPolicy.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/DeveloperPolicy.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/DeveloperPolicy.html (added)
+++ www-releases/trunk/3.4.1/docs/DeveloperPolicy.html Wed May 7 15:09:32 2014
@@ -0,0 +1,552 @@
+
+
+<!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 Developer Policy — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="LLVM Makefile Guide" href="MakefileGuide.html" />
+ <link rel="prev" title="User Guide for NVPTX Back-end" href="NVPTXUsage.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="MakefileGuide.html" title="LLVM Makefile Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+ 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-developer-policy">
+<h1>LLVM Developer Policy<a class="headerlink" href="#llvm-developer-policy" 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="id6">Introduction</a></li>
+<li><a class="reference internal" href="#developer-policies" id="id7">Developer Policies</a><ul>
+<li><a class="reference internal" href="#stay-informed" id="id8">Stay Informed</a></li>
+<li><a class="reference internal" href="#making-a-patch" id="id9">Making a Patch</a></li>
+<li><a class="reference internal" href="#code-reviews" id="id10">Code Reviews</a></li>
+<li><a class="reference internal" href="#code-owners" id="id11">Code Owners</a></li>
+<li><a class="reference internal" href="#test-cases" id="id12">Test Cases</a></li>
+<li><a class="reference internal" href="#quality" id="id13">Quality</a></li>
+<li><a class="reference internal" href="#obtaining-commit-access" id="id14">Obtaining Commit Access</a></li>
+<li><a class="reference internal" href="#making-a-major-change" id="id15">Making a Major Change</a></li>
+<li><a class="reference internal" href="#incremental-development" id="id16">Incremental Development</a></li>
+<li><a class="reference internal" href="#attribution-of-changes" id="id17">Attribution of Changes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#copyright-license-and-patents" id="id18">Copyright, License, and Patents</a><ul>
+<li><a class="reference internal" href="#copyright" id="id19">Copyright</a></li>
+<li><a class="reference internal" href="#license" id="id20">License</a></li>
+<li><a class="reference internal" href="#patents" id="id21">Patents</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id6">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains the LLVM Developer Policy which defines the project’s
+policy towards developers and their contributions. The intent of this policy is
+to eliminate miscommunication, rework, and confusion that might arise from the
+distributed nature of LLVM’s development. By stating the policy in clear terms,
+we hope each developer can know ahead of time what to expect when making LLVM
+contributions. This policy covers all llvm.org subprojects, including Clang,
+LLDB, libc++, etc.</p>
+<p>This policy is also designed to accomplish the following objectives:</p>
+<ol class="arabic simple">
+<li>Attract both users and developers to the LLVM project.</li>
+<li>Make life as simple and easy for contributors as possible.</li>
+<li>Keep the top of Subversion trees as stable as possible.</li>
+<li>Establish awareness of the project’s <a class="reference internal" href="#copyright-license-patents"><em>copyright, license, and patent
+policies</em></a> with contributors to the project.</li>
+</ol>
+<p>This policy is aimed at frequent contributors to LLVM. People interested in
+contributing one-off patches can do so in an informal way by sending them to the
+<a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits mailing list</a> and engaging another
+developer to see it through the process.</p>
+</div>
+<div class="section" id="developer-policies">
+<h2><a class="toc-backref" href="#id7">Developer Policies</a><a class="headerlink" href="#developer-policies" title="Permalink to this headline">¶</a></h2>
+<p>This section contains policies that pertain to frequent LLVM developers. We
+always welcome <a class="reference internal" href="#one-off-patches">one-off patches</a> from people who do not routinely contribute to
+LLVM, but we expect more from frequent contributors to keep the system as
+efficient as possible for everyone. Frequent LLVM contributors are expected to
+meet the following requirements in order for LLVM to maintain a high standard of
+quality.</p>
+<div class="section" id="stay-informed">
+<h3><a class="toc-backref" href="#id8">Stay Informed</a><a class="headerlink" href="#stay-informed" title="Permalink to this headline">¶</a></h3>
+<p>Developers should stay informed by reading at least the “dev” mailing list for
+the projects you are interested in, such as <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> for LLVM, <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">cfe-dev</a> for Clang, or <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/lldb-dev">lldb-dev</a> for LLDB. If you are
+doing anything more than just casual work on LLVM, it is suggested that you also
+subscribe to the “commits” mailing list for the subproject you’re interested in,
+such as <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a>, <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits">cfe-commits</a>, or <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits">lldb-commits</a>. Reading the
+“commits” list and paying attention to changes being made by others is a good
+way to see what other people are interested in and watching the flow of the
+project as a whole.</p>
+<p>We recommend that active developers register an email account with <a class="reference external" href="http://llvm.org/bugs/">LLVM
+Bugzilla</a> and preferably subscribe to the <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmbugs">llvm-bugs</a> email list to keep track
+of bugs and enhancements occurring in LLVM. We really appreciate people who are
+proactive at catching incoming bugs in their components and dealing with them
+promptly.</p>
+<p>Please be aware that all public LLVM mailing lists are public and archived, and
+that notices of confidentiality or non-disclosure cannot be respected.</p>
+</div>
+<div class="section" id="making-a-patch">
+<span id="one-off-patches"></span><span id="patch"></span><h3><a class="toc-backref" href="#id9">Making a Patch</a><a class="headerlink" href="#making-a-patch" title="Permalink to this headline">¶</a></h3>
+<p>When making a patch for review, the goal is to make it as easy for the reviewer
+to read it as possible. As such, we recommend that you:</p>
+<ol class="arabic simple">
+<li>Make your patch against the Subversion trunk, not a branch, and not an old
+version of LLVM. This makes it easy to apply the patch. For information on
+how to check out SVN trunk, please see the <a class="reference external" href="GettingStarted.html#checkout">Getting Started
+Guide</a>.</li>
+<li>Similarly, patches should be submitted soon after they are generated. Old
+patches may not apply correctly if the underlying code changes between the
+time the patch was created and the time it is applied.</li>
+<li>Patches should be made with <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">diff</span></tt>, or similar. If you use a
+different tool, make sure it uses the <tt class="docutils literal"><span class="pre">diff</span> <span class="pre">-u</span></tt> format and that it
+doesn’t contain clutter which makes it hard to read.</li>
+<li>If you are modifying generated files, such as the top-level <tt class="docutils literal"><span class="pre">configure</span></tt>
+script, please separate out those changes into a separate patch from the rest
+of your changes.</li>
+</ol>
+<p>When sending a patch to a mailing list, it is a good idea to send it as an
+<em>attachment</em> to the message, not embedded into the text of the message. This
+ensures that your mailer will not mangle the patch when it sends it (e.g. by
+making whitespace changes or by wrapping lines).</p>
+<p><em>For Thunderbird users:</em> Before submitting a patch, please open <em>Preferences >
+Advanced > General > Config Editor</em>, find the key
+<tt class="docutils literal"><span class="pre">mail.content_disposition_type</span></tt>, and set its value to <tt class="docutils literal"><span class="pre">1</span></tt>. Without this
+setting, Thunderbird sends your attachment using <tt class="docutils literal"><span class="pre">Content-Disposition:</span> <span class="pre">inline</span></tt>
+rather than <tt class="docutils literal"><span class="pre">Content-Disposition:</span> <span class="pre">attachment</span></tt>. Apple Mail gamely displays such
+a file inline, making it difficult to work with for reviewers using that
+program.</p>
+<p>When submitting patches, please do not add confidentiality or non-disclosure
+notices to the patches themselves. These notices conflict with the <a class="reference internal" href="#llvm-license">LLVM
+License</a> and may result in your contribution being excluded.</p>
+</div>
+<div class="section" id="code-reviews">
+<span id="code-review"></span><h3><a class="toc-backref" href="#id10">Code Reviews</a><a class="headerlink" href="#code-reviews" title="Permalink to this headline">¶</a></h3>
+<p>LLVM has a code review policy. Code review is one way to increase the quality of
+software. We generally follow these policies:</p>
+<ol class="arabic simple">
+<li>All developers are required to have significant changes reviewed before they
+are committed to the repository.</li>
+<li>Code reviews are conducted by email, usually on the llvm-commits list.</li>
+<li>Code can be reviewed either before it is committed or after. We expect major
+changes to be reviewed before being committed, but smaller changes (or
+changes where the developer owns the component) can be reviewed after commit.</li>
+<li>The developer responsible for a code change is also responsible for making
+all necessary review-related changes.</li>
+<li>Code review can be an iterative process, which continues until the patch is
+ready to be committed. Specifically, once a patch is sent out for review, it
+needs an explicit “looks good” before it is submitted. Do not assume silent
+approval, or request active objections to the patch with a deadline.</li>
+</ol>
+<p>Sometimes code reviews will take longer than you would hope for, especially for
+larger features. Accepted ways to speed up review times for your patches are:</p>
+<ul class="simple">
+<li>Review other people’s patches. If you help out, everybody will be more
+willing to do the same for you; goodwill is our currency.</li>
+<li>Ping the patch. If it is urgent, provide reasons why it is important to you to
+get this patch landed and ping it every couple of days. If it is
+not urgent, the common courtesy ping rate is one week. Remember that you’re
+asking for valuable time from other professional developers.</li>
+<li>Ask for help on IRC. Developers on IRC will be able to either help you
+directly, or tell you who might be a good reviewer.</li>
+<li>Split your patch into multiple smaller patches that build on each other. The
+smaller your patch, the higher the probability that somebody will take a quick
+look at it.</li>
+</ul>
+<p>Developers should participate in code reviews as both reviewers and
+reviewees. If someone is kind enough to review your code, you should return the
+favor for someone else. Note that anyone is welcome to review and give feedback
+on a patch, but only people with Subversion write access can approve it.</p>
+<p>There is a web based code review tool that can optionally be used
+for code reviews. See <a class="reference internal" href="Phabricator.html"><em>Code Reviews with Phabricator</em></a>.</p>
+</div>
+<div class="section" id="code-owners">
+<h3><a class="toc-backref" href="#id11">Code Owners</a><a class="headerlink" href="#code-owners" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM Project relies on two features of its process to maintain rapid
+development in addition to the high quality of its source base: the combination
+of code review plus post-commit review for trusted maintainers. Having both is
+a great way for the project to take advantage of the fact that most people do
+the right thing most of the time, and only commit patches without pre-commit
+review when they are confident they are right.</p>
+<p>The trick to this is that the project has to guarantee that all patches that are
+committed are reviewed after they go in: you don’t want everyone to assume
+someone else will review it, allowing the patch to go unreviewed. To solve this
+problem, we have a notion of an ‘owner’ for a piece of the code. The sole
+responsibility of a code owner is to ensure that a commit to their area of the
+code is appropriately reviewed, either by themself or by someone else. The list
+of current code owners can be found in the file
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project/llvm/trunk/CODE_OWNERS.TXT?view=markup">CODE_OWNERS.TXT</a>
+in the root of the LLVM source tree.</p>
+<p>Note that code ownership is completely different than reviewers: anyone can
+review a piece of code, and we welcome code review from anyone who is
+interested. Code owners are the “last line of defense” to guarantee that all
+patches that are committed are actually reviewed.</p>
+<p>Being a code owner is a somewhat unglamorous position, but it is incredibly
+important for the ongoing success of the project. Because people get busy,
+interests change, and unexpected things happen, code ownership is purely opt-in,
+and anyone can choose to resign their “title” at any time. For now, we do not
+have an official policy on how one gets elected to be a code owner.</p>
+</div>
+<div class="section" id="test-cases">
+<span id="include-a-testcase"></span><h3><a class="toc-backref" href="#id12">Test Cases</a><a class="headerlink" href="#test-cases" title="Permalink to this headline">¶</a></h3>
+<p>Developers are required to create test cases for any bugs fixed and any new
+features added. Some tips for getting your testcase approved:</p>
+<ul class="simple">
+<li>All feature and regression test cases are added to the <tt class="docutils literal"><span class="pre">llvm/test</span></tt>
+directory. The appropriate sub-directory should be selected (see the
+<a class="reference internal" href="TestingGuide.html"><em>Testing Guide</em></a> for details).</li>
+<li>Test cases should be written in <a class="reference external" href="LangRef.html">LLVM assembly language</a>
+unless the feature or regression being tested requires another language
+(e.g. the bug being fixed or feature being implemented is in the llvm-gcc C++
+front-end, in which case it must be written in C++).</li>
+<li>Test cases, especially for regressions, should be reduced as much as possible,
+by <a class="reference external" href="Bugpoint.html">bugpoint</a> or manually. It is unacceptable to place an
+entire failing program into <tt class="docutils literal"><span class="pre">llvm/test</span></tt> as this creates a <em>time-to-test</em>
+burden on all developers. Please keep them short.</li>
+</ul>
+<p>Note that llvm/test and clang/test are designed for regression and small feature
+tests only. More extensive test cases (e.g., entire applications, benchmarks,
+etc) should be added to the <tt class="docutils literal"><span class="pre">llvm-test</span></tt> test suite. The llvm-test suite is
+for coverage (correctness, performance, etc) testing, not feature or regression
+testing.</p>
+</div>
+<div class="section" id="quality">
+<h3><a class="toc-backref" href="#id13">Quality</a><a class="headerlink" href="#quality" title="Permalink to this headline">¶</a></h3>
+<p>The minimum quality standards that any change must satisfy before being
+committed to the main development branch are:</p>
+<ol class="arabic simple">
+<li>Code must adhere to the <a class="reference external" href="CodingStandards.html">LLVM Coding Standards</a>.</li>
+<li>Code must compile cleanly (no errors, no warnings) on at least one platform.</li>
+<li>Bug fixes and new features should <a class="reference internal" href="#include-a-testcase">include a testcase</a> so we know if the
+fix/feature ever regresses in the future.</li>
+<li>Code must pass the <tt class="docutils literal"><span class="pre">llvm/test</span></tt> test suite.</li>
+<li>The code must not cause regressions on a reasonable subset of llvm-test,
+where “reasonable” depends on the contributor’s judgement and the scope of
+the change (more invasive changes require more testing). A reasonable subset
+might be something like “<tt class="docutils literal"><span class="pre">llvm-test/MultiSource/Benchmarks</span></tt>”.</li>
+</ol>
+<p>Additionally, the committer is responsible for addressing any problems found in
+the future that the change is responsible for. For example:</p>
+<ul class="simple">
+<li>The code should compile cleanly on all supported platforms.</li>
+<li>The changes should not cause any correctness regressions in the <tt class="docutils literal"><span class="pre">llvm-test</span></tt>
+suite and must not cause any major performance regressions.</li>
+<li>The change set should not cause performance or correctness regressions for the
+LLVM tools.</li>
+<li>The changes should not cause performance or correctness regressions in code
+compiled by LLVM on all applicable targets.</li>
+<li>You are expected to address any <a class="reference external" href="http://llvm.org/bugs/">Bugzilla bugs</a> that
+result from your change.</li>
+</ul>
+<p>We prefer for this to be handled before submission but understand that it isn’t
+possible to test all of this for every submission. Our build bots and nightly
+testing infrastructure normally finds these problems. A good rule of thumb is
+to check the nightly testers for regressions the day after your change. Build
+bots will directly email you if a group of commits that included yours caused a
+failure. You are expected to check the build bot messages to see if they are
+your fault and, if so, fix the breakage.</p>
+<p>Commits that violate these quality standards (e.g. are very broken) may be
+reverted. This is necessary when the change blocks other developers from making
+progress. The developer is welcome to re-commit the change after the problem has
+been fixed.</p>
+</div>
+<div class="section" id="obtaining-commit-access">
+<h3><a class="toc-backref" href="#id14">Obtaining Commit Access</a><a class="headerlink" href="#obtaining-commit-access" title="Permalink to this headline">¶</a></h3>
+<p>We grant commit access to contributors with a track record of submitting high
+quality patches. If you would like commit access, please send an email to
+<a class="reference external" href="mailto:sabre%40nondot.org">Chris</a> with the following information:</p>
+<ol class="arabic simple">
+<li>The user name you want to commit with, e.g. “hacker”.</li>
+<li>The full name and email address you want message to llvm-commits to come
+from, e.g. “J. Random Hacker <<a class="reference external" href="mailto:hacker%40yoyodyne.com">hacker<span>@</span>yoyodyne<span>.</span>com</a>>”.</li>
+<li>A “password hash” of the password you want to use, e.g. “<tt class="docutils literal"><span class="pre">2ACR96qjUqsyM</span></tt>”.
+Note that you don’t ever tell us what your password is; you just give it to
+us in an encrypted form. To get this, run “<tt class="docutils literal"><span class="pre">htpasswd</span></tt>” (a utility that
+comes with apache) in crypt mode (often enabled with “<tt class="docutils literal"><span class="pre">-d</span></tt>”), or find a web
+page that will do it for you.</li>
+</ol>
+<p>Once you’ve been granted commit access, you should be able to check out an LLVM
+tree with an SVN URL of “<a class="reference external" href="https://username@llvm.org/">https://username@llvm.org/</a>...” instead of the normal
+anonymous URL of “<a class="reference external" href="http://llvm.org/">http://llvm.org/</a>...”. The first time you commit you’ll have
+to type in your password. Note that you may get a warning from SVN about an
+untrusted key; you can ignore this. To verify that your commit access works,
+please do a test commit (e.g. change a comment or add a blank line). Your first
+commit to a repository may require the autogenerated email to be approved by a
+mailing list. This is normal and will be done when the mailing list owner has
+time.</p>
+<p>If you have recently been granted commit access, these policies apply:</p>
+<ol class="arabic simple">
+<li>You are granted <em>commit-after-approval</em> to all parts of LLVM. To get
+approval, submit a <a class="reference internal" href="#patch">patch</a> to <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a>. When approved,
+you may commit it yourself.</li>
+<li>You are allowed to commit patches without approval which you think are
+obvious. This is clearly a subjective decision — we simply expect you to
+use good judgement. Examples include: fixing build breakage, reverting
+obviously broken patches, documentation/comment changes, any other minor
+changes.</li>
+<li>You are allowed to commit patches without approval to those portions of LLVM
+that you have contributed or maintain (i.e., have been assigned
+responsibility for), with the proviso that such commits must not break the
+build. This is a “trust but verify” policy, and commits of this nature are
+reviewed after they are committed.</li>
+<li>Multiple violations of these policies or a single egregious violation may
+cause commit access to be revoked.</li>
+</ol>
+<p>In any case, your changes are still subject to <a class="reference internal" href="#code-review">code review</a> (either before or
+after they are committed, depending on the nature of the change). You are
+encouraged to review other peoples’ patches as well, but you aren’t required
+to do so.</p>
+</div>
+<div class="section" id="making-a-major-change">
+<span id="discuss-the-change-gather-consensus"></span><h3><a class="toc-backref" href="#id15">Making a Major Change</a><a class="headerlink" href="#making-a-major-change" title="Permalink to this headline">¶</a></h3>
+<p>When a developer begins a major new project with the aim of contributing it back
+to LLVM, s/he should inform the community with an email to the <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a> email list, to the extent
+possible. The reason for this is to:</p>
+<ol class="arabic simple">
+<li>keep the community informed about future changes to LLVM,</li>
+<li>avoid duplication of effort by preventing multiple parties working on the
+same thing and not knowing about it, and</li>
+<li>ensure that any technical issues around the proposed work are discussed and
+resolved before any significant work is done.</li>
+</ol>
+<p>The design of LLVM is carefully controlled to ensure that all the pieces fit
+together well and are as consistent as possible. If you plan to make a major
+change to the way LLVM works or want to add a major new extension, it is a good
+idea to get consensus with the development community before you start working on
+it.</p>
+<p>Once the design of the new feature is finalized, the work itself should be done
+as a series of <a class="reference internal" href="#incremental-changes">incremental changes</a>, not as a long-term development branch.</p>
+</div>
+<div class="section" id="incremental-development">
+<span id="incremental-changes"></span><h3><a class="toc-backref" href="#id16">Incremental Development</a><a class="headerlink" href="#incremental-development" title="Permalink to this headline">¶</a></h3>
+<p>In the LLVM project, we do all significant changes as a series of incremental
+patches. We have a strong dislike for huge changes or long-term development
+branches. Long-term development branches have a number of drawbacks:</p>
+<ol class="arabic simple">
+<li>Branches must have mainline merged into them periodically. If the branch
+development and mainline development occur in the same pieces of code,
+resolving merge conflicts can take a lot of time.</li>
+<li>Other people in the community tend to ignore work on branches.</li>
+<li>Huge changes (produced when a branch is merged back onto mainline) are
+extremely difficult to <a class="reference internal" href="#code-review">code review</a>.</li>
+<li>Branches are not routinely tested by our nightly tester infrastructure.</li>
+<li>Changes developed as monolithic large changes often don’t work until the
+entire set of changes is done. Breaking it down into a set of smaller
+changes increases the odds that any of the work will be committed to the main
+repository.</li>
+</ol>
+<p>To address these problems, LLVM uses an incremental development style and we
+require contributors to follow this practice when making a large/invasive
+change. Some tips:</p>
+<ul class="simple">
+<li>Large/invasive changes usually have a number of secondary changes that are
+required before the big change can be made (e.g. API cleanup, etc). These
+sorts of changes can often be done before the major change is done,
+independently of that work.</li>
+<li>The remaining inter-related work should be decomposed into unrelated sets of
+changes if possible. Once this is done, define the first increment and get
+consensus on what the end goal of the change is.</li>
+<li>Each change in the set can be stand alone (e.g. to fix a bug), or part of a
+planned series of changes that works towards the development goal.</li>
+<li>Each change should be kept as small as possible. This simplifies your work
+(into a logical progression), simplifies code review and reduces the chance
+that you will get negative feedback on the change. Small increments also
+facilitate the maintenance of a high quality code base.</li>
+<li>Often, an independent precursor to a big change is to add a new API and slowly
+migrate clients to use the new API. Each change to use the new API is often
+“obvious” and can be committed without review. Once the new API is in place
+and used, it is much easier to replace the underlying implementation of the
+API. This implementation change is logically separate from the API
+change.</li>
+</ul>
+<p>If you are interested in making a large change, and this scares you, please make
+sure to first <a class="reference internal" href="#discuss-the-change-gather-consensus">discuss the change/gather consensus</a> then ask about the best way
+to go about making the change.</p>
+</div>
+<div class="section" id="attribution-of-changes">
+<h3><a class="toc-backref" href="#id17">Attribution of Changes</a><a class="headerlink" href="#attribution-of-changes" title="Permalink to this headline">¶</a></h3>
+<p>We believe in correct attribution of contributions to their contributors.
+However, we do not want the source code to be littered with random attributions
+“this code written by J. Random Hacker” (this is noisy and distracting). In
+practice, the revision control system keeps a perfect history of who changed
+what, and the CREDITS.txt file describes higher-level contributions. If you
+commit a patch for someone else, please say “patch contributed by J. Random
+Hacker!” in the commit message.</p>
+<p>Overall, please do not add contributor names to the source code.</p>
+</div>
+</div>
+<div class="section" id="copyright-license-and-patents">
+<span id="copyright-license-patents"></span><h2><a class="toc-backref" href="#id18">Copyright, License, and Patents</a><a class="headerlink" href="#copyright-license-and-patents" title="Permalink to this headline">¶</a></h2>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This section deals with legal matters but does not provide legal advice. We
+are not lawyers — please seek legal counsel from an attorney.</p>
+</div>
+<p>This section addresses the issues of copyright, license and patents for the LLVM
+project. The copyright for the code is held by the individual contributors of
+the code and the terms of its license to LLVM users and developers is the
+<a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a> (with portions dual licensed
+under the <a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>,
+see below). As contributor to the LLVM project, you agree to allow any
+contributions to the project to licensed under these terms.</p>
+<div class="section" id="copyright">
+<h3><a class="toc-backref" href="#id19">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM project does not require copyright assignments, which means that the
+copyright for the code in the project is held by its respective contributors who
+have each agreed to release their contributed code under the terms of the <a class="reference internal" href="#llvm-license">LLVM
+License</a>.</p>
+<p>An implication of this is that the LLVM license is unlikely to ever change:
+changing it would require tracking down all the contributors to LLVM and getting
+them to agree that a license change is acceptable for their contribution. Since
+there are no plans to change the license, this is not a cause for concern.</p>
+<p>As a contributor to the project, this means that you (or your company) retain
+ownership of the code you contribute, that it cannot be used in a way that
+contradicts the license (which is a liberal BSD-style license), and that the
+license for your contributions won’t change without your approval in the
+future.</p>
+</div>
+<div class="section" id="license">
+<span id="llvm-license"></span><h3><a class="toc-backref" href="#id20">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h3>
+<p>We intend to keep LLVM perpetually open source and to use a liberal open source
+license. <strong>As a contributor to the project, you agree that any contributions be
+licensed under the terms of the corresponding subproject.</strong> All of the code in
+LLVM is available under the <a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a>, which boils down to
+this:</p>
+<ul class="simple">
+<li>You can freely distribute LLVM.</li>
+<li>You must retain the copyright notice if you redistribute LLVM.</li>
+<li>Binaries derived from LLVM must reproduce the copyright notice (e.g. in an
+included readme file).</li>
+<li>You can’t use our names to promote your LLVM derived products.</li>
+<li>There’s no warranty on LLVM at all.</li>
+</ul>
+<p>We believe this fosters the widest adoption of LLVM because it <strong>allows
+commercial products to be derived from LLVM</strong> with few restrictions and without
+a requirement for making any derived works also open source (i.e. LLVM’s
+license is not a “copyleft” license like the GPL). We suggest that you read the
+<a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">License</a> if further
+clarification is needed.</p>
+<p>In addition to the UIUC license, the runtime library components of LLVM
+(<strong>compiler_rt, libc++, and libclc</strong>) are also licensed under the <a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>, which does not contain
+the binary redistribution clause. As a user of these runtime libraries, it
+means that you can choose to use the code under either license (and thus don’t
+need the binary redistribution clause), and as a contributor to the code that
+you agree that any contributions to these libraries be licensed under both
+licenses. We feel that this is important for runtime libraries, because they
+are implicitly linked into applications and therefore should not subject those
+applications to the binary redistribution clause. This also means that it is ok
+to move code from (e.g.) libc++ to the LLVM core without concern, but that code
+cannot be moved from the LLVM core to libc++ without the copyright owner’s
+permission.</p>
+<p>Note that the LLVM Project does distribute llvm-gcc and dragonegg, <strong>which are
+GPL.</strong> This means that anything “linked” into llvm-gcc must itself be compatible
+with the GPL, and must be releasable under the terms of the GPL. This implies
+that <strong>any code linked into llvm-gcc and distributed to others may be subject to
+the viral aspects of the GPL</strong> (for example, a proprietary code generator linked
+into llvm-gcc must be made available under the GPL). This is not a problem for
+code already distributed under a more liberal license (like the UIUC license),
+and GPL-containing subprojects are kept in separate SVN repositories whose
+LICENSE.txt files specifically indicate that they contain GPL code.</p>
+<p>We have no plans to change the license of LLVM. If you have questions or
+comments about the license, please contact the <a class="reference external" href="mailto:llvmdev%40cs.uiuc.edu">LLVM Developer's Mailing
+List</a>.</p>
+</div>
+<div class="section" id="patents">
+<h3><a class="toc-backref" href="#id21">Patents</a><a class="headerlink" href="#patents" title="Permalink to this headline">¶</a></h3>
+<p>To the best of our knowledge, LLVM does not infringe on any patents (we have
+actually removed code from LLVM in the past that was found to infringe). Having
+code in LLVM that infringes on patents would violate an important goal of the
+project by making it hard or impossible to reuse the code for arbitrary purposes
+(including commercial use).</p>
+<p>When contributing code, we expect contributors to notify us of any potential for
+patent-related trouble with their changes (including from third parties). If
+you or your employer own the rights to a patent and would like to contribute
+code to LLVM that relies on it, we require that the copyright owner sign an
+agreement that allows any other user of LLVM to freely use your patent. Please
+contact the <a class="reference external" href="mailto:llvm-oversight%40cs.uiuc.edu">oversight group</a> for more
+details.</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="MakefileGuide.html" title="LLVM Makefile Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/ExceptionHandling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/ExceptionHandling.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/ExceptionHandling.html (added)
+++ www-releases/trunk/3.4.1/docs/ExceptionHandling.html Wed May 7 15:09:32 2014
@@ -0,0 +1,434 @@
+
+
+<!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>Exception Handling in LLVM — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="LLVM Link Time Optimization: Design and Implementation" href="LinkTimeOptimization.html" />
+ <link rel="prev" title="The LLVM Target-Independent Code Generator" href="CodeGenerator.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="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent 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>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="exception-handling-in-llvm">
+<h1>Exception Handling in LLVM<a class="headerlink" href="#exception-handling-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="id5">Introduction</a><ul>
+<li><a class="reference internal" href="#itanium-abi-zero-cost-exception-handling" id="id6">Itanium ABI Zero-cost Exception Handling</a></li>
+<li><a class="reference internal" href="#setjmp-longjmp-exception-handling" id="id7">Setjmp/Longjmp Exception Handling</a></li>
+<li><a class="reference internal" href="#overview" id="id8">Overview</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-code-generation" id="id9">LLVM Code Generation</a><ul>
+<li><a class="reference internal" href="#throw" id="id10">Throw</a></li>
+<li><a class="reference internal" href="#try-catch" id="id11">Try/Catch</a></li>
+<li><a class="reference internal" href="#cleanups" id="id12">Cleanups</a></li>
+<li><a class="reference internal" href="#throw-filters" id="id13">Throw Filters</a></li>
+<li><a class="reference internal" href="#restrictions" id="id14">Restrictions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#exception-handling-intrinsics" id="id15">Exception Handling Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-eh-typeid-for" id="id16"><tt class="docutils literal"><span class="pre">llvm.eh.typeid.for</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-setjmp" id="id17"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.setjmp</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-longjmp" id="id18"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-lsda" id="id19"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-callsite" id="id20"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#asm-table-formats" id="id21">Asm Table Formats</a><ul>
+<li><a class="reference internal" href="#exception-handling-frame" id="id22">Exception Handling Frame</a></li>
+<li><a class="reference internal" href="#exception-tables" id="id23">Exception Tables</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id5">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is the central repository for all information pertaining to
+exception handling in LLVM. It describes the format that LLVM exception
+handling information takes, which is useful for those interested in creating
+front-ends or dealing directly with the information. Further, this document
+provides specific examples of what exception handling information is used for in
+C and C++.</p>
+<div class="section" id="itanium-abi-zero-cost-exception-handling">
+<h3><a class="toc-backref" href="#id6">Itanium ABI Zero-cost Exception Handling</a><a class="headerlink" href="#itanium-abi-zero-cost-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>Exception handling for most programming languages is designed to recover from
+conditions that rarely occur during general use of an application. To that end,
+exception handling should not interfere with the main flow of an application’s
+algorithm by performing checkpointing tasks, such as saving the current pc or
+register state.</p>
+<p>The Itanium ABI Exception Handling Specification defines a methodology for
+providing outlying data in the form of exception tables without inlining
+speculative exception handling code in the flow of an application’s main
+algorithm. Thus, the specification is said to add “zero-cost” to the normal
+execution of an application.</p>
+<p>A more complete description of the Itanium ABI exception handling runtime
+support of can be found at <a class="reference external" href="http://mentorembedded.github.com/cxx-abi/abi-eh.html">Itanium C++ ABI: Exception Handling</a>. A description of the
+exception frame format can be found at <a class="reference external" href="http://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception Frames</a>,
+with details of the DWARF 4 specification at <a class="reference external" href="http://dwarfstd.org/Dwarf4Std.php">DWARF 4 Standard</a>. A description for the C++ exception
+table formats can be found at <a class="reference external" href="http://mentorembedded.github.com/cxx-abi/exceptions.pdf">Exception Handling Tables</a>.</p>
+</div>
+<div class="section" id="setjmp-longjmp-exception-handling">
+<h3><a class="toc-backref" href="#id7">Setjmp/Longjmp Exception Handling</a><a class="headerlink" href="#setjmp-longjmp-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
+<a class="reference internal" href="#llvm-eh-sjlj-setjmp">llvm.eh.sjlj.setjmp</a> and <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a> to handle control flow for
+exception handling.</p>
+<p>For each function which does exception processing — be it <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt>
+blocks or cleanups — that function registers itself on a global frame
+list. When exceptions are unwinding, the runtime uses this list to identify
+which functions need processing.</p>
+<p>Landing pad selection is encoded in the call site entry of the function
+context. The runtime returns to the function via <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a>, where
+a switch table transfers control to the appropriate landing pad based on the
+index stored in the function context.</p>
+<p>In contrast to DWARF exception handling, which encodes exception regions and
+frame information in out-of-line tables, SJLJ exception handling builds and
+removes the unwind frame context at runtime. This results in faster exception
+handling at the expense of slower execution when no exceptions are thrown. As
+exceptions are, by their nature, intended for uncommon code paths, DWARF
+exception handling is generally preferred to SJLJ.</p>
+</div>
+<div class="section" id="overview">
+<h3><a class="toc-backref" href="#id8">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
+<p>When an exception is thrown in LLVM code, the runtime does its best to find a
+handler suited to processing the circumstance.</p>
+<p>The runtime first attempts to find an <em>exception frame</em> corresponding to the
+function where the exception was thrown. If the programming language supports
+exception handling (e.g. C++), the exception frame contains a reference to an
+exception table describing how to process the exception. If the language does
+not support exception handling (e.g. C), or if the exception needs to be
+forwarded to a prior activation, the exception frame contains information about
+how to unwind the current activation and restore the state of the prior
+activation. This process is repeated until the exception is handled. If the
+exception is not handled and no activations remain, then the application is
+terminated with an appropriate error message.</p>
+<p>Because different programming languages have different behaviors when handling
+exceptions, the exception handling ABI provides a mechanism for
+supplying <em>personalities</em>. An exception handling personality is defined by
+way of a <em>personality function</em> (e.g. <tt class="docutils literal"><span class="pre">__gxx_personality_v0</span></tt> in C++),
+which receives the context of the exception, an <em>exception structure</em>
+containing the exception object type and value, and a reference to the exception
+table for the current function. The personality function for the current
+compile unit is specified in a <em>common exception frame</em>.</p>
+<p>The organization of an exception table is language dependent. For C++, an
+exception table is organized as a series of code ranges defining what to do if
+an exception occurs in that range. Typically, the information associated with a
+range defines which types of exception objects (using C++ <em>type info</em>) that are
+handled in that range, and an associated action that should take place. Actions
+typically pass control to a <em>landing pad</em>.</p>
+<p>A landing pad corresponds roughly to the code found in the <tt class="docutils literal"><span class="pre">catch</span></tt> portion of
+a <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> sequence. When execution resumes at a landing pad, it
+receives an <em>exception structure</em> and a <em>selector value</em> corresponding to the
+<em>type</em> of exception thrown. The selector is then used to determine which <em>catch</em>
+should actually process the exception.</p>
+</div>
+</div>
+<div class="section" id="llvm-code-generation">
+<h2><a class="toc-backref" href="#id9">LLVM Code Generation</a><a class="headerlink" href="#llvm-code-generation" title="Permalink to this headline">¶</a></h2>
+<p>From a C++ developer’s perspective, exceptions are defined in terms of the
+<tt class="docutils literal"><span class="pre">throw</span></tt> and <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> statements. In this section we will describe the
+implementation of LLVM exception handling in terms of C++ examples.</p>
+<div class="section" id="throw">
+<h3><a class="toc-backref" href="#id10">Throw</a><a class="headerlink" href="#throw" title="Permalink to this headline">¶</a></h3>
+<p>Languages that support exception handling typically provide a <tt class="docutils literal"><span class="pre">throw</span></tt>
+operation to initiate the exception process. Internally, a <tt class="docutils literal"><span class="pre">throw</span></tt> operation
+breaks down into two steps.</p>
+<ol class="arabic simple">
+<li>A request is made to allocate exception space for an exception structure.
+This structure needs to survive beyond the current activation. This structure
+will contain the type and value of the object being thrown.</li>
+<li>A call is made to the runtime to raise the exception, passing the exception
+structure as an argument.</li>
+</ol>
+<p>In C++, the allocation of the exception structure is done by the
+<tt class="docutils literal"><span class="pre">__cxa_allocate_exception</span></tt> runtime function. The exception raising is handled
+by <tt class="docutils literal"><span class="pre">__cxa_throw</span></tt>. The type of the exception is represented using a C++ RTTI
+structure.</p>
+</div>
+<div class="section" id="try-catch">
+<h3><a class="toc-backref" href="#id11">Try/Catch</a><a class="headerlink" href="#try-catch" title="Permalink to this headline">¶</a></h3>
+<p>A call within the scope of a <em>try</em> statement can potentially raise an
+exception. In those circumstances, the LLVM C++ front-end replaces the call with
+an <tt class="docutils literal"><span class="pre">invoke</span></tt> instruction. Unlike a call, the <tt class="docutils literal"><span class="pre">invoke</span></tt> has two potential
+continuation points:</p>
+<ol class="arabic simple">
+<li>where to continue when the call succeeds as per normal, and</li>
+<li>where to continue if the call raises an exception, either by a throw or the
+unwinding of a throw</li>
+</ol>
+<p>The term used to define a the place where an <tt class="docutils literal"><span class="pre">invoke</span></tt> continues after an
+exception is called a <em>landing pad</em>. LLVM landing pads are conceptually
+alternative function entry points where an exception structure reference and a
+type info index are passed in as arguments. The landing pad saves the exception
+structure reference and then proceeds to select the catch block that corresponds
+to the type info of the exception object.</p>
+<p>The LLVM <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> is used to convey information about the landing
+pad to the back end. For C++, the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction returns a pointer
+and integer pair corresponding to the pointer to the <em>exception structure</em> and
+the <em>selector value</em> respectively.</p>
+<p>The <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction takes a reference to the personality function to
+be used for this <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> sequence. The remainder of the instruction is
+a list of <em>cleanup</em>, <em>catch</em>, and <em>filter</em> clauses. The exception is tested
+against the clauses sequentially from first to last. The selector value is a
+positive number if the exception matched a type info, a negative number if it
+matched a filter, and zero if it matched a cleanup. If nothing is matched, the
+behavior of the program is <a class="reference internal" href="#undefined">undefined</a>. If a type info matched, then the
+selector value is the index of the type info in the exception table, which can
+be obtained using the <a class="reference internal" href="#llvm-eh-typeid-for">llvm.eh.typeid.for</a> intrinsic.</p>
+<p>Once the landing pad has the type info selector, the code branches to the code
+for the first catch. The catch then checks the value of the type info selector
+against the index of type info for that catch. Since the type info index is not
+known until all the type infos have been gathered in the backend, the catch code
+must call the <a class="reference internal" href="#llvm-eh-typeid-for">llvm.eh.typeid.for</a> intrinsic to determine the index for a given
+type info. If the catch fails to match the selector then control is passed on to
+the next catch.</p>
+<p>Finally, the entry and exit of catch code is bracketed with calls to
+<tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt> and <tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt>.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt> takes an exception structure reference as an argument
+and returns the value of the exception object.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt> takes no arguments. This function:</p>
+<ol class="arabic simple">
+<li>Locates the most recently caught exception and decrements its handler
+count,</li>
+<li>Removes the exception from the <em>caught</em> stack if the handler count goes to
+zero, and</li>
+<li>Destroys the exception if the handler count goes to zero and the exception
+was not re-thrown by throw.</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">a rethrow from within the catch may replace this call with a
+<tt class="docutils literal"><span class="pre">__cxa_rethrow</span></tt>.</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="cleanups">
+<h3><a class="toc-backref" href="#id12">Cleanups</a><a class="headerlink" href="#cleanups" title="Permalink to this headline">¶</a></h3>
+<p>A cleanup is extra code which needs to be run as part of unwinding a scope. C++
+destructors are a typical example, but other languages and language extensions
+provide a variety of different kinds of cleanups. In general, a landing pad may
+need to run arbitrary amounts of cleanup code before actually entering a catch
+block. To indicate the presence of cleanups, a <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> should have
+a <em>cleanup</em> clause. Otherwise, the unwinder will not stop at the landing pad if
+there are no catches or filters that require it to.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Do not allow a new exception to propagate out of the execution of a
+cleanup. This can corrupt the internal state of the unwinder. Different
+languages describe different high-level semantics for these situations: for
+example, C++ requires that the process be terminated, whereas Ada cancels both
+exceptions and throws a third.</p>
+</div>
+<p>When all cleanups are finished, if the exception is not handled by the current
+function, resume unwinding by calling the <a class="reference external" href="LangRef.html#i_resume">resume
+instruction</a>, passing in the result of the
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction for the original landing pad.</p>
+</div>
+<div class="section" id="throw-filters">
+<h3><a class="toc-backref" href="#id13">Throw Filters</a><a class="headerlink" href="#throw-filters" title="Permalink to this headline">¶</a></h3>
+<p>C++ allows the specification of which exception types may be thrown from a
+function. To represent this, a top level landing pad may exist to filter out
+invalid types. To express this in LLVM code the <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> will have a
+filter clause. The clause consists of an array of type infos.
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> will return a negative value
+if the exception does not match any of the type infos. If no match is found then
+a call to <tt class="docutils literal"><span class="pre">__cxa_call_unexpected</span></tt> should be made, otherwise
+<tt class="docutils literal"><span class="pre">_Unwind_Resume</span></tt>. Each of these functions requires a reference to the
+exception structure. Note that the most general form of a <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction can have any number of catch, cleanup, and filter clauses (though
+having more than one cleanup is pointless). The LLVM C++ front-end can generate
+such <tt class="docutils literal"><span class="pre">landingpad</span></tt> instructions due to inlining creating nested exception
+handling scopes.</p>
+</div>
+<div class="section" id="restrictions">
+<span id="undefined"></span><h3><a class="toc-backref" href="#id14">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h3>
+<p>The unwinder delegates the decision of whether to stop in a call frame to that
+call frame’s language-specific personality function. Not all unwinders guarantee
+that they will stop to perform cleanups. For example, the GNU C++ unwinder
+doesn’t do so unless the exception is actually caught somewhere further up the
+stack.</p>
+<p>In order for inlining to behave correctly, landing pads must be prepared to
+handle selector results that they did not originally advertise. Suppose that a
+function catches exceptions of type <tt class="docutils literal"><span class="pre">A</span></tt>, and it’s inlined into a function that
+catches exceptions of type <tt class="docutils literal"><span class="pre">B</span></tt>. The inliner will update the <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction for the inlined landing pad to include the fact that <tt class="docutils literal"><span class="pre">B</span></tt> is also
+caught. If that landing pad assumes that it will only be entered to catch an
+<tt class="docutils literal"><span class="pre">A</span></tt>, it’s in for a rude awakening. Consequently, landing pads must test for
+the selector results they understand and then resume exception propagation with
+the <a class="reference external" href="LangRef.html#i_resume">resume instruction</a> if none of the conditions
+match.</p>
+</div>
+</div>
+<div class="section" id="exception-handling-intrinsics">
+<h2><a class="toc-backref" href="#id15">Exception Handling Intrinsics</a><a class="headerlink" href="#exception-handling-intrinsics" title="Permalink to this headline">¶</a></h2>
+<p>In addition to the <tt class="docutils literal"><span class="pre">landingpad</span></tt> and <tt class="docutils literal"><span class="pre">resume</span></tt> instructions, LLVM uses several
+intrinsic functions (name prefixed with <tt class="docutils literal"><span class="pre">llvm.eh</span></tt>) to provide exception
+handling information at various points in generated code.</p>
+<div class="section" id="llvm-eh-typeid-for">
+<span id="id2"></span><h3><a class="toc-backref" href="#id16"><tt class="docutils literal"><span class="pre">llvm.eh.typeid.for</span></tt></a><a class="headerlink" href="#llvm-eh-typeid-for" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i32</span> <span class="vg">@llvm.eh.typeid.for</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%type_info</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic returns the type info index in the exception table of the current
+function. This value can be used to compare against the result of
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. The single argument is a reference to a type info.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-setjmp">
+<span id="id3"></span><h3><a class="toc-backref" href="#id17"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.setjmp</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-setjmp" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i32</span> <span class="vg">@llvm.eh.sjlj.setjmp</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%setjmp_buf</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, this intrinsic forces register saving for the
+current function and stores the address of the following instruction for use as
+a destination address by <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a>. The buffer format and the
+overall functioning of this intrinsic is compatible with the GCC
+<tt class="docutils literal"><span class="pre">__builtin_setjmp</span></tt> implementation allowing code built with the clang and GCC
+to interoperate.</p>
+<p>The single parameter is a pointer to a five word buffer in which the calling
+context is saved. The front end places the frame pointer in the first word, and
+the target implementation of this intrinsic should place the destination address
+for a <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a> in the second word. The following three words are
+available for use in a target-specific manner.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-longjmp">
+<span id="id4"></span><h3><a class="toc-backref" href="#id18"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-longjmp" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.sjlj.longjmp</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%setjmp_buf</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt> intrinsic is
+used to implement <tt class="docutils literal"><span class="pre">__builtin_longjmp()</span></tt>. The single parameter is a pointer to
+a buffer populated by <a class="reference internal" href="#llvm-eh-sjlj-setjmp">llvm.eh.sjlj.setjmp</a>. The frame pointer and stack
+pointer are restored from the buffer, then control is transferred to the
+destination address.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-lsda">
+<h3><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-lsda" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.eh.sjlj.lsda</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt> intrinsic returns
+the address of the Language Specific Data Area (LSDA) for the current
+function. The SJLJ front-end code stores this address in the exception handling
+function context for use by the runtime.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-callsite">
+<h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-callsite" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.sjlj.callsite</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%call_site_num</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt> intrinsic
+identifies the callsite value associated with the following <tt class="docutils literal"><span class="pre">invoke</span></tt>
+instruction. This is used to ensure that landing pad entries in the LSDA are
+generated in matching order.</p>
+</div>
+</div>
+<div class="section" id="asm-table-formats">
+<h2><a class="toc-backref" href="#id21">Asm Table Formats</a><a class="headerlink" href="#asm-table-formats" title="Permalink to this headline">¶</a></h2>
+<p>There are two tables that are used by the exception handling runtime to
+determine which actions should be taken when an exception is thrown.</p>
+<div class="section" id="exception-handling-frame">
+<h3><a class="toc-backref" href="#id22">Exception Handling Frame</a><a class="headerlink" href="#exception-handling-frame" title="Permalink to this headline">¶</a></h3>
+<p>An exception handling frame <tt class="docutils literal"><span class="pre">eh_frame</span></tt> is very similar to the unwind frame
+used by DWARF debug info. The frame contains all the information necessary to
+tear down the current frame and restore the state of the prior frame. There is
+an exception handling frame for each function in a compile unit, plus a common
+exception handling frame that defines information common to all functions in the
+unit.</p>
+</div>
+<div class="section" id="exception-tables">
+<h3><a class="toc-backref" href="#id23">Exception Tables</a><a class="headerlink" href="#exception-tables" title="Permalink to this headline">¶</a></h3>
+<p>An exception table contains information about what actions to take when an
+exception is thrown in a particular part of a function’s code. There is one
+exception table per function, except leaf functions and functions that have
+calls only to non-throwing functions. They do not need an exception table.</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="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent Code Generator"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/ExtendingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/ExtendingLLVM.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/ExtendingLLVM.html (added)
+++ www-releases/trunk/3.4.1/docs/ExtendingLLVM.html Wed May 7 15:09:32 2014
@@ -0,0 +1,363 @@
+
+
+<!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>Extending LLVM: Adding instructions, intrinsics, types, etc. — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="How to set up LLVM-style RTTI for your class hierarchy" href="HowToSetUpLLVMStyleRTTI.html" />
+ <link rel="prev" title="Architecture & Platform Information for Compiler Writers" href="CompilerWriterInfo.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="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ 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="extending-llvm-adding-instructions-intrinsics-types-etc">
+<h1>Extending LLVM: Adding instructions, intrinsics, types, etc.<a class="headerlink" href="#extending-llvm-adding-instructions-intrinsics-types-etc" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-and-warning">
+<h2>Introduction and Warning<a class="headerlink" href="#introduction-and-warning" title="Permalink to this headline">¶</a></h2>
+<p>During the course of using LLVM, you may wish to customize it for your research
+project or for experimentation. At this point, you may realize that you need to
+add something to LLVM, whether it be a new fundamental type, a new intrinsic
+function, or a whole new instruction.</p>
+<p>When you come to this realization, stop and think. Do you really need to extend
+LLVM? Is it a new fundamental capability that LLVM does not support at its
+current incarnation or can it be synthesized from already pre-existing LLVM
+elements? If you are not sure, ask on the <a class="reference external" href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM-dev</a> list. The reason is that
+extending LLVM will get involved as you need to update all the different passes
+that you intend to use with your extension, and there are <tt class="docutils literal"><span class="pre">many</span></tt> LLVM analyses
+and transformations, so it may be quite a bit of work.</p>
+<p>Adding an <a class="reference internal" href="#intrinsic-function">intrinsic function</a> is far easier than adding an
+instruction, and is transparent to optimization passes. If your added
+functionality can be expressed as a function call, an intrinsic function is the
+method of choice for LLVM extension.</p>
+<p>Before you invest a significant amount of effort into a non-trivial extension,
+<strong>ask on the list</strong> if what you are looking to do can be done with
+already-existing infrastructure, or if maybe someone else is already working on
+it. You will save yourself a lot of time and effort by doing so.</p>
+</div>
+<div class="section" id="adding-a-new-intrinsic-function">
+<span id="intrinsic-function"></span><h2>Adding a new intrinsic function<a class="headerlink" href="#adding-a-new-intrinsic-function" title="Permalink to this headline">¶</a></h2>
+<p>Adding a new intrinsic function to LLVM is much easier than adding a new
+instruction. Almost all extensions to LLVM should start as an intrinsic
+function and then be turned into an instruction if warranted.</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/docs/LangRef.html</span></tt>:</p>
+<p>Document the intrinsic. Decide whether it is code generator specific and
+what the restrictions are. Talk to other people about it so that you are
+sure it’s a good idea.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Intrinsics*.td</span></tt>:</p>
+<p>Add an entry for your intrinsic. Describe its memory access characteristics
+for optimization (this controls whether it will be DCE’d, CSE’d, etc). Note
+that any intrinsic using the <tt class="docutils literal"><span class="pre">llvm_int_ty</span></tt> type for an argument will
+be deemed by <tt class="docutils literal"><span class="pre">tblgen</span></tt> as overloaded and the corresponding suffix will
+be required on the intrinsic’s name.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Analysis/ConstantFolding.cpp</span></tt>:</p>
+<p>If it is possible to constant fold your intrinsic, add support to it in the
+<tt class="docutils literal"><span class="pre">canConstantFoldCallTo</span></tt> and <tt class="docutils literal"><span class="pre">ConstantFoldCall</span></tt> functions.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/Regression/*</span></tt>:</p>
+<p>Add test cases for your test cases to the test suite</p>
+</li>
+</ol>
+<p>Once the intrinsic has been added to the system, you must add code generator
+support for it. Generally you must do the following steps:</p>
+<p>Add support to the .td file for the target(s) of your choice in
+<tt class="docutils literal"><span class="pre">lib/Target/*/*.td</span></tt>.</p>
+<blockquote>
+<div>This is usually a matter of adding a pattern to the .td file that matches the
+intrinsic, though it may obviously require adding the instructions you want to
+generate as well. There are lots of examples in the PowerPC and X86 backend
+to follow.</div></blockquote>
+</div>
+<div class="section" id="adding-a-new-selectiondag-node">
+<h2>Adding a new SelectionDAG node<a class="headerlink" href="#adding-a-new-selectiondag-node" title="Permalink to this headline">¶</a></h2>
+<p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier than
+adding a new instruction. New nodes are often added to help represent
+instructions common to many targets. These nodes often map to an LLVM
+instruction (add, sub) or intrinsic (byteswap, population count). In other
+cases, new nodes have been added to allow many targets to perform a common task
+(converting between floating point and integer representation) or capture more
+complicated behavior in a single node (rotate).</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/llvm/CodeGen/ISDOpcodes.h</span></tt>:</p>
+<p>Add an enum value for the new SelectionDAG node.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/SelectionDAG.cpp</span></tt>:</p>
+<dl class="docutils">
+<dt>Add code to print the node to <tt class="docutils literal"><span class="pre">getOperationName</span></tt>. If your new node can be</dt>
+<dd><p class="first last">evaluated at compile time when given constant arguments (such as an add of a
+constant with another constant), find the <tt class="docutils literal"><span class="pre">getNode</span></tt> method that takes the
+appropriate number of arguments, and add a case for your node to the switch
+statement that performs constant folding for nodes that take the same number
+of arguments as your new node.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<p>Add code to <a class="reference external" href="CodeGenerator.html#selectiondag_legalize">legalize, promote, and expand</a> the node as necessary. At a
+minimum, you will need to add a case statement for your node in
+<tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> which calls LegalizeOp on the node’s operands, and returns a
+new node if any of the operands changed as a result of being legalized. It
+is likely that not all targets supported by the SelectionDAG framework will
+natively support the new node. In this case, you must also add code in your
+node’s case statement in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> to Expand your node into simpler,
+legal operations. The case for <tt class="docutils literal"><span class="pre">ISD::UREM</span></tt> for expanding a remainder into
+a divide, multiply, and a subtract is a good example.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<dl class="docutils">
+<dt>If targets may support the new node being added only at certain sizes, you</dt>
+<dd><p class="first last">will also need to add code to your node’s case statement in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt>
+to Promote your node’s operands to a larger size, and perform the correct
+operation. You will also need to add code to <tt class="docutils literal"><span class="pre">PromoteOp</span></tt> to do this as
+well. For a good example, see <tt class="docutils literal"><span class="pre">ISD::BSWAP</span></tt>, which promotes its operand to
+a wider size, performs the byteswap, and then shifts the correct bytes right
+to emulate the narrower byteswap in the wider type.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<p>Add a case for your node in <tt class="docutils literal"><span class="pre">ExpandOp</span></tt> to teach the legalizer how to
+perform the action represented by the new node on a value that has been split
+into high and low halves. This case will be used to support your node with a
+64 bit operand on a 32 bit target.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/DAGCombiner.cpp</span></tt>:</p>
+<p>If your node can be combined with itself, or other existing nodes in a
+peephole-like fashion, add a visit function for it, and call that function
+from. There are several good examples for simple combines you can do;
+<tt class="docutils literal"><span class="pre">visitFABS</span></tt> and <tt class="docutils literal"><span class="pre">visitSRL</span></tt> are good starting places.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/PowerPC/PPCISelLowering.cpp</span></tt>:</p>
+<p>Each target has an implementation of the <tt class="docutils literal"><span class="pre">TargetLowering</span></tt> class, usually in
+its own file (although some targets include it in the same file as the
+DAGToDAGISel). The default behavior for a target is to assume that your new
+node is legal for all types that are legal for that target. If this target
+does not natively support your node, then tell the target to either Promote
+it (if it is supported at a larger type) or Expand it. This will cause the
+code you wrote in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> above to decompose your new node into other
+legal nodes for this target.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/TargetSelectionDAG.td</span></tt>:</p>
+<p>Most current targets supported by LLVM generate code using the DAGToDAG
+method, where SelectionDAG nodes are pattern matched to target-specific
+nodes, which represent individual instructions. In order for the targets to
+match an instruction to your new node, you must add a def for that node to
+the list in this file, with the appropriate type constraints. Look at
+<tt class="docutils literal"><span class="pre">add</span></tt>, <tt class="docutils literal"><span class="pre">bswap</span></tt>, and <tt class="docutils literal"><span class="pre">fadd</span></tt> for examples.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/PowerPC/PPCInstrInfo.td</span></tt>:</p>
+<p>Each target has a tablegen file that describes the target’s instruction set.
+For targets that use the DAGToDAG instruction selection framework, add a
+pattern for your new node that uses one or more target nodes. Documentation
+for this is a bit sparse right now, but there are several decent examples.
+See the patterns for <tt class="docutils literal"><span class="pre">rotl</span></tt> in <tt class="docutils literal"><span class="pre">PPCInstrInfo.td</span></tt>.</p>
+</li>
+<li><p class="first">TODO: document complex patterns.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/Regression/CodeGen/*</span></tt>:</p>
+<p>Add test cases for your new node to the test suite.
+<tt class="docutils literal"><span class="pre">llvm/test/Regression/CodeGen/X86/bswap.ll</span></tt> is a good example.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-new-instruction">
+<h2>Adding a new instruction<a class="headerlink" href="#adding-a-new-instruction" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding instructions changes the bitcode format, and it will take some effort
+to maintain compatibility with the previous version. Only add an instruction
+if it is absolutely necessary.</p>
+</div>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/Instruction.def</span></tt>:</p>
+<p>add a number for your instruction and an enum name</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/Instructions.h</span></tt>:</p>
+<p>add a definition for the class that will represent your instruction</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/Support/InstVisitor.h</span></tt>:</p>
+<p>add a prototype for a visitor to your new instruction type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/Lexer.l</span></tt>:</p>
+<p>add a new token to parse your instruction from assembly text file</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/llvmAsmParser.y</span></tt>:</p>
+<p>add the grammar on how your instruction can be read and what it will
+construct as a result</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/Reader.cpp</span></tt>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/VMCore/Instruction.cpp</span></tt>:</p>
+<p>add a case for how your instruction will be printed out to assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/VMCore/Instructions.cpp</span></tt>:</p>
+<p>implement the class you defined in <tt class="docutils literal"><span class="pre">llvm/include/llvm/Instructions.h</span></tt></p>
+</li>
+<li><p class="first">Test your instruction</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Target/*</span></tt>:</p>
+<p>add support for your instruction to code generators, or add a lowering pass.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/Regression/*</span></tt>:</p>
+<p>add your test cases to the test suite.</p>
+</li>
+</ol>
+<p>Also, you need to implement (or modify) any analyses or passes that you want to
+understand this new instruction.</p>
+</div>
+<div class="section" id="adding-a-new-type">
+<h2>Adding a new type<a class="headerlink" href="#adding-a-new-type" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding new types changes the bitcode format, and will break compatibility with
+currently-existing LLVM installations. Only add new types if it is absolutely
+necessary.</p>
+</div>
+<div class="section" id="adding-a-fundamental-type">
+<h3>Adding a fundamental type<a class="headerlink" href="#adding-a-fundamental-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/Type.h</span></tt>:</p>
+<p>add enum for the new type; add static <tt class="docutils literal"><span class="pre">Type*</span></tt> for this type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/VMCore/Type.cpp</span></tt>:</p>
+<p>add mapping from <tt class="docutils literal"><span class="pre">TypeID</span></tt> => <tt class="docutils literal"><span class="pre">Type*</span></tt>; initialize the static <tt class="docutils literal"><span class="pre">Type*</span></tt></p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmReader/Lexer.l</span></tt>:</p>
+<p>add ability to parse in the type from text assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmReader/llvmAsmParser.y</span></tt>:</p>
+<p>add a token for that type</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-derived-type">
+<h3>Adding a derived type<a class="headerlink" href="#adding-a-derived-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/Type.h</span></tt>:</p>
+<p>add enum for the new type; add a forward declaration of the type also</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/DerivedTypes.h</span></tt>:</p>
+<p>add new class to represent new class in the hierarchy; add forward
+declaration to the TypeMap value type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/VMCore/Type.cpp</span></tt>:</p>
+<p>add support for derived type to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">getTypeDescription</span><span class="p">(</span><span class="k">const</span> <span class="n">Type</span> <span class="o">&</span><span class="n">Ty</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="k">const</span> <span class="n">Type</span><span class="o">*></span> <span class="o">&</span><span class="n">TypeStack</span><span class="p">)</span>
+<span class="kt">bool</span> <span class="n">TypesEqual</span><span class="p">(</span><span class="k">const</span> <span class="n">Type</span> <span class="o">*</span><span class="n">Ty</span><span class="p">,</span> <span class="k">const</span> <span class="n">Type</span> <span class="o">*</span><span class="n">Ty2</span><span class="p">,</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">map</span><span class="o"><</span><span class="k">const</span> <span class="n">Type</span><span class="o">*</span><span class="p">,</span> <span class="k">const</span> <span class="n">Type</span><span class="o">*></span> <span class="o">&</span><span class="n">EqTypes</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>add necessary member functions for type, and factory methods</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmReader/Lexer.l</span></tt>:</p>
+<p>add ability to parse in the type from text assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Writer/Writer.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">void</span> <span class="pre">BitcodeWriter::outputType(const</span> <span class="pre">Type</span> <span class="pre">*T)</span></tt> to serialize your
+type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/Reader.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">const</span> <span class="pre">Type</span> <span class="pre">*BitcodeReader::ParseType()</span></tt> to read your data type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/VMCore/AsmWriter.cpp</span></tt>:</p>
+<p>modify</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="n">calcTypeName</span><span class="p">(</span><span class="k">const</span> <span class="n">Type</span> <span class="o">*</span><span class="n">Ty</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="k">const</span> <span class="n">Type</span><span class="o">*></span> <span class="o">&</span><span class="n">TypeStack</span><span class="p">,</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">map</span><span class="o"><</span><span class="k">const</span> <span class="n">Type</span><span class="o">*</span><span class="p">,</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="o">&</span><span class="n">TypeNames</span><span class="p">,</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">Result</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>to output the new derived type</p>
+</li>
+</ol>
+</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="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/Extensions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/Extensions.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/Extensions.html (added)
+++ www-releases/trunk/3.4.1/docs/Extensions.html Wed May 7 15:09:32 2014
@@ -0,0 +1,234 @@
+
+
+<!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 Extensions — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="LLVM Alias Analysis Infrastructure" href="AliasAnalysis.html" />
+ <link rel="prev" title="LLVM Programmerâs Manual" href="ProgrammersManual.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="AliasAnalysis.html" title="LLVM Alias Analysis Infrastructure"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs 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="llvm-extensions">
+<h1>LLVM Extensions<a class="headerlink" href="#llvm-extensions" 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="#general-assembly-syntax" id="id2">General Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#c99-style-hexadecimal-floating-point-constants" id="id3">C99-style Hexadecimal Floating-point Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#machine-specific-assembly-syntax" id="id4">Machine-specific Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#x86-coff-dependent" id="id5">X86/COFF-Dependent</a><ul>
+<li><a class="reference internal" href="#relocations" id="id6">Relocations</a></li>
+<li><a class="reference internal" href="#linkonce-directive" id="id7"><tt class="docutils literal"><span class="pre">.linkonce</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#section-directive" id="id8"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</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 extensions to tools and formats LLVM seeks compatibility
+with.</p>
+</div>
+<div class="section" id="general-assembly-syntax">
+<h2><a class="toc-backref" href="#id2">General Assembly Syntax</a><a class="headerlink" href="#general-assembly-syntax" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="c99-style-hexadecimal-floating-point-constants">
+<h3><a class="toc-backref" href="#id3">C99-style Hexadecimal Floating-point Constants</a><a class="headerlink" href="#c99-style-hexadecimal-floating-point-constants" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s assemblers allow floating-point constants to be written in C99’s
+hexadecimal format instead of decimal if desired.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.data</span>
+<span class="na">.float</span> <span class="mi">0x1c2</span><span class="no">.2ap3</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="machine-specific-assembly-syntax">
+<h2><a class="toc-backref" href="#id4">Machine-specific Assembly Syntax</a><a class="headerlink" href="#machine-specific-assembly-syntax" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="x86-coff-dependent">
+<h3><a class="toc-backref" href="#id5">X86/COFF-Dependent</a><a class="headerlink" href="#x86-coff-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="relocations">
+<h4><a class="toc-backref" href="#id6">Relocations</a><a class="headerlink" href="#relocations" title="Permalink to this headline">¶</a></h4>
+<p>The following additional relocation type is supported:</p>
+<p><strong>@IMGREL</strong> (AT&T syntax only) generates an image-relative relocation that
+corresponds to the COFF relocation types <tt class="docutils literal"><span class="pre">IMAGE_REL_I386_DIR32NB</span></tt> (32-bit) or
+<tt class="docutils literal"><span class="pre">IMAGE_REL_AMD64_ADDR32NB</span></tt> (64-bit).</p>
+<div class="highlight-gas"><pre>.text
+fun:
+ mov foo at IMGREL(%ebx, %ecx, 4), %eax
+
+.section .pdata
+ .long fun at IMGREL
+ .long (fun at imgrel + 0x3F)
+ .long $unwind$fun at imgrel</pre>
+</div>
+</div>
+<div class="section" id="linkonce-directive">
+<h4><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">.linkonce</span></tt> Directive</a><a class="headerlink" href="#linkonce-directive" title="Permalink to this headline">¶</a></h4>
+<p>Syntax:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">.linkonce</span> <span class="pre">[</span> <span class="pre">comdat</span> <span class="pre">type</span> <span class="pre">[</span> <span class="pre">section</span> <span class="pre">identifier</span> <span class="pre">]</span> <span class="pre">]</span></tt></div></blockquote>
+<p>Supported COMDAT types:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">discard</span></tt></dt>
+<dd>Discards duplicate sections with the same COMDAT symbol. This is the default
+if no type is specified.</dd>
+<dt><tt class="docutils literal"><span class="pre">one_only</span></tt></dt>
+<dd>If the symbol is defined multiple times, the linker issues an error.</dd>
+<dt><tt class="docutils literal"><span class="pre">same_size</span></tt></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any have
+different sizes.</dd>
+<dt><tt class="docutils literal"><span class="pre">same_contents</span></tt></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any duplicates
+do not have exactly the same content.</dd>
+<dt><tt class="docutils literal"><span class="pre">associative</span></tt></dt>
+<dd><p class="first">Links the section if a certain other COMDAT section is linked. This other
+section is indicated by its section identifier following the comdat type.
+The following restrictions apply to the associated section:</p>
+<ol class="last arabic simple">
+<li>It must be the name of a section already defined.</li>
+<li>It must differ from the current section.</li>
+<li>It must be a COMDAT section.</li>
+<li>It cannot be another associative COMDAT section.</li>
+</ol>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">largest</span></tt></dt>
+<dd>Links the largest section from among the duplicates.</dd>
+<dt><tt class="docutils literal"><span class="pre">newest</span></tt></dt>
+<dd>Links the newest section from among the duplicates.</dd>
+</dl>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.text$foo</span>
+<span class="na">.linkonce</span>
+ <span class="na">...</span>
+
+<span class="na">.section</span> <span class="no">.xdata$foo</span>
+<span class="na">.linkonce</span> <span class="no">associative</span> <span class="no">.text$foo</span>
+ <span class="na">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="section-directive">
+<h4><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a><a class="headerlink" href="#section-directive" title="Permalink to this headline">¶</a></h4>
+<p>MC supports passing the information in <tt class="docutils literal"><span class="pre">.linkonce</span></tt> at the end of
+<tt class="docutils literal"><span class="pre">.section</span></tt>. For example, these two codes are equivalent</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span>
+<span class="na">.linkonce</span> <span class="no">discard</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<p>Note that in the combined form the COMDAT symbol is explict. This
+extension exits to support multiple sections with the same name in
+different comdats:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+
+<span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol2"</span>
+<span class="na">.globl</span> <span class="no">Symbol2</span>
+<span class="nl">Symbol2:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</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="AliasAnalysis.html" title="LLVM Alias Analysis Infrastructure"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs 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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/FAQ.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/FAQ.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/FAQ.html (added)
+++ www-releases/trunk/3.4.1/docs/FAQ.html Wed May 7 15:09:32 2014
@@ -0,0 +1,565 @@
+
+
+<!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>Frequently Asked Questions (FAQ) — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="The LLVM Lexicon" href="Lexicon.html" />
+ <link rel="prev" title="Getting Started with the LLVM System using Microsoft Visual Studio" href="GettingStartedVS.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="Lexicon.html" title="The LLVM Lexicon"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ 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="frequently-asked-questions-faq">
+<h1>Frequently Asked Questions (FAQ)<a class="headerlink" href="#frequently-asked-questions-faq" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#license" id="id1">License</a><ul>
+<li><a class="reference internal" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" id="id2">Does the University of Illinois Open Source License really qualify as an “open source” license?</a></li>
+<li><a class="reference internal" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" id="id3">Can I modify LLVM source code and redistribute the modified source?</a></li>
+<li><a class="reference internal" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" id="id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-code" id="id5">Source Code</a><ul>
+<li><a class="reference internal" href="#in-what-language-is-llvm-written" id="id6">In what language is LLVM written?</a></li>
+<li><a class="reference internal" href="#how-portable-is-the-llvm-source-code" id="id7">How portable is the LLVM source code?</a></li>
+<li><a class="reference internal" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" id="id8">What API do I use to store a value to one of the virtual registers in LLVM IR’s SSA representation?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#build-problems" id="id9">Build Problems</a><ul>
+<li><a class="reference internal" href="#when-i-run-configure-it-finds-the-wrong-c-compiler" id="id10">When I run configure, it finds the wrong C compiler.</a></li>
+<li><a class="reference internal" href="#the-configure-script-finds-the-right-c-compiler-but-it-uses-the-llvm-tools-from-a-previous-build-what-do-i-do" id="id11">The <tt class="docutils literal"><span class="pre">configure</span></tt> script finds the right C compiler, but it uses the LLVM tools from a previous build. What do I do?</a></li>
+<li><a class="reference internal" href="#when-creating-a-dynamic-library-i-get-a-strange-glibc-error" id="id12">When creating a dynamic library, I get a strange GLIBC error.</a></li>
+<li><a class="reference internal" href="#i-ve-updated-my-source-tree-from-subversion-and-now-my-build-is-trying-to-use-a-file-directory-that-doesn-t-exist" id="id13">I’ve updated my source tree from Subversion, and now my build is trying to use a file/directory that doesn’t exist.</a></li>
+<li><a class="reference internal" href="#i-ve-modified-a-makefile-in-my-source-tree-but-my-build-tree-keeps-using-the-old-version-what-do-i-do" id="id14">I’ve modified a Makefile in my source tree, but my build tree keeps using the old version. What do I do?</a></li>
+<li><a class="reference internal" href="#i-ve-upgraded-to-a-new-version-of-llvm-and-i-get-strange-build-errors" id="id15">I’ve upgraded to a new version of LLVM, and I get strange build errors.</a></li>
+<li><a class="reference internal" href="#i-ve-built-llvm-and-am-testing-it-but-the-tests-freeze" id="id16">I’ve built LLVM and am testing it, but the tests freeze.</a></li>
+<li><a class="reference internal" href="#why-do-test-results-differ-when-i-perform-different-types-of-builds" id="id17">Why do test results differ when I perform different types of builds?</a></li>
+<li><a class="reference internal" href="#compiling-llvm-with-gcc-3-3-2-fails-what-should-i-do" id="id18">Compiling LLVM with GCC 3.3.2 fails, what should I do?</a></li>
+<li><a class="reference internal" href="#compiling-llvm-with-gcc-succeeds-but-the-resulting-tools-do-not-work-what-can-be-wrong" id="id19">Compiling LLVM with GCC succeeds, but the resulting tools do not work, what can be wrong?</a></li>
+<li><a class="reference internal" href="#after-subversion-update-rebuilding-gives-the-error-no-rule-to-make-target" id="id20">After Subversion update, rebuilding gives the error “No rule to make target”.</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-languages" id="id21">Source Languages</a><ul>
+<li><a class="reference internal" href="#what-source-languages-are-supported" id="id22">What source languages are supported?</a></li>
+<li><a class="reference internal" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" id="id23">I’d like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a></li>
+<li><a class="reference internal" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" id="id24">What support is there for a higher level source language constructs for building a compiler?</a></li>
+<li><a class="reference internal" href="#i-don-t-understand-the-getelementptr-instruction-help" id="id25">I don’t understand the <tt class="docutils literal"><span class="pre">GetElementPtr</span></tt> instruction. Help!</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#using-the-c-and-c-front-ends" id="id26">Using the C and C++ Front Ends</a><ul>
+<li><a class="reference internal" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" id="id27">Can I compile C or C++ code to platform-independent LLVM bitcode?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#questions-about-code-generated-by-the-demo-page" id="id28">Questions about code generated by the demo page</a><ul>
+<li><a class="reference internal" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" id="id29">What is this <tt class="docutils literal"><span class="pre">llvm.global_ctors</span></tt> and <tt class="docutils literal"><span class="pre">_GLOBAL__I_a...</span></tt> stuff that happens when I <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt>?</a></li>
+<li><a class="reference internal" href="#where-did-all-of-my-code-go" id="id30">Where did all of my code go??</a></li>
+<li><a class="reference internal" href="#what-is-this-undef-thing-that-shows-up-in-my-code" id="id31">What is this “<tt class="docutils literal"><span class="pre">undef</span></tt>” thing that shows up in my code?</a></li>
+<li><a class="reference internal" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" id="id32">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into “unreachable”? Why not make the verifier reject it?</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="license">
+<h2><a class="toc-backref" href="#id1">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license">
+<h3><a class="toc-backref" href="#id2">Does the University of Illinois Open Source License really qualify as an “open source” license?</a><a class="headerlink" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" title="Permalink to this headline">¶</a></h3>
+<p>Yes, the license is <a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open Source
+Initiative (OSI).</p>
+</div>
+<div class="section" id="can-i-modify-llvm-source-code-and-redistribute-the-modified-source">
+<h3><a class="toc-backref" href="#id3">Can I modify LLVM source code and redistribute the modified source?</a><a class="headerlink" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. The modified source distribution must retain the copyright notice and
+follow the three bulletted conditions listed in the <a class="reference external" href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM license</a>.</p>
+</div>
+<div class="section" id="can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source">
+<h3><a class="toc-backref" href="#id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a><a class="headerlink" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is why we distribute LLVM under a less restrictive license than GPL,
+as explained in the first question above.</p>
+</div>
+</div>
+<div class="section" id="source-code">
+<h2><a class="toc-backref" href="#id5">Source Code</a><a class="headerlink" href="#source-code" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="in-what-language-is-llvm-written">
+<h3><a class="toc-backref" href="#id6">In what language is LLVM written?</a><a class="headerlink" href="#in-what-language-is-llvm-written" title="Permalink to this headline">¶</a></h3>
+<p>All of the LLVM tools and libraries are written in C++ with extensive use of
+the STL.</p>
+</div>
+<div class="section" id="how-portable-is-the-llvm-source-code">
+<h3><a class="toc-backref" href="#id7">How portable is the LLVM source code?</a><a class="headerlink" href="#how-portable-is-the-llvm-source-code" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM source code should be portable to most modern Unix-like operating
+systems. Most of the code is written in standard C++ with operating system
+services abstracted to a support library. The tools required to build and
+test LLVM have been ported to a plethora of platforms.</p>
+<p>Some porting problems may exist in the following areas:</p>
+<ul class="simple">
+<li>The autoconf/makefile build system relies heavily on UNIX shell tools,
+like the Bourne Shell and sed. Porting to systems without these tools
+(MacOS 9, Plan 9) will require more effort.</li>
+</ul>
+</div>
+<div class="section" id="what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation">
+<h3><a class="toc-backref" href="#id8">What API do I use to store a value to one of the virtual registers in LLVM IR’s SSA representation?</a><a class="headerlink" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" title="Permalink to this headline">¶</a></h3>
+<p>In short: you can’t. It’s actually kind of a silly question once you grok
+what’s going on. Basically, in code like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%result</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%foo</span><span class="p">,</span> <span class="nv">%bar</span>
+</pre></div>
+</div>
+<p>, <tt class="docutils literal"><span class="pre">%result</span></tt> is just a name given to the <tt class="docutils literal"><span class="pre">Value</span></tt> of the <tt class="docutils literal"><span class="pre">add</span></tt>
+instruction. In other words, <tt class="docutils literal"><span class="pre">%result</span></tt> <em>is</em> the add instruction. The
+“assignment” doesn’t explicitly “store” anything to any “virtual register”;
+the “<tt class="docutils literal"><span class="pre">=</span></tt>” is more like the mathematical sense of equality.</p>
+<p>Longer explanation: In order to generate a textual representation of the
+IR, some kind of name has to be given to each instruction so that other
+instructions can textually reference it. However, the isomorphic in-memory
+representation that you manipulate from C++ has no such restriction since
+instructions can simply keep pointers to any other <tt class="docutils literal"><span class="pre">Value</span></tt>‘s that they
+reference. In fact, the names of dummy numbered temporaries like <tt class="docutils literal"><span class="pre">%1</span></tt> are
+not explicitly represented in the in-memory representation at all (see
+<tt class="docutils literal"><span class="pre">Value::getName()</span></tt>).</p>
+</div>
+</div>
+<div class="section" id="build-problems">
+<h2><a class="toc-backref" href="#id9">Build Problems</a><a class="headerlink" href="#build-problems" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="when-i-run-configure-it-finds-the-wrong-c-compiler">
+<h3><a class="toc-backref" href="#id10">When I run configure, it finds the wrong C compiler.</a><a class="headerlink" href="#when-i-run-configure-it-finds-the-wrong-c-compiler" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">configure</span></tt> script attempts to locate first <tt class="docutils literal"><span class="pre">gcc</span></tt> and then <tt class="docutils literal"><span class="pre">cc</span></tt>,
+unless it finds compiler paths set in <tt class="docutils literal"><span class="pre">CC</span></tt> and <tt class="docutils literal"><span class="pre">CXX</span></tt> for the C and C++
+compiler, respectively.</p>
+<p>If <tt class="docutils literal"><span class="pre">configure</span></tt> finds the wrong compiler, either adjust your <tt class="docutils literal"><span class="pre">PATH</span></tt>
+environment variable or set <tt class="docutils literal"><span class="pre">CC</span></tt> and <tt class="docutils literal"><span class="pre">CXX</span></tt> explicitly.</p>
+</div>
+<div class="section" id="the-configure-script-finds-the-right-c-compiler-but-it-uses-the-llvm-tools-from-a-previous-build-what-do-i-do">
+<h3><a class="toc-backref" href="#id11">The <tt class="docutils literal"><span class="pre">configure</span></tt> script finds the right C compiler, but it uses the LLVM tools from a previous build. What do I do?</a><a class="headerlink" href="#the-configure-script-finds-the-right-c-compiler-but-it-uses-the-llvm-tools-from-a-previous-build-what-do-i-do" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">configure</span></tt> script uses the <tt class="docutils literal"><span class="pre">PATH</span></tt> to find executables, so if it’s
+grabbing the wrong linker/assembler/etc, there are two ways to fix it:</p>
+<ol class="arabic simple">
+<li>Adjust your <tt class="docutils literal"><span class="pre">PATH</span></tt> environment variable so that the correct program
+appears first in the <tt class="docutils literal"><span class="pre">PATH</span></tt>. This may work, but may not be convenient
+when you want them <em>first</em> in your path for other work.</li>
+<li>Run <tt class="docutils literal"><span class="pre">configure</span></tt> with an alternative <tt class="docutils literal"><span class="pre">PATH</span></tt> that is correct. In a
+Bourne compatible shell, the syntax would be:</li>
+</ol>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">PATH</span><span class="o">=[</span>the path without the bad program<span class="o">]</span> ./configure ...
+</pre></div>
+</div>
+<p>This is still somewhat inconvenient, but it allows <tt class="docutils literal"><span class="pre">configure</span></tt> to do its
+work without having to adjust your <tt class="docutils literal"><span class="pre">PATH</span></tt> permanently.</p>
+</div>
+<div class="section" id="when-creating-a-dynamic-library-i-get-a-strange-glibc-error">
+<h3><a class="toc-backref" href="#id12">When creating a dynamic library, I get a strange GLIBC error.</a><a class="headerlink" href="#when-creating-a-dynamic-library-i-get-a-strange-glibc-error" title="Permalink to this headline">¶</a></h3>
+<p>Under some operating systems (i.e. Linux), libtool does not work correctly if
+GCC was compiled with the <tt class="docutils literal"><span class="pre">--disable-shared</span> <span class="pre">option</span></tt>. To work around this,
+install your own version of GCC that has shared libraries enabled by default.</p>
+</div>
+<div class="section" id="i-ve-updated-my-source-tree-from-subversion-and-now-my-build-is-trying-to-use-a-file-directory-that-doesn-t-exist">
+<h3><a class="toc-backref" href="#id13">I’ve updated my source tree from Subversion, and now my build is trying to use a file/directory that doesn’t exist.</a><a class="headerlink" href="#i-ve-updated-my-source-tree-from-subversion-and-now-my-build-is-trying-to-use-a-file-directory-that-doesn-t-exist" title="Permalink to this headline">¶</a></h3>
+<p>You need to re-run configure in your object directory. When new Makefiles
+are added to the source tree, they have to be copied over to the object tree
+in order to be used by the build.</p>
+</div>
+<div class="section" id="i-ve-modified-a-makefile-in-my-source-tree-but-my-build-tree-keeps-using-the-old-version-what-do-i-do">
+<h3><a class="toc-backref" href="#id14">I’ve modified a Makefile in my source tree, but my build tree keeps using the old version. What do I do?</a><a class="headerlink" href="#i-ve-modified-a-makefile-in-my-source-tree-but-my-build-tree-keeps-using-the-old-version-what-do-i-do" title="Permalink to this headline">¶</a></h3>
+<p>If the Makefile already exists in your object tree, you can just run the
+following command in the top level directory of your object tree:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> ./config.status <relative path to Makefile>;
+</pre></div>
+</div>
+<p>If the Makefile is new, you will have to modify the configure script to copy
+it over.</p>
+</div>
+<div class="section" id="i-ve-upgraded-to-a-new-version-of-llvm-and-i-get-strange-build-errors">
+<h3><a class="toc-backref" href="#id15">I’ve upgraded to a new version of LLVM, and I get strange build errors.</a><a class="headerlink" href="#i-ve-upgraded-to-a-new-version-of-llvm-and-i-get-strange-build-errors" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes, changes to the LLVM source code alters how the build system works.
+Changes in <tt class="docutils literal"><span class="pre">libtool</span></tt>, <tt class="docutils literal"><span class="pre">autoconf</span></tt>, or header file dependencies are
+especially prone to this sort of problem.</p>
+<p>The best thing to try is to remove the old files and re-build. In most cases,
+this takes care of the problem. To do this, just type <tt class="docutils literal"><span class="pre">make</span> <span class="pre">clean</span></tt> and then
+<tt class="docutils literal"><span class="pre">make</span></tt> in the directory that fails to build.</p>
+</div>
+<div class="section" id="i-ve-built-llvm-and-am-testing-it-but-the-tests-freeze">
+<h3><a class="toc-backref" href="#id16">I’ve built LLVM and am testing it, but the tests freeze.</a><a class="headerlink" href="#i-ve-built-llvm-and-am-testing-it-but-the-tests-freeze" title="Permalink to this headline">¶</a></h3>
+<p>This is most likely occurring because you built a profile or release
+(optimized) build of LLVM and have not specified the same information on the
+<tt class="docutils literal"><span class="pre">gmake</span></tt> command line.</p>
+<p>For example, if you built LLVM with the command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> gmake <span class="nv">ENABLE_PROFILING</span><span class="o">=</span>1
+</pre></div>
+</div>
+<p>...then you must run the tests with the following commands:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/test
+<span class="gp">%</span> gmake <span class="nv">ENABLE_PROFILING</span><span class="o">=</span>1
+</pre></div>
+</div>
+</div>
+<div class="section" id="why-do-test-results-differ-when-i-perform-different-types-of-builds">
+<h3><a class="toc-backref" href="#id17">Why do test results differ when I perform different types of builds?</a><a class="headerlink" href="#why-do-test-results-differ-when-i-perform-different-types-of-builds" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM test suite is dependent upon several features of the LLVM tools and
+libraries.</p>
+<p>First, the debugging assertions in code are not enabled in optimized or
+profiling builds. Hence, tests that used to fail may pass.</p>
+<p>Second, some tests may rely upon debugging options or behavior that is only
+available in the debug build. These tests will fail in an optimized or
+profile build.</p>
+</div>
+<div class="section" id="compiling-llvm-with-gcc-3-3-2-fails-what-should-i-do">
+<h3><a class="toc-backref" href="#id18">Compiling LLVM with GCC 3.3.2 fails, what should I do?</a><a class="headerlink" href="#compiling-llvm-with-gcc-3-3-2-fails-what-should-i-do" title="Permalink to this headline">¶</a></h3>
+<p>This is <a class="reference external" href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392">a bug in GCC</a>,
+and affects projects other than LLVM. Try upgrading or downgrading your GCC.</p>
+</div>
+<div class="section" id="compiling-llvm-with-gcc-succeeds-but-the-resulting-tools-do-not-work-what-can-be-wrong">
+<h3><a class="toc-backref" href="#id19">Compiling LLVM with GCC succeeds, but the resulting tools do not work, what can be wrong?</a><a class="headerlink" href="#compiling-llvm-with-gcc-succeeds-but-the-resulting-tools-do-not-work-what-can-be-wrong" title="Permalink to this headline">¶</a></h3>
+<p>Several versions of GCC have shown a weakness in miscompiling the LLVM
+codebase. Please consult your compiler version (<tt class="docutils literal"><span class="pre">gcc</span> <span class="pre">--version</span></tt>) to find
+out whether it is <a class="reference external" href="GettingStarted.html#brokengcc">broken</a>. If so, your only
+option is to upgrade GCC to a known good version.</p>
+</div>
+<div class="section" id="after-subversion-update-rebuilding-gives-the-error-no-rule-to-make-target">
+<h3><a class="toc-backref" href="#id20">After Subversion update, rebuilding gives the error “No rule to make target”.</a><a class="headerlink" href="#after-subversion-update-rebuilding-gives-the-error-no-rule-to-make-target" title="Permalink to this headline">¶</a></h3>
+<p>If the error is of the form:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">gmake[2]: *** No rule to make target `/path/to/somefile',</span>
+<span class="go"> needed by `/path/to/another/file.d'.</span>
+<span class="go">Stop.</span>
+</pre></div>
+</div>
+<p>This may occur anytime files are moved within the Subversion repository or
+removed entirely. In this case, the best solution is to erase all <tt class="docutils literal"><span class="pre">.d</span></tt>
+files, which list dependencies for source files, and rebuild:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd</span> <span class="nv">$LLVM_OBJ_DIR</span>
+<span class="gp">%</span> rm -f <span class="sb">`</span>find . -name <span class="se">\*\.</span>d<span class="sb">`</span>
+<span class="gp">%</span> gmake
+</pre></div>
+</div>
+<p>In other cases, it may be necessary to run <tt class="docutils literal"><span class="pre">make</span> <span class="pre">clean</span></tt> before rebuilding.</p>
+</div>
+</div>
+<div class="section" id="source-languages">
+<h2><a class="toc-backref" href="#id21">Source Languages</a><a class="headerlink" href="#source-languages" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-source-languages-are-supported">
+<h3><a class="toc-backref" href="#id22">What source languages are supported?</a><a class="headerlink" href="#what-source-languages-are-supported" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently has full support for C and C++ source languages. These are
+available through both <a class="reference external" href="http://clang.llvm.org/">Clang</a> and <a class="reference external" href="http://dragonegg.llvm.org/">DragonEgg</a>.</p>
+<p>The PyPy developers are working on integrating LLVM into the PyPy backend so
+that PyPy language can translate to LLVM.</p>
+</div>
+<div class="section" id="i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators">
+<h3><a class="toc-backref" href="#id23">I’d like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a><a class="headerlink" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" title="Permalink to this headline">¶</a></h3>
+<p>Your compiler front-end will communicate with LLVM by creating a module in the
+LLVM intermediate representation (IR) format. Assuming you want to write your
+language’s compiler in the language itself (rather than C++), there are 3
+major ways to tackle generating LLVM IR from a front-end:</p>
+<ol class="arabic simple">
+<li><strong>Call into the LLVM libraries code using your language’s FFI (foreign
+function interface).</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc format</li>
+<li><em>for:</em> enables running LLVM optimization passes without a emit/parse
+overhead</li>
+<li><em>for:</em> adapts well to a JIT context</li>
+<li><em>against:</em> lots of ugly glue code to write</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="2">
+<li><strong>Emit LLVM assembly from your compiler’s native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> very straightforward to get started</li>
+<li><em>against:</em> the .ll parser is slower than the bitcode reader when
+interfacing to the middle end</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="3">
+<li><strong>Emit LLVM bitcode from your compiler’s native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> can use the more-efficient bitcode reader when interfacing to the
+middle end</li>
+<li><em>against:</em> you’ll have to re-engineer the LLVM IR object model and bitcode
+writer in your language</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<p>If you go with the first option, the C bindings in include/llvm-c should help
+a lot, since most languages have strong support for interfacing with C. The
+most common hurdle with calling C from managed code is interfacing with the
+garbage collector. The C interface was designed to require very little memory
+management, and so is straightforward in this regard.</p>
+</div>
+<div class="section" id="what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler">
+<h3><a class="toc-backref" href="#id24">What support is there for a higher level source language constructs for building a compiler?</a><a class="headerlink" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" title="Permalink to this headline">¶</a></h3>
+<p>Currently, there isn’t much. LLVM supports an intermediate representation
+which is useful for code representation but will not support the high level
+(abstract syntax tree) representation needed by most compilers. There are no
+facilities for lexical nor semantic analysis.</p>
+</div>
+<div class="section" id="i-don-t-understand-the-getelementptr-instruction-help">
+<h3><a class="toc-backref" href="#id25">I don’t understand the <tt class="docutils literal"><span class="pre">GetElementPtr</span></tt> instruction. Help!</a><a class="headerlink" href="#i-don-t-understand-the-getelementptr-instruction-help" title="Permalink to this headline">¶</a></h3>
+<p>See <a class="reference external" href="GetElementPtr.html">The Often Misunderstood GEP Instruction</a>.</p>
+</div>
+</div>
+<div class="section" id="using-the-c-and-c-front-ends">
+<h2><a class="toc-backref" href="#id26">Using the C and C++ Front Ends</a><a class="headerlink" href="#using-the-c-and-c-front-ends" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode">
+<h3><a class="toc-backref" href="#id27">Can I compile C or C++ code to platform-independent LLVM bitcode?</a><a class="headerlink" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" title="Permalink to this headline">¶</a></h3>
+<p>No. C and C++ are inherently platform-dependent languages. The most obvious
+example of this is the preprocessor. A very common way that C code is made
+portable is by using the preprocessor to include platform-specific code. In
+practice, information about other platforms is lost after preprocessing, so
+the result is inherently dependent on the platform that the preprocessing was
+targeting.</p>
+<p>Another example is <tt class="docutils literal"><span class="pre">sizeof</span></tt>. It’s common for <tt class="docutils literal"><span class="pre">sizeof(long)</span></tt> to vary
+between platforms. In most C front-ends, <tt class="docutils literal"><span class="pre">sizeof</span></tt> is expanded to a
+constant immediately, thus hard-wiring a platform-specific detail.</p>
+<p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
+lower-level than C, front-ends currently must emit platform-specific IR in
+order to have the result conform to the platform ABI.</p>
+</div>
+</div>
+<div class="section" id="questions-about-code-generated-by-the-demo-page">
+<h2><a class="toc-backref" href="#id28">Questions about code generated by the demo page</a><a class="headerlink" href="#questions-about-code-generated-by-the-demo-page" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream">
+<h3><a class="toc-backref" href="#id29">What is this <tt class="docutils literal"><span class="pre">llvm.global_ctors</span></tt> and <tt class="docutils literal"><span class="pre">_GLOBAL__I_a...</span></tt> stuff that happens when I <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt>?</a><a class="headerlink" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" title="Permalink to this headline">¶</a></h3>
+<p>If you <tt class="docutils literal"><span class="pre">#include</span></tt> the <tt class="docutils literal"><span class="pre"><iostream></span></tt> header into a C++ translation unit,
+the file will probably use the <tt class="docutils literal"><span class="pre">std::cin</span></tt>/<tt class="docutils literal"><span class="pre">std::cout</span></tt>/... global objects.
+However, C++ does not guarantee an order of initialization between static
+objects in different translation units, so if a static ctor/dtor in your .cpp
+file used <tt class="docutils literal"><span class="pre">std::cout</span></tt>, for example, the object would not necessarily be
+automatically initialized before your use.</p>
+<p>To make <tt class="docutils literal"><span class="pre">std::cout</span></tt> and friends work correctly in these scenarios, the STL
+that we use declares a static object that gets created in every translation
+unit that includes <tt class="docutils literal"><span class="pre"><iostream></span></tt>. This object has a static constructor
+and destructor that initializes and destroys the global iostream objects
+before they could possibly be used in the file. The code that you see in the
+<tt class="docutils literal"><span class="pre">.ll</span></tt> file corresponds to the constructor and destructor registration code.</p>
+<p>If you would like to make it easier to <em>understand</em> the LLVM code generated
+by the compiler in the demo page, consider using <tt class="docutils literal"><span class="pre">printf()</span></tt> instead of
+<tt class="docutils literal"><span class="pre">iostream</span></tt>s to print values.</p>
+</div>
+<div class="section" id="where-did-all-of-my-code-go">
+<h3><a class="toc-backref" href="#id30">Where did all of my code go??</a><a class="headerlink" href="#where-did-all-of-my-code-go" title="Permalink to this headline">¶</a></h3>
+<p>If you are using the LLVM demo page, you may often wonder what happened to
+all of the code that you typed in. Remember that the demo script is running
+the code through the LLVM optimizers, so if your code doesn’t actually do
+anything useful, it might all be deleted.</p>
+<p>To prevent this, make sure that the code is actually needed. For example, if
+you are computing some expression, return the value from the function instead
+of leaving it in a local variable. If you really want to constrain the
+optimizer, you can read from and assign to <tt class="docutils literal"><span class="pre">volatile</span></tt> global variables.</p>
+</div>
+<div class="section" id="what-is-this-undef-thing-that-shows-up-in-my-code">
+<h3><a class="toc-backref" href="#id31">What is this “<tt class="docutils literal"><span class="pre">undef</span></tt>” thing that shows up in my code?</a><a class="headerlink" href="#what-is-this-undef-thing-that-shows-up-in-my-code" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">undef</span></tt> is the LLVM way of representing a value that is not defined. You
+can get these if you do not initialize a variable before you use it. For
+example, the C function:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">X</span><span class="p">()</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="k">return</span> <span class="n">i</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Is compiled to “<tt class="docutils literal"><span class="pre">ret</span> <span class="pre">i32</span> <span class="pre">undef</span></tt>” because “<tt class="docutils literal"><span class="pre">i</span></tt>” never has a value specified
+for it.</p>
+</div>
+<div class="section" id="why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it">
+<h3><a class="toc-backref" href="#id32">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into “unreachable”? Why not make the verifier reject it?</a><a class="headerlink" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" title="Permalink to this headline">¶</a></h3>
+<p>This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function. For
+example, this code:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</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">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Is optimized to:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</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">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">unreachable</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>... with “<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></tt>”. This often bites people because
+“all their code disappears”. Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not
+make the verifier reject this sort of thing.</p>
+<p>The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesn’t, and there is valid code that can
+create this sort of construct (in dead code). The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Here’s an example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</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="k">internal</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="nv">%FP</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F</span>
+<span class="nl">T:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="nv">%FP</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="nl">F:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="nv">%FP</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">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="vg">@foo</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this example, “test” always passes <tt class="docutils literal"><span class="pre">@foo</span></tt>/<tt class="docutils literal"><span class="pre">false</span></tt> into <tt class="docutils literal"><span class="pre">bar</span></tt>, which
+ensures that it is dynamically called with the right calling conv (thus, the
+code is perfectly well defined). If you run this through the inliner, you
+get this (the explicit “or” is there so that the inliner doesn’t dead code
+eliminate a bunch of stuff):</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</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">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here you can see that the inlining pass made an undefined call to <tt class="docutils literal"><span class="pre">@foo</span></tt>
+with the wrong calling convention. We really don’t want to make the inliner
+have to know about this sort of thing, so it needs to be valid code. In this
+case, dead code elimination can trivially remove the undefined code. However,
+if <tt class="docutils literal"><span class="pre">%X</span></tt> was an input argument to <tt class="docutils literal"><span class="pre">@test</span></tt>, the inliner would produce this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</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">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The interesting thing about this is that <tt class="docutils literal"><span class="pre">%X</span></tt> <em>must</em> be false for the
+code to be well-defined, but no amount of dead code elimination will be able
+to delete the broken call as unreachable. However, since
+<tt class="docutils literal"><span class="pre">instcombine</span></tt>/<tt class="docutils literal"><span class="pre">simplifycfg</span></tt> turns the undefined call into unreachable, we
+end up with a branch on a condition that goes to unreachable: a branch to
+unreachable can never happen, so “<tt class="docutils literal"><span class="pre">-inline</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></tt>” is
+able to produce:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</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">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</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="Lexicon.html" title="The LLVM Lexicon"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/GarbageCollection.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/GarbageCollection.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/GarbageCollection.html (added)
+++ www-releases/trunk/3.4.1/docs/GarbageCollection.html Wed May 7 15:09:32 2014
@@ -0,0 +1,1151 @@
+
+
+<!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>Accurate Garbage Collection with LLVM — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="Writing an LLVM Pass" href="WritingAnLLVMPass.html" />
+ <link rel="prev" title="How To Use Instruction Mappings" href="HowToUseInstrMappings.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="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ 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="accurate-garbage-collection-with-llvm">
+<h1>Accurate Garbage Collection with LLVM<a class="headerlink" href="#accurate-garbage-collection-with-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="id1">Introduction</a><ul>
+<li><a class="reference internal" href="#goals-and-non-goals" id="id2">Goals and non-goals</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#getting-started" id="id3">Getting started</a><ul>
+<li><a class="reference internal" href="#in-your-compiler" id="id4">In your compiler</a></li>
+<li><a class="reference internal" href="#in-your-runtime" id="id5">In your runtime</a></li>
+<li><a class="reference internal" href="#about-the-shadow-stack" id="id6">About the shadow stack</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ir-features" id="id7">IR features</a><ul>
+<li><a class="reference internal" href="#specifying-gc-code-generation-gc" id="id8">Specifying GC code generation: <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"..."</span></tt></a></li>
+<li><a class="reference internal" href="#gcroot" id="id9">Identifying GC roots on the stack: <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt></a></li>
+<li><a class="reference internal" href="#reading-and-writing-references-in-the-heap" id="id10">Reading and writing references in the heap</a><ul>
+<li><a class="reference internal" href="#write-barrier-llvm-gcwrite" id="id11">Write barrier: <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a></li>
+<li><a class="reference internal" href="#read-barrier-llvm-gcread" id="id12">Read barrier: <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#implementing-a-collector-plugin" id="id13">Implementing a collector plugin</a><ul>
+<li><a class="reference internal" href="#overview-of-available-features" id="id14">Overview of available features</a></li>
+<li><a class="reference internal" href="#computing-stack-maps" id="id15">Computing stack maps</a></li>
+<li><a class="reference internal" href="#initializing-roots-to-null-initroots" id="id16">Initializing roots to null: <tt class="docutils literal"><span class="pre">InitRoots</span></tt></a></li>
+<li><a class="reference internal" href="#custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers" id="id17">Custom lowering of intrinsics: <tt class="docutils literal"><span class="pre">CustomRoots</span></tt>, <tt class="docutils literal"><span class="pre">CustomReadBarriers</span></tt>, and <tt class="docutils literal"><span class="pre">CustomWriteBarriers</span></tt></a></li>
+<li><a class="reference internal" href="#generating-safe-points-neededsafepoints" id="id18">Generating safe points: <tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt></a></li>
+<li><a class="reference internal" href="#emitting-assembly-code-gcmetadataprinter" id="id19">Emitting assembly code: <tt class="docutils literal"><span class="pre">GCMetadataPrinter</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#references" id="id20">References</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>Garbage collection is a widely used technique that frees the programmer from
+having to know the lifetimes of heap objects, making software easier to produce
+and maintain. Many programming languages rely on garbage collection for
+automatic memory management. There are two primary forms of garbage collection:
+conservative and accurate.</p>
+<p>Conservative garbage collection often does not require any special support from
+either the language or the compiler: it can handle non-type-safe programming
+languages (such as C/C++) and does not require any special information from the
+compiler. The <a class="reference external" href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm collector</a> is an example of a
+state-of-the-art conservative collector.</p>
+<p>Accurate garbage collection requires the ability to identify all pointers in the
+program at run-time (which requires that the source-language be type-safe in
+most cases). Identifying pointers at run-time requires compiler support to
+locate all places that hold live pointer variables at run-time, including the
+<a class="reference internal" href="#gcroot"><em>processor stack and registers</em></a>.</p>
+<p>Conservative garbage collection is attractive because it does not require any
+special compiler support, but it does have problems. In particular, because the
+conservative garbage collector cannot <em>know</em> that a particular word in the
+machine is a pointer, it cannot move live objects in the heap (preventing the
+use of compacting and generational GC algorithms) and it can occasionally suffer
+from memory leaks due to integer values that happen to point to objects in the
+program. In addition, some aggressive compiler transformations can break
+conservative garbage collectors (though these seem rare in practice).</p>
+<p>Accurate garbage collectors do not suffer from any of these problems, but they
+can suffer from degraded scalar optimization of the program. In particular,
+because the runtime must be able to identify and update all pointers active in
+the program, some optimizations are less effective. In practice, however, the
+locality and performance benefits of using aggressive garbage collection
+techniques dominates any low-level losses.</p>
+<p>This document describes the mechanisms and interfaces provided by LLVM to
+support accurate garbage collection.</p>
+<div class="section" id="goals-and-non-goals">
+<h3><a class="toc-backref" href="#id2">Goals and non-goals</a><a class="headerlink" href="#goals-and-non-goals" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s intermediate representation provides <a class="reference internal" href="#gc-intrinsics"><em>garbage collection intrinsics</em></a> that offer support for a broad class of collector models. For
+instance, the intrinsics permit:</p>
+<ul class="simple">
+<li>semi-space collectors</li>
+<li>mark-sweep collectors</li>
+<li>generational collectors</li>
+<li>reference counting</li>
+<li>incremental collectors</li>
+<li>concurrent collectors</li>
+<li>cooperative collectors</li>
+</ul>
+<p>We hope that the primitive support built into the LLVM IR is sufficient to
+support a broad class of garbage collected languages including Scheme, ML, Java,
+C#, Perl, Python, Lua, Ruby, other scripting languages, and more.</p>
+<p>However, LLVM does not itself provide a garbage collector — this should be
+part of your language’s runtime library. LLVM provides a framework for compile
+time <a class="reference internal" href="#plugin"><em>code generation plugins</em></a>. The role of these plugins is to
+generate code and data structures which conforms to the <em>binary interface</em>
+specified by the <em>runtime library</em>. This is similar to the relationship between
+LLVM and DWARF debugging info, for example. The difference primarily lies in
+the lack of an established standard in the domain of garbage collection — thus
+the plugins.</p>
+<p>The aspects of the binary interface with which LLVM’s GC support is
+concerned are:</p>
+<ul class="simple">
+<li>Creation of GC-safe points within code where collection is allowed to execute
+safely.</li>
+<li>Computation of the stack map. For each safe point in the code, object
+references within the stack frame must be identified so that the collector may
+traverse and perhaps update them.</li>
+<li>Write barriers when storing object references to the heap. These are commonly
+used to optimize incremental scans in generational collectors.</li>
+<li>Emission of read barriers when loading object references. These are useful
+for interoperating with concurrent collectors.</li>
+</ul>
+<p>There are additional areas that LLVM does not directly address:</p>
+<ul class="simple">
+<li>Registration of global roots with the runtime.</li>
+<li>Registration of stack map entries with the runtime.</li>
+<li>The functions used by the program to allocate memory, trigger a collection,
+etc.</li>
+<li>Computation or compilation of type maps, or registration of them with the
+runtime. These are used to crawl the heap for object references.</li>
+</ul>
+<p>In general, LLVM’s support for GC does not include features which can be
+adequately addressed with other features of the IR and does not specify a
+particular binary interface. On the plus side, this means that you should be
+able to integrate LLVM with an existing runtime. On the other hand, it leaves a
+lot of work for the developer of a novel language. However, it’s easy to get
+started quickly and scale up to a more sophisticated implementation as your
+compiler matures.</p>
+</div>
+</div>
+<div class="section" id="getting-started">
+<h2><a class="toc-backref" href="#id3">Getting started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
+<p>Using a GC with LLVM implies many things, for example:</p>
+<ul class="simple">
+<li>Write a runtime library or find an existing one which implements a GC heap.<ol class="arabic">
+<li>Implement a memory allocator.</li>
+<li>Design a binary interface for the stack map, used to identify references
+within a stack frame on the machine stack.*</li>
+<li>Implement a stack crawler to discover functions on the call stack.*</li>
+<li>Implement a registry for global roots.</li>
+<li>Design a binary interface for type maps, used to identify references
+within heap objects.</li>
+<li>Implement a collection routine bringing together all of the above.</li>
+</ol>
+</li>
+<li>Emit compatible code from your compiler.<ul>
+<li>Initialization in the main function.</li>
+<li>Use the <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"..."</span></tt> attribute to enable GC code generation (or
+<tt class="docutils literal"><span class="pre">F.setGC("...")</span></tt>).</li>
+<li>Use <tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> to mark stack roots.</li>
+<li>Use <tt class="docutils literal"><span class="pre">@llvm.gcread</span></tt> and/or <tt class="docutils literal"><span class="pre">@llvm.gcwrite</span></tt> to manipulate GC references,
+if necessary.</li>
+<li>Allocate memory using the GC allocation routine provided by the runtime
+library.</li>
+<li>Generate type maps according to your runtime’s binary interface.</li>
+</ul>
+</li>
+<li>Write a compiler plugin to interface LLVM with the runtime library.*<ul>
+<li>Lower <tt class="docutils literal"><span class="pre">@llvm.gcread</span></tt> and <tt class="docutils literal"><span class="pre">@llvm.gcwrite</span></tt> to appropriate code
+sequences.*</li>
+<li>Compile LLVM’s stack map to the binary form expected by the runtime.</li>
+</ul>
+</li>
+<li>Load the plugin into the compiler. Use <tt class="docutils literal"><span class="pre">llc</span> <span class="pre">-load</span></tt> or link the plugin
+statically with your language’s compiler.*</li>
+<li>Link program executables with the runtime.</li>
+</ul>
+<p>To help with several of these tasks (those indicated with a *), LLVM includes a
+highly portable, built-in ShadowStack code generator. It is compiled into
+<tt class="docutils literal"><span class="pre">llc</span></tt> and works even with the interpreter and C backends.</p>
+<div class="section" id="in-your-compiler">
+<h3><a class="toc-backref" href="#id4">In your compiler</a><a class="headerlink" href="#in-your-compiler" title="Permalink to this headline">¶</a></h3>
+<p>To turn the shadow stack on for your functions, first call:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"shadow-stack"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for each function your compiler emits. Since the shadow stack is built into
+LLVM, you do not need to load a plugin.</p>
+<p>Your compiler must also use <tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> as documented. Don’t forget to
+create a root for each intermediate value that is generated when evaluating an
+expression. In <tt class="docutils literal"><span class="pre">h(f(),</span> <span class="pre">g())</span></tt>, the result of <tt class="docutils literal"><span class="pre">f()</span></tt> could easily be collected
+if evaluating <tt class="docutils literal"><span class="pre">g()</span></tt> triggers a collection.</p>
+<p>There’s no need to use <tt class="docutils literal"><span class="pre">@llvm.gcread</span></tt> and <tt class="docutils literal"><span class="pre">@llvm.gcwrite</span></tt> over plain
+<tt class="docutils literal"><span class="pre">load</span></tt> and <tt class="docutils literal"><span class="pre">store</span></tt> for now. You will need them when switching to a more
+advanced GC.</p>
+</div>
+<div class="section" id="in-your-runtime">
+<h3><a class="toc-backref" href="#id5">In your runtime</a><a class="headerlink" href="#in-your-runtime" title="Permalink to this headline">¶</a></h3>
+<p>The shadow stack doesn’t imply a memory allocation algorithm. A semispace
+collector or building atop <tt class="docutils literal"><span class="pre">malloc</span></tt> are great places to start, and can be
+implemented with very little code.</p>
+<p>When it comes time to collect, however, your runtime needs to traverse the stack
+roots, and for this it needs to integrate with the shadow stack. Luckily, doing
+so is very simple. (This code is heavily commented to help you understand the
+data structure, but there are only 20 lines of meaningful code.)</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">/// @brief The map for a single function's stack frame. One of these is</span>
+<span class="c1">/// compiled as constant data into the executable for each function.</span>
+<span class="c1">///</span>
+<span class="c1">/// Storage of metadata values is elided if the %metadata parameter to</span>
+<span class="c1">/// @llvm.gcroot is null.</span>
+<span class="k">struct</span> <span class="n">FrameMap</span> <span class="p">{</span>
+ <span class="kt">int32_t</span> <span class="n">NumRoots</span><span class="p">;</span> <span class="c1">//< Number of roots in stack frame.</span>
+ <span class="kt">int32_t</span> <span class="n">NumMeta</span><span class="p">;</span> <span class="c1">//< Number of metadata entries. May be < NumRoots.</span>
+ <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">//< Metadata for each root.</span>
+<span class="p">};</span>
+
+<span class="c1">/// @brief A link in the dynamic shadow stack. One of these is embedded in</span>
+<span class="c1">/// the stack frame of each function on the call stack.</span>
+<span class="k">struct</span> <span class="n">StackEntry</span> <span class="p">{</span>
+ <span class="n">StackEntry</span> <span class="o">*</span><span class="n">Next</span><span class="p">;</span> <span class="c1">//< Link to next stack entry (the caller's).</span>
+ <span class="k">const</span> <span class="n">FrameMap</span> <span class="o">*</span><span class="n">Map</span><span class="p">;</span> <span class="c1">//< Pointer to constant FrameMap.</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">Roots</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">//< Stack roots (in-place array).</span>
+<span class="p">};</span>
+
+<span class="c1">/// @brief The head of the singly-linked list of StackEntries. Functions push</span>
+<span class="c1">/// and pop onto this in their prologue and epilogue.</span>
+<span class="c1">///</span>
+<span class="c1">/// Since there is only a global list, this technique is not threadsafe.</span>
+<span class="n">StackEntry</span> <span class="o">*</span><span class="n">llvm_gc_root_chain</span><span class="p">;</span>
+
+<span class="c1">/// @brief Calls Visitor(root, meta) for each GC root on the stack.</span>
+<span class="c1">/// root and meta are exactly the values passed to</span>
+<span class="c1">/// @llvm.gcroot.</span>
+<span class="c1">///</span>
+<span class="c1">/// Visitor could be a function to recursively mark live objects. Or it</span>
+<span class="c1">/// might copy them to another heap or generation.</span>
+<span class="c1">///</span>
+<span class="c1">/// @param Visitor A function to invoke for every GC root on the stack.</span>
+<span class="kt">void</span> <span class="nf">visitGCRoots</span><span class="p">(</span><span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">Visitor</span><span class="p">)(</span><span class="kt">void</span> <span class="o">**</span><span class="n">Root</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">StackEntry</span> <span class="o">*</span><span class="n">R</span> <span class="o">=</span> <span class="n">llvm_gc_root_chain</span><span class="p">;</span> <span class="n">R</span><span class="p">;</span> <span class="n">R</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Next</span><span class="p">)</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="c1">// For roots [0, NumMeta), the metadata pointer is in the FrameMap.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumMeta</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="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">Meta</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+
+ <span class="c1">// For roots [NumMeta, NumRoots), the metadata pointer is null.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumRoots</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="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="nb">NULL</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="about-the-shadow-stack">
+<h3><a class="toc-backref" href="#id6">About the shadow stack</a><a class="headerlink" href="#about-the-shadow-stack" title="Permalink to this headline">¶</a></h3>
+<p>Unlike many GC algorithms which rely on a cooperative code generator to compile
+stack maps, this algorithm carefully maintains a linked list of stack roots
+[<a class="reference internal" href="#henderson02"><em>Henderson2002</em></a>]. This so-called “shadow stack” mirrors the
+machine stack. Maintaining this data structure is slower than using a stack map
+compiled into the executable as constant data, but has a significant portability
+advantage because it requires no special support from the target code generator,
+and does not require tricky platform-specific code to crawl the machine stack.</p>
+<p>The tradeoff for this simplicity and portability is:</p>
+<ul class="simple">
+<li>High overhead per function call.</li>
+<li>Not thread-safe.</li>
+</ul>
+<p>Still, it’s an easy way to get started. After your compiler and runtime are up
+and running, writing a <a class="reference internal" href="#plugin"><em>plugin</em></a> will allow you to take advantage
+of <a class="reference internal" href="#collector-algos"><em>more advanced GC features</em></a> of LLVM in order to
+improve performance.</p>
+</div>
+</div>
+<div class="section" id="ir-features">
+<span id="gc-intrinsics"></span><h2><a class="toc-backref" href="#id7">IR features</a><a class="headerlink" href="#ir-features" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the garbage collection facilities provided by the
+<a class="reference internal" href="LangRef.html"><em>LLVM intermediate representation</em></a>. The exact behavior of these
+IR features is specified by the binary interface implemented by a <a class="reference internal" href="#plugin"><em>code
+generation plugin</em></a>, not by this document.</p>
+<p>These facilities are limited to those strictly necessary; they are not intended
+to be a complete interface to any garbage collector. A program will need to
+interface with the GC library using the facilities provided by that program.</p>
+<div class="section" id="specifying-gc-code-generation-gc">
+<h3><a class="toc-backref" href="#id8">Specifying GC code generation: <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"..."</span></tt></a><a class="headerlink" href="#specifying-gc-code-generation-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><pre>define ty @name(...) gc "name" { ...</pre>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">gc</span></tt> function attribute is used to specify the desired GC style to the
+compiler. Its programmatic equivalent is the <tt class="docutils literal"><span class="pre">setGC</span></tt> method of <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+<p>Setting <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"name"</span></tt> on a function triggers a search for a matching code
+generation plugin “<em>name</em>”; it is that plugin which defines the exact nature of
+the code generated to support GC. If none is found, the compiler will raise an
+error.</p>
+<p>Specifying the GC style on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms (or none at all).</p>
+</div>
+<div class="section" id="gcroot">
+<span id="identifying-gc-roots-on-the-stack-llvm-gcroot"></span><h3><a class="toc-backref" href="#id9">Identifying GC roots on the stack: <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt></a><a class="headerlink" href="#gcroot" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%ptrloc</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> intrinsic is used to inform LLVM that a stack variable
+references an object on the heap and is to be tracked for garbage collection.
+The exact impact on generated code is specified by a <a class="reference internal" href="#plugin"><em>compiler plugin</em></a>. All calls to <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> <strong>must</strong> reside inside the first basic
+block.</p>
+<p>A compiler which uses mem2reg to raise imperative code using <tt class="docutils literal"><span class="pre">alloca</span></tt> into SSA
+form need only add a call to <tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> for those variables which a
+pointers into the GC heap.</p>
+<p>It is also important to mark intermediate values with <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt>. For
+example, consider <tt class="docutils literal"><span class="pre">h(f(),</span> <span class="pre">g())</span></tt>. Beware leaking the result of <tt class="docutils literal"><span class="pre">f()</span></tt> in the
+case that <tt class="docutils literal"><span class="pre">g()</span></tt> triggers a collection. Note, that stack variables must be
+initialized and marked with <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> in function’s prologue.</p>
+<p>The first argument <strong>must</strong> be a value referring to an alloca instruction or a
+bitcast of an alloca. The second contains a pointer to metadata that should be
+associated with the pointer, and <strong>must</strong> be a constant or global value
+address. If your target collector uses tags, use a null pointer for metadata.</p>
+<p>The <tt class="docutils literal"><span class="pre">%metadata</span></tt> argument can be used to avoid requiring heap objects to have
+‘isa’ pointers or tag bits. [<a class="reference internal" href="#appel89">Appel89</a>, <a class="reference internal" href="#goldberg91">Goldberg91</a>, <a class="reference internal" href="#tolmach94">Tolmach94</a>] If specified,
+its value will be tracked along with the location of the pointer in the stack
+frame.</p>
+<p>Consider the following fragment of Java code:</p>
+<div class="highlight-java"><div class="highlight"><pre><span class="o">{</span>
+ <span class="n">Object</span> <span class="n">X</span><span class="o">;</span> <span class="c1">// A null-initialized reference to an object</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+</div>
+<p>This block (which may be located in the middle of a function or in a loop nest),
+could be compiled to this LLVM code:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nl">Entry:</span>
+ <span class="c">;; In the entry block for the function, allocate the</span>
+ <span class="c">;; stack space for X, which is an LLVM pointer.</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="nv">%Object</span><span class="p">*</span>
+
+ <span class="c">;; Tell LLVM that the stack space is a stack root.</span>
+ <span class="c">;; Java has type-tags on objects, so we pass null as metadata.</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span> <span class="k">to</span> <span class="k">i8</span><span class="p">**</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%tmp</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="k">null</span><span class="p">)</span>
+ <span class="p">...</span>
+
+ <span class="c">;; "CodeBlock" is the block corresponding to the start</span>
+ <span class="c">;; of the scope above.</span>
+<span class="nl">CodeBlock:</span>
+ <span class="c">;; Java null-initializes pointers.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+
+ <span class="p">...</span>
+
+ <span class="c">;; As the pointer goes out of scope, store a null value into</span>
+ <span class="c">;; it, to indicate that the value is no longer live.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="reading-and-writing-references-in-the-heap">
+<h3><a class="toc-backref" href="#id10">Reading and writing references in the heap</a><a class="headerlink" href="#reading-and-writing-references-in-the-heap" title="Permalink to this headline">¶</a></h3>
+<p>Some collectors need to be informed when the mutator (the program that needs
+garbage collection) either reads a pointer from or writes a pointer to a field
+of a heap object. The code fragments inserted at these points are called <em>read
+barriers</em> and <em>write barriers</em>, respectively. The amount of code that needs to
+be executed is usually quite small and not on the critical path of any
+computation, so the overall performance impact of the barrier is tolerable.</p>
+<p>Barriers often require access to the <em>object pointer</em> rather than the <em>derived
+pointer</em> (which is a pointer to the field within the object). Accordingly,
+these intrinsics take both pointers as separate arguments for completeness. In
+this snippet, <tt class="docutils literal"><span class="pre">%object</span></tt> is the object pointer, and <tt class="docutils literal"><span class="pre">%derived</span></tt> is the derived
+pointer:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;; An array type.</span>
+<span class="nv">%class.Array</span> <span class="p">=</span> <span class="k">type</span> <span class="p">{</span> <span class="nv">%class.Object</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">[</span><span class="m">0</span> <span class="k">x</span> <span class="nv">%class.Object</span><span class="p">*]</span> <span class="p">}</span>
+<span class="p">...</span>
+
+<span class="c">;; Load the object pointer from a gcroot.</span>
+<span class="nv">%object</span> <span class="p">=</span> <span class="k">load</span> <span class="nv">%class.Array</span><span class="p">**</span> <span class="nv">%object_addr</span>
+
+<span class="c">;; Compute the derived pointer.</span>
+<span class="nv">%derived</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%object</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">i32</span> <span class="nv">%n</span>
+</pre></div>
+</div>
+<p>LLVM does not enforce this relationship between the object and derived pointer
+(although a <a class="reference internal" href="#plugin"><em>plugin</em></a> might). However, it would be an unusual
+collector that violated it.</p>
+<p>The use of these intrinsics is naturally optional if the target GC does require
+the corresponding barrier. Such a GC plugin will replace the intrinsic calls
+with the corresponding <tt class="docutils literal"><span class="pre">load</span></tt> or <tt class="docutils literal"><span class="pre">store</span></tt> instruction if they are used.</p>
+<div class="section" id="write-barrier-llvm-gcwrite">
+<h4><a class="toc-backref" href="#id11">Write barrier: <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a><a class="headerlink" href="#write-barrier-llvm-gcwrite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.gcwrite</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%value</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For write barriers, LLVM provides the <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt> intrinsic function. It
+has exactly the same semantics as a non-volatile <tt class="docutils literal"><span class="pre">store</span></tt> to the derived
+pointer (the third argument). The exact code generated is specified by a
+compiler <a class="reference internal" href="#plugin"><em>plugin</em></a>.</p>
+<p>Many important algorithms require write barriers, including generational and
+concurrent collectors. Additionally, write barriers could be used to implement
+reference counting.</p>
+</div>
+<div class="section" id="read-barrier-llvm-gcread">
+<h4><a class="toc-backref" href="#id12">Read barrier: <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt></a><a class="headerlink" href="#read-barrier-llvm-gcread" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.gcread</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For read barriers, LLVM provides the <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt> intrinsic function. It has
+exactly the same semantics as a non-volatile <tt class="docutils literal"><span class="pre">load</span></tt> from the derived pointer
+(the second argument). The exact code generated is specified by a
+<a class="reference internal" href="#plugin"><em>compiler plugin</em></a>.</p>
+<p>Read barriers are needed by fewer algorithms than write barriers, and may have a
+greater performance impact since pointer reads are more frequent than writes.</p>
+</div>
+</div>
+</div>
+<div class="section" id="implementing-a-collector-plugin">
+<span id="plugin"></span><h2><a class="toc-backref" href="#id13">Implementing a collector plugin</a><a class="headerlink" href="#implementing-a-collector-plugin" title="Permalink to this headline">¶</a></h2>
+<p>User code specifies which GC code generation to use with the <tt class="docutils literal"><span class="pre">gc</span></tt> function
+attribute or, equivalently, with the <tt class="docutils literal"><span class="pre">setGC</span></tt> method of <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+<p>To implement a GC plugin, it is necessary to subclass <tt class="docutils literal"><span class="pre">llvm::GCStrategy</span></tt>,
+which can be accomplished in a few lines of boilerplate code. LLVM’s
+infrastructure provides access to several important algorithms. For an
+uncontroversial collector, all that remains may be to compile LLVM’s computed
+stack map to assembly code (using the binary representation expected by the
+runtime library). This can be accomplished in about 100 lines of code.</p>
+<p>This is not the appropriate place to implement a garbage collected heap or a
+garbage collector itself. That code should exist in the language’s runtime
+library. The compiler plugin is responsible for generating code which conforms
+to the binary interface defined by library, most essentially the <a class="reference internal" href="#stack-map"><em>stack map</em></a>.</p>
+<p>To subclass <tt class="docutils literal"><span class="pre">llvm::GCStrategy</span></tt> and register it with the compiler:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// lib/MyGC/MyGC.cpp - Example LLVM GC plugin</span>
+
+<span class="cp">#include "llvm/CodeGen/GCStrategy.h"</span>
+<span class="cp">#include "llvm/CodeGen/GCMetadata.h"</span>
+<span class="cp">#include "llvm/Support/Compiler.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="n">MyGC</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCStrategy</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+ <span class="n">MyGC</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="p">};</span>
+
+ <span class="n">GCRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGC</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This boilerplate collector does nothing. More specifically:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">llvm.gcread</span></tt> calls are replaced with the corresponding <tt class="docutils literal"><span class="pre">load</span></tt>
+instruction.</li>
+<li><tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt> calls are replaced with the corresponding <tt class="docutils literal"><span class="pre">store</span></tt>
+instruction.</li>
+<li>No safe points are added to the code.</li>
+<li>The stack map is not compiled into the executable.</li>
+</ul>
+<p>Using the LLVM makefiles (like the <a class="reference external" href="http://llvm.org/viewvc/llvm-project/llvm/trunk/projects/sample/">sample project</a>), this code
+can be compiled as a plugin using a simple makefile:</p>
+<div class="highlight-make"><div class="highlight"><pre><span class="c"># lib/MyGC/Makefile</span>
+
+<span class="nv">LEVEL</span> <span class="o">:=</span> ../..
+<span class="nv">LIBRARYNAME</span> <span class="o">=</span> MyGC
+<span class="nv">LOADABLE_MODULE</span> <span class="o">=</span> 1
+
+<span class="cp">include $(LEVEL)/Makefile.common</span>
+</pre></div>
+</div>
+<p>Once the plugin is compiled, code using it may be compiled using <tt class="docutils literal"><span class="pre">llc</span>
+<span class="pre">-load=MyGC.so</span></tt> (though MyGC.so may have some other platform-specific
+extension):</p>
+<div class="highlight-python"><pre>$ cat sample.ll
+define void @f() gc "mygc" {
+entry:
+ ret void
+}
+$ llvm-as < sample.ll | llc -load=MyGC.so</pre>
+</div>
+<p>It is also possible to statically link the collector plugin into tools, such as
+a language-specific compiler front-end.</p>
+<div class="section" id="overview-of-available-features">
+<span id="collector-algos"></span><h3><a class="toc-backref" href="#id14">Overview of available features</a><a class="headerlink" href="#overview-of-available-features" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">GCStrategy</span></tt> provides a range of features through which a plugin may do useful
+work. Some of these are callbacks, some are algorithms that can be enabled,
+disabled, or customized. This matrix summarizes the supported (and planned)
+features and correlates them with the collection techniques which typically
+require them.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="14%" />
+<col width="7%" />
+<col width="9%" />
+<col width="11%" />
+<col width="8%" />
+<col width="10%" />
+<col width="15%" />
+<col width="11%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Algorithm</th>
+<th class="head">Done</th>
+<th class="head">Shadow
+stack</th>
+<th class="head">refcount</th>
+<th class="head">mark-
+sweep</th>
+<th class="head">copying</th>
+<th class="head">incremental</th>
+<th class="head">threaded</th>
+<th class="head">concurrent</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>stack map</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>initialize
+roots</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>derived
+pointers</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong>*</td>
+<td><strong>N</strong>*</td>
+</tr>
+<tr class="row-odd"><td><strong>custom
+lowering</strong></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>gcroot</em></td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-odd"><td><em>gcwrite</em></td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>gcread</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><strong>safe
+points</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>in
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>before
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>for
+loops</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><em>before
+escape</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>emit code
+at safe
+points</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><strong>output</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>assembly</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>JIT</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td><em>obj</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td>live
+analysis</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td>register
+map</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td colspan="9">* Derived pointers only pose a hasard to copying collections.</td>
+</tr>
+<tr class="row-even"><td colspan="9"><strong>?</strong> denotes a feature which could be utilized if available.</td>
+</tr>
+</tbody>
+</table>
+<p>To be clear, the collection techniques above are defined as:</p>
+<dl class="docutils">
+<dt>Shadow Stack</dt>
+<dd>The mutator carefully maintains a linked list of stack roots.</dd>
+<dt>Reference Counting</dt>
+<dd>The mutator maintains a reference count for each object and frees an object
+when its count falls to zero.</dd>
+<dt>Mark-Sweep</dt>
+<dd>When the heap is exhausted, the collector marks reachable objects starting
+from the roots, then deallocates unreachable objects in a sweep phase.</dd>
+<dt>Copying</dt>
+<dd>As reachability analysis proceeds, the collector copies objects from one heap
+area to another, compacting them in the process. Copying collectors enable
+highly efficient “bump pointer” allocation and can improve locality of
+reference.</dd>
+<dt>Incremental</dt>
+<dd>(Including generational collectors.) Incremental collectors generally have all
+the properties of a copying collector (regardless of whether the mature heap
+is compacting), but bring the added complexity of requiring write barriers.</dd>
+<dt>Threaded</dt>
+<dd>Denotes a multithreaded mutator; the collector must still stop the mutator
+(“stop the world”) before beginning reachability analysis. Stopping a
+multithreaded mutator is a complicated problem. It generally requires highly
+platform specific code in the runtime, and the production of carefully
+designed machine code at safe points.</dd>
+<dt>Concurrent</dt>
+<dd>In this technique, the mutator and the collector run concurrently, with the
+goal of eliminating pause times. In a <em>cooperative</em> collector, the mutator
+further aids with collection should a pause occur, allowing collection to take
+advantage of multiprocessor hosts. The “stop the world” problem of threaded
+collectors is generally still present to a limited extent. Sophisticated
+marking algorithms are necessary. Read barriers may be necessary.</dd>
+</dl>
+<p>As the matrix indicates, LLVM’s garbage collection infrastructure is already
+suitable for a wide variety of collectors, but does not currently extend to
+multithreaded programs. This will be added in the future as there is
+interest.</p>
+</div>
+<div class="section" id="computing-stack-maps">
+<span id="stack-map"></span><h3><a class="toc-backref" href="#id15">Computing stack maps</a><a class="headerlink" href="#computing-stack-maps" title="Permalink to this headline">¶</a></h3>
+<p>LLVM automatically computes a stack map. One of the most important features
+of a <tt class="docutils literal"><span class="pre">GCStrategy</span></tt> is to compile this information into the executable in
+the binary representation expected by the runtime library.</p>
+<p>The stack map consists of the location and identity of each GC root in the
+each function in the module. For each root:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">RootNum</span></tt>: The index of the root.</li>
+<li><tt class="docutils literal"><span class="pre">StackOffset</span></tt>: The offset of the object relative to the frame pointer.</li>
+<li><tt class="docutils literal"><span class="pre">RootMetadata</span></tt>: The value passed as the <tt class="docutils literal"><span class="pre">%metadata</span></tt> parameter to the
+<tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> intrinsic.</li>
+</ul>
+<p>Also, for the function as a whole:</p>
+<ul>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal"><span class="pre">getFrameSize()</span></tt>: The overall size of the function’s initial stack frame,</dt>
+<dd><p class="first last">not accounting for any dynamic allocation.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">roots_size()</span></tt>: The count of roots in the function.</p>
+</li>
+</ul>
+<p>To access the stack map, use <tt class="docutils literal"><span class="pre">GCFunctionMetadata::roots_begin()</span></tt> and
+-<tt class="docutils literal"><span class="pre">end()</span></tt> from the <a class="reference internal" href="#assembly"><em>GCMetadataPrinter</em></a>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">I</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">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">GCFunctionInfo</span> <span class="o">*</span><span class="n">FI</span> <span class="o">=</span> <span class="o">*</span><span class="n">I</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">FrameSize</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">getFrameSize</span><span class="p">();</span>
+ <span class="kt">size_t</span> <span class="n">RootCount</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_size</span><span class="p">();</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">roots_iterator</span> <span class="n">RI</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_begin</span><span class="p">(),</span>
+ <span class="n">RE</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_end</span><span class="p">();</span>
+ <span class="n">RI</span> <span class="o">!=</span> <span class="n">RE</span><span class="p">;</span> <span class="o">++</span><span class="n">RI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">RootNum</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Num</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">RootStackOffset</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">;</span>
+ <span class="n">Constant</span> <span class="o">*</span><span class="n">RootMetadata</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Metadata</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> intrinsic is eliminated before code generation by a
+custom lowering pass, LLVM will compute an empty stack map. This may be useful
+for collector plugins which implement reference counting or a shadow stack.</p>
+</div>
+<div class="section" id="initializing-roots-to-null-initroots">
+<span id="init-roots"></span><h3><a class="toc-backref" href="#id16">Initializing roots to null: <tt class="docutils literal"><span class="pre">InitRoots</span></tt></a><a class="headerlink" href="#initializing-roots-to-null-initroots" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">InitRoots</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>When set, LLVM will automatically initialize each root to <tt class="docutils literal"><span class="pre">null</span></tt> upon entry to
+the function. This prevents the GC’s sweep phase from visiting uninitialized
+pointers, which will almost certainly cause it to crash. This initialization
+occurs before custom lowering, so the two may be used together.</p>
+<p>Since LLVM does not yet compute liveness information, there is no means of
+distinguishing an uninitialized stack root from an initialized one. Therefore,
+this feature should be used by all GC plugins. It is enabled by default.</p>
+</div>
+<div class="section" id="custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers">
+<h3><a class="toc-backref" href="#id17">Custom lowering of intrinsics: <tt class="docutils literal"><span class="pre">CustomRoots</span></tt>, <tt class="docutils literal"><span class="pre">CustomReadBarriers</span></tt>, and <tt class="docutils literal"><span class="pre">CustomWriteBarriers</span></tt></a><a class="headerlink" href="#custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers" title="Permalink to this headline">¶</a></h3>
+<p>For GCs which use barriers or unusual treatment of stack roots, these flags
+allow the collector to perform arbitrary transformations of the LLVM IR:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyGC</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCStrategy</span> <span class="p">{</span>
+<span class="nl">public:</span>
+ <span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">CustomRoots</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+ <span class="n">CustomReadBarriers</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+ <span class="n">CustomWriteBarriers</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="n">initializeCustomLowering</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">performCustomLowering</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>If any of these flags are set, then LLVM suppresses its default lowering for the
+corresponding intrinsics and instead calls <tt class="docutils literal"><span class="pre">performCustomLowering</span></tt>.</p>
+<p>LLVM’s default action for each intrinsic is as follows:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt>: Leave it alone. The code generator must see it or the stack
+map will not be computed.</li>
+<li><tt class="docutils literal"><span class="pre">llvm.gcread</span></tt>: Substitute a <tt class="docutils literal"><span class="pre">load</span></tt> instruction.</li>
+<li><tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt>: Substitute a <tt class="docutils literal"><span class="pre">store</span></tt> instruction.</li>
+</ul>
+<p>If <tt class="docutils literal"><span class="pre">CustomReadBarriers</span></tt> or <tt class="docutils literal"><span class="pre">CustomWriteBarriers</span></tt> are specified, then
+<tt class="docutils literal"><span class="pre">performCustomLowering</span></tt> <strong>must</strong> eliminate the corresponding barriers.</p>
+<p><tt class="docutils literal"><span class="pre">performCustomLowering</span></tt> must comply with the same restrictions as
+<a class="reference internal" href="WritingAnLLVMPass.html#writing-an-llvm-pass-runonfunction"><em>FunctionPass::runOnFunction</em></a>
+Likewise, <tt class="docutils literal"><span class="pre">initializeCustomLowering</span></tt> has the same semantics as
+<a class="reference internal" href="WritingAnLLVMPass.html#writing-an-llvm-pass-doinitialization-mod"><em>Pass::doInitialization(Module&)</em></a></p>
+<p>The following can be used as a template:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/IR/Module.h"</span>
+<span class="cp">#include "llvm/IR/IntrinsicInst.h"</span>
+
+<span class="kt">bool</span> <span class="n">MyGC</span><span class="o">::</span><span class="n">initializeCustomLowering</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">bool</span> <span class="n">MyGC</span><span class="o">::</span><span class="n">performCustomLowering</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">MadeChange</span> <span class="o">=</span> <span class="nb">false</span><span class="p">;</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">Function</span><span class="o">::</span><span class="n">iterator</span> <span class="n">BB</span> <span class="o">=</span> <span class="n">F</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">F</span><span class="p">.</span><span class="n">end</span><span class="p">();</span> <span class="n">BB</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">BB</span><span class="p">)</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">BasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">II</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">II</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">IntrinsicInst</span> <span class="o">*</span><span class="n">CI</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">IntrinsicInst</span><span class="o">></span><span class="p">(</span><span class="n">II</span><span class="o">++</span><span class="p">))</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Function</span> <span class="o">*</span><span class="n">F</span> <span class="o">=</span> <span class="n">CI</span><span class="o">-></span><span class="n">getCalledFunction</span><span class="p">())</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">F</span><span class="o">-></span><span class="n">getIntrinsicID</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">Intrinsic</span>:<span class="o">:</span><span class="n">gcwrite</span><span class="o">:</span>
+ <span class="c1">// Handle llvm.gcwrite.</span>
+ <span class="n">CI</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+ <span class="n">MadeChange</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">Intrinsic</span>:<span class="o">:</span><span class="n">gcread</span><span class="o">:</span>
+ <span class="c1">// Handle llvm.gcread.</span>
+ <span class="n">CI</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+ <span class="n">MadeChange</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">Intrinsic</span>:<span class="o">:</span><span class="n">gcroot</span><span class="o">:</span>
+ <span class="c1">// Handle llvm.gcroot.</span>
+ <span class="n">CI</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+ <span class="n">MadeChange</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="n">MadeChange</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="generating-safe-points-neededsafepoints">
+<span id="safe-points"></span><h3><a class="toc-backref" href="#id18">Generating safe points: <tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt></a><a class="headerlink" href="#generating-safe-points-neededsafepoints" title="Permalink to this headline">¶</a></h3>
+<p>LLVM can compute four kinds of safe points:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">GC</span> <span class="p">{</span>
+ <span class="c1">/// PointKind - The type of a collector-safe point.</span>
+ <span class="c1">///</span>
+ <span class="k">enum</span> <span class="n">PointKind</span> <span class="p">{</span>
+ <span class="n">Loop</span><span class="p">,</span> <span class="c1">//< Instr is a loop (backwards branch).</span>
+ <span class="n">Return</span><span class="p">,</span> <span class="c1">//< Instr is a return instruction.</span>
+ <span class="n">PreCall</span><span class="p">,</span> <span class="c1">//< Instr is a call instruction.</span>
+ <span class="n">PostCall</span> <span class="c1">//< Instr is the return address of a call.</span>
+ <span class="p">};</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A collector can request any combination of the four by setting the
+<tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt> mask:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">NeededSafePoints</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">Loop</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">Return</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">PreCall</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">PostCall</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It can then use the following routines to access safe points.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">I</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">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">GCFunctionInfo</span> <span class="o">*</span><span class="n">MD</span> <span class="o">=</span> <span class="o">*</span><span class="n">I</span><span class="p">;</span>
+ <span class="kt">size_t</span> <span class="n">PointCount</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">size</span><span class="p">();</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span>
+ <span class="n">PE</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">PE</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GC</span><span class="o">::</span><span class="n">PointKind</span> <span class="n">PointKind</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Kind</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">PointNum</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Num</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Almost every collector requires <tt class="docutils literal"><span class="pre">PostCall</span></tt> safe points, since these correspond
+to the moments when the function is suspended during a call to a subroutine.</p>
+<p>Threaded programs generally require <tt class="docutils literal"><span class="pre">Loop</span></tt> safe points to guarantee that the
+application will reach a safe point within a bounded amount of time, even if it
+is executing a long-running loop which contains no function calls.</p>
+<p>Threaded collectors may also require <tt class="docutils literal"><span class="pre">Return</span></tt> and <tt class="docutils literal"><span class="pre">PreCall</span></tt> safe points to
+implement “stop the world” techniques using self-modifying code, where it is
+important that the program not exit the function without reaching a safe point
+(because only the topmost function has been patched).</p>
+</div>
+<div class="section" id="emitting-assembly-code-gcmetadataprinter">
+<span id="assembly"></span><h3><a class="toc-backref" href="#id19">Emitting assembly code: <tt class="docutils literal"><span class="pre">GCMetadataPrinter</span></tt></a><a class="headerlink" href="#emitting-assembly-code-gcmetadataprinter" title="Permalink to this headline">¶</a></h3>
+<p>LLVM allows a plugin to print arbitrary assembly code before and after the rest
+of a module’s assembly code. At the end of the module, the GC can compile the
+LLVM stack map into assembly code. (At the beginning, this information is not
+yet computed.)</p>
+<p>Since AsmWriter and CodeGen are separate components of LLVM, a separate abstract
+base class and registry is provided for printing assembly code, the
+<tt class="docutils literal"><span class="pre">GCMetadaPrinter</span></tt> and <tt class="docutils literal"><span class="pre">GCMetadataPrinterRegistry</span></tt>. The AsmWriter will look
+for such a subclass if the <tt class="docutils literal"><span class="pre">GCStrategy</span></tt> sets <tt class="docutils literal"><span class="pre">UsesMetadata</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">UsesMetadata</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This separation allows JIT-only clients to be smaller.</p>
+<p>Note that LLVM does not currently have analogous APIs to support code generation
+in the JIT, nor using the object writers.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// lib/MyGC/MyGCPrinter.cpp - Example LLVM GC printer</span>
+
+<span class="cp">#include "llvm/CodeGen/GCMetadataPrinter.h"</span>
+<span class="cp">#include "llvm/Support/Compiler.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="n">MyGCPrinter</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCMetadataPrinter</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+ <span class="p">};</span>
+
+ <span class="n">GCMetadataPrinterRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGCPrinter</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The collector should use <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> to print portable assembly code. The
+collector itself contains the stack map for the entire module, and may access
+the <tt class="docutils literal"><span class="pre">GCFunctionInfo</span></tt> using its own <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> methods. Here’s
+a realistic example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/AsmPrinter.h"</span>
+<span class="cp">#include "llvm/IR/Function.h"</span>
+<span class="cp">#include "llvm/IR/DataLayout.h"</span>
+<span class="cp">#include "llvm/Target/TargetAsmInfo.h"</span>
+<span class="cp">#include "llvm/Target/TargetMachine.h"</span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Nothing to do.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MCStreamer</span> <span class="o">&</span><span class="n">OS</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">OutStreamer</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">IntPtrSize</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">TM</span><span class="p">.</span><span class="n">getDataLayout</span><span class="p">()</span><span class="o">-></span><span class="n">getPointerSize</span><span class="p">();</span>
+
+ <span class="c1">// Put this in the data section.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">SwitchSection</span><span class="p">(</span><span class="n">AP</span><span class="p">.</span><span class="n">getObjFileLowering</span><span class="p">().</span><span class="n">getDataSection</span><span class="p">());</span>
+
+ <span class="c1">// For each function...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">FI</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">FE</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">FI</span> <span class="o">!=</span> <span class="n">FE</span><span class="p">;</span> <span class="o">++</span><span class="n">FI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">&</span><span class="n">MD</span> <span class="o">=</span> <span class="o">**</span><span class="n">FI</span><span class="p">;</span>
+
+ <span class="c1">// A compact GC layout. Emit this data structure:</span>
+ <span class="c1">//</span>
+ <span class="c1">// struct {</span>
+ <span class="c1">// int32_t PointCount;</span>
+ <span class="c1">// void *SafePointAddress[PointCount];</span>
+ <span class="c1">// int32_t StackFrameSize; // in words</span>
+ <span class="c1">// int32_t StackArity;</span>
+ <span class="c1">// int32_t LiveCount;</span>
+ <span class="c1">// int32_t LiveOffsets[LiveCount];</span>
+ <span class="c1">// } __gcmap_<FUNCTIONNAME>;</span>
+
+ <span class="c1">// Align to address width.</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitAlignment</span><span class="p">(</span><span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">2</span> <span class="o">:</span> <span class="mi">3</span><span class="p">);</span>
+
+ <span class="c1">// Emit PointCount.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">size</span><span class="p">());</span>
+
+ <span class="c1">// And each safe point...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span>
+ <span class="n">PE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">end</span><span class="p">();</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">PE</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit the address of the safe point.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point address"</span><span class="p">);</span>
+ <span class="n">MCSymbol</span> <span class="o">*</span><span class="n">Label</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Label</span><span class="p">;</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitLabelPlusOffset</span><span class="p">(</span><span class="n">Label</span><span class="cm">/*Hi*/</span><span class="p">,</span> <span class="mi">0</span><span class="cm">/*Offset*/</span><span class="p">,</span> <span class="mi">4</span><span class="cm">/*Size*/</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="c1">// Stack information never change in safe points! Only print info from the</span>
+ <span class="c1">// first call-site.</span>
+ <span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+
+ <span class="c1">// Emit the stack frame size.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack frame size (in words)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">getFrameSize</span><span class="p">()</span> <span class="o">/</span> <span class="n">IntPtrSize</span><span class="p">);</span>
+
+ <span class="c1">// Emit stack arity, i.e. the number of stacked arguments.</span>
+ <span class="kt">unsigned</span> <span class="n">RegisteredArgs</span> <span class="o">=</span> <span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">5</span> <span class="o">:</span> <span class="mi">6</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">StackArity</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">></span> <span class="n">RegisteredArgs</span> <span class="o">?</span>
+ <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">-</span> <span class="n">RegisteredArgs</span> <span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack arity"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">StackArity</span><span class="p">);</span>
+
+ <span class="c1">// Emit the number of live roots in the function.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"live root count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">live_size</span><span class="p">(</span><span class="n">PI</span><span class="p">));</span>
+
+ <span class="c1">// And for each live root...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">live_iterator</span> <span class="n">LI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_begin</span><span class="p">(</span><span class="n">PI</span><span class="p">),</span>
+ <span class="n">LE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_end</span><span class="p">(</span><span class="n">PI</span><span class="p">);</span>
+ <span class="n">LI</span> <span class="o">!=</span> <span class="n">LE</span><span class="p">;</span> <span class="o">++</span><span class="n">LI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit live root's offset within the stack frame.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack index (offset / wordsize)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitInt32</span><span class="p">(</span><span class="n">LI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="references">
+<h2><a class="toc-backref" href="#id20">References</a><a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
+<p id="appel89">[Appel89] Runtime Tags Aren’t Necessary. Andrew W. Appel. Lisp and Symbolic
+Computation 19(7):703-705, July 1989.</p>
+<p id="goldberg91">[Goldberg91] Tag-free garbage collection for strongly typed programming
+languages. Benjamin Goldberg. ACM SIGPLAN PLDI‘91.</p>
+<p id="tolmach94">[Tolmach94] Tag-free garbage collection using explicit type parameters. Andrew
+Tolmach. Proceedings of the 1994 ACM conference on LISP and functional
+programming.</p>
+<p id="henderson02">[Henderson2002] <a class="reference external" href="http://citeseer.ist.psu.edu/henderson02accurate.html">Accurate Garbage Collection in an Uncooperative Environment</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="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/GetElementPtr.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/GetElementPtr.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/GetElementPtr.html (added)
+++ www-releases/trunk/3.4.1/docs/GetElementPtr.html Wed May 7 15:09:32 2014
@@ -0,0 +1,565 @@
+
+
+<!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>The Often Misunderstood GEP Instruction — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="MCJIT Design and Implementation" href="MCJITDesignAndImplementation.html" />
+ <link rel="prev" title="YAML I/O" href="YamlIO.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="MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ 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="the-often-misunderstood-gep-instruction">
+<h1>The Often Misunderstood GEP Instruction<a class="headerlink" href="#the-often-misunderstood-gep-instruction" 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="id2">Introduction</a></li>
+<li><a class="reference internal" href="#address-computation" id="id3">Address Computation</a><ul>
+<li><a class="reference internal" href="#what-is-the-first-index-of-the-gep-instruction" id="id4">What is the first index of the GEP instruction?</a></li>
+<li><a class="reference internal" href="#why-is-the-extra-0-index-required" id="id5">Why is the extra 0 index required?</a></li>
+<li><a class="reference internal" href="#what-is-dereferenced-by-gep" id="id6">What is dereferenced by GEP?</a></li>
+<li><a class="reference internal" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" id="id7">Why don’t GEP x,0,0,1 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" id="id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#can-gep-index-into-vector-elements" id="id9">Can GEP index into vector elements?</a></li>
+<li><a class="reference internal" href="#what-effect-do-address-spaces-have-on-geps" id="id10">What effect do address spaces have on GEPs?</a></li>
+<li><a class="reference internal" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" id="id11">How is GEP different from <tt class="docutils literal"><span class="pre">ptrtoint</span></tt>, arithmetic, and <tt class="docutils literal"><span class="pre">inttoptr</span></tt>?</a></li>
+<li><a class="reference internal" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" id="id12">I’m writing a backend for a target which needs custom lowering for GEP. How do I do this?</a></li>
+<li><a class="reference internal" href="#how-does-vla-addressing-work-with-geps" id="id13">How does VLA addressing work with GEPs?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rules" id="id14">Rules</a><ul>
+<li><a class="reference internal" href="#what-happens-if-an-array-index-is-out-of-bounds" id="id15">What happens if an array index is out of bounds?</a></li>
+<li><a class="reference internal" href="#can-array-indices-be-negative" id="id16">Can array indices be negative?</a></li>
+<li><a class="reference internal" href="#can-i-compare-two-values-computed-with-geps" id="id17">Can I compare two values computed with GEPs?</a></li>
+<li><a class="reference internal" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" id="id18">Can I do GEP with a different pointer type than the type of the underlying object?</a></li>
+<li><a class="reference internal" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" id="id19">Can I cast an object’s address to integer and add it to null?</a></li>
+<li><a class="reference internal" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" id="id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a></li>
+<li><a class="reference internal" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" id="id21">Can I do type-based alias analysis on LLVM IR?</a></li>
+<li><a class="reference internal" href="#what-happens-if-a-gep-computation-overflows" id="id22">What happens if a GEP computation overflows?</a></li>
+<li><a class="reference internal" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" id="id23">How can I tell if my front-end is following the rules?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rationale" id="id24">Rationale</a><ul>
+<li><a class="reference internal" href="#why-is-gep-designed-this-way" id="id25">Why is GEP designed this way?</a></li>
+<li><a class="reference internal" href="#why-do-struct-member-indices-always-use-i32" id="id26">Why do struct member indices always use <tt class="docutils literal"><span class="pre">i32</span></tt>?</a></li>
+<li><a class="reference internal" href="#what-s-an-uglygep" id="id27">What’s an uglygep?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#summary" id="id28">Summary</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document seeks to dispel the mystery and confusion surrounding LLVM’s
+<a class="reference external" href="LangRef.html#i_getelementptr">GetElementPtr</a> (GEP) instruction. Questions
+about the wily GEP instruction are probably the most frequently occurring
+questions once a developer gets down to coding with LLVM. Here we lay out the
+sources of confusion and show that the GEP instruction is really quite simple.</p>
+</div>
+<div class="section" id="address-computation">
+<h2><a class="toc-backref" href="#id3">Address Computation</a><a class="headerlink" href="#address-computation" title="Permalink to this headline">¶</a></h2>
+<p>When people are first confronted with the GEP instruction, they tend to relate
+it to known concepts from other programming paradigms, most notably C array
+indexing and field selection. GEP closely resembles C array indexing and field
+selection, however it is a little different and this leads to the following
+questions.</p>
+<div class="section" id="what-is-the-first-index-of-the-gep-instruction">
+<h3><a class="toc-backref" href="#id4">What is the first index of the GEP instruction?</a><a class="headerlink" href="#what-is-the-first-index-of-the-gep-instruction" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: The index stepping through the first operand.</p>
+<p>The confusion with the first index usually arises from thinking about the
+GetElementPtr instruction as if it was a C index operator. They aren’t the
+same. For example, when we write, in “C”:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">AType</span> <span class="o">*</span><span class="n">Foo</span><span class="p">;</span>
+<span class="p">...</span>
+<span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="o">-></span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is natural to think that there is only one index, the selection of the field
+<tt class="docutils literal"><span class="pre">F</span></tt>. However, in this example, <tt class="docutils literal"><span class="pre">Foo</span></tt> is a pointer. That pointer
+must be indexed explicitly in LLVM. C, on the other hand, indices through it
+transparently. To arrive at the same address location as the C code, you would
+provide the GEP instruction with two index operands. The first operand indexes
+through the pointer; the second operand indexes the field <tt class="docutils literal"><span class="pre">F</span></tt> of the
+structure, just as if you wrote:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Sometimes this question gets rephrased as:</p>
+<blockquote id="gep-index-through-first-pointer">
+<div><em>Why is it okay to index through the first pointer, but subsequent pointers
+won’t be dereferenced?</em></div></blockquote>
+<p>The answer is simply because memory does not have to be accessed to perform the
+computation. The first operand to the GEP instruction must be a value of a
+pointer type. The value of the pointer is provided directly to the GEP
+instruction as an operand without any need for accessing memory. It must,
+therefore be indexed and requires an index operand. Consider this example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">munger_struct</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">f1</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">f2</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="kt">void</span> <span class="nf">munge</span><span class="p">(</span><span class="k">struct</span> <span class="n">munger_struct</span> <span class="o">*</span><span class="n">P</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">P</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">f1</span> <span class="o">=</span> <span class="n">P</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="n">f1</span> <span class="o">+</span> <span class="n">P</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">f2</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="p">...</span>
+<span class="n">munger_struct</span> <span class="n">Array</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span>
+<span class="p">...</span>
+<span class="n">munge</span><span class="p">(</span><span class="n">Array</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In this “C” example, the front end compiler (llvm-gcc) will generate three GEP
+instructions for the three indices through “P” in the assignment statement. The
+function argument <tt class="docutils literal"><span class="pre">P</span></tt> will be the first operand of each of these GEP
+instructions. The second operand indexes through that pointer. The third
+operand will be the field offset into the <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">munger_struct</span></tt> type, for
+either the <tt class="docutils literal"><span class="pre">f1</span></tt> or <tt class="docutils literal"><span class="pre">f2</span></tt> field. So, in LLVM assembly the <tt class="docutils literal"><span class="pre">munge</span></tt> function
+looks like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="nv">%munge</span><span class="p">(</span><span class="nv">%struct.munger_struct</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="nv">%tmp</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp6</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span>
+ <span class="nv">%tmp7</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp6</span>
+ <span class="nv">%tmp8</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%tmp7</span><span class="p">,</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp9</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%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">0</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%tmp8</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp9</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In each case the first operand is the pointer through which the GEP instruction
+starts. The same is true whether the first operand is an argument, allocated
+memory, or a global variable.</p>
+<p>To make this clear, let’s consider a more obtuse example:</p>
+<div class="highlight-llvm"><pre>%MyVar = uninitialized global i32
+...
+%idx1 = getelementptr i32* %MyVar, i64 0
+%idx2 = getelementptr i32* %MyVar, i64 1
+%idx3 = getelementptr i32* %MyVar, i64 2</pre>
+</div>
+<p>These GEP instructions are simply making address computations from the base
+address of <tt class="docutils literal"><span class="pre">MyVar</span></tt>. They compute, as follows (using C syntax):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">idx1</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">0</span>
+<span class="n">idx2</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">4</span>
+<span class="n">idx3</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">8</span>
+</pre></div>
+</div>
+<p>Since the type <tt class="docutils literal"><span class="pre">i32</span></tt> is known to be four bytes long, the indices 0, 1 and 2
+translate into memory offsets of 0, 4, and 8, respectively. No memory is
+accessed to make these computations because the address of <tt class="docutils literal"><span class="pre">%MyVar</span></tt> is passed
+directly to the GEP instructions.</p>
+<p>The obtuse part of this example is in the cases of <tt class="docutils literal"><span class="pre">%idx2</span></tt> and <tt class="docutils literal"><span class="pre">%idx3</span></tt>. They
+result in the computation of addresses that point to memory past the end of the
+<tt class="docutils literal"><span class="pre">%MyVar</span></tt> global, which is only one <tt class="docutils literal"><span class="pre">i32</span></tt> long, not three <tt class="docutils literal"><span class="pre">i32</span></tt>s long.
+While this is legal in LLVM, it is inadvisable because any load or store with
+the pointer that results from these GEP instructions would produce undefined
+results.</p>
+</div>
+<div class="section" id="why-is-the-extra-0-index-required">
+<h3><a class="toc-backref" href="#id5">Why is the extra 0 index required?</a><a class="headerlink" href="#why-is-the-extra-0-index-required" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: there are no superfluous indices.</p>
+<p>This question arises most often when the GEP instruction is applied to a global
+variable which is always a pointer type. For example, consider this:</p>
+<div class="highlight-llvm"><pre>%MyStruct = uninitialized global { float*, i32 }
+...
+%idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1</pre>
+</div>
+<p>The GEP above yields an <tt class="docutils literal"><span class="pre">i32*</span></tt> by indexing the <tt class="docutils literal"><span class="pre">i32</span></tt> typed field of the
+structure <tt class="docutils literal"><span class="pre">%MyStruct</span></tt>. When people first look at it, they wonder why the <tt class="docutils literal"><span class="pre">i64</span>
+<span class="pre">0</span></tt> index is needed. However, a closer inspection of how globals and GEPs work
+reveals the need. Becoming aware of the following facts will dispel the
+confusion:</p>
+<ol class="arabic simple">
+<li>The type of <tt class="docutils literal"><span class="pre">%MyStruct</span></tt> is <em>not</em> <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}</span></tt> but rather <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span>
+<span class="pre">i32</span> <span class="pre">}*</span></tt>. That is, <tt class="docutils literal"><span class="pre">%MyStruct</span></tt> is a pointer to a structure containing a
+pointer to a <tt class="docutils literal"><span class="pre">float</span></tt> and an <tt class="docutils literal"><span class="pre">i32</span></tt>.</li>
+<li>Point #1 is evidenced by noticing the type of the first operand of the GEP
+instruction (<tt class="docutils literal"><span class="pre">%MyStruct</span></tt>) which is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}*</span></tt>.</li>
+<li>The first index, <tt class="docutils literal"><span class="pre">i64</span> <span class="pre">0</span></tt> is required to step over the global variable
+<tt class="docutils literal"><span class="pre">%MyStruct</span></tt>. Since the first argument to the GEP instruction must always
+be a value of pointer type, the first index steps through that pointer. A
+value of 0 means 0 elements offset from that pointer.</li>
+<li>The second index, <tt class="docutils literal"><span class="pre">i32</span> <span class="pre">1</span></tt> selects the second field of the structure (the
+<tt class="docutils literal"><span class="pre">i32</span></tt>).</li>
+</ol>
+</div>
+<div class="section" id="what-is-dereferenced-by-gep">
+<h3><a class="toc-backref" href="#id6">What is dereferenced by GEP?</a><a class="headerlink" href="#what-is-dereferenced-by-gep" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: nothing.</p>
+<p>The GetElementPtr instruction dereferences nothing. That is, it doesn’t access
+memory in any way. That’s what the Load and Store instructions are for. GEP is
+only involved in the computation of addresses. For example, consider this:</p>
+<div class="highlight-llvm"><pre>%MyVar = uninitialized global { [40 x i32 ]* }
+...
+%idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17</pre>
+</div>
+<p>In this example, we have a global variable, <tt class="docutils literal"><span class="pre">%MyVar</span></tt> that is a pointer to a
+structure containing a pointer to an array of 40 ints. The GEP instruction seems
+to be accessing the 18th integer of the structure’s array of ints. However, this
+is actually an illegal GEP instruction. It won’t compile. The reason is that the
+pointer in the structure <em>must</em> be dereferenced in order to index into the
+array of 40 ints. Since the GEP instruction never accesses memory, it is
+illegal.</p>
+<p>In order to access the 18th integer in the array, you would need to do the
+following:</p>
+<div class="highlight-llvm"><pre>%idx = getelementptr { [40 x i32]* }* %, i64 0, i32 0
+%arr = load [40 x i32]** %idx
+%idx = getelementptr [40 x i32]* %arr, i64 0, i64 17</pre>
+</div>
+<p>In this case, we have to load the pointer in the structure with a load
+instruction before we can index into the array. If the example was changed to:</p>
+<div class="highlight-llvm"><pre>%MyVar = uninitialized global { [40 x i32 ] }
+...
+%idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17</pre>
+</div>
+<p>then everything works fine. In this case, the structure does not contain a
+pointer and the GEP instruction can index through the global variable, into the
+first field of the structure and access the 18th <tt class="docutils literal"><span class="pre">i32</span></tt> in the array there.</p>
+</div>
+<div class="section" id="why-don-t-gep-x-0-0-1-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id7">Why don’t GEP x,0,0,1 and GEP x,1 alias?</a><a class="headerlink" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute different address locations.</p>
+<p>If you look at the first indices in these GEP instructions you find that they
+are different (0 and 1), therefore the address computation diverges with that
+index. Consider this example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span> <span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span> <span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</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">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span> <span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, <tt class="docutils literal"><span class="pre">idx1</span></tt> computes the address of the second integer in the
+array that is in the structure in <tt class="docutils literal"><span class="pre">%MyVar</span></tt>, that is <tt class="docutils literal"><span class="pre">MyVar+4</span></tt>. The type of
+<tt class="docutils literal"><span class="pre">idx1</span></tt> is <tt class="docutils literal"><span class="pre">i32*</span></tt>. However, <tt class="docutils literal"><span class="pre">idx2</span></tt> computes the address of <em>the next</em>
+structure after <tt class="docutils literal"><span class="pre">%MyVar</span></tt>. The type of <tt class="docutils literal"><span class="pre">idx2</span></tt> is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span> <span class="pre">i32]</span> <span class="pre">}*</span></tt> and its
+value is equivalent to <tt class="docutils literal"><span class="pre">MyVar</span> <span class="pre">+</span> <span class="pre">40</span></tt> because it indexes past the ten 4-byte
+integers in <tt class="docutils literal"><span class="pre">MyVar</span></tt>. Obviously, in such a situation, the pointers don’t
+alias.</p>
+</div>
+<div class="section" id="why-do-gep-x-1-0-0-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a><a class="headerlink" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute the same address location.</p>
+<p>These two GEP instructions will compute the same address because indexing
+through the 0th element does not change the address. However, it does change the
+type. Consider this example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span> <span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span> <span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span> <span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, the value of <tt class="docutils literal"><span class="pre">%idx1</span></tt> is <tt class="docutils literal"><span class="pre">%MyVar+40</span></tt> and its type is
+<tt class="docutils literal"><span class="pre">i32*</span></tt>. The value of <tt class="docutils literal"><span class="pre">%idx2</span></tt> is also <tt class="docutils literal"><span class="pre">MyVar+40</span></tt> but its type is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span>
+<span class="pre">i32]</span> <span class="pre">}*</span></tt>.</p>
+</div>
+<div class="section" id="can-gep-index-into-vector-elements">
+<h3><a class="toc-backref" href="#id9">Can GEP index into vector elements?</a><a class="headerlink" href="#can-gep-index-into-vector-elements" title="Permalink to this headline">¶</a></h3>
+<p>This hasn’t always been forcefully disallowed, though it’s not recommended. It
+leads to awkward special cases in the optimizers, and fundamental inconsistency
+in the IR. In the future, it will probably be outright disallowed.</p>
+</div>
+<div class="section" id="what-effect-do-address-spaces-have-on-geps">
+<h3><a class="toc-backref" href="#id10">What effect do address spaces have on GEPs?</a><a class="headerlink" href="#what-effect-do-address-spaces-have-on-geps" title="Permalink to this headline">¶</a></h3>
+<p>None, except that the address space qualifier on the first operand pointer type
+always matches the address space qualifier on the result type.</p>
+</div>
+<div class="section" id="how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr">
+<h3><a class="toc-backref" href="#id11">How is GEP different from <tt class="docutils literal"><span class="pre">ptrtoint</span></tt>, arithmetic, and <tt class="docutils literal"><span class="pre">inttoptr</span></tt>?</a><a class="headerlink" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" title="Permalink to this headline">¶</a></h3>
+<p>It’s very similar; there are only subtle differences.</p>
+<p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
+this is safe on everything LLVM supports (LLVM internally assumes pointers are
+never wider than 64 bits in many places), and the optimizer will actually narrow
+the i64 arithmetic down to the actual pointer size on targets which don’t
+support 64-bit arithmetic in most cases. However, there are some cases where it
+doesn’t do this. With GEP you can avoid this problem.</p>
+<p>Also, GEP carries additional pointer aliasing rules. It’s invalid to take a GEP
+from one object, address into a different separately allocated object, and
+dereference it. IR producers (front-ends) must follow this rule, and consumers
+(optimizers, specifically alias analysis) benefit from being able to rely on
+it. See the <a class="reference internal" href="#rules">Rules</a> section for more information.</p>
+<p>And, GEP is more concise in common cases.</p>
+<p>However, for the underlying integer computation implied, there is no
+difference.</p>
+</div>
+<div class="section" id="i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this">
+<h3><a class="toc-backref" href="#id12">I’m writing a backend for a target which needs custom lowering for GEP. How do I do this?</a><a class="headerlink" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" title="Permalink to this headline">¶</a></h3>
+<p>You don’t. The integer computation implied by a GEP is target-independent.
+Typically what you’ll need to do is make your backend pattern-match expressions
+trees involving ADD, MUL, etc., which are what GEP is lowered into. This has the
+advantage of letting your code work correctly in more cases.</p>
+<p>GEP does use target-dependent parameters for the size and layout of data types,
+which targets can customize.</p>
+<p>If you require support for addressing units which are not 8 bits, you’ll need to
+fix a lot of code in the backend, with GEP lowering being only a small piece of
+the overall picture.</p>
+</div>
+<div class="section" id="how-does-vla-addressing-work-with-geps">
+<h3><a class="toc-backref" href="#id13">How does VLA addressing work with GEPs?</a><a class="headerlink" href="#how-does-vla-addressing-work-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>GEPs don’t natively support VLAs. LLVM’s type system is entirely static, and GEP
+address computations are guided by an LLVM type.</p>
+<p>VLA indices can be implemented as linearized indices. For example, an expression
+like <tt class="docutils literal"><span class="pre">X[a][b][c]</span></tt>, must be effectively lowered into a form like
+<tt class="docutils literal"><span class="pre">X[a*m+b*n+c]</span></tt>, so that it appears to the GEP as a single-dimensional array
+reference.</p>
+<p>This means if you want to write an analysis which understands array indices and
+you want to support VLAs, your code will have to be prepared to reverse-engineer
+the linearization. One way to solve this problem is to use the ScalarEvolution
+library, which always presents VLA and non-VLA indexing in the same manner.</p>
+</div>
+</div>
+<div class="section" id="rules">
+<span id="id1"></span><h2><a class="toc-backref" href="#id14">Rules</a><a class="headerlink" href="#rules" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-happens-if-an-array-index-is-out-of-bounds">
+<h3><a class="toc-backref" href="#id15">What happens if an array index is out of bounds?</a><a class="headerlink" href="#what-happens-if-an-array-index-is-out-of-bounds" title="Permalink to this headline">¶</a></h3>
+<p>There are two senses in which an array index can be out of bounds.</p>
+<p>First, there’s the array type which comes from the (static) type of the first
+operand to the GEP. Indices greater than the number of elements in the
+corresponding static array type are valid. There is no problem with out of
+bounds indices in this sense. Indexing into an array only depends on the size of
+the array element, not the number of elements.</p>
+<p>A common example of how this is used is arrays where the size is not known.
+It’s common to use array types with zero length to represent these. The fact
+that the static type says there are zero elements is irrelevant; it’s perfectly
+valid to compute arbitrary element indices, as the computation only depends on
+the size of the array element, not the number of elements. Note that zero-sized
+arrays are not a special case here.</p>
+<p>This sense is unconnected with <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword. The <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword is
+designed to describe low-level pointer arithmetic overflow conditions, rather
+than high-level array indexing rules.</p>
+<p>Analysis passes which wish to understand array indexing should not assume that
+the static array type bounds are respected.</p>
+<p>The second sense of being out of bounds is computing an address that’s beyond
+the actual underlying allocated object.</p>
+<p>With the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the result value of the GEP is undefined if the
+address is outside the actual underlying allocated object and not the address
+one-past-the-end.</p>
+<p>Without the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, there are no restrictions on computing
+out-of-bounds addresses. Obviously, performing a load or a store requires an
+address of allocated and sufficiently aligned memory. But the GEP itself is only
+concerned with computing addresses.</p>
+</div>
+<div class="section" id="can-array-indices-be-negative">
+<h3><a class="toc-backref" href="#id16">Can array indices be negative?</a><a class="headerlink" href="#can-array-indices-be-negative" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is basically a special case of array indices being out of bounds.</p>
+</div>
+<div class="section" id="can-i-compare-two-values-computed-with-geps">
+<h3><a class="toc-backref" href="#id17">Can I compare two values computed with GEPs?</a><a class="headerlink" href="#can-i-compare-two-values-computed-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>Yes. If both addresses are within the same allocated object, or
+one-past-the-end, you’ll get the comparison result you expect. If either is
+outside of it, integer arithmetic wrapping may occur, so the comparison may not
+be meaningful.</p>
+</div>
+<div class="section" id="can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object">
+<h3><a class="toc-backref" href="#id18">Can I do GEP with a different pointer type than the type of the underlying object?</a><a class="headerlink" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" title="Permalink to this headline">¶</a></h3>
+<p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
+pointer type. The types in a GEP serve only to define the parameters for the
+underlying integer computation. They need not correspond with the actual type of
+the underlying object.</p>
+<p>Furthermore, loads and stores don’t have to use the same types as the type of
+the underlying object. Types in this context serve only to specify memory size
+and alignment. Beyond that there are merely a hint to the optimizer indicating
+how the value will likely be used.</p>
+</div>
+<div class="section" id="can-i-cast-an-object-s-address-to-integer-and-add-it-to-null">
+<h3><a class="toc-backref" href="#id19">Can I cast an object’s address to integer and add it to null?</a><a class="headerlink" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" title="Permalink to this headline">¶</a></h3>
+<p>You can compute an address that way, but if you use GEP to do the add, you can’t
+use that pointer to actually access the object, unless the object is managed
+outside of LLVM.</p>
+<p>The underlying integer computation is sufficiently defined; null has a defined
+value — zero — and you can add whatever value you want to it.</p>
+<p>However, it’s invalid to access (load from or store to) an LLVM-aware object
+with such a pointer. This includes <tt class="docutils literal"><span class="pre">GlobalVariables</span></tt>, <tt class="docutils literal"><span class="pre">Allocas</span></tt>, and objects
+pointed to by noalias pointers.</p>
+<p>If you really need this functionality, you can do the arithmetic with explicit
+integer instructions, and use inttoptr to convert the result to an address. Most
+of GEP’s special aliasing rules do not apply to pointers computed from ptrtoint,
+arithmetic, and inttoptr sequences.</p>
+</div>
+<div class="section" id="can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address">
+<h3><a class="toc-backref" href="#id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a><a class="headerlink" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" title="Permalink to this headline">¶</a></h3>
+<p>As with arithmetic on null, you can use GEP to compute an address that way, but
+you can’t use that pointer to actually access the object if you do, unless the
+object is managed outside of LLVM.</p>
+<p>Also as above, ptrtoint and inttoptr provide an alternative way to do this which
+do not have this restriction.</p>
+</div>
+<div class="section" id="can-i-do-type-based-alias-analysis-on-llvm-ir">
+<h3><a class="toc-backref" href="#id21">Can I do type-based alias analysis on LLVM IR?</a><a class="headerlink" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>You can’t do type-based alias analysis using LLVM’s built-in type system,
+because LLVM has no restrictions on mixing types in addressing, loads or stores.</p>
+<p>LLVM’s type-based alias analysis pass uses metadata to describe a different type
+system (such as the C type system), and performs type-based aliasing on top of
+that. Further details are in the <a class="reference external" href="LangRef.html#tbaa">language reference</a>.</p>
+</div>
+<div class="section" id="what-happens-if-a-gep-computation-overflows">
+<h3><a class="toc-backref" href="#id22">What happens if a GEP computation overflows?</a><a class="headerlink" href="#what-happens-if-a-gep-computation-overflows" title="Permalink to this headline">¶</a></h3>
+<p>If the GEP lacks the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the value is the result from
+evaluating the implied two’s complement integer computation. However, since
+there’s no guarantee of where an object will be allocated in the address space,
+such values have limited meaning.</p>
+<p>If the GEP has the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the result value is undefined (a “trap
+value”) if the GEP overflows (i.e. wraps around the end of the address space).</p>
+<p>As such, there are some ramifications of this for inbounds GEPs: scales implied
+by array/vector/pointer indices are always known to be “nsw” since they are
+signed values that are scaled by the element size. These values are also
+allowed to be negative (e.g. “<tt class="docutils literal"><span class="pre">gep</span> <span class="pre">i32</span> <span class="pre">*%P,</span> <span class="pre">i32</span> <span class="pre">-1</span></tt>”) but the pointer itself
+is logically treated as an unsigned value. This means that GEPs have an
+asymmetric relation between the pointer base (which is treated as unsigned) and
+the offset applied to it (which is treated as signed). The result of the
+additions within the offset calculation cannot have signed overflow, but when
+applied to the base pointer, there can be signed overflow.</p>
+</div>
+<div class="section" id="how-can-i-tell-if-my-front-end-is-following-the-rules">
+<h3><a class="toc-backref" href="#id23">How can I tell if my front-end is following the rules?</a><a class="headerlink" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" title="Permalink to this headline">¶</a></h3>
+<p>There is currently no checker for the getelementptr rules. Currently, the only
+way to do this is to manually check each place in your front-end where
+GetElementPtr operators are created.</p>
+<p>It’s not possible to write a checker which could find all rule violations
+statically. It would be possible to write a checker which works by instrumenting
+the code with dynamic checks though. Alternatively, it would be possible to
+write a static checker which catches a subset of possible problems. However, no
+such checker exists today.</p>
+</div>
+</div>
+<div class="section" id="rationale">
+<h2><a class="toc-backref" href="#id24">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="why-is-gep-designed-this-way">
+<h3><a class="toc-backref" href="#id25">Why is GEP designed this way?</a><a class="headerlink" href="#why-is-gep-designed-this-way" title="Permalink to this headline">¶</a></h3>
+<p>The design of GEP has the following goals, in rough unofficial order of
+priority:</p>
+<ul class="simple">
+<li>Support C, C-like languages, and languages which can be conceptually lowered
+into C (this covers a lot).</li>
+<li>Support optimizations such as those that are common in C compilers. In
+particular, GEP is a cornerstone of LLVM’s <a class="reference external" href="LangRef.html#pointeraliasing">pointer aliasing
+model</a>.</li>
+<li>Provide a consistent method for computing addresses so that address
+computations don’t need to be a part of load and store instructions in the IR.</li>
+<li>Support non-C-like languages, to the extent that it doesn’t interfere with
+other goals.</li>
+<li>Minimize target-specific information in the IR.</li>
+</ul>
+</div>
+<div class="section" id="why-do-struct-member-indices-always-use-i32">
+<h3><a class="toc-backref" href="#id26">Why do struct member indices always use <tt class="docutils literal"><span class="pre">i32</span></tt>?</a><a class="headerlink" href="#why-do-struct-member-indices-always-use-i32" title="Permalink to this headline">¶</a></h3>
+<p>The specific type i32 is probably just a historical artifact, however it’s wide
+enough for all practical purposes, so there’s been no need to change it. It
+doesn’t necessarily imply i32 address arithmetic; it’s just an identifier which
+identifies a field in a struct. Requiring that all struct indices be the same
+reduces the range of possibilities for cases where two GEPs are effectively the
+same but have distinct operand types.</p>
+</div>
+<div class="section" id="what-s-an-uglygep">
+<h3><a class="toc-backref" href="#id27">What’s an uglygep?</a><a class="headerlink" href="#what-s-an-uglygep" title="Permalink to this headline">¶</a></h3>
+<p>Some LLVM optimizers operate on GEPs by internally lowering them into more
+primitive integer expressions, which allows them to be combined with other
+integer expressions and/or split into multiple separate integer expressions. If
+they’ve made non-trivial changes, translating back into LLVM IR can involve
+reverse-engineering the structure of the addressing in order to fit it into the
+static type of the original first operand. It isn’t always possibly to fully
+reconstruct this structure; sometimes the underlying addressing doesn’t
+correspond with the static type at all. In such cases the optimizer instead will
+emit a GEP with the base pointer casted to a simple address-unit pointer, using
+the name “uglygep”. This isn’t pretty, but it’s just as valid, and it’s
+sufficient to preserve the pointer aliasing guarantees that GEP provides.</p>
+</div>
+</div>
+<div class="section" id="summary">
+<h2><a class="toc-backref" href="#id28">Summary</a><a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2>
+<p>In summary, here’s some things to always remember about the GetElementPtr
+instruction:</p>
+<ol class="arabic simple">
+<li>The GEP instruction never accesses memory, it only provides pointer
+computations.</li>
+<li>The first operand to the GEP instruction is always a pointer and it must be
+indexed.</li>
+<li>There are no superfluous indices for the GEP instruction.</li>
+<li>Trailing zero indices are superfluous for pointer aliasing, but not for the
+types of the pointers.</li>
+<li>Leading zero indices are not superfluous for pointer aliasing nor the types
+of the pointers.</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="MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/GettingStarted.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/GettingStarted.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/GettingStarted.html (added)
+++ www-releases/trunk/3.4.1/docs/GettingStarted.html Wed May 7 15:09:32 2014
@@ -0,0 +1,1394 @@
+
+
+<!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>Getting Started with the LLVM System — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="Getting Started with the LLVM System using Microsoft Visual Studio" href="GettingStartedVS.html" />
+ <link rel="prev" title="llvm-readobj - LLVM Object Reader" href="CommandGuide/llvm-readobj.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="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CommandGuide/llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ 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="getting-started-with-the-llvm-system">
+<h1>Getting Started with the LLVM System<a class="headerlink" href="#getting-started-with-the-llvm-system" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id5">Overview</a></li>
+<li><a class="reference internal" href="#getting-started-quickly-a-summary" id="id6">Getting Started Quickly (A Summary)</a></li>
+<li><a class="reference internal" href="#requirements" id="id7">Requirements</a><ul>
+<li><a class="reference internal" href="#hardware" id="id8">Hardware</a></li>
+<li><a class="reference internal" href="#software" id="id9">Software</a></li>
+<li><a class="reference internal" href="#broken-versions-of-gcc-and-other-tools" id="id10">Broken versions of GCC and other tools</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#getting-started-with-llvm" id="id11">Getting Started with LLVM</a><ul>
+<li><a class="reference internal" href="#terminology-and-notation" id="id12">Terminology and Notation</a></li>
+<li><a class="reference internal" href="#setting-up-your-environment" id="id13">Setting Up Your Environment</a></li>
+<li><a class="reference internal" href="#unpacking-the-llvm-archives" id="id14">Unpacking the LLVM Archives</a></li>
+<li><a class="reference internal" href="#checkout-llvm-from-subversion" id="id15">Checkout LLVM from Subversion</a></li>
+<li><a class="reference internal" href="#git-mirror" id="id16">Git Mirror</a><ul>
+<li><a class="reference internal" href="#sending-patches-with-git" id="id17">Sending patches with Git</a></li>
+<li><a class="reference internal" href="#for-developers-to-work-with-git-svn" id="id18">For developers to work with git-svn</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#local-llvm-configuration" id="id19">Local LLVM Configuration</a></li>
+<li><a class="reference internal" href="#compiling-the-llvm-suite-source-code" id="id20">Compiling the LLVM Suite Source Code</a></li>
+<li><a class="reference internal" href="#cross-compiling-llvm" id="id21">Cross-Compiling LLVM</a></li>
+<li><a class="reference internal" href="#the-location-of-llvm-object-files" id="id22">The Location of LLVM Object Files</a></li>
+<li><a class="reference internal" href="#optional-configuration-items" id="id23">Optional Configuration Items</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#general-layout" id="id24">Program Layout</a><ul>
+<li><a class="reference internal" href="#llvm-examples" id="id25"><tt class="docutils literal"><span class="pre">llvm/examples</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-include" id="id26"><tt class="docutils literal"><span class="pre">llvm/include</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-lib" id="id27"><tt class="docutils literal"><span class="pre">llvm/lib</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-projects" id="id28"><tt class="docutils literal"><span class="pre">llvm/projects</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-runtime" id="id29"><tt class="docutils literal"><span class="pre">llvm/runtime</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-test" id="id30"><tt class="docutils literal"><span class="pre">llvm/test</span></tt></a></li>
+<li><a class="reference internal" href="#test-suite" id="id31"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-tools" id="id32"><tt class="docutils literal"><span class="pre">llvm/tools</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-utils" id="id33"><tt class="docutils literal"><span class="pre">llvm/utils</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#an-example-using-the-llvm-tool-chain" id="id34">An Example Using the LLVM Tool Chain</a><ul>
+<li><a class="reference internal" href="#example-with-clang" id="id35">Example with clang</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#common-problems" id="id36">Common Problems</a></li>
+<li><a class="reference internal" href="#links" id="id37">Links</a></li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id5">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to LLVM! In order to get started, you first need to know some basic
+information.</p>
+<p>First, LLVM comes in three pieces. The first piece is the LLVM suite. This
+contains all of the tools, libraries, and header files needed to use LLVM. It
+contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It
+also contains basic regression tests that can be used to test the LLVM tools and
+the Clang front end.</p>
+<p>The second piece is the <a class="reference external" href="http://clang.llvm.org/">Clang</a> front end. This
+component compiles C, C++, Objective C, and Objective C++ code into LLVM
+bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the
+LLVM tools from the LLVM suite.</p>
+<p>There is a third, optional piece called Test Suite. It is a suite of programs
+with a testing harness that can be used to further test LLVM’s functionality
+and performance.</p>
+</div>
+<div class="section" id="getting-started-quickly-a-summary">
+<h2><a class="toc-backref" href="#id6">Getting Started Quickly (A Summary)</a><a class="headerlink" href="#getting-started-quickly-a-summary" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM Getting Started documentation may be out of date. So, the <a class="reference external" href="http://clang.llvm.org/get_started.html">Clang
+Getting Started</a> page might also be a
+good place to start.</p>
+<p>Here’s the short story for getting up and running quickly with LLVM:</p>
+<ol class="arabic simple">
+<li>Read the documentation.</li>
+<li>Read the documentation.</li>
+<li>Remember that you were warned twice about reading the documentation.</li>
+<li>Checkout LLVM:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/llvm/trunk</span> <span class="pre">llvm</span></tt></li>
+</ul>
+</li>
+<li>Checkout Clang:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/cfe/trunk</span> <span class="pre">clang</span></tt></li>
+</ul>
+</li>
+<li>Checkout Compiler-RT:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/projects</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/compiler-rt/trunk</span> <span class="pre">compiler-rt</span></tt></li>
+</ul>
+</li>
+<li>Get the Test Suite Source Code <strong>[Optional]</strong><ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/projects</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/test-suite/trunk</span> <span class="pre">test-suite</span></tt></li>
+</ul>
+</li>
+<li>Configure and build LLVM and Clang:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-to-build-llvm</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">mkdir</span> <span class="pre">build</span></tt> (for building without polluting the source dir)</li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">build</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">../llvm/configure</span> <span class="pre">[options]</span></tt>
+Some common options:<ul>
+<li><tt class="docutils literal"><span class="pre">--prefix=directory</span></tt> — Specify for <em>directory</em> the full pathname of
+where you want the LLVM tools and libraries to be installed (default
+<tt class="docutils literal"><span class="pre">/usr/local</span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">--enable-optimized</span></tt> — Compile with optimizations enabled (default
+is NO).</li>
+<li><tt class="docutils literal"><span class="pre">--enable-assertions</span></tt> — Compile with assertion checks enabled
+(default is YES).</li>
+</ul>
+</li>
+<li><tt class="docutils literal"><span class="pre">make</span> <span class="pre">[-j]</span></tt> — The <tt class="docutils literal"><span class="pre">-j</span></tt> specifies the number of jobs (commands) to run
+simultaneously. This builds both LLVM and Clang for Debug+Asserts mode.
+The <tt class="docutils literal"><span class="pre">--enable-optimized</span></tt> configure option is used to specify a Release
+build.</li>
+<li><tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt> — This run the regression tests to ensure everything
+is in working order.</li>
+<li><tt class="docutils literal"><span class="pre">make</span> <span class="pre">update</span></tt> — This command is used to update all the svn repositories
+at once, rather then having to <tt class="docutils literal"><span class="pre">cd</span></tt> into the individual repositories and
+running <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">update</span></tt>.</li>
+<li>It is also possible to use CMake instead of the makefiles. With CMake it is
+possible to generate project files for several IDEs: Xcode, Eclipse CDT4,
+CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.</li>
+<li>If you get an “internal compiler error (ICE)” or test failures, see
+<cite>below</cite>.</li>
+</ul>
+</li>
+</ol>
+<p>Consult the <a class="reference internal" href="#getting-started-with-llvm">Getting Started with LLVM</a> section for detailed information on
+configuring and compiling LLVM. See <a class="reference internal" href="#setting-up-your-environment">Setting Up Your Environment</a> for tips
+that simplify working with the Clang front end and LLVM tools. Go to <a class="reference internal" href="#program-layout">Program
+Layout</a> to learn about the layout of the source code tree.</p>
+</div>
+<div class="section" id="requirements">
+<h2><a class="toc-backref" href="#id7">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
+<p>Before you begin to use the LLVM system, review the requirements given below.
+This may save you some trouble by knowing ahead of time what hardware and
+software you will need.</p>
+<div class="section" id="hardware">
+<h3><a class="toc-backref" href="#id8">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h3>
+<p>LLVM is known to work on the following platforms:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="34%" />
+<col width="39%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">OS</th>
+<th class="head">Arch</th>
+<th class="head">Compilers</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>AuroraUX</td>
+<td>x86<sup>1</sup></td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>Linux</td>
+<td>x86<sup>1</sup></td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>Linux</td>
+<td>amd64</td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>Linux</td>
+<td>ARM<sup>13</sup></td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>Solaris</td>
+<td>V9 (Ultrasparc)</td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>FreeBSD</td>
+<td>x86<sup>1</sup></td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>FreeBSD</td>
+<td>amd64</td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>MacOS X<sup>2</sup></td>
+<td>PowerPC</td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>MacOS X<sup>9</sup></td>
+<td>x86</td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>Cygwin/Win32</td>
+<td>x86<sup>1, 8, 11</sup></td>
+<td>GCC 3.4.X, binutils 2.20</td>
+</tr>
+</tbody>
+</table>
+<p>LLVM has partial support for the following platforms:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="23%" />
+<col width="26%" />
+<col width="51%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">OS</th>
+<th class="head">Arch</th>
+<th class="head">Compilers</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>Windows</td>
+<td>x86<sup>1</sup></td>
+<td>Visual Studio 2000 or higher<sup>4,5</sup></td>
+</tr>
+<tr class="row-odd"><td>AIX<sup>3,4</sup></td>
+<td>PowerPC</td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>Linux<sup>3,5</sup></td>
+<td>PowerPC</td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>Linux<sup>7</sup></td>
+<td>Alpha</td>
+<td>GCC</td>
+</tr>
+<tr class="row-even"><td>Linux<sup>7</sup></td>
+<td>Itanium (IA-64)</td>
+<td>GCC</td>
+</tr>
+<tr class="row-odd"><td>HP-UX<sup>7</sup></td>
+<td>Itanium (IA-64)</td>
+<td>HP aCC</td>
+</tr>
+<tr class="row-even"><td>Windows x64</td>
+<td>x86-64</td>
+<td>mingw-w64’s GCC-4.5.x<sup>12</sup></td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<ol class="last arabic simple">
+<li>Code generation supported for Pentium processors and up</li>
+<li>Code generation supported for 32-bit ABI only</li>
+<li>No native code generation</li>
+<li>Build is not complete: one or more tools do not link or function</li>
+<li>The GCC-based C/C++ frontend does not build</li>
+<li>The port is done using the MSYS shell.</li>
+<li>Native code generation exists but is not complete.</li>
+<li>Binutils 2.20 or later is required to build the assembler generated by LLVM properly.</li>
+<li>Xcode 2.5 and gcc 4.0.1 (Apple Build 5370) will trip internal LLVM assert
+messages when compiled for Release at optimization levels greater than 0
+(i.e., <tt class="docutils literal"><span class="pre">-O1</span></tt> and higher). Add <tt class="docutils literal"><span class="pre">OPTIMIZE_OPTION="-O0"</span></tt> to the build
+command line if compiling for LLVM Release or bootstrapping the LLVM
+toolchain.</li>
+<li>For MSYS/MinGW on Windows, be sure to install the MSYS version of the perl
+package, and be sure it appears in your path before any Windows-based
+versions such as Strawberry Perl and ActivePerl, as these have
+Windows-specifics that will cause the build to fail.</li>
+<li>To use LLVM modules on Win32-based system, you may configure LLVM
+with <tt class="docutils literal"><span class="pre">--enable-shared</span></tt>.</li>
+<li>To compile SPU backend, you need to add <tt class="docutils literal"><span class="pre">LDFLAGS=-Wl,--stack,16777216</span></tt> to
+configure.</li>
+<li>MCJIT not working well pre-v7, old JIT engine not supported any more.</li>
+</ol>
+</div>
+<p>Note that you will need about 1-3 GB of space for a full LLVM build in Debug
+mode, depending on the system (it is so large because of all the debugging
+information and the fact that the libraries are statically linked into multiple
+tools). If you do not need many of the tools and you are space-conscious, you
+can pass <tt class="docutils literal"><span class="pre">ONLY_TOOLS="tools</span> <span class="pre">you</span> <span class="pre">need"</span></tt> to make. The Release build requires
+considerably less space.</p>
+<p>The LLVM suite <em>may</em> compile on other platforms, but it is not guaranteed to do
+so. If compilation is successful, the LLVM utilities should be able to
+assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation
+should work as well, although the generated native code may not work on your
+platform.</p>
+</div>
+<div class="section" id="software">
+<h3><a class="toc-backref" href="#id9">Software</a><a class="headerlink" href="#software" title="Permalink to this headline">¶</a></h3>
+<p>Compiling LLVM requires that you have several software packages installed. The
+table below lists those required packages. The Package column is the usual name
+for the software package that LLVM depends on. The Version column provides
+“known to work” versions of the package. The Notes column describes how LLVM
+uses the package and provides other details.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="50%" />
+<col width="14%" />
+<col width="36%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Package</th>
+<th class="head">Version</th>
+<th class="head">Notes</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><a class="reference external" href="http://savannah.gnu.org/projects/make">GNU Make</a></td>
+<td>3.79, 3.79.1</td>
+<td>Makefile/build processor</td>
+</tr>
+<tr class="row-odd"><td><a class="reference external" href="http://gcc.gnu.org/">GCC</a></td>
+<td>3.4.2</td>
+<td>C/C++ compiler<sup>1</sup></td>
+</tr>
+<tr class="row-even"><td><a class="reference external" href="http://www.gnu.org/software/texinfo/">TeXinfo</a></td>
+<td>4.5</td>
+<td>For building the CFE</td>
+</tr>
+<tr class="row-odd"><td><a class="reference external" href="http://subversion.tigris.org/project_packages.html">SVN</a></td>
+<td>>=1.3</td>
+<td>Subversion access to LLVM<sup>2</sup></td>
+</tr>
+<tr class="row-even"><td><a class="reference external" href="http://www.python.org/">python</a></td>
+<td>>=2.5</td>
+<td>Automated test suite<sup>3</sup></td>
+</tr>
+<tr class="row-odd"><td><a class="reference external" href="http://savannah.gnu.org/projects/m4">GNU M4</a></td>
+<td>1.4</td>
+<td>Macro processor for configuration<sup>4</sup></td>
+</tr>
+<tr class="row-even"><td><a class="reference external" href="http://www.gnu.org/software/autoconf/">GNU Autoconf</a></td>
+<td>2.60</td>
+<td>Configuration script builder<sup>4</sup></td>
+</tr>
+<tr class="row-odd"><td><a class="reference external" href="http://www.gnu.org/software/automake/">GNU Automake</a></td>
+<td>1.9.6</td>
+<td>aclocal macro generator<sup>4</sup></td>
+</tr>
+<tr class="row-even"><td><a class="reference external" href="http://savannah.gnu.org/projects/libtool">libtool</a></td>
+<td>1.5.22</td>
+<td>Shared library manager<sup>4</sup></td>
+</tr>
+<tr class="row-odd"><td><a class="reference external" href="http://zlib.net">zlib</a></td>
+<td>>=1.2.3.4</td>
+<td>Compression library<sup>5</sup></td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<ol class="last arabic simple">
+<li>Only the C and C++ languages are needed so there’s no need to build the
+other languages for LLVM’s purposes. See <cite>below</cite> for specific version
+info.</li>
+<li>You only need Subversion if you intend to build from the latest LLVM
+sources. If you’re working from a release distribution, you don’t need
+Subversion.</li>
+<li>Only needed if you want to run the automated test suite in the
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory.</li>
+<li>If you want to make changes to the configure scripts, you will need GNU
+autoconf (2.60), and consequently, GNU M4 (version 1.4 or higher). You
+will also need automake (1.9.6). We only use aclocal from that package.</li>
+<li>Optional, adds compression/uncompression capabilities to selected LLVM
+tools.</li>
+</ol>
+</div>
+<p>Additionally, your compilation host is expected to have the usual plethora of
+Unix utilities. Specifically:</p>
+<ul class="simple">
+<li><strong>ar</strong> — archive library builder</li>
+<li><strong>bzip2</strong> — bzip2 command for distribution generation</li>
+<li><strong>bunzip2</strong> — bunzip2 command for distribution checking</li>
+<li><strong>chmod</strong> — change permissions on a file</li>
+<li><strong>cat</strong> — output concatenation utility</li>
+<li><strong>cp</strong> — copy files</li>
+<li><strong>date</strong> — print the current date/time</li>
+<li><strong>echo</strong> — print to standard output</li>
+<li><strong>egrep</strong> — extended regular expression search utility</li>
+<li><strong>find</strong> — find files/dirs in a file system</li>
+<li><strong>grep</strong> — regular expression search utility</li>
+<li><strong>gzip</strong> — gzip command for distribution generation</li>
+<li><strong>gunzip</strong> — gunzip command for distribution checking</li>
+<li><strong>install</strong> — install directories/files</li>
+<li><strong>mkdir</strong> — create a directory</li>
+<li><strong>mv</strong> — move (rename) files</li>
+<li><strong>ranlib</strong> — symbol table builder for archive libraries</li>
+<li><strong>rm</strong> — remove (delete) files and directories</li>
+<li><strong>sed</strong> — stream editor for transforming output</li>
+<li><strong>sh</strong> — Bourne shell for make build scripts</li>
+<li><strong>tar</strong> — tape archive for distribution generation</li>
+<li><strong>test</strong> — test things in file system</li>
+<li><strong>unzip</strong> — unzip command for distribution checking</li>
+<li><strong>zip</strong> — zip command for distribution generation</li>
+</ul>
+</div>
+<div class="section" id="broken-versions-of-gcc-and-other-tools">
+<span id="check-here"></span><span id="below"></span><h3><a class="toc-backref" href="#id10">Broken versions of GCC and other tools</a><a class="headerlink" href="#broken-versions-of-gcc-and-other-tools" title="Permalink to this headline">¶</a></h3>
+<p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
+bugs in the compiler. In particular, several versions of GCC crash when trying
+to compile LLVM. We routinely use GCC 4.2 (and higher) or Clang. Other
+versions of GCC will probably work as well. GCC versions listed here are known
+to not work. If you are using one of these versions, please try to upgrade your
+GCC to something more recent. If you run into a problem with a version of GCC
+not listed here, please <a class="reference external" href="mailto:llvmdev%40cs.uiuc.edu">let us know</a>. Please use
+the “<tt class="docutils literal"><span class="pre">gcc</span> <span class="pre">-v</span></tt>” command to find out which version of GCC you are using.</p>
+<p><strong>GCC versions prior to 3.0</strong>: GCC 2.96.x and before had several problems in the
+STL that effectively prevent it from compiling LLVM.</p>
+<p><strong>GCC 3.2.2 and 3.2.3</strong>: These versions of GCC fails to compile LLVM with a
+bogus template error. This was fixed in later GCCs.</p>
+<p><strong>GCC 3.3.2</strong>: This version of GCC suffered from a <a class="reference external" href="http://gcc.gnu.org/PR13392">serious bug</a> which causes it to crash in the
+“<tt class="docutils literal"><span class="pre">convert_from_eh_region_ranges_1</span></tt>” GCC function.</p>
+<p><strong>Cygwin GCC 3.3.3</strong>: The version of GCC 3.3.3 commonly shipped with Cygwin does
+not work.</p>
+<p><strong>SuSE GCC 3.3.3</strong>: The version of GCC 3.3.3 shipped with SuSE 9.1 (and possibly
+others) does not compile LLVM correctly (it appears that exception handling is
+broken in some cases). Please download the FSF 3.3.3 or upgrade to a newer
+version of GCC.</p>
+<p><strong>GCC 3.4.0 on linux/x86 (32-bit)</strong>: GCC miscompiles portions of the code
+generator, causing an infinite loop in the llvm-gcc build when built with
+optimizations enabled (i.e. a release build).</p>
+<p><strong>GCC 3.4.2 on linux/x86 (32-bit)</strong>: GCC miscompiles portions of the code
+generator at -O3, as with 3.4.0. However gcc 3.4.2 (unlike 3.4.0) correctly
+compiles LLVM at -O2. A work around is to build release LLVM builds with
+“<tt class="docutils literal"><span class="pre">make</span> <span class="pre">ENABLE_OPTIMIZED=1</span> <span class="pre">OPTIMIZE_OPTION=-O2</span> <span class="pre">...</span></tt>“</p>
+<p><strong>GCC 3.4.x on X86-64/amd64</strong>: GCC <a class="reference external" href="http://llvm.org/PR1056">miscompiles portions of LLVM</a>.</p>
+<p><strong>GCC 3.4.4 (CodeSourcery ARM 2005q3-2)</strong>: this compiler miscompiles LLVM when
+building with optimizations enabled. It appears to work with “<tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">ENABLE_OPTIMIZED=1</span> <span class="pre">OPTIMIZE_OPTION=-O1</span></tt>” or build a debug build.</p>
+<p><strong>IA-64 GCC 4.0.0</strong>: The IA-64 version of GCC 4.0.0 is known to miscompile LLVM.</p>
+<p><strong>Apple Xcode 2.3</strong>: GCC crashes when compiling LLVM at -O3 (which is the
+default with ENABLE_OPTIMIZED=1. To work around this, build with
+“<tt class="docutils literal"><span class="pre">ENABLE_OPTIMIZED=1</span> <span class="pre">OPTIMIZE_OPTION=-O2</span></tt>”.</p>
+<p><strong>GCC 4.1.1</strong>: GCC fails to build LLVM with template concept check errors
+compiling some files. At the time of this writing, GCC mainline (4.2) did not
+share the problem.</p>
+<p><strong>GCC 4.1.1 on X86-64/amd64</strong>: GCC <a class="reference external" href="http://llvm.org/PR1063">miscompiles portions of LLVM</a> when compiling llvm itself into 64-bit code. LLVM
+will appear to mostly work but will be buggy, e.g. failing portions of its
+testsuite.</p>
+<p><strong>GCC 4.1.2 on OpenSUSE</strong>: Seg faults during libstdc++ build and on x86_64
+platforms compiling md5.c gets a mangled constant.</p>
+<p><strong>GCC 4.1.2 (20061115 (prerelease) (Debian 4.1.1-21)) on Debian</strong>: Appears to
+miscompile parts of LLVM 2.4. One symptom is ValueSymbolTable complaining about
+symbols remaining in the table on destruction.</p>
+<p><strong>GCC 4.1.2 20071124 (Red Hat 4.1.2-42)</strong>: Suffers from the same symptoms as the
+previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).</p>
+<p><strong>Cygwin GCC 4.3.2 20080827 (beta) 2</strong>: Users <a class="reference external" href="http://llvm.org/PR4145">reported</a> various problems related with link errors when using
+this GCC version.</p>
+<p><strong>Debian GCC 4.3.2 on X86</strong>: Crashes building some files in LLVM 2.6.</p>
+<p><strong>GCC 4.3.3 (Debian 4.3.3-10) on ARM</strong>: Miscompiles parts of LLVM 2.6 when
+optimizations are turned on. The symptom is an infinite loop in
+<tt class="docutils literal"><span class="pre">FoldingSetImpl::RemoveNode</span></tt> while running the code generator.</p>
+<p><strong>SUSE 11 GCC 4.3.4</strong>: Miscompiles LLVM, causing crashes in ValueHandle logic.</p>
+<p><strong>GCC 4.3.5 and GCC 4.4.5 on ARM</strong>: These can miscompile <tt class="docutils literal"><span class="pre">value</span> <span class="pre">>></span> <span class="pre">1</span></tt> even at
+<tt class="docutils literal"><span class="pre">-O0</span></tt>. A test failure in <tt class="docutils literal"><span class="pre">test/Assembler/alignstack.ll</span></tt> is one symptom of
+the problem.</p>
+<p><strong>GCC 4.6.3 on ARM</strong>: Miscompiles <tt class="docutils literal"><span class="pre">llvm-readobj</span></tt> at <tt class="docutils literal"><span class="pre">-O3</span></tt>. A test failure
+in <tt class="docutils literal"><span class="pre">test/Object/readobj-shared-object.test</span></tt> is one symptom of the problem.</p>
+<p><strong>GNU ld 2.16.X</strong>. Some 2.16.X versions of the ld linker will produce very long
+warning messages complaining that some “<tt class="docutils literal"><span class="pre">.gnu.linkonce.t.*</span></tt>” symbol was
+defined in a discarded section. You can safely ignore these messages as they are
+erroneous and the linkage is correct. These messages disappear using ld 2.17.</p>
+<p><strong>GNU binutils 2.17</strong>: Binutils 2.17 contains <a class="reference external" href="http://sourceware.org/bugzilla/show_bug.cgi?id=3111">a bug</a> which causes huge link
+times (minutes instead of seconds) when building LLVM. We recommend upgrading
+to a newer version (2.17.50.0.4 or later).</p>
+<p><strong>GNU Binutils 2.19.1 Gold</strong>: This version of Gold contained <a class="reference external" href="http://sourceware.org/bugzilla/show_bug.cgi?id=9836">a bug</a> which causes
+intermittent failures when building LLVM with position independent code. The
+symptom is an error about cyclic dependencies. We recommend upgrading to a
+newer version of Gold.</p>
+<p><strong>Clang 3.0 with libstdc++ 4.7.x</strong>: a few Linux distributions (Ubuntu 12.10,
+Fedora 17) have both Clang 3.0 and libstdc++ 4.7 in their repositories. Clang
+3.0 does not implement a few builtins that are used in this library. We
+recommend using the system GCC to compile LLVM and Clang in this case.</p>
+<p><strong>Clang 3.0 on Mageia 2</strong>. There’s a packaging issue: Clang can not find at
+least some (<tt class="docutils literal"><span class="pre">cxxabi.h</span></tt>) libstdc++ headers.</p>
+</div>
+</div>
+<div class="section" id="getting-started-with-llvm">
+<span id="id1"></span><h2><a class="toc-backref" href="#id11">Getting Started with LLVM</a><a class="headerlink" href="#getting-started-with-llvm" title="Permalink to this headline">¶</a></h2>
+<p>The remainder of this guide is meant to get you up and running with LLVM and to
+give you some basic information about the LLVM environment.</p>
+<p>The later sections of this guide describe the <a class="reference internal" href="#general-layout">general layout</a> of the LLVM
+source tree, a <a class="reference internal" href="#simple-example">simple example</a> using the LLVM tool chain, and <a class="reference internal" href="#links">links</a> to find
+more information about LLVM or to get help via e-mail.</p>
+<div class="section" id="terminology-and-notation">
+<h3><a class="toc-backref" href="#id12">Terminology and Notation</a><a class="headerlink" href="#terminology-and-notation" title="Permalink to this headline">¶</a></h3>
+<p>Throughout this manual, the following names are used to denote paths specific to
+the local system and working environment. <em>These are not environment variables
+you need to set but just strings used in the rest of this document below</em>. In
+any of the examples below, simply replace each of these names with the
+appropriate pathname on your local system. All these paths are absolute:</p>
+<p><tt class="docutils literal"><span class="pre">SRC_ROOT</span></tt></p>
+<blockquote>
+<div>This is the top level directory of the LLVM source tree.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">OBJ_ROOT</span></tt></p>
+<blockquote>
+<div>This is the top level directory of the LLVM object tree (i.e. the tree where
+object files and compiled programs will be placed. It can be the same as
+SRC_ROOT).</div></blockquote>
+</div>
+<div class="section" id="setting-up-your-environment">
+<span id="id2"></span><h3><a class="toc-backref" href="#id13">Setting Up Your Environment</a><a class="headerlink" href="#setting-up-your-environment" title="Permalink to this headline">¶</a></h3>
+<p>In order to compile and use LLVM, you may need to set some environment
+variables.</p>
+<p><tt class="docutils literal"><span class="pre">LLVM_LIB_SEARCH_PATH=/path/to/your/bitcode/libs</span></tt></p>
+<blockquote>
+<div>[Optional] This environment variable helps LLVM linking tools find the
+locations of your bitcode libraries. It is provided only as a convenience
+since you can specify the paths using the -L options of the tools and the
+C/C++ front-end will automatically use the bitcode files installed in its
+<tt class="docutils literal"><span class="pre">lib</span></tt> directory.</div></blockquote>
+</div>
+<div class="section" id="unpacking-the-llvm-archives">
+<h3><a class="toc-backref" href="#id14">Unpacking the LLVM Archives</a><a class="headerlink" href="#unpacking-the-llvm-archives" title="Permalink to this headline">¶</a></h3>
+<p>If you have the LLVM distribution, you will need to unpack it before you can
+begin to compile it. LLVM is distributed as a set of two files: the LLVM suite
+and the LLVM GCC front end compiled for your platform. There is an additional
+test suite that is optional. Each file is a TAR archive that is compressed with
+the gzip program.</p>
+<p>The files are as follows, with <em>x.y</em> marking the version number:</p>
+<p><tt class="docutils literal"><span class="pre">llvm-x.y.tar.gz</span></tt></p>
+<blockquote>
+<div>Source release for the LLVM libraries and tools.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-test-x.y.tar.gz</span></tt></p>
+<blockquote>
+<div>Source release for the LLVM test-suite.</div></blockquote>
+</div>
+<div class="section" id="checkout-llvm-from-subversion">
+<span id="checkout"></span><h3><a class="toc-backref" href="#id15">Checkout LLVM from Subversion</a><a class="headerlink" href="#checkout-llvm-from-subversion" title="Permalink to this headline">¶</a></h3>
+<p>If you have access to our Subversion repository, you can get a fresh copy of the
+entire source code. All you need to do is check it out from Subversion as
+follows:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">where-you-want-llvm-to-live</span></tt></li>
+<li>Read-Only: <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/llvm/trunk</span> <span class="pre">llvm</span></tt></li>
+<li>Read-Write:<tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">https://user@llvm.org/svn/llvm-project/llvm/trunk</span> <span class="pre">llvm</span></tt></li>
+</ul>
+<p>This will create an ‘<tt class="docutils literal"><span class="pre">llvm</span></tt>‘ directory in the current directory and fully
+populate it with the LLVM source code, Makefiles, test directories, and local
+copies of documentation files.</p>
+<p>If you want to get a specific release (as opposed to the most recent revision),
+you can checkout it from the ‘<tt class="docutils literal"><span class="pre">tags</span></tt>‘ directory (instead of ‘<tt class="docutils literal"><span class="pre">trunk</span></tt>‘). The
+following releases are located in the following subdirectories of the ‘<tt class="docutils literal"><span class="pre">tags</span></tt>‘
+directory:</p>
+<ul class="simple">
+<li>Release 3.3: <strong>RELEASE_33/final</strong></li>
+<li>Release 3.2: <strong>RELEASE_32/final</strong></li>
+<li>Release 3.1: <strong>RELEASE_31/final</strong></li>
+<li>Release 3.0: <strong>RELEASE_30/final</strong></li>
+<li>Release 2.9: <strong>RELEASE_29/final</strong></li>
+<li>Release 2.8: <strong>RELEASE_28</strong></li>
+<li>Release 2.7: <strong>RELEASE_27</strong></li>
+<li>Release 2.6: <strong>RELEASE_26</strong></li>
+<li>Release 2.5: <strong>RELEASE_25</strong></li>
+<li>Release 2.4: <strong>RELEASE_24</strong></li>
+<li>Release 2.3: <strong>RELEASE_23</strong></li>
+<li>Release 2.2: <strong>RELEASE_22</strong></li>
+<li>Release 2.1: <strong>RELEASE_21</strong></li>
+<li>Release 2.0: <strong>RELEASE_20</strong></li>
+<li>Release 1.9: <strong>RELEASE_19</strong></li>
+<li>Release 1.8: <strong>RELEASE_18</strong></li>
+<li>Release 1.7: <strong>RELEASE_17</strong></li>
+<li>Release 1.6: <strong>RELEASE_16</strong></li>
+<li>Release 1.5: <strong>RELEASE_15</strong></li>
+<li>Release 1.4: <strong>RELEASE_14</strong></li>
+<li>Release 1.3: <strong>RELEASE_13</strong></li>
+<li>Release 1.2: <strong>RELEASE_12</strong></li>
+<li>Release 1.1: <strong>RELEASE_11</strong></li>
+<li>Release 1.0: <strong>RELEASE_1</strong></li>
+</ul>
+<p>If you would like to get the LLVM test suite (a separate package as of 1.4), you
+get it from the Subversion repository:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> svn co http://llvm.org/svn/llvm-project/test-suite/trunk <span class="nb">test</span>-suite
+</pre></div>
+</div>
+<p>By placing it in the <tt class="docutils literal"><span class="pre">llvm/projects</span></tt>, it will be automatically configured by
+the LLVM configure script as well as automatically updated when you run <tt class="docutils literal"><span class="pre">svn</span>
+<span class="pre">update</span></tt>.</p>
+</div>
+<div class="section" id="git-mirror">
+<h3><a class="toc-backref" href="#id16">Git Mirror</a><a class="headerlink" href="#git-mirror" title="Permalink to this headline">¶</a></h3>
+<p>Git mirrors are available for a number of LLVM subprojects. These mirrors sync
+automatically with each Subversion commit and contain all necessary git-svn
+marks (so, you can recreate git-svn metadata locally). Note that right now
+mirrors reflect only <tt class="docutils literal"><span class="pre">trunk</span></tt> for each project. You can do the read-only Git
+clone of LLVM via:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git clone http://llvm.org/git/llvm.git
+</pre></div>
+</div>
+<p>If you want to check out clang too, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/tools
+<span class="gp">%</span> git clone http://llvm.org/git/clang.git
+</pre></div>
+</div>
+<p>If you want to check out compiler-rt too, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> git clone http://llvm.org/git/compiler-rt.git
+</pre></div>
+</div>
+<p>If you want to check out the Test Suite Source Code (optional), run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>llvm/projects
+<span class="gp">%</span> git clone http://llvm.org/git/test-suite.git
+</pre></div>
+</div>
+<p>Since the upstream repository is in Subversion, you should use <tt class="docutils literal"><span class="pre">git</span>
+<span class="pre">pull</span> <span class="pre">--rebase</span></tt> instead of <tt class="docutils literal"><span class="pre">git</span> <span class="pre">pull</span></tt> to avoid generating a non-linear history
+in your clone. To configure <tt class="docutils literal"><span class="pre">git</span> <span class="pre">pull</span></tt> to pass <tt class="docutils literal"><span class="pre">--rebase</span></tt> by default on the
+master branch, run the following command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git config branch.master.rebase <span class="nb">true</span>
+</pre></div>
+</div>
+<div class="section" id="sending-patches-with-git">
+<h4><a class="toc-backref" href="#id17">Sending patches with Git</a><a class="headerlink" href="#sending-patches-with-git" title="Permalink to this headline">¶</a></h4>
+<p>Please read <a class="reference external" href="DeveloperPolicy.html#one-off-patches">Developer Policy</a>, too.</p>
+<p>Assume <tt class="docutils literal"><span class="pre">master</span></tt> points the upstream and <tt class="docutils literal"><span class="pre">mybranch</span></tt> points your working
+branch, and <tt class="docutils literal"><span class="pre">mybranch</span></tt> is rebased onto <tt class="docutils literal"><span class="pre">master</span></tt>. At first you may check
+sanity of whitespaces:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git diff --check master..mybranch
+</pre></div>
+</div>
+<p>The easiest way to generate a patch is as below:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git diff master..mybranch > /path/to/mybranch.diff
+</pre></div>
+</div>
+<p>It is a little different from svn-generated diff. git-diff-generated diff has
+prefixes like <tt class="docutils literal"><span class="pre">a/</span></tt> and <tt class="docutils literal"><span class="pre">b/</span></tt>. Don’t worry, most developers might know it
+could be accepted with <tt class="docutils literal"><span class="pre">patch</span> <span class="pre">-p1</span> <span class="pre">-N</span></tt>.</p>
+<p>But you may generate patchset with git-format-patch. It generates by-each-commit
+patchset. To generate patch files to attach to your article:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git format-patch --no-attach master..mybranch -o /path/to/your/patchset
+</pre></div>
+</div>
+<p>If you would like to send patches directly, you may use git-send-email or
+git-imap-send. Here is an example to generate the patchset in Gmail’s [Drafts].</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git format-patch --attach master..mybranch --stdout | git imap-send
+</pre></div>
+</div>
+<p>Then, your .git/config should have [imap] sections.</p>
+<div class="highlight-ini"><div class="highlight"><pre><span class="k">[imap]</span>
+ <span class="na">host</span> <span class="o">=</span> <span class="s">imaps://imap.gmail.com</span>
+<span class="s"> user = your.gmail.account at gmail.com</span>
+<span class="s"> pass = himitsu!</span>
+<span class="s"> port = 993</span>
+<span class="s"> sslverify = false</span>
+<span class="c1">; in English</span>
+ <span class="na">folder</span> <span class="o">=</span> <span class="s">"[Gmail]/Drafts"</span>
+<span class="c1">; example for Japanese, "Modified UTF-7" encoded.</span>
+ <span class="na">folder</span> <span class="o">=</span> <span class="s">"[Gmail]/&Tgtm+DBN-"</span>
+<span class="c1">; example for Traditional Chinese</span>
+ <span class="na">folder</span> <span class="o">=</span> <span class="s">"[Gmail]/&g0l6Pw-"</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="for-developers-to-work-with-git-svn">
+<h4><a class="toc-backref" href="#id18">For developers to work with git-svn</a><a class="headerlink" href="#for-developers-to-work-with-git-svn" title="Permalink to this headline">¶</a></h4>
+<p>To set up clone from which you can submit code using <tt class="docutils literal"><span class="pre">git-svn</span></tt>, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git clone http://llvm.org/git/llvm.git
+<span class="gp">%</span> <span class="nb">cd </span>llvm
+<span class="gp">%</span> git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username<span class="o">=</span><username>
+<span class="gp">%</span> git config svn-remote.svn.fetch :refs/remotes/origin/master
+<span class="gp">%</span> git svn rebase -l <span class="c"># -l avoids fetching ahead of the git mirror.</span>
+
+<span class="gp">#</span> If you have clang too:
+<span class="gp">%</span> <span class="nb">cd </span>tools
+<span class="gp">%</span> git clone http://llvm.org/git/clang.git
+<span class="gp">%</span> <span class="nb">cd </span>clang
+<span class="gp">%</span> git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username<span class="o">=</span><username>
+<span class="gp">%</span> git config svn-remote.svn.fetch :refs/remotes/origin/master
+<span class="gp">%</span> git svn rebase -l
+</pre></div>
+</div>
+<p>Likewise for compiler-rt and test-suite.</p>
+<p>To update this clone without generating git-svn tags that conflict with the
+upstream Git repo, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git fetch <span class="o">&&</span> <span class="o">(</span><span class="nb">cd </span>tools/clang <span class="o">&&</span> git fetch<span class="o">)</span> <span class="c"># Get matching revisions of both trees.</span>
+<span class="gp">%</span> git checkout master
+<span class="gp">%</span> git svn rebase -l
+<span class="gp">%</span> <span class="o">(</span><span class="nb">cd </span>tools/clang <span class="o">&&</span>
+<span class="go"> git checkout master &&</span>
+<span class="go"> git svn rebase -l)</span>
+</pre></div>
+</div>
+<p>Likewise for compiler-rt and test-suite.</p>
+<p>This leaves your working directories on their master branches, so you’ll need to
+<tt class="docutils literal"><span class="pre">checkout</span></tt> each working branch individually and <tt class="docutils literal"><span class="pre">rebase</span></tt> it on top of its
+parent branch.</p>
+<p>For those who wish to be able to update an llvm repo/revert patches easily using
+git-svn, please look in the directory for the scripts <tt class="docutils literal"><span class="pre">git-svnup</span></tt> and
+<tt class="docutils literal"><span class="pre">git-svnrevert</span></tt>.</p>
+<p>To perform the aforementioned update steps go into your source directory and
+just type <tt class="docutils literal"><span class="pre">git-svnup</span></tt> or <tt class="docutils literal"><span class="pre">git</span> <span class="pre">svnup</span></tt> and everything will just work.</p>
+<p>If one wishes to revert a commit with git-svn, but do not want the git hash to
+escape into the commit message, one can use the script <tt class="docutils literal"><span class="pre">git-svnrevert</span></tt> or
+<tt class="docutils literal"><span class="pre">git</span> <span class="pre">svnrevert</span></tt> which will take in the git hash for the commit you want to
+revert, look up the appropriate svn revision, and output a message where all
+references to the git hash have been replaced with the svn revision.</p>
+<p>To commit back changes via git-svn, use <tt class="docutils literal"><span class="pre">git</span> <span class="pre">svn</span> <span class="pre">dcommit</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> git svn dcommit
+</pre></div>
+</div>
+<p>Note that git-svn will create one SVN commit for each Git commit you have pending,
+so squash and edit each commit before executing <tt class="docutils literal"><span class="pre">dcommit</span></tt> to make sure they all
+conform to the coding standards and the developers’ policy.</p>
+<p>On success, <tt class="docutils literal"><span class="pre">dcommit</span></tt> will rebase against the HEAD of SVN, so to avoid conflict,
+please make sure your current branch is up-to-date (via fetch/rebase) before
+proceeding.</p>
+<p>The git-svn metadata can get out of sync after you mess around with branches and
+<tt class="docutils literal"><span class="pre">dcommit</span></tt>. When that happens, <tt class="docutils literal"><span class="pre">git</span> <span class="pre">svn</span> <span class="pre">dcommit</span></tt> stops working, complaining
+about files with uncommitted changes. The fix is to rebuild the metadata:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> rm -rf .git/svn
+<span class="gp">%</span> git svn rebase -l
+</pre></div>
+</div>
+<p>Please, refer to the Git-SVN manual (<tt class="docutils literal"><span class="pre">man</span> <span class="pre">git-svn</span></tt>) for more information.</p>
+</div>
+</div>
+<div class="section" id="local-llvm-configuration">
+<h3><a class="toc-backref" href="#id19">Local LLVM Configuration</a><a class="headerlink" href="#local-llvm-configuration" title="Permalink to this headline">¶</a></h3>
+<p>Once checked out from the Subversion repository, the LLVM suite source code must
+be configured via the <tt class="docutils literal"><span class="pre">configure</span></tt> script. This script sets variables in the
+various <tt class="docutils literal"><span class="pre">*.in</span></tt> files, most notably <tt class="docutils literal"><span class="pre">llvm/Makefile.config</span></tt> and
+<tt class="docutils literal"><span class="pre">llvm/include/Config/config.h</span></tt>. It also populates <em>OBJ_ROOT</em> with the
+Makefiles needed to begin building LLVM.</p>
+<p>The following environment variables are used by the <tt class="docutils literal"><span class="pre">configure</span></tt> script to
+configure the build system:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="17%" />
+<col width="83%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Variable</th>
+<th class="head">Purpose</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>CC</td>
+<td>Tells <tt class="docutils literal"><span class="pre">configure</span></tt> which C compiler to use. By default,
+<tt class="docutils literal"><span class="pre">configure</span></tt> will check <tt class="docutils literal"><span class="pre">PATH</span></tt> for <tt class="docutils literal"><span class="pre">clang</span></tt> and GCC C
+compilers (in this order). Use this variable to override
+<tt class="docutils literal"><span class="pre">configure</span></tt>‘s default behavior.</td>
+</tr>
+<tr class="row-odd"><td>CXX</td>
+<td>Tells <tt class="docutils literal"><span class="pre">configure</span></tt> which C++ compiler to use. By
+default, <tt class="docutils literal"><span class="pre">configure</span></tt> will check <tt class="docutils literal"><span class="pre">PATH</span></tt> for
+<tt class="docutils literal"><span class="pre">clang++</span></tt> and GCC C++ compilers (in this order). Use
+this variable to override <tt class="docutils literal"><span class="pre">configure</span></tt>‘s default
+behavior.</td>
+</tr>
+</tbody>
+</table>
+<p>The following options can be used to set or enable LLVM specific options:</p>
+<p><tt class="docutils literal"><span class="pre">--enable-optimized</span></tt></p>
+<blockquote>
+<div>Enables optimized compilation (debugging symbols are removed and GCC
+optimization flags are enabled). Note that this is the default setting if you
+are using the LLVM distribution. The default behavior of an Subversion
+checkout is to use an unoptimized build (also known as a debug build).</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">--enable-debug-runtime</span></tt></p>
+<blockquote>
+<div>Enables debug symbols in the runtime libraries. The default is to strip debug
+symbols from the runtime libraries.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">--enable-jit</span></tt></p>
+<blockquote>
+<div>Compile the Just In Time (JIT) compiler functionality. This is not available
+on all platforms. The default is dependent on platform, so it is best to
+explicitly enable it if you want it.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">--enable-targets=target-option</span></tt></p>
+<blockquote>
+<div><p>Controls which targets will be built and linked into llc. The default value
+for <tt class="docutils literal"><span class="pre">target_options</span></tt> is “all” which builds and links all available targets.
+The value “host-only” can be specified to build only a native compiler (no
+cross-compiler targets available). The “native” target is selected as the
+target of the build host. You can also specify a comma separated list of
+target names that you want available in llc. The target names use all lower
+case. The current set of targets is:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">arm,</span> <span class="pre">cpp,</span> <span class="pre">hexagon,</span> <span class="pre">mips,</span> <span class="pre">mipsel,</span> <span class="pre">msp430,</span> <span class="pre">powerpc,</span> <span class="pre">ptx,</span> <span class="pre">sparc,</span> <span class="pre">spu,</span>
+<span class="pre">systemz,</span> <span class="pre">x86,</span> <span class="pre">x86_64,</span> <span class="pre">xcore</span></tt>.</div></blockquote>
+</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">--enable-doxygen</span></tt></p>
+<blockquote>
+<div>Look for the doxygen program and enable construction of doxygen based
+documentation from the source code. This is disabled by default because
+generating the documentation can take a long time and producess 100s of
+megabytes of output.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">--with-udis86</span></tt></p>
+<blockquote>
+<div>LLVM can use external disassembler library for various purposes (now it’s used
+only for examining code produced by JIT). This option will enable usage of
+<a class="reference external" href="http://udis86.sourceforge.net/">udis86</a> x86 (both 32 and 64 bits)
+disassembler library.</div></blockquote>
+<p>To configure LLVM, follow these steps:</p>
+<ol class="arabic">
+<li><p class="first">Change directory into the object root directory:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>OBJ_ROOT
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the <tt class="docutils literal"><span class="pre">configure</span></tt> script located in the LLVM source tree:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> SRC_ROOT/configure --prefix<span class="o">=</span>/install/path <span class="o">[</span>other options<span class="o">]</span>
+</pre></div>
+</div>
+</li>
+</ol>
+</div>
+<div class="section" id="compiling-the-llvm-suite-source-code">
+<h3><a class="toc-backref" href="#id20">Compiling the LLVM Suite Source Code</a><a class="headerlink" href="#compiling-the-llvm-suite-source-code" title="Permalink to this headline">¶</a></h3>
+<p>Once you have configured LLVM, you can build it. There are three types of
+builds:</p>
+<p>Debug Builds</p>
+<blockquote>
+<div>These builds are the default when one is using an Subversion checkout and
+types <tt class="docutils literal"><span class="pre">gmake</span></tt> (unless the <tt class="docutils literal"><span class="pre">--enable-optimized</span></tt> option was used during
+configuration). The build system will compile the tools and libraries with
+debugging information. To get a Debug Build using the LLVM distribution the
+<tt class="docutils literal"><span class="pre">--disable-optimized</span></tt> option must be passed to <tt class="docutils literal"><span class="pre">configure</span></tt>.</div></blockquote>
+<p>Release (Optimized) Builds</p>
+<blockquote>
+<div>These builds are enabled with the <tt class="docutils literal"><span class="pre">--enable-optimized</span></tt> option to
+<tt class="docutils literal"><span class="pre">configure</span></tt> or by specifying <tt class="docutils literal"><span class="pre">ENABLE_OPTIMIZED=1</span></tt> on the <tt class="docutils literal"><span class="pre">gmake</span></tt> command
+line. For these builds, the build system will compile the tools and libraries
+with GCC optimizations enabled and strip debugging information from the
+libraries and executables it generates. Note that Release Builds are default
+when using an LLVM distribution.</div></blockquote>
+<p>Profile Builds</p>
+<blockquote>
+<div>These builds are for use with profiling. They compile profiling information
+into the code for use with programs like <tt class="docutils literal"><span class="pre">gprof</span></tt>. Profile builds must be
+started by specifying <tt class="docutils literal"><span class="pre">ENABLE_PROFILING=1</span></tt> on the <tt class="docutils literal"><span class="pre">gmake</span></tt> command line.</div></blockquote>
+<p>Once you have LLVM configured, you can build it by entering the <em>OBJ_ROOT</em>
+directory and issuing the following command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> gmake
+</pre></div>
+</div>
+<p>If the build fails, please <a class="reference internal" href="#check-here">check here</a> to see if you are using a version of
+GCC that is known not to compile LLVM.</p>
+<p>If you have multiple processors in your machine, you may wish to use some of the
+parallel build options provided by GNU Make. For example, you could use the
+command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> gmake -j2
+</pre></div>
+</div>
+<p>There are several special targets which are useful when working with the LLVM
+source code:</p>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">clean</span></tt></p>
+<blockquote>
+<div>Removes all files generated by the build. This includes object files,
+generated C/C++ files, libraries, and executables.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">dist-clean</span></tt></p>
+<blockquote>
+<div>Removes everything that <tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">clean</span></tt> does, but also removes files generated
+by <tt class="docutils literal"><span class="pre">configure</span></tt>. It attempts to return the source tree to the original state
+in which it was shipped.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">install</span></tt></p>
+<blockquote>
+<div>Installs LLVM header files, libraries, tools, and documentation in a hierarchy
+under <tt class="docutils literal"><span class="pre">$PREFIX</span></tt>, specified with <tt class="docutils literal"><span class="pre">./configure</span> <span class="pre">--prefix=[dir]</span></tt>, which
+defaults to <tt class="docutils literal"><span class="pre">/usr/local</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">-C</span> <span class="pre">runtime</span> <span class="pre">install-bytecode</span></tt></p>
+<blockquote>
+<div>Assuming you built LLVM into $OBJDIR, when this command is run, it will
+install bitcode libraries into the GCC front end’s bitcode library directory.
+If you need to update your bitcode libraries, this is the target to use once
+you’ve built them.</div></blockquote>
+<p>Please see the <a class="reference external" href="MakefileGuide.html">Makefile Guide</a> for further details on
+these <tt class="docutils literal"><span class="pre">make</span></tt> targets and descriptions of other targets available.</p>
+<p>It is also possible to override default values from <tt class="docutils literal"><span class="pre">configure</span></tt> by declaring
+variables on the command line. The following are some examples:</p>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">ENABLE_OPTIMIZED=1</span></tt></p>
+<blockquote>
+<div>Perform a Release (Optimized) build.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">ENABLE_OPTIMIZED=1</span> <span class="pre">DISABLE_ASSERTIONS=1</span></tt></p>
+<blockquote>
+<div>Perform a Release (Optimized) build without assertions enabled.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">ENABLE_OPTIMIZED=0</span></tt></p>
+<blockquote>
+<div>Perform a Debug build.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">ENABLE_PROFILING=1</span></tt></p>
+<blockquote>
+<div>Perform a Profiling build.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">VERBOSE=1</span></tt></p>
+<blockquote>
+<div>Print what <tt class="docutils literal"><span class="pre">gmake</span></tt> is doing on standard output.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TOOL_VERBOSE=1</span></tt></p>
+<blockquote>
+<div>Ask each tool invoked by the makefiles to print out what it is doing on
+the standard output. This also implies <tt class="docutils literal"><span class="pre">VERBOSE=1</span></tt>.</div></blockquote>
+<p>Every directory in the LLVM object tree includes a <tt class="docutils literal"><span class="pre">Makefile</span></tt> to build it and
+any subdirectories that it contains. Entering any directory inside the LLVM
+object tree and typing <tt class="docutils literal"><span class="pre">gmake</span></tt> should rebuild anything in or below that
+directory that is out of date.</p>
+<p>This does not apply to building the documentation.
+LLVM’s (non-Doxygen) documentation is produced with the
+<a class="reference external" href="http://sphinx-doc.org/">Sphinx</a> documentation generation system.
+There are some HTML documents that have not yet been converted to the new
+system (which uses the easy-to-read and easy-to-write
+<a class="reference external" href="http://sphinx-doc.org/rest.html">reStructuredText</a> plaintext markup
+language).
+The generated documentation is built in the <tt class="docutils literal"><span class="pre">SRC_ROOT/docs</span></tt> directory using
+a special makefile.
+For instructions on how to install Sphinx, see
+<a class="reference external" href="http://lld.llvm.org/sphinx_intro.html">Sphinx Introduction for LLVM Developers</a>.
+After following the instructions there for installing Sphinx, build the LLVM
+HTML documentation by doing the following:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">cd </span>SRC_ROOT/docs
+<span class="gp">$</span> make -f Makefile.sphinx
+</pre></div>
+</div>
+<p>This creates a <tt class="docutils literal"><span class="pre">_build/html</span></tt> sub-directory with all of the HTML files, not
+just the generated ones.
+This directory corresponds to <tt class="docutils literal"><span class="pre">llvm.org/docs</span></tt>.
+For example, <tt class="docutils literal"><span class="pre">_build/html/SphinxQuickstartTemplate.html</span></tt> corresponds to
+<tt class="docutils literal"><span class="pre">llvm.org/docs/SphinxQuickstartTemplate.html</span></tt>.
+The <a class="reference internal" href="SphinxQuickstartTemplate.html"><em>Sphinx Quickstart Template</em></a> is useful when creating a new document.</p>
+</div>
+<div class="section" id="cross-compiling-llvm">
+<h3><a class="toc-backref" href="#id21">Cross-Compiling LLVM</a><a class="headerlink" href="#cross-compiling-llvm" title="Permalink to this headline">¶</a></h3>
+<p>It is possible to cross-compile LLVM itself. That is, you can create LLVM
+executables and libraries to be hosted on a platform different from the platform
+where they are built (a Canadian Cross build). To configure a cross-compile,
+supply the configure script with <tt class="docutils literal"><span class="pre">--build</span></tt> and <tt class="docutils literal"><span class="pre">--host</span></tt> options that are
+different. The values of these options must be legal target triples that your
+GCC compiler supports.</p>
+<p>The result of such a build is executables that are not runnable on on the build
+host (–build option) but can be executed on the compile host (–host option).</p>
+<p>Check <a class="reference internal" href="HowToCrossCompileLLVM.html"><em>How To Cross-Compile Clang/LLVM using Clang/LLVM</em></a> and <a class="reference external" href="http://clang.llvm.org/docs/CrossCompilation.html">Clang docs on how to cross-compile in general</a> for more information
+about cross-compiling.</p>
+</div>
+<div class="section" id="the-location-of-llvm-object-files">
+<h3><a class="toc-backref" href="#id22">The Location of LLVM Object Files</a><a class="headerlink" href="#the-location-of-llvm-object-files" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM build system is capable of sharing a single LLVM source tree among
+several LLVM builds. Hence, it is possible to build LLVM for several different
+platforms or configurations using the same source tree.</p>
+<p>This is accomplished in the typical autoconf manner:</p>
+<ul>
+<li><p class="first">Change directory to where the LLVM object files should live:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nb">cd </span>OBJ_ROOT
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the <tt class="docutils literal"><span class="pre">configure</span></tt> script found in the LLVM source directory:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> SRC_ROOT/configure
+</pre></div>
+</div>
+</li>
+</ul>
+<p>The LLVM build will place files underneath <em>OBJ_ROOT</em> in directories named after
+the build type:</p>
+<p>Debug Builds with assertions enabled (the default)</p>
+<blockquote>
+<div><p>Tools</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">OBJ_ROOT/Debug+Asserts/bin</span></tt></div></blockquote>
+<p>Libraries</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">OBJ_ROOT/Debug+Asserts/lib</span></tt></div></blockquote>
+</div></blockquote>
+<p>Release Builds</p>
+<blockquote>
+<div><p>Tools</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">OBJ_ROOT/Release/bin</span></tt></div></blockquote>
+<p>Libraries</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">OBJ_ROOT/Release/lib</span></tt></div></blockquote>
+</div></blockquote>
+<p>Profile Builds</p>
+<blockquote>
+<div><p>Tools</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">OBJ_ROOT/Profile/bin</span></tt></div></blockquote>
+<p>Libraries</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">OBJ_ROOT/Profile/lib</span></tt></div></blockquote>
+</div></blockquote>
+</div>
+<div class="section" id="optional-configuration-items">
+<h3><a class="toc-backref" href="#id23">Optional Configuration Items</a><a class="headerlink" href="#optional-configuration-items" title="Permalink to this headline">¶</a></h3>
+<p>If you’re running on a Linux system that supports the <a class="reference external" href="http://en.wikipedia.org/wiki/binfmt_misc">binfmt_misc</a>
+module, and you have root access on the system, you can set your system up to
+execute LLVM bitcode files directly. To do this, use commands like this (the
+first command may not be required if you are already using the module):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+<span class="gp">%</span> <span class="nb">echo</span> <span class="s1">':llvm:M::BC::/path/to/lli:'</span> > /proc/sys/fs/binfmt_misc/register
+<span class="gp">%</span> chmod u+x hello.bc <span class="o">(</span><span class="k">if </span>needed<span class="o">)</span>
+<span class="gp">%</span> ./hello.bc
+</pre></div>
+</div>
+<p>This allows you to execute LLVM bitcode files directly. On Debian, you can also
+use this command instead of the ‘echo’ command above:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sudo update-binfmts --install llvm /path/to/lli --magic <span class="s1">'BC'</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="general-layout">
+<span id="program-layout"></span><span id="id3"></span><h2><a class="toc-backref" href="#id24">Program Layout</a><a class="headerlink" href="#general-layout" title="Permalink to this headline">¶</a></h2>
+<p>One useful source of information about the LLVM source base is the LLVM <a class="reference external" href="http://www.doxygen.org/">doxygen</a> documentation available at
+<a class="reference external" href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a>. The following is a brief introduction to code
+layout:</p>
+<div class="section" id="llvm-examples">
+<h3><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">llvm/examples</span></tt></a><a class="headerlink" href="#llvm-examples" title="Permalink to this headline">¶</a></h3>
+<p>This directory contains some simple examples of how to use the LLVM IR and JIT.</p>
+</div>
+<div class="section" id="llvm-include">
+<h3><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">llvm/include</span></tt></a><a class="headerlink" href="#llvm-include" title="Permalink to this headline">¶</a></h3>
+<p>This directory contains public header files exported from the LLVM library. The
+three main subdirectories of this directory are:</p>
+<p><tt class="docutils literal"><span class="pre">llvm/include/llvm</span></tt></p>
+<blockquote>
+<div>This directory contains all of the LLVM specific header files. This directory
+also has subdirectories for different portions of LLVM: <tt class="docutils literal"><span class="pre">Analysis</span></tt>,
+<tt class="docutils literal"><span class="pre">CodeGen</span></tt>, <tt class="docutils literal"><span class="pre">Target</span></tt>, <tt class="docutils literal"><span class="pre">Transforms</span></tt>, etc...</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/include/llvm/Support</span></tt></p>
+<blockquote>
+<div>This directory contains generic support libraries that are provided with LLVM
+but not necessarily specific to LLVM. For example, some C++ STL utilities and
+a Command Line option processing library store their header files here.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/include/llvm/Config</span></tt></p>
+<blockquote>
+<div>This directory contains header files configured by the <tt class="docutils literal"><span class="pre">configure</span></tt> script.
+They wrap “standard” UNIX and C header files. Source code can include these
+header files which automatically take care of the conditional #includes that
+the <tt class="docutils literal"><span class="pre">configure</span></tt> script generates.</div></blockquote>
+</div>
+<div class="section" id="llvm-lib">
+<h3><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">llvm/lib</span></tt></a><a class="headerlink" href="#llvm-lib" title="Permalink to this headline">¶</a></h3>
+<p>This directory contains most of the source files of the LLVM system. In LLVM,
+almost all code exists in libraries, making it very easy to share code among the
+different <a class="reference internal" href="#tools">tools</a>.</p>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/VMCore/</span></tt></p>
+<blockquote>
+<div>This directory holds the core LLVM source files that implement core classes
+like Instruction and BasicBlock.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/</span></tt></p>
+<blockquote>
+<div>This directory holds the source code for the LLVM assembly language parser
+library.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/</span></tt></p>
+<blockquote>
+<div>This directory holds code for reading and write LLVM bitcode.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Analysis/</span></tt></p>
+<blockquote>
+<div>This directory contains a variety of different program analyses, such as
+Dominator Information, Call Graphs, Induction Variables, Interval
+Identification, Natural Loop Identification, etc.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Transforms/</span></tt></p>
+<blockquote>
+<div>This directory contains the source code for the LLVM to LLVM program
+transformations, such as Aggressive Dead Code Elimination, Sparse Conditional
+Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global
+Elimination, and many others.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Target/</span></tt></p>
+<blockquote>
+<div>This directory contains files that describe various target architectures for
+code generation. For example, the <tt class="docutils literal"><span class="pre">llvm/lib/Target/X86</span></tt> directory holds the
+X86 machine description while <tt class="docutils literal"><span class="pre">llvm/lib/Target/ARM</span></tt> implements the ARM
+backend.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/CodeGen/</span></tt></p>
+<blockquote>
+<div>This directory contains the major parts of the code generator: Instruction
+Selector, Instruction Scheduling, and Register Allocation.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/MC/</span></tt></p>
+<blockquote>
+<div>(FIXME: T.B.D.)</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Debugger/</span></tt></p>
+<blockquote>
+<div>This directory contains the source level debugger library that makes it
+possible to instrument LLVM programs so that a debugger could identify source
+code locations at which the program is executing.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/ExecutionEngine/</span></tt></p>
+<blockquote>
+<div>This directory contains libraries for executing LLVM bitcode directly at
+runtime in both interpreted and JIT compiled fashions.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm/lib/Support/</span></tt></p>
+<blockquote>
+<div>This directory contains the source code that corresponds to the header files
+located in <tt class="docutils literal"><span class="pre">llvm/include/ADT/</span></tt> and <tt class="docutils literal"><span class="pre">llvm/include/Support/</span></tt>.</div></blockquote>
+</div>
+<div class="section" id="llvm-projects">
+<h3><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">llvm/projects</span></tt></a><a class="headerlink" href="#llvm-projects" title="Permalink to this headline">¶</a></h3>
+<p>This directory contains projects that are not strictly part of LLVM but are
+shipped with LLVM. This is also the directory where you should create your own
+LLVM-based projects. See <tt class="docutils literal"><span class="pre">llvm/projects/sample</span></tt> for an example of how to set
+up your own project.</p>
+</div>
+<div class="section" id="llvm-runtime">
+<h3><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">llvm/runtime</span></tt></a><a class="headerlink" href="#llvm-runtime" title="Permalink to this headline">¶</a></h3>
+<p>This directory contains libraries which are compiled into LLVM bitcode and used
+when linking programs with the Clang front end. Most of these libraries are
+skeleton versions of real libraries; for example, libc is a stripped down
+version of glibc.</p>
+<p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end
+to compile.</p>
+</div>
+<div class="section" id="llvm-test">
+<h3><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">llvm/test</span></tt></a><a class="headerlink" href="#llvm-test" title="Permalink to this headline">¶</a></h3>
+<p>This directory contains feature and regression tests and other basic sanity
+checks on the LLVM infrastructure. These are intended to run quickly and cover a
+lot of territory without being exhaustive.</p>
+</div>
+<div class="section" id="test-suite">
+<h3><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h3>
+<p>This is not a directory in the normal llvm module; it is a separate Subversion
+module that must be checked out (usually to <tt class="docutils literal"><span class="pre">projects/test-suite</span></tt>). This
+module contains a comprehensive correctness, performance, and benchmarking test
+suite for LLVM. It is a separate Subversion module because not every LLVM user
+is interested in downloading or building such a comprehensive test suite. For
+further details on this test suite, please see the <a class="reference internal" href="TestingGuide.html"><em>Testing Guide</em></a> document.</p>
+</div>
+<div class="section" id="llvm-tools">
+<span id="tools"></span><h3><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">llvm/tools</span></tt></a><a class="headerlink" href="#llvm-tools" title="Permalink to this headline">¶</a></h3>
+<p>The <strong>tools</strong> directory contains the executables built out of the libraries
+above, which form the main part of the user interface. You can always get help
+for a tool by typing <tt class="docutils literal"><span class="pre">tool_name</span> <span class="pre">-help</span></tt>. The following is a brief introduction
+to the most important tools. More detailed information is in
+the <a class="reference external" href="CommandGuide/index.html">Command Guide</a>.</p>
+<p><tt class="docutils literal"><span class="pre">bugpoint</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">bugpoint</span></tt> is used to debug optimization passes or code generation backends
+by narrowing down the given test case to the minimum number of passes and/or
+instructions that still cause a problem, whether it is a crash or
+miscompilation. See <a class="reference external" href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information on using
+<tt class="docutils literal"><span class="pre">bugpoint</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-ar</span></tt></p>
+<blockquote>
+<div>The archiver produces an archive containing the given LLVM bitcode files,
+optionally with an index for faster lookup.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-as</span></tt></p>
+<blockquote>
+<div>The assembler transforms the human readable LLVM assembly to LLVM bitcode.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-dis</span></tt></p>
+<blockquote>
+<div>The disassembler transforms the LLVM bitcode to human readable LLVM assembly.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvm-link</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">llvm-link</span></tt>, not surprisingly, links multiple LLVM modules into a single
+program.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">lli</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">lli</span></tt> is the LLVM interpreter, which can directly execute LLVM bitcode
+(although very slowly...). For architectures that support it (currently x86,
+Sparc, and PowerPC), by default, <tt class="docutils literal"><span class="pre">lli</span></tt> will function as a Just-In-Time
+compiler (if the functionality was compiled in), and will execute the code
+<em>much</em> faster than the interpreter.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llc</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">llc</span></tt> is the LLVM backend compiler, which translates LLVM bitcode to a
+native code assembly file or to C code (with the <tt class="docutils literal"><span class="pre">-march=c</span></tt> option).</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">opt</span></tt></p>
+<blockquote>
+<div><p><tt class="docutils literal"><span class="pre">opt</span></tt> reads LLVM bitcode, applies a series of LLVM to LLVM transformations
+(which are specified on the command line), and then outputs the resultant
+bitcode. The ‘<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-help</span></tt>‘ command is a good way to get a list of the
+program transformations available in LLVM.</p>
+<p><tt class="docutils literal"><span class="pre">opt</span></tt> can also be used to run a specific analysis on an input LLVM bitcode
+file and print out the results. It is primarily useful for debugging
+analyses, or familiarizing yourself with what an analysis does.</p>
+</div></blockquote>
+</div>
+<div class="section" id="llvm-utils">
+<h3><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">llvm/utils</span></tt></a><a class="headerlink" href="#llvm-utils" title="Permalink to this headline">¶</a></h3>
+<p>This directory contains utilities for working with LLVM source code, and some of
+the utilities are actually required as part of the build process because they
+are code generators for parts of LLVM infrastructure.</p>
+<p><tt class="docutils literal"><span class="pre">codegen-diff</span></tt></p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">codegen-diff</span></tt> is a script that finds differences between code that LLC
+generates and code that LLI generates. This is a useful tool if you are
+debugging one of them, assuming that the other generates correct output. For
+the full user manual, run <tt class="docutils literal"><span class="pre">`perldoc</span> <span class="pre">codegen-diff'</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">emacs/</span></tt></p>
+<blockquote>
+<div>The <tt class="docutils literal"><span class="pre">emacs</span></tt> directory contains syntax-highlighting files which will work
+with Emacs and XEmacs editors, providing syntax highlighting support for LLVM
+assembly files and TableGen description files. For information on how to use
+the syntax files, consult the <tt class="docutils literal"><span class="pre">README</span></tt> file in that directory.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">getsrcs.sh</span></tt></p>
+<blockquote>
+<div>The <tt class="docutils literal"><span class="pre">getsrcs.sh</span></tt> script finds and outputs all non-generated source files,
+which is useful if one wishes to do a lot of development across directories
+and does not want to individually find each file. One way to use it is to run,
+for example: <tt class="docutils literal"><span class="pre">xemacs</span> <span class="pre">`utils/getsources.sh`</span></tt> from the top of your LLVM source
+tree.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">llvmgrep</span></tt></p>
+<blockquote>
+<div>This little tool performs an <tt class="docutils literal"><span class="pre">egrep</span> <span class="pre">-H</span> <span class="pre">-n</span></tt> on each source file in LLVM and
+passes to it a regular expression provided on <tt class="docutils literal"><span class="pre">llvmgrep</span></tt>‘s command
+line. This is a very efficient way of searching the source base for a
+particular regular expression.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">makellvm</span></tt></p>
+<blockquote>
+<div>The <tt class="docutils literal"><span class="pre">makellvm</span></tt> script compiles all files in the current directory and then
+compiles and links the tool that is the first argument. For example, assuming
+you are in the directory <tt class="docutils literal"><span class="pre">llvm/lib/Target/Sparc</span></tt>, if <tt class="docutils literal"><span class="pre">makellvm</span></tt> is in your
+path, simply running <tt class="docutils literal"><span class="pre">makellvm</span> <span class="pre">llc</span></tt> will make a build of the current
+directory, switch to directory <tt class="docutils literal"><span class="pre">llvm/tools/llc</span></tt> and build it, causing a
+re-linking of LLC.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">TableGen/</span></tt></p>
+<blockquote>
+<div>The <tt class="docutils literal"><span class="pre">TableGen</span></tt> directory contains the tool used to generate register
+descriptions, instruction set descriptions, and even assemblers from common
+TableGen description files.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">vim/</span></tt></p>
+<blockquote>
+<div>The <tt class="docutils literal"><span class="pre">vim</span></tt> directory contains syntax-highlighting files which will work with
+the VIM editor, providing syntax highlighting support for LLVM assembly files
+and TableGen description files. For information on how to use the syntax
+files, consult the <tt class="docutils literal"><span class="pre">README</span></tt> file in that directory.</div></blockquote>
+</div>
+</div>
+<div class="section" id="an-example-using-the-llvm-tool-chain">
+<span id="simple-example"></span><h2><a class="toc-backref" href="#id34">An Example Using the LLVM Tool Chain</a><a class="headerlink" href="#an-example-using-the-llvm-tool-chain" title="Permalink to this headline">¶</a></h2>
+<p>This section gives an example of using LLVM with the Clang front end.</p>
+<div class="section" id="example-with-clang">
+<h3><a class="toc-backref" href="#id35">Example with clang</a><a class="headerlink" href="#example-with-clang" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first">First, create a simple C file, name it ‘hello.c’:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</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>
+</li>
+<li><p class="first">Next, compile the C file into a native executable:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang hello.c -o hello
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang works just like GCC by default. The standard -S and -c arguments
+work as usual (producing a native .s or .o file, respectively).</p>
+</div>
+</li>
+<li><p class="first">Next, compile the C file into an LLVM bitcode file:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang -O3 -emit-llvm hello.c -c -o hello.bc
+</pre></div>
+</div>
+<p>The -emit-llvm option can be used with the -S or -c options to emit an LLVM
+<tt class="docutils literal"><span class="pre">.ll</span></tt> or <tt class="docutils literal"><span class="pre">.bc</span></tt> file (respectively) for the code. This allows you to use
+the <a class="reference external" href="CommandGuide/index.html">standard LLVM tools</a> on the bitcode file.</p>
+</li>
+<li><p class="first">Run the program in both forms. To run the program, use:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> ./hello
+</pre></div>
+</div>
+<p>and</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> lli hello.bc
+</pre></div>
+</div>
+<p>The second examples shows how to invoke the LLVM JIT, <a class="reference internal" href="CommandGuide/lli.html"><em>lli</em></a>.</p>
+</li>
+<li><p class="first">Use the <tt class="docutils literal"><span class="pre">llvm-dis</span></tt> utility to take a look at the LLVM assembly code:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> llvm-dis < hello.bc | less
+</pre></div>
+</div>
+</li>
+<li><p class="first">Compile the program to native assembly using the LLC code generator:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> llc hello.bc -o hello.s
+</pre></div>
+</div>
+</li>
+<li><p class="first">Assemble the native assembly language file into a program:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> /opt/SUNWspro/bin/cc -xarch<span class="o">=</span>v9 hello.s -o hello.native <span class="c"># On Solaris</span>
+
+<span class="gp">%</span> gcc hello.s -o hello.native <span class="c"># On others</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Execute the native code program:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> ./hello.native
+</pre></div>
+</div>
+<p>Note that using clang to compile directly to native code (i.e. when the
+<tt class="docutils literal"><span class="pre">-emit-llvm</span></tt> option is not present) does steps 6/7/8 for you.</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="section" id="common-problems">
+<h2><a class="toc-backref" href="#id36">Common Problems</a><a class="headerlink" href="#common-problems" title="Permalink to this headline">¶</a></h2>
+<p>If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the <a class="reference external" href="FAQ.html">Frequently Asked
+Questions</a> page.</p>
+</div>
+<div class="section" id="links">
+<span id="id4"></span><h2><a class="toc-backref" href="#id37">Links</a><a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h2>
+<p>This document is just an <strong>introduction</strong> on how to use LLVM to do some simple
+things... there are many more interesting and complicated things that you can do
+that aren’t documented here (but we’ll gladly accept a patch if you want to
+write something up!). For more information about LLVM, check out:</p>
+<ul class="simple">
+<li><a class="reference external" href="http://llvm.org/">LLVM Homepage</a></li>
+<li><a class="reference external" href="http://llvm.org/doxygen/">LLVM Doxygen Tree</a></li>
+<li><a class="reference external" href="http://llvm.org/docs/Projects.html">Starting a Project that Uses LLVM</a></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="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CommandGuide/llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/GettingStartedVS.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/GettingStartedVS.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/GettingStartedVS.html (added)
+++ www-releases/trunk/3.4.1/docs/GettingStartedVS.html Wed May 7 15:09:32 2014
@@ -0,0 +1,332 @@
+
+
+<!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>Getting Started with the LLVM System using Microsoft Visual Studio — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="Frequently Asked Questions (FAQ)" href="FAQ.html" />
+ <link rel="prev" title="Getting Started with the LLVM System" href="GettingStarted.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="FAQ.html" title="Frequently Asked Questions (FAQ)"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GettingStarted.html" title="Getting Started with the LLVM System"
+ 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="getting-started-with-the-llvm-system-using-microsoft-visual-studio">
+<h1>Getting Started with the LLVM System using Microsoft Visual Studio<a class="headerlink" href="#getting-started-with-the-llvm-system-using-microsoft-visual-studio" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id3">Overview</a></li>
+<li><a class="reference internal" href="#requirements" id="id4">Requirements</a><ul>
+<li><a class="reference internal" href="#hardware" id="id5">Hardware</a></li>
+<li><a class="reference internal" href="#software" id="id6">Software</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id1" id="id7">Getting Started</a></li>
+<li><a class="reference internal" href="#an-example-using-the-llvm-tool-chain" id="id8">An Example Using the LLVM Tool Chain</a></li>
+<li><a class="reference internal" href="#common-problems" id="id9">Common Problems</a></li>
+<li><a class="reference internal" href="#links" id="id10">Links</a></li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id3">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>Welcome to LLVM on Windows! This document only covers LLVM on Windows using
+Visual Studio, not mingw or cygwin. In order to get started, you first need to
+know some basic information.</p>
+<p>There are many different projects that compose LLVM. The first is the LLVM
+suite. This contains all of the tools, libraries, and header files needed to
+use LLVM. It contains an assembler, disassembler,
+bitcode analyzer and bitcode optimizer. It also contains a test suite that can
+be used to test the LLVM tools.</p>
+<p>Another useful project on Windows is <a class="reference external" href="http://clang.llvm.org/">Clang</a>.
+Clang is a C family ([Objective]C/C++) compiler. Clang mostly works on
+Windows, but does not currently understand all of the Microsoft extensions
+to C and C++. Because of this, clang cannot parse the C++ standard library
+included with Visual Studio, nor parts of the Windows Platform SDK. However,
+most standard C programs do compile. Clang can be used to emit bitcode,
+directly emit object files or even linked executables using Visual Studio’s
+<tt class="docutils literal"><span class="pre">link.exe</span></tt>.</p>
+<p>The large LLVM test suite cannot be run on the Visual Studio port at this
+time.</p>
+<p>Most of the tools build and work. <tt class="docutils literal"><span class="pre">bugpoint</span></tt> does build, but does
+not work.</p>
+<p>Additional information about the LLVM directory structure and tool chain
+can be found on the main <a class="reference external" href="GettingStarted.html">Getting Started</a> page.</p>
+</div>
+<div class="section" id="requirements">
+<h2><a class="toc-backref" href="#id4">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
+<p>Before you begin to use the LLVM system, review the requirements given
+below. This may save you some trouble by knowing ahead of time what hardware
+and software you will need.</p>
+<div class="section" id="hardware">
+<h3><a class="toc-backref" href="#id5">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h3>
+<p>Any system that can adequately run Visual Studio 2010 is fine. The LLVM
+source tree and object files, libraries and executables will consume
+approximately 3GB.</p>
+</div>
+<div class="section" id="software">
+<h3><a class="toc-backref" href="#id6">Software</a><a class="headerlink" href="#software" title="Permalink to this headline">¶</a></h3>
+<p>You will need Visual Studio 2010 or higher. Earlier versions of Visual
+Studio have bugs, are not completely compatible, or do not support the C++
+standard well enough.</p>
+<p>You will also need the <a class="reference external" href="http://www.cmake.org/">CMake</a> build system since it
+generates the project files you will use to build with.</p>
+<p>If you would like to run the LLVM tests you will need <a class="reference external" href="http://www.python.org/">Python</a>. Versions 2.4-2.7 are known to work. You will need
+<a class="reference external" href="http://gnuwin32.sourceforge.net/">GnuWin32</a> tools, too.</p>
+<p>Do not install the LLVM directory tree into a path containing spaces (e.g.
+<tt class="docutils literal"><span class="pre">C:\Documents</span> <span class="pre">and</span> <span class="pre">Settings\...</span></tt>) as the configure step will fail.</p>
+</div>
+</div>
+<div class="section" id="id1">
+<h2><a class="toc-backref" href="#id7">Getting Started</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
+<p>Here’s the short story for getting up and running quickly with LLVM:</p>
+<ol class="arabic">
+<li><p class="first">Read the documentation.</p>
+</li>
+<li><p class="first">Seriously, read the documentation.</p>
+</li>
+<li><p class="first">Remember that you were warned twice about reading the documentation.</p>
+</li>
+<li><p class="first">Get the Source Code</p>
+<ul>
+<li><p class="first">With the distributed files:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre"><where-you-want-llvm-to-live></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">gunzip</span> <span class="pre">--stdout</span> <span class="pre">llvm-VERSION.tar.gz</span> <span class="pre">|</span> <span class="pre">tar</span> <span class="pre">-xvf</span> <span class="pre">-</span></tt>
+(<em>or use WinZip</em>)</li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm</span></tt></li>
+</ol>
+</div></blockquote>
+</li>
+<li><p class="first">With anonymous Subversion access:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre"><where-you-want-llvm-to-live></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/llvm/trunk</span> <span class="pre">llvm</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm</span></tt></li>
+</ol>
+</div></blockquote>
+</li>
+</ul>
+</li>
+<li><p class="first">Use <a class="reference external" href="http://www.cmake.org/">CMake</a> to generate up-to-date project files:</p>
+<ul class="simple">
+<li>Once CMake is installed then the simplest way is to just start the
+CMake GUI, select the directory where you have LLVM extracted to, and
+the default options should all be fine. One option you may really
+want to change, regardless of anything else, might be the
+<tt class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></tt> setting to select a directory to INSTALL to
+once compiling is complete, although installation is not mandatory for
+using LLVM. Another important option is <tt class="docutils literal"><span class="pre">LLVM_TARGETS_TO_BUILD</span></tt>,
+which controls the LLVM target architectures that are included on the
+build.</li>
+<li>See the <a class="reference external" href="CMake.html">LLVM CMake guide</a> for detailed information about
+how to configure the LLVM build.</li>
+</ul>
+</li>
+<li><p class="first">Start Visual Studio</p>
+<ul class="simple">
+<li>In the directory you created the project files will have an <tt class="docutils literal"><span class="pre">llvm.sln</span></tt>
+file, just double-click on that to open Visual Studio.</li>
+</ul>
+</li>
+<li><p class="first">Build the LLVM Suite:</p>
+<ul class="simple">
+<li>The projects may still be built individually, but to build them all do
+not just select all of them in batch build (as some are meant as
+configuration projects), but rather select and build just the
+<tt class="docutils literal"><span class="pre">ALL_BUILD</span></tt> project to build everything, or the <tt class="docutils literal"><span class="pre">INSTALL</span></tt> project,
+which first builds the <tt class="docutils literal"><span class="pre">ALL_BUILD</span></tt> project, then installs the LLVM
+headers, libs, and other useful things to the directory set by the
+<tt class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></tt> setting when you first configured CMake.</li>
+<li>The Fibonacci project is a sample program that uses the JIT. Modify the
+project’s debugging properties to provide a numeric command line argument
+or run it from the command line. The program will print the
+corresponding fibonacci value.</li>
+</ul>
+</li>
+<li><p class="first">Test LLVM on Visual Studio:</p>
+<ul class="simple">
+<li>If <tt class="docutils literal"><span class="pre">%PATH%</span></tt> does not contain GnuWin32, you may specify
+<tt class="docutils literal"><span class="pre">LLVM_LIT_TOOLS_DIR</span></tt> on CMake for the path to GnuWin32.</li>
+<li>You can run LLVM tests by merely building the project “check”. The test
+results will be shown in the VS output window.</li>
+</ul>
+</li>
+</ol>
+<ol class="arabic" start="9">
+<li><p class="first">Test LLVM:</p>
+<ul>
+<li><p class="first">The LLVM tests can be run by changing directory to the llvm source
+directory and running:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..\llvm<span class="p">></span> <span class="n">python</span> ..\build\bin\llvm-lit --param build_config<span class="o">=</span>Win<span class="m">32</span> --param build_mode<span class="o">=</span>Debug --param llvm_site_config<span class="o">=</span>..<span class="n">/build/test/lit.site.cfg</span> test
+</pre></div>
+</div>
+<p>This example assumes that Python is in your PATH variable, you
+have built a Win32 Debug version of llvm with a standard out of
+line build. You should not see any unexpected failures, but will
+see many unsupported tests and expected failures.</p>
+<p>A specific test or test directory can be run with:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..\llvm<span class="p">></span> <span class="n">python</span> ..\build\bin\llvm-lit --param build_config<span class="o">=</span>Win<span class="m">32</span> --param build_mode<span class="o">=</span>Debug --param llvm_site_config<span class="o">=</span>..<span class="n">/build/test/lit.site.cfg</span> test<span class="n">/path/to/test</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</li>
+</ol>
+</div>
+<div class="section" id="an-example-using-the-llvm-tool-chain">
+<h2><a class="toc-backref" href="#id8">An Example Using the LLVM Tool Chain</a><a class="headerlink" href="#an-example-using-the-llvm-tool-chain" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic">
+<li><p class="first">First, create a simple C file, name it ‘<tt class="docutils literal"><span class="pre">hello.c</span></tt>‘:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</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>
+</li>
+<li><p class="first">Next, compile the C file into an LLVM bitcode file:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">clang</span> -c hello.c -emit-llvm -o hello.bc
+</pre></div>
+</div>
+<p>This will create the result file <tt class="docutils literal"><span class="pre">hello.bc</span></tt> which is the LLVM bitcode
+that corresponds the compiled program and the library facilities that
+it required. You can execute this file directly using <tt class="docutils literal"><span class="pre">lli</span></tt> tool,
+compile it to native assembly with the <tt class="docutils literal"><span class="pre">llc</span></tt>, optimize or analyze it
+further with the <tt class="docutils literal"><span class="pre">opt</span></tt> tool, etc.</p>
+<p>Alternatively you can directly output an executable with clang with:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">clang</span> hello.c -o hello.exe
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">-o</span> <span class="pre">hello.exe</span></tt> is required because clang currently outputs <tt class="docutils literal"><span class="pre">a.out</span></tt>
+when neither <tt class="docutils literal"><span class="pre">-o</span></tt> nor <tt class="docutils literal"><span class="pre">-c</span></tt> are given.</p>
+</li>
+<li><p class="first">Run the program using the just-in-time compiler:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">lli</span> hello.bc
+</pre></div>
+</div>
+</li>
+<li><p class="first">Use the <tt class="docutils literal"><span class="pre">llvm-dis</span></tt> utility to take a look at the LLVM assembly code:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">llvm</span>-dis <span class="p"><</span> <span class="n">hello</span>.bc <span class="p">|</span> <span class="n">more</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Compile the program to object code using the LLC code generator:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">llc</span> -filetype<span class="o">=</span>obj hello.bc
+</pre></div>
+</div>
+</li>
+<li><p class="first">Link to binary using Microsoft link:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">link</span> hello.obj -defaultlib:libcmt
+</pre></div>
+</div>
+</li>
+<li><p class="first">Execute the native code program:</p>
+<div class="highlight-bat"><div class="highlight"><pre>C:\..<span class="p">></span> <span class="n">hello</span>.exe
+</pre></div>
+</div>
+</li>
+</ol>
+</div>
+<div class="section" id="common-problems">
+<h2><a class="toc-backref" href="#id9">Common Problems</a><a class="headerlink" href="#common-problems" title="Permalink to this headline">¶</a></h2>
+<p>If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the <a class="reference external" href="FAQ.html">Frequently Asked Questions</a> page.</p>
+</div>
+<div class="section" id="links">
+<h2><a class="toc-backref" href="#id10">Links</a><a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h2>
+<p>This document is just an <strong>introduction</strong> to how to use LLVM to do some simple
+things... there are many more interesting and complicated things that you can
+do that aren’t documented here (but we’ll gladly accept a patch if you want to
+write something up!). For more information about LLVM, check out:</p>
+<ul class="simple">
+<li><a class="reference external" href="http://llvm.org/">LLVM homepage</a></li>
+<li><a class="reference external" href="http://llvm.org/doxygen/">LLVM doxygen tree</a></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="FAQ.html" title="Frequently Asked Questions (FAQ)"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GettingStarted.html" title="Getting Started with the LLVM System"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/GoldPlugin.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/GoldPlugin.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/GoldPlugin.html (added)
+++ www-releases/trunk/3.4.1/docs/GoldPlugin.html Wed May 7 15:09:32 2014
@@ -0,0 +1,247 @@
+
+
+<!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>The LLVM gold plugin — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="LLVMâs Optional Rich Disassembly Output" href="MarkedUpDisassembly.html" />
+ <link rel="prev" title="Debugging JIT-ed Code With GDB" href="DebuggingJITedCode.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="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ 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="the-llvm-gold-plugin">
+<h1>The LLVM gold plugin<a class="headerlink" href="#the-llvm-gold-plugin" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Building with link time optimization requires cooperation from
+the system linker. LTO support on Linux systems requires that you use the
+<a class="reference external" href="http://sourceware.org/binutils">gold linker</a> which supports LTO via plugins. This is the same mechanism
+used by the <a class="reference external" href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a> project.</p>
+<p>The LLVM gold plugin implements the gold plugin interface on top of
+<a class="reference internal" href="LinkTimeOptimization.html#liblto"><em>libLTO</em></a>. The same plugin can also be used by other tools such as
+<tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm</span></tt>.</p>
+</div>
+<div class="section" id="how-to-build-it">
+<span id="lto-how-to-build"></span><h2>How to build it<a class="headerlink" href="#how-to-build-it" title="Permalink to this headline">¶</a></h2>
+<p>You need to have gold with plugin support and build the LLVMgold plugin.
+Check whether you have gold running <tt class="docutils literal"><span class="pre">/usr/bin/ld</span> <span class="pre">-v</span></tt>. It will report “GNU
+gold” or else “GNU ld” if not. If you have gold, check for plugin support
+by running <tt class="docutils literal"><span class="pre">/usr/bin/ld</span> <span class="pre">-plugin</span></tt>. If it complains “missing argument” then
+you have plugin support. If not, such as an “unknown option” error then you
+will either need to build gold or install a version with plugin support.</p>
+<ul>
+<li><p class="first">Download, configure and build gold with plugin support:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils
+<span class="nv">$ </span>mkdir build
+<span class="nv">$ </span><span class="nb">cd </span>build
+<span class="nv">$ </span>../binutils/configure --enable-gold --enable-plugins --disable-werror
+<span class="nv">$ </span>make all-gold
+</pre></div>
+</div>
+<p>That should leave you with <tt class="docutils literal"><span class="pre">build/gold/ld-new</span></tt> which supports
+the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option. Running <tt class="docutils literal"><span class="pre">make</span></tt> will additionally build
+<tt class="docutils literal"><span class="pre">build/binutils/ar</span></tt> and <tt class="docutils literal"><span class="pre">nm-new</span></tt> binaries supporting plugins.</p>
+</li>
+<li><p class="first">Build the LLVMgold plugin: Configure LLVM with
+<tt class="docutils literal"><span class="pre">--with-binutils-include=/path/to/binutils/include</span></tt> and run
+<tt class="docutils literal"><span class="pre">make</span></tt>.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>The linker takes a <tt class="docutils literal"><span class="pre">-plugin</span></tt> option that points to the path of
+the plugin <tt class="docutils literal"><span class="pre">.so</span></tt> file. To find out what link command <tt class="docutils literal"><span class="pre">gcc</span></tt>
+would run in a given situation, run <tt class="docutils literal"><span class="pre">gcc</span> <span class="pre">-v</span> <span class="pre">[...]</span></tt> and
+look for the line where it runs <tt class="docutils literal"><span class="pre">collect2</span></tt>. Replace that with
+<tt class="docutils literal"><span class="pre">ld-new</span> <span class="pre">-plugin</span> <span class="pre">/path/to/LLVMgold.so</span></tt> to test it out. Once you’re
+ready to switch to using gold, backup your existing <tt class="docutils literal"><span class="pre">/usr/bin/ld</span></tt>
+then replace it with <tt class="docutils literal"><span class="pre">ld-new</span></tt>.</p>
+<p>You should produce bitcode files from <tt class="docutils literal"><span class="pre">clang</span></tt> with the option
+<tt class="docutils literal"><span class="pre">-flto</span></tt>. This flag will also cause <tt class="docutils literal"><span class="pre">clang</span></tt> to look for the gold plugin in
+the <tt class="docutils literal"><span class="pre">lib</span></tt> directory under its prefix and pass the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option to
+<tt class="docutils literal"><span class="pre">ld</span></tt>. It will not look for an alternate linker, which is why you need
+gold to be the installed system linker in your path.</p>
+<p><tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm</span></tt> also accept the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option and it’s possible to
+to install <tt class="docutils literal"><span class="pre">LLVMgold.so</span></tt> to <tt class="docutils literal"><span class="pre">/usr/lib/bfd-plugins</span></tt> for a seamless setup.
+If you built your own gold, be sure to install the <tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm-new</span></tt> you
+built to <tt class="docutils literal"><span class="pre">/usr/bin</span></tt>.</p>
+<div class="section" id="example-of-link-time-optimization">
+<h3>Example of link time optimization<a class="headerlink" href="#example-of-link-time-optimization" title="Permalink to this headline">¶</a></h3>
+<p>The following example shows a worked example of the gold plugin mixing LLVM
+bitcode and native code.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">---</span> <span class="n">a</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
+<span class="cp">#include <stdio.h></span>
+
+<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+<span class="k">extern</span> <span class="kt">void</span> <span class="nf">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"Foo2</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">foo3</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo4</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo1</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="o">---</span> <span class="n">b</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
+<span class="cp">#include <stdio.h></span>
+
+<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">foo2</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"Foo4"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-bash"><div class="highlight"><pre>--- <span class="nb">command </span>lines ---
+<span class="nv">$ </span>clang -flto a.c -c -o a.o <span class="c"># <-- a.o is LLVM bitcode file</span>
+<span class="nv">$ </span>ar q a.a a.o <span class="c"># <-- a.a is an archive with LLVM bitcode</span>
+<span class="nv">$ </span>clang b.c -c -o b.o <span class="c"># <-- b.o is native object file</span>
+<span class="nv">$ </span>clang -flto a.a b.o -o main <span class="c"># <-- link with LLVMgold plugin</span>
+</pre></div>
+</div>
+<p>Gold informs the plugin that foo3 is never referenced outside the IR,
+leading LLVM to delete that function. However, unlike in the <a class="reference internal" href="LinkTimeOptimization.html#liblto-example"><em>libLTO
+example</em></a> gold does not currently eliminate foo4.</p>
+</div>
+</div>
+<div class="section" id="quickstart-for-using-lto-with-autotooled-projects">
+<h2>Quickstart for using LTO with autotooled projects<a class="headerlink" href="#quickstart-for-using-lto-with-autotooled-projects" title="Permalink to this headline">¶</a></h2>
+<p>Once your system <tt class="docutils literal"><span class="pre">ld</span></tt>, <tt class="docutils literal"><span class="pre">ar</span></tt>, and <tt class="docutils literal"><span class="pre">nm</span></tt> all support LLVM bitcode,
+everything is in place for an easy to use LTO build of autotooled projects:</p>
+<ul>
+<li><p class="first">Follow the instructions <a class="reference internal" href="#lto-how-to-build"><em>on how to build LLVMgold.so</em></a>.</p>
+</li>
+<li><p class="first">Install the newly built binutils to <tt class="docutils literal"><span class="pre">$PREFIX</span></tt></p>
+</li>
+<li><p class="first">Copy <tt class="docutils literal"><span class="pre">Release/lib/LLVMgold.so</span></tt> to <tt class="docutils literal"><span class="pre">$PREFIX/lib/bfd-plugins/</span></tt></p>
+</li>
+<li><p class="first">Set environment variables (<tt class="docutils literal"><span class="pre">$PREFIX</span></tt> is where you installed clang and
+binutils):</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nb">export </span><span class="nv">CC</span><span class="o">=</span><span class="s2">"$PREFIX/bin/clang -flto"</span>
+<span class="nb">export </span><span class="nv">CXX</span><span class="o">=</span><span class="s2">"$PREFIX/bin/clang++ -flto"</span>
+<span class="nb">export </span><span class="nv">AR</span><span class="o">=</span><span class="s2">"$PREFIX/bin/ar"</span>
+<span class="nb">export </span><span class="nv">NM</span><span class="o">=</span><span class="s2">"$PREFIX/bin/nm"</span>
+<span class="nb">export </span><span class="nv">RANLIB</span><span class="o">=</span>/bin/true <span class="c">#ranlib is not needed, and doesn't support .bc files in .a</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Or you can just set your path:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"$PREFIX/bin:$PATH"</span>
+<span class="nb">export </span><span class="nv">CC</span><span class="o">=</span><span class="s2">"clang -flto"</span>
+<span class="nb">export </span><span class="nv">CXX</span><span class="o">=</span><span class="s2">"clang++ -flto"</span>
+<span class="nb">export </span><span class="nv">RANLIB</span><span class="o">=</span>/bin/true
+</pre></div>
+</div>
+</li>
+<li><p class="first">Configure and build the project as usual:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% ./configure <span class="o">&&</span> make <span class="o">&&</span> make check
+</pre></div>
+</div>
+</li>
+</ul>
+<p>The environment variable settings may work for non-autotooled projects too,
+but you may need to set the <tt class="docutils literal"><span class="pre">LD</span></tt> environment variable as well.</p>
+</div>
+<div class="section" id="licensing">
+<h2>Licensing<a class="headerlink" href="#licensing" title="Permalink to this headline">¶</a></h2>
+<p>Gold is licensed under the GPLv3. LLVMgold uses the interface file
+<tt class="docutils literal"><span class="pre">plugin-api.h</span></tt> from gold which means that the resulting <tt class="docutils literal"><span class="pre">LLVMgold.so</span></tt>
+binary is also GPLv3. This can still be used to link non-GPLv3 programs
+just as much as gold could without the plugin.</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="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToAddABuilder.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToAddABuilder.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToAddABuilder.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToAddABuilder.html Wed May 7 15:09:32 2014
@@ -0,0 +1,181 @@
+
+
+<!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>How To Add Your Build Configuration To LLVM Buildbot Infrastructure — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="yaml2obj" href="yaml2obj.html" />
+ <link rel="prev" title="The LLVM Lexicon" href="Lexicon.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="yaml2obj.html" title="yaml2obj"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ 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="how-to-add-your-build-configuration-to-llvm-buildbot-infrastructure">
+<h1>How To Add Your Build Configuration To LLVM Buildbot Infrastructure<a class="headerlink" href="#how-to-add-your-build-configuration-to-llvm-buildbot-infrastructure" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about adding a build configuration and
+buildslave to private slave builder to LLVM Buildbot Infrastructure
+<a class="reference external" href="http://lab.llvm.org:8011">http://lab.llvm.org:8011</a>.</p>
+</div>
+<div class="section" id="steps-to-add-builder-to-llvm-buildbot">
+<h2>Steps To Add Builder To LLVM Buildbot<a class="headerlink" href="#steps-to-add-builder-to-llvm-buildbot" title="Permalink to this headline">¶</a></h2>
+<p>Volunteers can provide their build machines to work as build slaves to
+public LLVM Buildbot.</p>
+<p>Here are the steps you can follow to do so:</p>
+<ol class="arabic">
+<li><p class="first">Check the existing build configurations to make sure the one you are
+interested in is not covered yet or gets built on your computer much
+faster than on the existing one. We prefer faster builds so developers
+will get feedback sooner after changes get committed.</p>
+</li>
+<li><p class="first">The computer you will be registering with the LLVM buildbot
+infrastructure should have all dependencies installed and you can
+actually build your configuration successfully. Please check what degree
+of parallelism (-j param) would give the fastest build. You can build
+multiple configurations on one computer.</p>
+</li>
+<li><p class="first">Install buildslave (currently we are using buildbot version 0.8.5).
+Depending on the platform, buildslave could be available to download and
+install with your packet manager, or you can download it directly from
+<a class="reference external" href="http://trac.buildbot.net">http://trac.buildbot.net</a> and install it manually.</p>
+</li>
+<li><p class="first">Create a designated user account, your buildslave will be running under,
+and set appropriate permissions.</p>
+</li>
+<li><p class="first">Choose the buildslave root directory (all builds will be placed under
+it), buildslave access name and password the build master will be using
+to authenticate your buildslave.</p>
+</li>
+<li><p class="first">Create a buildslave in context of that buildslave account. Point it to
+the <strong>lab.llvm.org</strong> port <strong>9990</strong> (see <a class="reference external" href="http://buildbot.net/buildbot/docs/current/full.html#creating-a-slave">Buildbot documentation,
+Creating a slave</a>
+for more details) by running the following command:</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>buildslave create-slave <buildslave-root-directory> <span class="se">\</span>
+ lab.llvm.org:9990 <span class="se">\</span>
+ <buildslave-access-name> <buildslave-access-password>
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+<li><p class="first">Fill the buildslave description and admin name/e-mail. Here is an
+example of the buildslave description:</p>
+<div class="highlight-python"><pre>Windows 7 x64
+Core i7 (2.66GHz), 16GB of RAM
+
+g++.exe (TDM-1 mingw32) 4.4.0
+GNU Binutils 2.19.1
+cmake version 2.8.4
+Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86</pre>
+</div>
+</li>
+<li><p class="first">Make sure you can actually start the buildslave successfully. Then set
+up your buildslave to start automatically at the start up time. See the
+buildbot documentation for help. You may want to restart your computer
+to see if it works.</p>
+</li>
+<li><p class="first">Send a patch which adds your build slave and your builder to zorg.</p>
+<ul class="simple">
+<li>slaves are added to <tt class="docutils literal"><span class="pre">buildbot/osuosl/master/config/slaves.py</span></tt></li>
+<li>builders are added to <tt class="docutils literal"><span class="pre">buildbot/osuosl/master/config/builders.py</span></tt></li>
+</ul>
+</li>
+<li><p class="first">Send the buildslave access name and the access password directly to
+<a class="reference external" href="mailto:gkistanova%40gmail.com">Galina Kistanova</a>, and wait till she
+will let you know that your changes are applied and buildmaster is
+reconfigured.</p>
+</li>
+<li><p class="first">Check the status of your buildslave on the <a class="reference external" href="http://lab.llvm.org:8011/waterfall">Waterfall Display</a> to make sure it is connected, and
+<tt class="docutils literal"><span class="pre">http://lab.llvm.org:8011/buildslaves/<your-buildslave-name></span></tt> to see
+if administrator contact and slave information are correct.</p>
+</li>
+<li><p class="first">Wait for the first build to succeed and enjoy.</p>
+</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="yaml2obj.html" title="yaml2obj"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToBuildOnARM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToBuildOnARM.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToBuildOnARM.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToBuildOnARM.html Wed May 7 15:09:32 2014
@@ -0,0 +1,162 @@
+
+
+<!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>How To Build On ARM — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="How To Cross-Compile Clang/LLVM using Clang/LLVM" href="HowToCrossCompileLLVM.html" />
+ <link rel="prev" title="Building LLVM with CMake" href="CMake.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="HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CMake.html" title="Building LLVM with CMake"
+ 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="how-to-build-on-arm">
+<h1>How To Build On ARM<a class="headerlink" href="#how-to-build-on-arm" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about building/testing LLVM and
+Clang on an ARM machine.</p>
+<p>This document is <em>NOT</em> tailored to help you cross-compile LLVM/Clang
+to ARM on another architecture, for example an x86_64 machine. To find
+out more about cross-compiling, please check <a class="reference internal" href="HowToCrossCompileLLVM.html"><em>How To Cross-Compile Clang/LLVM using Clang/LLVM</em></a>.</p>
+</div>
+<div class="section" id="notes-on-building-llvm-clang-on-arm">
+<h2>Notes On Building LLVM/Clang on ARM<a class="headerlink" href="#notes-on-building-llvm-clang-on-arm" title="Permalink to this headline">¶</a></h2>
+<p>Here are some notes on building/testing LLVM/Clang on ARM. Note that
+ARM encompasses a wide variety of CPUs; this advice is primarily based
+on the ARMv6 and ARMv7 architectures and may be inapplicable to older chips.</p>
+<ol class="arabic">
+<li><p class="first">If you are building LLVM/Clang on an ARM board with 1G of memory or less,
+please use <tt class="docutils literal"><span class="pre">gold</span></tt> rather then GNU <tt class="docutils literal"><span class="pre">ld</span></tt>.
+Building LLVM/Clang with <tt class="docutils literal"><span class="pre">--enable-optimized</span></tt>
+is preferred since it consumes less memory. Otherwise, the building
+process will very likely fail due to insufficient memory. In any
+case it is probably a good idea to set up a swap partition.</p>
+</li>
+<li><p class="first">If you want to run <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt> after building LLVM/Clang, to avoid
+false alarms (e.g., ARCMT failure) please use at least the following
+configuration:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>../<span class="nv">$LLVM_SRC_DIR</span>/configure --with-abi<span class="o">=</span>aapcs-vfp
+</pre></div>
+</div>
+</li>
+<li><p class="first">The most popular Linaro/Ubuntu OS’s for ARM boards, e.g., the
+Pandaboard, have become hard-float platforms. The following set
+of configuration options appears to be a good choice for this
+platform:</p>
+<div class="highlight-bash"><div class="highlight"><pre>./configure --build<span class="o">=</span>armv7l-unknown-linux-gnueabihf <span class="se">\</span>
+--host<span class="o">=</span>armv7l-unknown-linux-gnueabihf <span class="se">\</span>
+--target<span class="o">=</span>armv7l-unknown-linux-gnueabihf --with-cpu<span class="o">=</span>cortex-a9 <span class="se">\</span>
+--with-float<span class="o">=</span>hard --with-abi<span class="o">=</span>aapcs-vfp --with-fpu<span class="o">=</span>neon <span class="se">\</span>
+--enable-targets<span class="o">=</span>arm --enable-optimized --enable-assertions
+</pre></div>
+</div>
+</li>
+<li><p class="first">ARM development boards can be unstable and you may experience that cores
+are disappearing, caches being flushed on every big.LITTLE switch, and
+other similar issues. To help ease the effect of this, set the Linux
+scheduler to “performance” on <strong>all</strong> cores using this little script:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># The code below requires the package 'cpufrequtils' to be installed.</span>
+<span class="k">for</span> <span class="o">((</span><span class="nv">cpu</span><span class="o">=</span>0; cpu<<span class="sb">`</span>grep -c proc /proc/cpuinfo<span class="sb">`</span>; cpu++<span class="o">))</span>; <span class="k">do</span>
+<span class="k"> </span>sudo cpufreq-set -c <span class="nv">$cpu</span> -g performance
+<span class="k">done</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Running the build on SD cards is ok, but they are more prone to failures
+than good quality USB sticks, and those are more prone to failures than
+external hard-drives (those are also a lot faster). So, at least, you
+should consider to buy a fast USB stick. On systems with a fast eMMC,
+that’s a good option too.</p>
+</li>
+<li><p class="first">Make sure you have a decent power supply (dozens of dollars worth) that can
+provide <em>at least</em> 4 amperes, this is especially important if you use USB
+devices with your board.</p>
+</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="HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CMake.html" title="Building LLVM with CMake"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToCrossCompileLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToCrossCompileLLVM.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToCrossCompileLLVM.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToCrossCompileLLVM.html Wed May 7 15:09:32 2014
@@ -0,0 +1,260 @@
+
+
+<!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>How To Cross-Compile Clang/LLVM using Clang/LLVM — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="LLVM Command Guide" href="CommandGuide/index.html" />
+ <link rel="prev" title="How To Build On ARM" href="HowToBuildOnARM.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="CommandGuide/index.html" title="LLVM Command Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToBuildOnARM.html" title="How To Build On ARM"
+ 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="how-to-cross-compile-clang-llvm-using-clang-llvm">
+<h1>How To Cross-Compile Clang/LLVM using Clang/LLVM<a class="headerlink" href="#how-to-cross-compile-clang-llvm-using-clang-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about building LLVM and
+Clang on host machine, targeting another platform.</p>
+<p>For more information on how to use Clang as a cross-compiler,
+please check <a class="reference external" href="http://clang.llvm.org/docs/CrossCompilation.html">http://clang.llvm.org/docs/CrossCompilation.html</a>.</p>
+<p>TODO: Add MIPS and other platforms to this document.</p>
+</div>
+<div class="section" id="cross-compiling-from-x86-64-to-arm">
+<h2>Cross-Compiling from x86_64 to ARM<a class="headerlink" href="#cross-compiling-from-x86-64-to-arm" title="Permalink to this headline">¶</a></h2>
+<p>In this use case, we’ll be using CMake and Ninja, on a Debian-based Linux
+system, cross-compiling from an x86_64 host (most Intel and AMD chips
+nowadays) to a hard-float ARM target (most ARM targets nowadays).</p>
+<p>The packages you’ll need are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">cmake</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">ninja-build</span></tt> (from backports in Ubuntu)</li>
+<li><tt class="docutils literal"><span class="pre">gcc-4.7-arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">gcc-4.7-multilib-arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">binutils-arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libgcc1-armhf-cross</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libsfgcc1-armhf-cross</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libstdc++6-armhf-cross</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">libstdc++6-4.7-dev-armhf-cross</span></tt></li>
+</ul>
+</div></blockquote>
+<div class="section" id="configuring-cmake">
+<h3>Configuring CMake<a class="headerlink" href="#configuring-cmake" title="Permalink to this headline">¶</a></h3>
+<p>For more information on how to configure CMake for LLVM/Clang,
+see <a class="reference internal" href="CMake.html"><em>Building LLVM with CMake</em></a>.</p>
+<dl class="docutils">
+<dt>The CMake options you need to add are:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_CROSSCOMPILING=True</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_INSTALL_PREFIX=<install-dir></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_TARGET_ARCH=ARM</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DLLVM_TARGETS_TO_BUILD=ARM</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">-DCMAKE_CXX_FLAGS='-target</span> <span class="pre">armv7a-linux-gnueabihf</span> <span class="pre">-mcpu=cortex-a9</span> <span class="pre">-I/usr/arm-linux-gnueabihf/include/c++/4.7.2/arm-linux-gnueabihf/</span> <span class="pre">-I/usr/arm-linux-gnueabihf/include/</span> <span class="pre">-mfloat-abi=hard</span> <span class="pre">-ccc-gcc-name</span> <span class="pre">arm-linux-gnueabihf-gcc'</span></tt></li>
+</ul>
+</dd>
+</dl>
+<p>The TableGen options are required to compile it with the host compiler,
+so you’ll need to compile LLVM (or at least <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt>) to your host
+platform before you start. The CXX flags define the target, cpu (which
+defaults to <tt class="docutils literal"><span class="pre">fpu=VFP3</span></tt> with NEON), and forcing the hard-float ABI. If you’re
+using Clang as a cross-compiler, you will <em>also</em> have to set <tt class="docutils literal"><span class="pre">-ccc-gcc-name</span></tt>,
+to make sure it picks the correct linker.</p>
+<p>Most of the time, what you want is to have a native compiler to the
+platform itself, but not others. It might not even be feasible to
+produce x86 binaries from ARM targets, so there’s no point in compiling
+all back-ends. For that reason, you should also set the
+<tt class="docutils literal"><span class="pre">TARGETS_TO_BUILD</span></tt> to only build the ARM back-end.</p>
+<p>You must set the <tt class="docutils literal"><span class="pre">CMAKE_INSTALL_PREFIX</span></tt>, otherwise a <tt class="docutils literal"><span class="pre">ninja</span> <span class="pre">install</span></tt>
+will copy ARM binaries to your root filesystem, which is not what you
+want.</p>
+</div>
+<div class="section" id="hacks">
+<h3>Hacks<a class="headerlink" href="#hacks" title="Permalink to this headline">¶</a></h3>
+<p>There are some bugs in current LLVM, which require some fiddling before
+running CMake:</p>
+<ol class="arabic">
+<li><p class="first">If you’re using Clang as the cross-compiler, there is a problem in
+the LLVM ARM back-end that is producing absolute relocations on
+position-independent code (<tt class="docutils literal"><span class="pre">R_ARM_THM_MOVW_ABS_NC</span></tt>), so for now, you
+should disable PIC:</p>
+<div class="highlight-bash"><div class="highlight"><pre>-DLLVM_ENABLE_PIC<span class="o">=</span>False
+</pre></div>
+</div>
+<p>This is not a problem, since Clang/LLVM libraries are statically
+linked anyway, it shouldn’t affect much.</p>
+</li>
+<li><p class="first">The ARM libraries won’t be installed in your system, and possibly
+not easily installable anyway, so you’ll have to build/download
+them separately. But the CMake prepare step, which checks for
+dependencies, will check the <em>host</em> libraries, not the <em>target</em>
+ones.</p>
+<p>A quick way of getting the libraries is to download them from
+a distribution repository, like Debian (<a class="reference external" href="http://packages.debian.org/wheezy/">http://packages.debian.org/wheezy/</a>),
+and download the missing libraries. Note that the <tt class="docutils literal"><span class="pre">libXXX</span></tt>
+will have the shared objects (<tt class="docutils literal"><span class="pre">.so</span></tt>) and the <tt class="docutils literal"><span class="pre">libXXX-dev</span></tt> will
+give you the headers and the static (<tt class="docutils literal"><span class="pre">.a</span></tt>) library. Just in
+case, download both.</p>
+<p>The ones you need for ARM are: <tt class="docutils literal"><span class="pre">libtinfo</span></tt>, <tt class="docutils literal"><span class="pre">zlib1g</span></tt>,
+<tt class="docutils literal"><span class="pre">libxml2</span></tt> and <tt class="docutils literal"><span class="pre">liblzma</span></tt>. In the Debian repository you’ll
+find downloads for all architectures.</p>
+<p>After you download and unpack all <tt class="docutils literal"><span class="pre">.deb</span></tt> packages, copy all
+<tt class="docutils literal"><span class="pre">.so</span></tt> and <tt class="docutils literal"><span class="pre">.a</span></tt> to a directory, make the appropriate
+symbolic links (if necessary), and add the relevant <tt class="docutils literal"><span class="pre">-L</span></tt>
+and <tt class="docutils literal"><span class="pre">-I</span></tt> paths to <tt class="docutils literal"><span class="pre">-DCMAKE_CXX_FLAGS</span></tt> above.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="running-cmake-and-building">
+<h3>Running CMake and Building<a class="headerlink" href="#running-cmake-and-building" title="Permalink to this headline">¶</a></h3>
+<p>Finally, if you’re using your platform compiler, run:</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>cmake -G Ninja <<span class="nb">source</span>-dir> <options above>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If you’re using Clang as the cross-compiler, run:</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ CC</span><span class="o">=</span><span class="s1">'clang'</span> <span class="nv">CXX</span><span class="o">=</span><span class="s1">'clang++'</span> cmake -G Ninja <<span class="nb">source</span>-dir> <options above>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If you have <tt class="docutils literal"><span class="pre">clang</span></tt>/<tt class="docutils literal"><span class="pre">clang++</span></tt> on the path, it should just work, and special
+Ninja files will be created in the build directory. I strongly suggest
+you to run <tt class="docutils literal"><span class="pre">cmake</span></tt> on a separate build directory, <em>not</em> inside the
+source tree.</p>
+<p>To build, simply type:</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ninja
+</pre></div>
+</div>
+</div></blockquote>
+<p>It should automatically find out how many cores you have, what are
+the rules that needs building and will build the whole thing.</p>
+<p>You can’t run <tt class="docutils literal"><span class="pre">ninja</span> <span class="pre">check-all</span></tt> on this tree because the created
+binaries are targeted to ARM, not x86_64.</p>
+</div>
+<div class="section" id="installing-and-using">
+<h3>Installing and Using<a class="headerlink" href="#installing-and-using" title="Permalink to this headline">¶</a></h3>
+<p>After the LLVM/Clang has built successfully, you should install it
+via:</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ninja install
+</pre></div>
+</div>
+</div></blockquote>
+<p>which will create a sysroot on the install-dir. You can then tar
+that directory into a binary with the full triple name (for easy
+identification), like:</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ln -sf <install-dir> arm-linux-gnueabihf-clang
+<span class="nv">$ </span>tar zchf arm-linux-gnueabihf-clang.tar.gz arm-linux-gnueabihf-clang
+</pre></div>
+</div>
+</div></blockquote>
+<p>If you copy that tarball to your target board, you’ll be able to use
+it for running the test-suite, for example. Follow the guidelines at
+<a class="reference external" href="http://llvm.org/docs/lnt/quickstart.html">http://llvm.org/docs/lnt/quickstart.html</a>, unpack the tarball in the
+test directory, and use options:</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>./sandbox/bin/python sandbox/bin/lnt runtest nt <span class="se">\</span>
+ --sandbox sandbox <span class="se">\</span>
+ --test-suite <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span>/test-suite <span class="se">\</span>
+ --cc <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span>/arm-linux-gnueabihf-clang/bin/clang <span class="se">\</span>
+ --cxx <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span>/arm-linux-gnueabihf-clang/bin/clang++
+</pre></div>
+</div>
+</div></blockquote>
+<p>Remember to add the <tt class="docutils literal"><span class="pre">-jN</span></tt> options to <tt class="docutils literal"><span class="pre">lnt</span></tt> to the number of CPUs
+on your board. Also, the path to your clang has to be absolute, so
+you’ll need the <cite>pwd</cite> trick above.</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="CommandGuide/index.html" title="LLVM Command Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToBuildOnARM.html" title="How To Build On ARM"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToReleaseLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToReleaseLLVM.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToReleaseLLVM.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToReleaseLLVM.html Wed May 7 15:09:32 2014
@@ -0,0 +1,565 @@
+
+
+<!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>How To Release LLVM To The Public — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="Advice on Packaging LLVM" href="Packaging.html" />
+ <link rel="prev" title="LLVMBuild Guide" href="LLVMBuild.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="Packaging.html" title="Advice on Packaging LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LLVMBuild.html" title="LLVMBuild 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="how-to-release-llvm-to-the-public">
+<h1>How To Release LLVM To The Public<a class="headerlink" href="#how-to-release-llvm-to-the-public" 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="id2">Introduction</a></li>
+<li><a class="reference internal" href="#release-timeline" id="id3">Release Timeline</a></li>
+<li><a class="reference internal" href="#release-process" id="id4">Release Process</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about successfully releasing LLVM —
+including subprojects: e.g., <tt class="docutils literal"><span class="pre">clang</span></tt> and <tt class="docutils literal"><span class="pre">dragonegg</span></tt> — to the public. It
+is the Release Manager’s responsibility to ensure that a high quality build of
+LLVM is released.</p>
+<p>If you’re looking for the document on how to test the release candidates and
+create the binary packages, please refer to the <a class="reference internal" href="ReleaseProcess.html"><em>How To Validate a New Release</em></a> instead.</p>
+</div>
+<div class="section" id="release-timeline">
+<span id="timeline"></span><h2><a class="toc-backref" href="#id3">Release Timeline</a><a class="headerlink" href="#release-timeline" title="Permalink to this headline">¶</a></h2>
+<p>LLVM is released on a time based schedule — roughly every 6 months. We do
+not normally have dot releases because of the nature of LLVM’s incremental
+development philosophy. That said, the only thing preventing dot releases for
+critical bug fixes from happening is a lack of resources — testers,
+machines, time, etc. And, because of the high quality we desire for LLVM
+releases, we cannot allow for a truncated form of release qualification.</p>
+<p>The release process is roughly as follows:</p>
+<ul class="simple">
+<li>Set code freeze and branch creation date for 6 months after last code freeze
+date. Announce release schedule to the LLVM community and update the website.</li>
+<li>Create release branch and begin release process.</li>
+<li>Send out release candidate sources for first round of testing. Testing lasts
+7-10 days. During the first round of testing, any regressions found should be
+fixed. Patches are merged from mainline into the release branch. Also, all
+features need to be completed during this time. Any features not completed at
+the end of the first round of testing will be removed or disabled for the
+release.</li>
+<li>Generate and send out the second release candidate sources. Only <em>critial</em>
+bugs found during this testing phase will be fixed. Any bugs introduced by
+merged patches will be fixed. If so a third round of testing is needed.</li>
+<li>The release notes are updated.</li>
+<li>Finally, release!</li>
+</ul>
+</div>
+<div class="section" id="release-process">
+<h2><a class="toc-backref" href="#id4">Release Process</a><a class="headerlink" href="#release-process" title="Permalink to this headline">¶</a></h2>
+<div class="contents local topic" id="id1">
+<ul class="simple">
+<li><a class="reference internal" href="#release-administrative-tasks" id="id5">Release Administrative Tasks</a><ul>
+<li><a class="reference internal" href="#create-release-branch" id="id6">Create Release Branch</a></li>
+<li><a class="reference internal" href="#update-llvm-version" id="id7">Update LLVM Version</a></li>
+<li><a class="reference internal" href="#build-the-llvm-release-candidates" id="id8">Build the LLVM Release Candidates</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#building-the-release" id="id9">Building the Release</a><ul>
+<li><a class="reference internal" href="#build-llvm" id="id10">Build LLVM</a></li>
+<li><a class="reference internal" href="#build-clang-binary-distribution" id="id11">Build Clang Binary Distribution</a></li>
+<li><a class="reference internal" href="#target-specific-build-details" id="id12">Target Specific Build Details</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#release-qualification-criteria" id="id13">Release Qualification Criteria</a><ul>
+<li><a class="reference internal" href="#qualify-llvm" id="id14">Qualify LLVM</a></li>
+<li><a class="reference internal" href="#qualify-clang" id="id15">Qualify Clang</a></li>
+<li><a class="reference internal" href="#specific-target-qualification-details" id="id16">Specific Target Qualification Details</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#community-testing" id="id17">Community Testing</a></li>
+<li><a class="reference internal" href="#release-patch-rules" id="id18">Release Patch Rules</a></li>
+<li><a class="reference internal" href="#release-final-tasks" id="id19">Release Final Tasks</a><ul>
+<li><a class="reference internal" href="#update-documentation" id="id20">Update Documentation</a></li>
+<li><a class="reference internal" href="#tag-the-llvm-final-release" id="id21">Tag the LLVM Final Release</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#update-the-llvm-demo-page" id="id22">Update the LLVM Demo Page</a><ul>
+<li><a class="reference internal" href="#update-the-llvm-website" id="id23">Update the LLVM Website</a></li>
+<li><a class="reference internal" href="#announce-the-release" id="id24">Announce the Release</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="release-administrative-tasks">
+<h3><a class="toc-backref" href="#id5">Release Administrative Tasks</a><a class="headerlink" href="#release-administrative-tasks" title="Permalink to this headline">¶</a></h3>
+<p>This section describes a few administrative tasks that need to be done for the
+release process to begin. Specifically, it involves:</p>
+<ul class="simple">
+<li>Creating the release branch,</li>
+<li>Setting version numbers, and</li>
+<li>Tagging release candidates for the release team to begin testing.</li>
+</ul>
+<div class="section" id="create-release-branch">
+<h4><a class="toc-backref" href="#id6">Create Release Branch</a><a class="headerlink" href="#create-release-branch" title="Permalink to this headline">¶</a></h4>
+<p>Branch the Subversion trunk using the following procedure:</p>
+<ol class="arabic">
+<li><p class="first">Remind developers that the release branching is imminent and to refrain from
+committing patches that might break the build. E.g., new features, large
+patches for works in progress, an overhaul of the type system, an exciting
+new TableGen feature, etc.</p>
+</li>
+<li><p class="first">Verify that the current Subversion trunk is in decent shape by
+examining nightly tester and buildbot results.</p>
+</li>
+<li><p class="first">Create the release branch for <tt class="docutils literal"><span class="pre">llvm</span></tt>, <tt class="docutils literal"><span class="pre">clang</span></tt>, the <tt class="docutils literal"><span class="pre">test-suite</span></tt>, and
+<tt class="docutils literal"><span class="pre">dragonegg</span></tt> from the last known good revision. The branch’s name is
+<tt class="docutils literal"><span class="pre">release_XY</span></tt>, where <tt class="docutils literal"><span class="pre">X</span></tt> is the major and <tt class="docutils literal"><span class="pre">Y</span></tt> the minor release
+numbers. The branches should be created using the following commands:</p>
+<div class="highlight-python"><pre>$ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
+ https://llvm.org/svn/llvm-project/llvm/branches/release_XY
+
+$ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
+ https://llvm.org/svn/llvm-project/cfe/branches/release_XY
+
+$ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
+ https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY
+
+$ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
+ https://llvm.org/svn/llvm-project/test-suite/branches/release_XY</pre>
+</div>
+</li>
+<li><p class="first">Advise developers that they may now check their patches into the Subversion
+tree again.</p>
+</li>
+<li><p class="first">The Release Manager should switch to the release branch, because all changes
+to the release will now be done in the branch. The easiest way to do this is
+to grab a working copy using the following commands:</p>
+<div class="highlight-python"><pre>$ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y
+
+$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y
+
+$ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY dragonegg-X.Y
+
+$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y</pre>
+</div>
+</li>
+</ol>
+</div>
+<div class="section" id="update-llvm-version">
+<h4><a class="toc-backref" href="#id7">Update LLVM Version</a><a class="headerlink" href="#update-llvm-version" title="Permalink to this headline">¶</a></h4>
+<p>After creating the LLVM release branch, update the release branches’
+<tt class="docutils literal"><span class="pre">autoconf</span></tt> and <tt class="docutils literal"><span class="pre">configure.ac</span></tt> versions from ‘<tt class="docutils literal"><span class="pre">X.Ysvn</span></tt>‘ to ‘<tt class="docutils literal"><span class="pre">X.Y</span></tt>‘.
+Update it on mainline as well to be the next version (‘<tt class="docutils literal"><span class="pre">X.Y+1svn</span></tt>‘).
+Regenerate the configure scripts for both <tt class="docutils literal"><span class="pre">llvm</span></tt> and the <tt class="docutils literal"><span class="pre">test-suite</span></tt>.</p>
+<p>In addition, the version numbers of all the Bugzilla components must be updated
+for the next release.</p>
+</div>
+<div class="section" id="build-the-llvm-release-candidates">
+<h4><a class="toc-backref" href="#id8">Build the LLVM Release Candidates</a><a class="headerlink" href="#build-the-llvm-release-candidates" title="Permalink to this headline">¶</a></h4>
+<p>Create release candidates for <tt class="docutils literal"><span class="pre">llvm</span></tt>, <tt class="docutils literal"><span class="pre">clang</span></tt>, <tt class="docutils literal"><span class="pre">dragonegg</span></tt>, and the LLVM
+<tt class="docutils literal"><span class="pre">test-suite</span></tt> by tagging the branch with the respective release candidate
+number. For instance, to create <strong>Release Candidate 1</strong> you would issue the
+following commands:</p>
+<div class="highlight-python"><pre>$ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY
+$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
+ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1
+
+$ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY
+$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
+ https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1
+
+$ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY
+$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
+ https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1
+
+$ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY
+$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
+ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1</pre>
+</div>
+<p>Similarly, <strong>Release Candidate 2</strong> would be named <tt class="docutils literal"><span class="pre">RC2</span></tt> and so on. This keeps
+a permanent copy of the release candidate around for people to export and build
+as they wish. The final released sources will be tagged in the <tt class="docutils literal"><span class="pre">RELEASE_XY</span></tt>
+directory as <tt class="docutils literal"><span class="pre">Final</span></tt> (c.f. <a class="reference internal" href="#tag"><em>Tag the LLVM Final Release</em></a>).</p>
+<p>The Release Manager may supply pre-packaged source tarballs for users. This can
+be done with the following commands:</p>
+<div class="highlight-python"><pre>$ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1 llvm-X.Yrc1
+$ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1 clang-X.Yrc1
+$ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1 dragonegg-X.Yrc1
+$ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1 llvm-test-X.Yrc1
+
+$ tar -cvf - llvm-X.Yrc1 | gzip > llvm-X.Yrc1.src.tar.gz
+$ tar -cvf - clang-X.Yrc1 | gzip > clang-X.Yrc1.src.tar.gz
+$ tar -cvf - dragonegg-X.Yrc1 | gzip > dragonegg-X.Yrc1.src.tar.gz
+$ tar -cvf - llvm-test-X.Yrc1 | gzip > llvm-test-X.Yrc1.src.tar.gz</pre>
+</div>
+</div>
+</div>
+<div class="section" id="building-the-release">
+<h3><a class="toc-backref" href="#id9">Building the Release</a><a class="headerlink" href="#building-the-release" title="Permalink to this headline">¶</a></h3>
+<p>The builds of <tt class="docutils literal"><span class="pre">llvm</span></tt>, <tt class="docutils literal"><span class="pre">clang</span></tt>, and <tt class="docutils literal"><span class="pre">dragonegg</span></tt> <em>must</em> be free of
+errors and warnings in Debug, Release+Asserts, and Release builds. If all
+builds are clean, then the release passes Build Qualification.</p>
+<p>The <tt class="docutils literal"><span class="pre">make</span></tt> options for building the different modes:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="73%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Mode</th>
+<th class="head">Options</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>Debug</td>
+<td><tt class="docutils literal"><span class="pre">ENABLE_OPTIMIZED=0</span></tt></td>
+</tr>
+<tr class="row-odd"><td>Release+Asserts</td>
+<td><tt class="docutils literal"><span class="pre">ENABLE_OPTIMIZED=1</span></tt></td>
+</tr>
+<tr class="row-even"><td>Release</td>
+<td><tt class="docutils literal"><span class="pre">ENABLE_OPTIMIZED=1</span> <span class="pre">DISABLE_ASSERTIONS=1</span></tt></td>
+</tr>
+</tbody>
+</table>
+<div class="section" id="build-llvm">
+<h4><a class="toc-backref" href="#id10">Build LLVM</a><a class="headerlink" href="#build-llvm" title="Permalink to this headline">¶</a></h4>
+<p>Build <tt class="docutils literal"><span class="pre">Debug</span></tt>, <tt class="docutils literal"><span class="pre">Release+Asserts</span></tt>, and <tt class="docutils literal"><span class="pre">Release</span></tt> versions
+of <tt class="docutils literal"><span class="pre">llvm</span></tt> on all supported platforms. Directions to build <tt class="docutils literal"><span class="pre">llvm</span></tt>
+are <a class="reference internal" href="GettingStarted.html"><em>here</em></a>.</p>
+</div>
+<div class="section" id="build-clang-binary-distribution">
+<h4><a class="toc-backref" href="#id11">Build Clang Binary Distribution</a><a class="headerlink" href="#build-clang-binary-distribution" title="Permalink to this headline">¶</a></h4>
+<p>Creating the <tt class="docutils literal"><span class="pre">clang</span></tt> binary distribution (Debug/Release+Asserts/Release)
+requires performing the following steps for each supported platform:</p>
+<ol class="arabic simple">
+<li>Build clang according to the directions <a class="reference external" href="http://clang.llvm.org/get_started.html">here</a>.</li>
+<li>Build both a Debug and Release version of clang. The binary will be the
+Release build.</li>
+<li>Package <tt class="docutils literal"><span class="pre">clang</span></tt> (details to follow).</li>
+</ol>
+</div>
+<div class="section" id="target-specific-build-details">
+<h4><a class="toc-backref" href="#id12">Target Specific Build Details</a><a class="headerlink" href="#target-specific-build-details" title="Permalink to this headline">¶</a></h4>
+<p>The table below specifies which compilers are used for each Arch/OS combination
+when qualifying the build of <tt class="docutils literal"><span class="pre">llvm</span></tt>, <tt class="docutils literal"><span class="pre">clang</span></tt>, and <tt class="docutils literal"><span class="pre">dragonegg</span></tt>.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="29%" />
+<col width="43%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Architecture</th>
+<th class="head">OS</th>
+<th class="head">compiler</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>x86-32</td>
+<td>Mac OS 10.5</td>
+<td>gcc 4.0.1</td>
+</tr>
+<tr class="row-odd"><td>x86-32</td>
+<td>Linux</td>
+<td>gcc 4.2.X, gcc 4.3.X</td>
+</tr>
+<tr class="row-even"><td>x86-32</td>
+<td>FreeBSD</td>
+<td>gcc 4.2.X</td>
+</tr>
+<tr class="row-odd"><td>x86-32</td>
+<td>mingw</td>
+<td>gcc 3.4.5</td>
+</tr>
+<tr class="row-even"><td>x86-64</td>
+<td>Mac OS 10.5</td>
+<td>gcc 4.0.1</td>
+</tr>
+<tr class="row-odd"><td>x86-64</td>
+<td>Linux</td>
+<td>gcc 4.2.X, gcc 4.3.X</td>
+</tr>
+<tr class="row-even"><td>x86-64</td>
+<td>FreeBSD</td>
+<td>gcc 4.2.X</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="release-qualification-criteria">
+<h3><a class="toc-backref" href="#id13">Release Qualification Criteria</a><a class="headerlink" href="#release-qualification-criteria" title="Permalink to this headline">¶</a></h3>
+<p>A release is qualified when it has no regressions from the previous release (or
+baseline). Regressions are related to correctness first and performance second.
+(We may tolerate some minor performance regressions if they are deemed
+necessary for the general quality of the compiler.)</p>
+<p><strong>Regressions are new failures in the set of tests that are used to qualify
+each product and only include things on the list. Every release will have
+some bugs in it. It is the reality of developing a complex piece of
+software. We need a very concrete and definitive release criteria that
+ensures we have monotonically improving quality on some metric. The metric we
+use is described below. This doesn’t mean that we don’t care about other
+criteria, but these are the criteria which we found to be most important and
+which must be satisfied before a release can go out.</strong></p>
+<div class="section" id="qualify-llvm">
+<h4><a class="toc-backref" href="#id14">Qualify LLVM</a><a class="headerlink" href="#qualify-llvm" title="Permalink to this headline">¶</a></h4>
+<p>LLVM is qualified when it has a clean test run without a front-end. And it has
+no regressions when using either <tt class="docutils literal"><span class="pre">clang</span></tt> or <tt class="docutils literal"><span class="pre">dragonegg</span></tt> with the
+<tt class="docutils literal"><span class="pre">test-suite</span></tt> from the previous release.</p>
+</div>
+<div class="section" id="qualify-clang">
+<h4><a class="toc-backref" href="#id15">Qualify Clang</a><a class="headerlink" href="#qualify-clang" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">Clang</span></tt> is qualified when front-end specific tests in the <tt class="docutils literal"><span class="pre">llvm</span></tt> regression
+test suite all pass, clang’s own test suite passes cleanly, and there are no
+regressions in the <tt class="docutils literal"><span class="pre">test-suite</span></tt>.</p>
+</div>
+<div class="section" id="specific-target-qualification-details">
+<h4><a class="toc-backref" href="#id16">Specific Target Qualification Details</a><a class="headerlink" href="#specific-target-qualification-details" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="19%" />
+<col width="18%" />
+<col width="22%" />
+<col width="40%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Architecture</th>
+<th class="head">OS</th>
+<th class="head">clang baseline</th>
+<th class="head">tests</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>x86-32</td>
+<td>Linux</td>
+<td>last release</td>
+<td>llvm regression tests,
+clang regression tests,
+test-suite (including spec)</td>
+</tr>
+<tr class="row-odd"><td>x86-32</td>
+<td>FreeBSD</td>
+<td>last release</td>
+<td>llvm regression tests,
+clang regression tests,
+test-suite</td>
+</tr>
+<tr class="row-even"><td>x86-32</td>
+<td>mingw</td>
+<td>none</td>
+<td>QT</td>
+</tr>
+<tr class="row-odd"><td>x86-64</td>
+<td>Mac OS 10.X</td>
+<td>last release</td>
+<td>llvm regression tests,
+clang regression tests,
+test-suite (including spec)</td>
+</tr>
+<tr class="row-even"><td>x86-64</td>
+<td>Linux</td>
+<td>last release</td>
+<td>llvm regression tests,
+clang regression tests,
+test-suite (including spec)</td>
+</tr>
+<tr class="row-odd"><td>x86-64</td>
+<td>FreeBSD</td>
+<td>last release</td>
+<td>llvm regression tests,
+clang regression tests,
+test-suite</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="community-testing">
+<h3><a class="toc-backref" href="#id17">Community Testing</a><a class="headerlink" href="#community-testing" title="Permalink to this headline">¶</a></h3>
+<p>Once all testing has been completed and appropriate bugs filed, the release
+candidate tarballs are put on the website and the LLVM community is notified.
+Ask that all LLVM developers test the release in 2 ways:</p>
+<ol class="arabic simple">
+<li>Download <tt class="docutils literal"><span class="pre">llvm-X.Y</span></tt>, <tt class="docutils literal"><span class="pre">llvm-test-X.Y</span></tt>, and the appropriate <tt class="docutils literal"><span class="pre">clang</span></tt>
+binary. Build LLVM. Run <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> and the full LLVM test suite (<tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">TEST=nightly</span> <span class="pre">report</span></tt>).</li>
+<li>Download <tt class="docutils literal"><span class="pre">llvm-X.Y</span></tt>, <tt class="docutils literal"><span class="pre">llvm-test-X.Y</span></tt>, and the <tt class="docutils literal"><span class="pre">clang</span></tt> sources. Compile
+everything. Run <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> and the full LLVM test suite (<tt class="docutils literal"><span class="pre">make</span>
+<span class="pre">TEST=nightly</span> <span class="pre">report</span></tt>).</li>
+</ol>
+<p>Ask LLVM developers to submit the test suite report and <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> results
+to the list. Verify that there are no regressions from the previous release.
+The results are not used to qualify a release, but to spot other potential
+problems. For unsupported targets, verify that <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> is at least
+clean.</p>
+<p>During the first round of testing, all regressions must be fixed before the
+second release candidate is tagged.</p>
+<p>If this is the second round of testing, the testing is only to ensure that bug
+fixes previously merged in have not created new major problems. <em>This is not
+the time to solve additional and unrelated bugs!</em> If no patches are merged in,
+the release is determined to be ready and the release manager may move onto the
+next stage.</p>
+</div>
+<div class="section" id="release-patch-rules">
+<h3><a class="toc-backref" href="#id18">Release Patch Rules</a><a class="headerlink" href="#release-patch-rules" title="Permalink to this headline">¶</a></h3>
+<p>Below are the rules regarding patching the release branch:</p>
+<ol class="arabic simple">
+<li>Patches applied to the release branch may only be applied by the release
+manager.</li>
+<li>During the first round of testing, patches that fix regressions or that are
+small and relatively risk free (verified by the appropriate code owner) are
+applied to the branch. Code owners are asked to be very conservative in
+approving patches for the branch. We reserve the right to reject any patch
+that does not fix a regression as previously defined.</li>
+<li>During the remaining rounds of testing, only patches that fix critical
+regressions may be applied.</li>
+</ol>
+</div>
+<div class="section" id="release-final-tasks">
+<h3><a class="toc-backref" href="#id19">Release Final Tasks</a><a class="headerlink" href="#release-final-tasks" title="Permalink to this headline">¶</a></h3>
+<p>The final stages of the release process involves tagging the “final” release
+branch, updating documentation that refers to the release, and updating the
+demo page.</p>
+<div class="section" id="update-documentation">
+<h4><a class="toc-backref" href="#id20">Update Documentation</a><a class="headerlink" href="#update-documentation" title="Permalink to this headline">¶</a></h4>
+<p>Review the documentation and ensure that it is up to date. The “Release Notes”
+must be updated to reflect new features, bug fixes, new known issues, and
+changes in the list of supported platforms. The “Getting Started Guide” should
+be updated to reflect the new release version number tag available from
+Subversion and changes in basic system requirements. Merge both changes from
+mainline into the release branch.</p>
+</div>
+<div class="section" id="tag-the-llvm-final-release">
+<span id="tag"></span><h4><a class="toc-backref" href="#id21">Tag the LLVM Final Release</a><a class="headerlink" href="#tag-the-llvm-final-release" title="Permalink to this headline">¶</a></h4>
+<p>Tag the final release sources using the following procedure:</p>
+<div class="highlight-python"><pre>$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
+ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/Final
+
+$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
+ https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/Final
+
+$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
+ https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/Final
+
+$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
+ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/Final</pre>
+</div>
+</div>
+</div>
+<div class="section" id="update-the-llvm-demo-page">
+<h3><a class="toc-backref" href="#id22">Update the LLVM Demo Page</a><a class="headerlink" href="#update-the-llvm-demo-page" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM demo page must be updated to use the new release. This consists of
+using the new <tt class="docutils literal"><span class="pre">clang</span></tt> binary and building LLVM.</p>
+<div class="section" id="update-the-llvm-website">
+<h4><a class="toc-backref" href="#id23">Update the LLVM Website</a><a class="headerlink" href="#update-the-llvm-website" title="Permalink to this headline">¶</a></h4>
+<p>The website must be updated before the release announcement is sent out. Here
+is what to do:</p>
+<ol class="arabic simple">
+<li>Check out the <tt class="docutils literal"><span class="pre">www</span></tt> module from Subversion.</li>
+<li>Create a new subdirectory <tt class="docutils literal"><span class="pre">X.Y</span></tt> in the releases directory.</li>
+<li>Commit the <tt class="docutils literal"><span class="pre">llvm</span></tt>, <tt class="docutils literal"><span class="pre">test-suite</span></tt>, <tt class="docutils literal"><span class="pre">clang</span></tt> source, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">binaries</span></tt>,
+<tt class="docutils literal"><span class="pre">dragonegg</span></tt> source, and <tt class="docutils literal"><span class="pre">dragonegg</span></tt> binaries in this new directory.</li>
+<li>Copy and commit the <tt class="docutils literal"><span class="pre">llvm/docs</span></tt> and <tt class="docutils literal"><span class="pre">LICENSE.txt</span></tt> files into this new
+directory. The docs should be built with <tt class="docutils literal"><span class="pre">BUILD_FOR_WEBSITE=1</span></tt>.</li>
+<li>Commit the <tt class="docutils literal"><span class="pre">index.html</span></tt> to the <tt class="docutils literal"><span class="pre">release/X.Y</span></tt> directory to redirect (use
+from previous release).</li>
+<li>Update the <tt class="docutils literal"><span class="pre">releases/download.html</span></tt> file with the new release.</li>
+<li>Update the <tt class="docutils literal"><span class="pre">releases/index.html</span></tt> with the new release and link to release
+documentation.</li>
+<li>Finally, update the main page (<tt class="docutils literal"><span class="pre">index.html</span></tt> and sidebar) to point to the
+new release and release announcement. Make sure this all gets committed back
+into Subversion.</li>
+</ol>
+</div>
+<div class="section" id="announce-the-release">
+<h4><a class="toc-backref" href="#id24">Announce the Release</a><a class="headerlink" href="#announce-the-release" title="Permalink to this headline">¶</a></h4>
+<p>Have Chris send out the release announcement when everything is finished.</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="Packaging.html" title="Advice on Packaging LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LLVMBuild.html" title="LLVMBuild 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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToSetUpLLVMStyleRTTI.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToSetUpLLVMStyleRTTI.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToSetUpLLVMStyleRTTI.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToSetUpLLVMStyleRTTI.html Wed May 7 15:09:32 2014
@@ -0,0 +1,461 @@
+
+
+<!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>How to set up LLVM-style RTTI for your class hierarchy — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="LLVM Programmerâs Manual" href="ProgrammersManual.html" />
+ <link rel="prev" title="Extending LLVM: Adding instructions, intrinsics, types, etc." href="ExtendingLLVM.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="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ 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="how-to-set-up-llvm-style-rtti-for-your-class-hierarchy">
+<h1><a class="toc-backref" href="#id1">How to set up LLVM-style RTTI for your class hierarchy</a><a class="headerlink" href="#how-to-set-up-llvm-style-rtti-for-your-class-hierarchy" title="Permalink to this headline">¶</a></h1>
+<div class="contents topic" id="contents">
+<p class="topic-title first">Contents</p>
+<ul class="simple">
+<li><a class="reference internal" href="#how-to-set-up-llvm-style-rtti-for-your-class-hierarchy" id="id1">How to set up LLVM-style RTTI for your class hierarchy</a><ul>
+<li><a class="reference internal" href="#background" id="id2">Background</a></li>
+<li><a class="reference internal" href="#basic-setup" id="id3">Basic Setup</a></li>
+<li><a class="reference internal" href="#concrete-bases-and-deeper-hierarchies" id="id4">Concrete Bases and Deeper Hierarchies</a><ul>
+<li><a class="reference internal" href="#a-bug-to-be-aware-of" id="id5">A Bug to be Aware Of</a></li>
+<li><a class="reference internal" href="#the-contract-of-classof" id="id6">The Contract of <tt class="docutils literal"><span class="pre">classof</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rules-of-thumb" id="id7">Rules of Thumb</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="background">
+<h2><a class="toc-backref" href="#id2">Background</a><a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2>
+<p>LLVM avoids using C++’s built in RTTI. Instead, it pervasively uses its
+own hand-rolled form of RTTI which is much more efficient and flexible,
+although it requires a bit more work from you as a class author.</p>
+<p>A description of how to use LLVM-style RTTI from a client’s perspective is
+given in the <a class="reference external" href="ProgrammersManual.html#isa">Programmer’s Manual</a>. This
+document, in contrast, discusses the steps you need to take as a class
+hierarchy author to make LLVM-style RTTI available to your clients.</p>
+<p>Before diving in, make sure that you are familiar with the Object Oriented
+Programming concept of “<a class="reference external" href="http://en.wikipedia.org/wiki/Is-a">is-a</a>”.</p>
+</div>
+<div class="section" id="basic-setup">
+<h2><a class="toc-backref" href="#id3">Basic Setup</a><a class="headerlink" href="#basic-setup" title="Permalink to this headline">¶</a></h2>
+<p>This section describes how to set up the most basic form of LLVM-style RTTI
+(which is sufficient for 99.9% of the cases). We will set up LLVM-style
+RTTI for this class hierarchy:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+<span class="nl">public:</span>
+ <span class="n">Shape</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Square</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">SideLength</span><span class="p">;</span>
+<span class="nl">public:</span>
+ <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="cm">/* override */</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Circle</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">Radius</span><span class="p">;</span>
+<span class="nl">public:</span>
+ <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="cm">/* override */</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The most basic working setup for LLVM-style RTTI requires the following
+steps:</p>
+<ol class="arabic">
+<li><p class="first">In the header where you declare <tt class="docutils literal"><span class="pre">Shape</span></tt>, you will want to <tt class="docutils literal"><span class="pre">#include</span>
+<span class="pre">"llvm/Support/Casting.h"</span></tt>, which declares LLVM’s RTTI templates. That
+way your clients don’t even have to think about it.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Support/Casting.h"</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">In the base class, introduce an enum which discriminates all of the
+different concrete classes in the hierarchy, and stash the enum value
+somewhere in the base class.</p>
+<p>Here is the code after introducing this change:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+<span class="o">+</span> <span class="c1">/// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)</span>
+<span class="o">+</span> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+<span class="o">+</span> <span class="n">SK_Square</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_Circle</span>
+<span class="o">+</span> <span class="p">};</span>
+<span class="o">+</span><span class="k">private</span><span class="o">:</span>
+<span class="o">+</span> <span class="k">const</span> <span class="n">ShapeKind</span> <span class="n">Kind</span><span class="p">;</span>
+<span class="o">+</span><span class="k">public</span><span class="o">:</span>
+<span class="o">+</span> <span class="n">ShapeKind</span> <span class="n">getKind</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Kind</span><span class="p">;</span> <span class="p">}</span>
+<span class="o">+</span>
+ <span class="n">Shape</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>You will usually want to keep the <tt class="docutils literal"><span class="pre">Kind</span></tt> member encapsulated and
+private, but let the enum <tt class="docutils literal"><span class="pre">ShapeKind</span></tt> be public along with providing a
+<tt class="docutils literal"><span class="pre">getKind()</span></tt> method. This is convenient for clients so that they can do
+a <tt class="docutils literal"><span class="pre">switch</span></tt> over the enum.</p>
+<p>A common naming convention is that these enums are “kind”s, to avoid
+ambiguity with the words “type” or “class” which have overloaded meanings
+in many contexts within LLVM. Sometimes there will be a natural name for
+it, like “opcode”. Don’t bikeshed over this; when in doubt use <tt class="docutils literal"><span class="pre">Kind</span></tt>.</p>
+<p>You might wonder why the <tt class="docutils literal"><span class="pre">Kind</span></tt> enum doesn’t have an entry for
+<tt class="docutils literal"><span class="pre">Shape</span></tt>. The reason for this is that since <tt class="docutils literal"><span class="pre">Shape</span></tt> is abstract
+(<tt class="docutils literal"><span class="pre">computeArea()</span> <span class="pre">=</span> <span class="pre">0;</span></tt>), you will never actually have non-derived
+instances of exactly that class (only subclasses). See <a class="reference internal" href="#concrete-bases-and-deeper-hierarchies">Concrete Bases
+and Deeper Hierarchies</a> for information on how to deal with
+non-abstract bases. It’s worth mentioning here that unlike
+<tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt>, LLVM-style RTTI can be used (and is often used) for
+classes that don’t have v-tables.</p>
+</li>
+<li><p class="first">Next, you need to make sure that the <tt class="docutils literal"><span class="pre">Kind</span></tt> gets initialized to the
+value corresponding to the dynamic type of the class. Typically, you will
+want to have it be an argument to the constructor of the base class, and
+then pass in the respective <tt class="docutils literal"><span class="pre">XXXKind</span></tt> from subclass constructors.</p>
+<p>Here is the code after that change:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+ <span class="c1">/// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)</span>
+ <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">};</span>
+ <span class="nl">private:</span>
+ <span class="k">const</span> <span class="n">ShapeKind</span> <span class="n">Kind</span><span class="p">;</span>
+ <span class="nl">public:</span>
+ <span class="n">ShapeKind</span> <span class="n">getKind</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Kind</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="o">-</span> <span class="n">Shape</span><span class="p">()</span> <span class="p">{}</span>
+<span class="o">+</span> <span class="n">Shape</span><span class="p">(</span><span class="n">ShapeKind</span> <span class="n">K</span><span class="p">)</span> <span class="o">:</span> <span class="n">Kind</span><span class="p">(</span><span class="n">K</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Square</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">SideLength</span><span class="p">;</span>
+ <span class="nl">public:</span>
+<span class="o">-</span> <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+<span class="o">+</span> <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Square</span><span class="p">),</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="cm">/* override */</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Circle</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">Radius</span><span class="p">;</span>
+ <span class="nl">public:</span>
+<span class="o">-</span> <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+<span class="o">+</span> <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Circle</span><span class="p">),</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="cm">/* override */</span><span class="p">;</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Finally, you need to inform LLVM’s RTTI templates how to dynamically
+determine the type of a class (i.e. whether the <tt class="docutils literal"><span class="pre">isa<></span></tt>/<tt class="docutils literal"><span class="pre">dyn_cast<></span></tt>
+should succeed). The default “99.9% of use cases” way to accomplish this
+is through a small static member function <tt class="docutils literal"><span class="pre">classof</span></tt>. In order to have
+proper context for an explanation, we will display this code first, and
+then below describe each part:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="k">class</span> <span class="nc">Shape</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+ <span class="c1">/// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)</span>
+ <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">};</span>
+ <span class="nl">private:</span>
+ <span class="k">const</span> <span class="n">ShapeKind</span> <span class="n">Kind</span><span class="p">;</span>
+ <span class="nl">public:</span>
+ <span class="n">ShapeKind</span> <span class="n">getKind</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="n">Kind</span><span class="p">;</span> <span class="p">}</span>
+
+ <span class="n">Shape</span><span class="p">(</span><span class="n">ShapeKind</span> <span class="n">K</span><span class="p">)</span> <span class="o">:</span> <span class="n">Kind</span><span class="p">(</span><span class="n">K</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="k">virtual</span> <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Square</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">SideLength</span><span class="p">;</span>
+ <span class="nl">public:</span>
+ <span class="n">Square</span><span class="p">(</span><span class="kt">double</span> <span class="n">S</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Square</span><span class="p">),</span> <span class="n">SideLength</span><span class="p">(</span><span class="n">S</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="cm">/* override */</span><span class="p">;</span>
+<span class="o">+</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Square</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+ <span class="p">};</span>
+
+ <span class="k">class</span> <span class="nc">Circle</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Shape</span> <span class="p">{</span>
+ <span class="kt">double</span> <span class="n">Radius</span><span class="p">;</span>
+ <span class="nl">public:</span>
+ <span class="n">Circle</span><span class="p">(</span><span class="kt">double</span> <span class="n">R</span><span class="p">)</span> <span class="o">:</span> <span class="n">Shape</span><span class="p">(</span><span class="n">SK_Circle</span><span class="p">),</span> <span class="n">Radius</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">double</span> <span class="n">computeArea</span><span class="p">()</span> <span class="cm">/* override */</span><span class="p">;</span>
+<span class="o">+</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Circle</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>The job of <tt class="docutils literal"><span class="pre">classof</span></tt> is to dynamically determine whether an object of
+a base class is in fact of a particular derived class. In order to
+downcast a type <tt class="docutils literal"><span class="pre">Base</span></tt> to a type <tt class="docutils literal"><span class="pre">Derived</span></tt>, there needs to be a
+<tt class="docutils literal"><span class="pre">classof</span></tt> in <tt class="docutils literal"><span class="pre">Derived</span></tt> which will accept an object of type <tt class="docutils literal"><span class="pre">Base</span></tt>.</p>
+<p>To be concrete, consider the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Shape</span> <span class="o">*</span><span class="n">S</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">Circle</span><span class="o">></span><span class="p">(</span><span class="n">S</span><span class="p">))</span> <span class="p">{</span>
+ <span class="cm">/* do something ... */</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The code of the <tt class="docutils literal"><span class="pre">isa<></span></tt> test in this code will eventually boil
+down—after template instantiation and some other machinery—to a
+check roughly like <tt class="docutils literal"><span class="pre">Circle::classof(S)</span></tt>. For more information, see
+<a class="reference internal" href="#classof-contract"><em>The Contract of classof</em></a>.</p>
+<p>The argument to <tt class="docutils literal"><span class="pre">classof</span></tt> should always be an <em>ancestor</em> class because
+the implementation has logic to allow and optimize away
+upcasts/up-<tt class="docutils literal"><span class="pre">isa<></span></tt>‘s automatically. It is as though every class
+<tt class="docutils literal"><span class="pre">Foo</span></tt> automatically has a <tt class="docutils literal"><span class="pre">classof</span></tt> like:</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="p">[...]</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+ <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">T</span> <span class="o">*</span><span class="p">,</span>
+ <span class="o">::</span><span class="n">llvm</span><span class="o">::</span><span class="n">enable_if_c</span><span class="o"><</span>
+ <span class="o">::</span><span class="n">llvm</span><span class="o">::</span><span class="n">is_base_of</span><span class="o"><</span><span class="n">Foo</span><span class="p">,</span> <span class="n">T</span><span class="o">>::</span><span class="n">value</span>
+ <span class="o">>::</span><span class="n">type</span><span class="o">*</span> <span class="o">=</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">true</span><span class="p">;</span> <span class="p">}</span>
+ <span class="p">[...]</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Note that this is the reason that we did not need to introduce a
+<tt class="docutils literal"><span class="pre">classof</span></tt> into <tt class="docutils literal"><span class="pre">Shape</span></tt>: all relevant classes derive from <tt class="docutils literal"><span class="pre">Shape</span></tt>,
+and <tt class="docutils literal"><span class="pre">Shape</span></tt> itself is abstract (has no entry in the <tt class="docutils literal"><span class="pre">Kind</span></tt> enum),
+so this notional inferred <tt class="docutils literal"><span class="pre">classof</span></tt> is all we need. See <a class="reference internal" href="#concrete-bases-and-deeper-hierarchies">Concrete
+Bases and Deeper Hierarchies</a> for more information about how to extend
+this example to more general hierarchies.</p>
+</li>
+</ol>
+<p>Although for this small example setting up LLVM-style RTTI seems like a lot
+of “boilerplate”, if your classes are doing anything interesting then this
+will end up being a tiny fraction of the code.</p>
+</div>
+<div class="section" id="concrete-bases-and-deeper-hierarchies">
+<h2><a class="toc-backref" href="#id4">Concrete Bases and Deeper Hierarchies</a><a class="headerlink" href="#concrete-bases-and-deeper-hierarchies" title="Permalink to this headline">¶</a></h2>
+<p>For concrete bases (i.e. non-abstract interior nodes of the inheritance
+tree), the <tt class="docutils literal"><span class="pre">Kind</span></tt> check inside <tt class="docutils literal"><span class="pre">classof</span></tt> needs to be a bit more
+complicated. The situation differs from the example above in that</p>
+<ul class="simple">
+<li>Since the class is concrete, it must itself have an entry in the <tt class="docutils literal"><span class="pre">Kind</span></tt>
+enum because it is possible to have objects with this class as a dynamic
+type.</li>
+<li>Since the class has children, the check inside <tt class="docutils literal"><span class="pre">classof</span></tt> must take them
+into account.</li>
+</ul>
+<p>Say that <tt class="docutils literal"><span class="pre">SpecialSquare</span></tt> and <tt class="docutils literal"><span class="pre">OtherSpecialSquare</span></tt> derive
+from <tt class="docutils literal"><span class="pre">Square</span></tt>, and so <tt class="docutils literal"><span class="pre">ShapeKind</span></tt> becomes:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+</pre></div>
+</div>
+<p>Then in <tt class="docutils literal"><span class="pre">Square</span></tt>, we would need to modify the <tt class="docutils literal"><span class="pre">classof</span></tt> like so:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="o">-</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">-</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Square</span><span class="p">;</span>
+<span class="o">-</span> <span class="p">}</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">>=</span> <span class="n">SK_Square</span> <span class="o">&&</span>
+<span class="o">+</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o"><=</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>The reason that we need to test a range like this instead of just equality
+is that both <tt class="docutils literal"><span class="pre">SpecialSquare</span></tt> and <tt class="docutils literal"><span class="pre">OtherSpecialSquare</span></tt> “is-a”
+<tt class="docutils literal"><span class="pre">Square</span></tt>, and so <tt class="docutils literal"><span class="pre">classof</span></tt> needs to return <tt class="docutils literal"><span class="pre">true</span></tt> for them.</p>
+<p>This approach can be made to scale to arbitrarily deep hierarchies. The
+trick is that you arrange the enum values so that they correspond to a
+preorder traversal of the class hierarchy tree. With that arrangement, all
+subclass tests can be done with two comparisons as shown above. If you just
+list the class hierarchy like a list of bullet points, you’ll get the
+ordering right:</p>
+<div class="highlight-python"><pre>| Shape
+ | Square
+ | SpecialSquare
+ | OtherSpecialSquare
+ | Circle</pre>
+</div>
+<div class="section" id="a-bug-to-be-aware-of">
+<h3><a class="toc-backref" href="#id5">A Bug to be Aware Of</a><a class="headerlink" href="#a-bug-to-be-aware-of" title="Permalink to this headline">¶</a></h3>
+<p>The example just given opens the door to bugs where the <tt class="docutils literal"><span class="pre">classof</span></tt>s are
+not updated to match the <tt class="docutils literal"><span class="pre">Kind</span></tt> enum when adding (or removing) classes to
+(from) the hierarchy.</p>
+<p>Continuing the example above, suppose we add a <tt class="docutils literal"><span class="pre">SomewhatSpecialSquare</span></tt> as
+a subclass of <tt class="docutils literal"><span class="pre">Square</span></tt>, and update the <tt class="docutils literal"><span class="pre">ShapeKind</span></tt> enum like so:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SomewhatSpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+</pre></div>
+</div>
+<p>Now, suppose that we forget to update <tt class="docutils literal"><span class="pre">Square::classof()</span></tt>, so it still
+looks like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="kt">bool</span> <span class="nf">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// BUG: Returns false when S->getKind() == SK_SomewhatSpecialSquare,</span>
+ <span class="c1">// even though SomewhatSpecialSquare "is a" Square.</span>
+ <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">>=</span> <span class="n">SK_Square</span> <span class="o">&&</span>
+ <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o"><=</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>As the comment indicates, this code contains a bug. A straightforward and
+non-clever way to avoid this is to introduce an explicit <tt class="docutils literal"><span class="pre">SK_LastSquare</span></tt>
+entry in the enum when adding the first subclass(es). For example, we could
+rewrite the example at the beginning of <a class="reference internal" href="#concrete-bases-and-deeper-hierarchies">Concrete Bases and Deeper
+Hierarchies</a> as:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_LastSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+<span class="p">...</span>
+<span class="c1">// Square::classof()</span>
+<span class="o">-</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">-</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">==</span> <span class="n">SK_Square</span><span class="p">;</span>
+<span class="o">-</span> <span class="p">}</span>
+<span class="o">+</span> <span class="k">static</span> <span class="kt">bool</span> <span class="n">classof</span><span class="p">(</span><span class="k">const</span> <span class="n">Shape</span> <span class="o">*</span><span class="n">S</span><span class="p">)</span> <span class="p">{</span>
+<span class="o">+</span> <span class="k">return</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o">>=</span> <span class="n">SK_Square</span> <span class="o">&&</span>
+<span class="o">+</span> <span class="n">S</span><span class="o">-></span><span class="n">getKind</span><span class="p">()</span> <span class="o"><=</span> <span class="n">SK_LastSquare</span><span class="p">;</span>
+<span class="o">+</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Then, adding new subclasses is easy:</p>
+<div class="highlight-c++"><div class="highlight"><pre> <span class="k">enum</span> <span class="n">ShapeKind</span> <span class="p">{</span>
+ <span class="n">SK_Square</span><span class="p">,</span>
+ <span class="n">SK_SpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_OtherSpecialSquare</span><span class="p">,</span>
+<span class="o">+</span> <span class="n">SK_SomewhatSpecialSquare</span><span class="p">,</span>
+ <span class="n">SK_LastSquare</span><span class="p">,</span>
+ <span class="n">SK_Circle</span>
+ <span class="p">}</span>
+</pre></div>
+</div>
+<p>Notice that <tt class="docutils literal"><span class="pre">Square::classof</span></tt> does not need to be changed.</p>
+</div>
+<div class="section" id="the-contract-of-classof">
+<span id="classof-contract"></span><h3><a class="toc-backref" href="#id6">The Contract of <tt class="docutils literal"><span class="pre">classof</span></tt></a><a class="headerlink" href="#the-contract-of-classof" title="Permalink to this headline">¶</a></h3>
+<p>To be more precise, let <tt class="docutils literal"><span class="pre">classof</span></tt> be inside a class <tt class="docutils literal"><span class="pre">C</span></tt>. Then the
+contract for <tt class="docutils literal"><span class="pre">classof</span></tt> is “return <tt class="docutils literal"><span class="pre">true</span></tt> if the dynamic type of the
+argument is-a <tt class="docutils literal"><span class="pre">C</span></tt>”. As long as your implementation fulfills this
+contract, you can tweak and optimize it as much as you want.</p>
+</div>
+</div>
+<div class="section" id="rules-of-thumb">
+<h2><a class="toc-backref" href="#id7">Rules of Thumb</a><a class="headerlink" href="#rules-of-thumb" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic simple">
+<li>The <tt class="docutils literal"><span class="pre">Kind</span></tt> enum should have one entry per concrete class, ordered
+according to a preorder traversal of the inheritance tree.</li>
+<li>The argument to <tt class="docutils literal"><span class="pre">classof</span></tt> should be a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">Base</span> <span class="pre">*</span></tt>, where <tt class="docutils literal"><span class="pre">Base</span></tt>
+is some ancestor in the inheritance hierarchy. The argument should
+<em>never</em> be a derived class or the class itself: the template machinery
+for <tt class="docutils literal"><span class="pre">isa<></span></tt> already handles this case and optimizes it.</li>
+<li>For each class in the hierarchy that has no children, implement a
+<tt class="docutils literal"><span class="pre">classof</span></tt> that checks only against its <tt class="docutils literal"><span class="pre">Kind</span></tt>.</li>
+<li>For each class in the hierarchy that has children, implement a
+<tt class="docutils literal"><span class="pre">classof</span></tt> that checks a range of the first child’s <tt class="docutils literal"><span class="pre">Kind</span></tt> and the
+last child’s <tt class="docutils literal"><span class="pre">Kind</span></tt>.</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="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToSubmitABug.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToSubmitABug.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToSubmitABug.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToSubmitABug.html Wed May 7 15:09:32 2014
@@ -0,0 +1,280 @@
+
+
+<!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>How to submit an LLVM bug report — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="Sphinx Quickstart Template" href="SphinxQuickstartTemplate.html" />
+ <link rel="prev" title="yaml2obj" href="yaml2obj.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="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="yaml2obj.html" title="yaml2obj"
+ 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="how-to-submit-an-llvm-bug-report">
+<h1>How to submit an LLVM bug report<a class="headerlink" href="#how-to-submit-an-llvm-bug-report" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-got-bugs">
+<h2>Introduction - Got bugs?<a class="headerlink" href="#introduction-got-bugs" title="Permalink to this headline">¶</a></h2>
+<p>If you’re working with LLVM and run into a bug, we definitely want to know
+about it. This document describes what you can do to increase the odds of
+getting it fixed quickly.</p>
+<p>Basically you have to do two things at a minimum. First, decide whether
+the bug <a class="reference internal" href="#crashes-the-compiler">crashes the compiler</a> (or an LLVM pass), or if the
+compiler is <a class="reference internal" href="#miscompiling">miscompiling</a> the program (i.e., the
+compiler successfully produces an executable, but it doesn’t run right).
+Based on what type of bug it is, follow the instructions in the linked
+section to narrow down the bug so that the person who fixes it will be able
+to find the problem more easily.</p>
+<p>Once you have a reduced test-case, go to <a class="reference external" href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking System</a> and fill out the form with the
+necessary details (note that you don’t need to pick a category, just use
+the “new-bugs” category if you’re not sure). The bug description should
+contain the following information:</p>
+<ul class="simple">
+<li>All information necessary to reproduce the problem.</li>
+<li>The reduced test-case that triggers the bug.</li>
+<li>The location where you obtained LLVM (if not from our Subversion
+repository).</li>
+</ul>
+<p>Thanks for helping us make LLVM better!</p>
+</div>
+<div class="section" id="crashing-bugs">
+<span id="crashes-the-compiler"></span><h2>Crashing Bugs<a class="headerlink" href="#crashing-bugs" title="Permalink to this headline">¶</a></h2>
+<p>More often than not, bugs in the compiler cause it to crash—often due to
+an assertion failure of some sort. The most important piece of the puzzle
+is to figure out if it is crashing in the GCC front-end or if it is one of
+the LLVM libraries (e.g. the optimizer or code generator) that has
+problems.</p>
+<p>To figure out which component is crashing (the front-end, optimizer or code
+generator), run the <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> command line as you were when the crash
+occurred, but with the following extra command line options:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-O0</span> <span class="pre">-emit-llvm</span></tt>: If <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> still crashes when passed these
+options (which disable the optimizer and code generator), then the crash
+is in the front-end. Jump ahead to the section on <a class="reference internal" href="#front-end"><em>front-end bugs</em></a>.</li>
+<li><tt class="docutils literal"><span class="pre">-emit-llvm</span></tt>: If <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> crashes with this option (which disables
+the code generator), you found an optimizer bug. Jump ahead to
+<a class="reference internal" href="#compile-time-optimization-bugs">compile-time optimization bugs</a>.</li>
+<li>Otherwise, you have a code generator crash. Jump ahead to <a class="reference internal" href="#code-generator-bugs">code
+generator bugs</a>.</li>
+</ul>
+<div class="section" id="front-end-bugs">
+<span id="front-end"></span><span id="front-end-bug"></span><h3>Front-end bugs<a class="headerlink" href="#front-end-bugs" title="Permalink to this headline">¶</a></h3>
+<p>If the problem is in the front-end, you should re-run the same <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>
+command that resulted in the crash, but add the <tt class="docutils literal"><span class="pre">-save-temps</span></tt> option.
+The compiler will crash again, but it will leave behind a <tt class="docutils literal"><span class="pre">foo.i</span></tt> file
+(containing preprocessed C source code) and possibly <tt class="docutils literal"><span class="pre">foo.s</span></tt> for each
+compiled <tt class="docutils literal"><span class="pre">foo.c</span></tt> file. Send us the <tt class="docutils literal"><span class="pre">foo.i</span></tt> file, along with the options
+you passed to <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>, and a brief description of the error it caused.</p>
+<p>The <a class="reference external" href="http://delta.tigris.org/">delta</a> tool helps to reduce the
+preprocessed file down to the smallest amount of code that still replicates
+the problem. You’re encouraged to use delta to reduce the code to make the
+developers’ lives easier. <a class="reference external" href="http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction">This website</a> has instructions
+on the best way to use delta.</p>
+</div>
+<div class="section" id="compile-time-optimization-bugs">
+<span id="id1"></span><h3>Compile-time optimization bugs<a class="headerlink" href="#compile-time-optimization-bugs" title="Permalink to this headline">¶</a></h3>
+<p>If you find that a bug crashes in the optimizer, compile your test-case to a
+<tt class="docutils literal"><span class="pre">.bc</span></tt> file by passing “<tt class="docutils literal"><span class="pre">-emit-llvm</span> <span class="pre">-O0</span> <span class="pre">-c</span> <span class="pre">-o</span> <span class="pre">foo.bc</span></tt>”.
+Then run:</p>
+<div class="highlight-bash"><div class="highlight"><pre>opt -std-compile-opts -debug-pass<span class="o">=</span>Arguments foo.bc -disable-output
+</pre></div>
+</div>
+<p>This command should do two things: it should print out a list of passes, and
+then it should crash in the same way as llvm-gcc. If it doesn’t crash, please
+follow the instructions for a <a class="reference internal" href="#front-end-bug">front-end bug</a>.</p>
+<p>If this does crash, then you should be able to debug this with the following
+bugpoint command:</p>
+<div class="highlight-bash"><div class="highlight"><pre>bugpoint foo.bc <list of passes printed by opt>
+</pre></div>
+</div>
+<p>Please run this, then file a bug with the instructions and reduced .bc
+files that bugpoint emits. If something goes wrong with bugpoint, please
+submit the “foo.bc” file and the list of passes printed by <tt class="docutils literal"><span class="pre">opt</span></tt>.</p>
+</div>
+<div class="section" id="code-generator-bugs">
+<span id="id2"></span><h3>Code generator bugs<a class="headerlink" href="#code-generator-bugs" title="Permalink to this headline">¶</a></h3>
+<p>If you find a bug that crashes llvm-gcc in the code generator, compile your
+source file to a .bc file by passing “<tt class="docutils literal"><span class="pre">-emit-llvm</span> <span class="pre">-c</span> <span class="pre">-o</span> <span class="pre">foo.bc</span></tt>” to
+llvm-gcc (in addition to the options you already pass). Once your have
+foo.bc, one of the following commands should fail:</p>
+<ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">llc</span> <span class="pre">foo.bc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=pic</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=static</span></tt></li>
+</ol>
+<p>If none of these crash, please follow the instructions for a <a class="reference internal" href="#front-end-bug">front-end
+bug</a>. If one of these do crash, you should be able to reduce this with
+one of the following bugpoint command lines (use the one corresponding to
+the command above that failed):</p>
+<ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span> <span class="pre">--tool-args</span> <span class="pre">-relocation-model=pic</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span> <span class="pre">--tool-args</span> <span class="pre">-relocation-model=static</span></tt></li>
+</ol>
+<p>Please run this, then file a bug with the instructions and reduced .bc file
+that bugpoint emits. If something goes wrong with bugpoint, please submit
+the “foo.bc” file and the option that llc crashes with.</p>
+</div>
+</div>
+<div class="section" id="miscompilations">
+<span id="miscompiling"></span><h2>Miscompilations<a class="headerlink" href="#miscompilations" title="Permalink to this headline">¶</a></h2>
+<p>If llvm-gcc successfully produces an executable, but that executable
+doesn’t run right, this is either a bug in the code or a bug in the
+compiler. The first thing to check is to make sure it is not using
+undefined behavior (e.g. reading a variable before it is defined). In
+particular, check to see if the program <a class="reference external" href="http://valgrind.org/">valgrind</a>‘s clean, passes purify, or some other memory
+checker tool. Many of the “LLVM bugs” that we have chased down ended up
+being bugs in the program being compiled, not LLVM.</p>
+<p>Once you determine that the program itself is not buggy, you should choose
+which code generator you wish to compile the program with (e.g. LLC or the JIT)
+and optionally a series of LLVM passes to run. For example:</p>
+<div class="highlight-bash"><div class="highlight"><pre>bugpoint -run-llc <span class="o">[</span>... optzn passes ...<span class="o">]</span> file-to-test.bc --args -- <span class="o">[</span>program arguments<span class="o">]</span>
+</pre></div>
+</div>
+<p>bugpoint will try to narrow down your list of passes to the one pass that
+causes an error, and simplify the bitcode file as much as it can to assist
+you. It will print a message letting you know how to reproduce the
+resulting error.</p>
+</div>
+<div class="section" id="incorrect-code-generation">
+<h2>Incorrect code generation<a class="headerlink" href="#incorrect-code-generation" title="Permalink to this headline">¶</a></h2>
+<p>Similarly to debugging incorrect compilation by mis-behaving passes, you
+can debug incorrect code generation by either LLC or the JIT, using
+<tt class="docutils literal"><span class="pre">bugpoint</span></tt>. The process <tt class="docutils literal"><span class="pre">bugpoint</span></tt> follows in this case is to try to
+narrow the code down to a function that is miscompiled by one or the other
+method, but since for correctness, the entire program must be run,
+<tt class="docutils literal"><span class="pre">bugpoint</span></tt> will compile the code it deems to not be affected with the C
+Backend, and then link in the shared object it generates.</p>
+<p>To debug the JIT:</p>
+<div class="highlight-bash"><div class="highlight"><pre>bugpoint -run-jit -output<span class="o">=[</span>correct output file<span class="o">]</span> <span class="o">[</span>bitcode file<span class="o">]</span> <span class="se">\</span>
+ --tool-args -- <span class="o">[</span>arguments to pass to lli<span class="o">]</span> <span class="se">\</span>
+ --args -- <span class="o">[</span>program arguments<span class="o">]</span>
+</pre></div>
+</div>
+<p>Similarly, to debug the LLC, one would run:</p>
+<div class="highlight-bash"><div class="highlight"><pre>bugpoint -run-llc -output<span class="o">=[</span>correct output file<span class="o">]</span> <span class="o">[</span>bitcode file<span class="o">]</span> <span class="se">\</span>
+ --tool-args -- <span class="o">[</span>arguments to pass to llc<span class="o">]</span> <span class="se">\</span>
+ --args -- <span class="o">[</span>program arguments<span class="o">]</span>
+</pre></div>
+</div>
+<p><strong>Special note:</strong> if you are debugging MultiSource or SPEC tests that
+already exist in the <tt class="docutils literal"><span class="pre">llvm/test</span></tt> hierarchy, there is an easier way to
+debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which
+will pass the program options specified in the Makefiles:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nb">cd </span>llvm/test/../../program
+make bugpoint-jit
+</pre></div>
+</div>
+<p>At the end of a successful <tt class="docutils literal"><span class="pre">bugpoint</span></tt> run, you will be presented
+with two bitcode files: a <em>safe</em> file which can be compiled with the C
+backend and the <em>test</em> file which either LLC or the JIT
+mis-codegenerates, and thus causes the error.</p>
+<p>To reproduce the error that <tt class="docutils literal"><span class="pre">bugpoint</span></tt> found, it is sufficient to do
+the following:</p>
+<ol class="arabic">
+<li><p class="first">Regenerate the shared object from the safe bitcode file:</p>
+<div class="highlight-bash"><div class="highlight"><pre>llc -march<span class="o">=</span>c safe.bc -o safe.c
+gcc -shared safe.c -o safe.so
+</pre></div>
+</div>
+</li>
+<li><p class="first">If debugging LLC, compile test bitcode native and link with the shared
+object:</p>
+<div class="highlight-bash"><div class="highlight"><pre>llc test.bc -o test.s
+gcc test.s safe.so -o test.llc
+./test.llc <span class="o">[</span>program options<span class="o">]</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">If debugging the JIT, load the shared object and supply the test
+bitcode:</p>
+<div class="highlight-bash"><div class="highlight"><pre>lli -load<span class="o">=</span>safe.so test.bc <span class="o">[</span>program options<span class="o">]</span>
+</pre></div>
+</div>
+</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="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="yaml2obj.html" title="yaml2obj"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToUseAttributes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToUseAttributes.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToUseAttributes.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToUseAttributes.html Wed May 7 15:09:32 2014
@@ -0,0 +1,170 @@
+
+
+<!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>How To Use Attributes — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="User Guide for NVPTX Back-end" href="NVPTXUsage.html" />
+ <link rel="prev" title="TableGen Language Reference" href="TableGen/LangRef.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="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TableGen/LangRef.html" title="TableGen Language Reference"
+ 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="how-to-use-attributes">
+<h1>How To Use Attributes<a class="headerlink" href="#how-to-use-attributes" 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="#attribute" id="id2"><tt class="docutils literal"><span class="pre">Attribute</span></tt></a></li>
+<li><a class="reference internal" href="#attributeset" id="id3"><tt class="docutils literal"><span class="pre">AttributeSet</span></tt></a></li>
+<li><a class="reference internal" href="#attrbuilder" id="id4"><tt class="docutils literal"><span class="pre">AttrBuilder</span></tt></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>Attributes in LLVM have changed in some fundamental ways. It was necessary to
+do this to support expanding the attributes to encompass more than a handful of
+attributes — e.g. command line options. The old way of handling attributes
+consisted of representing them as a bit mask of values. This bit mask was
+stored in a “list” structure that was reference counted. The advantage of this
+was that attributes could be manipulated with ‘or’s and ‘and’s. The
+disadvantage of this was that there was limited room for expansion, and
+virtually no support for attribute-value pairs other than alignment.</p>
+<p>In the new scheme, an <tt class="docutils literal"><span class="pre">Attribute</span></tt> object represents a single attribute that’s
+uniqued. You use the <tt class="docutils literal"><span class="pre">Attribute::get</span></tt> methods to create a new <tt class="docutils literal"><span class="pre">Attribute</span></tt>
+object. An attribute can be a single “enum” value (the enum being the
+<tt class="docutils literal"><span class="pre">Attribute::AttrKind</span></tt> enum), a string representing a target-dependent
+attribute, or an attribute-value pair. Some examples:</p>
+<ul class="simple">
+<li>Target-independent: <tt class="docutils literal"><span class="pre">noinline</span></tt>, <tt class="docutils literal"><span class="pre">zext</span></tt></li>
+<li>Target-dependent: <tt class="docutils literal"><span class="pre">"no-sse"</span></tt>, <tt class="docutils literal"><span class="pre">"thumb2"</span></tt></li>
+<li>Attribute-value pair: <tt class="docutils literal"><span class="pre">"cpu"</span> <span class="pre">=</span> <span class="pre">"cortex-a8"</span></tt>, <tt class="docutils literal"><span class="pre">align</span> <span class="pre">=</span> <span class="pre">4</span></tt></li>
+</ul>
+<p>Note: for an attribute value pair, we expect a target-dependent attribute to
+have a string for the value.</p>
+</div>
+<div class="section" id="attribute">
+<h2><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">Attribute</span></tt></a><a class="headerlink" href="#attribute" title="Permalink to this headline">¶</a></h2>
+<p>An <tt class="docutils literal"><span class="pre">Attribute</span></tt> object is designed to be passed around by value.</p>
+<p>Because attributes are no longer represented as a bit mask, you will need to
+convert any code which does treat them as a bit mask to use the new query
+methods on the Attribute class.</p>
+</div>
+<div class="section" id="attributeset">
+<h2><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">AttributeSet</span></tt></a><a class="headerlink" href="#attributeset" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">AttributeSet</span></tt> class replaces the old <tt class="docutils literal"><span class="pre">AttributeList</span></tt> class. The
+<tt class="docutils literal"><span class="pre">AttributeSet</span></tt> stores a collection of Attribute objects for each kind of
+object that may have an attribute associated with it: the function as a
+whole, the return type, or the function’s parameters. A function’s attributes
+are at index <tt class="docutils literal"><span class="pre">AttributeSet::FunctionIndex</span></tt>; the return type’s attributes are
+at index <tt class="docutils literal"><span class="pre">AttributeSet::ReturnIndex</span></tt>; and the function’s parameters’
+attributes are at indices 1, ..., n (where ‘n’ is the number of parameters).
+Most methods on the <tt class="docutils literal"><span class="pre">AttributeSet</span></tt> class take an index parameter.</p>
+<p>An <tt class="docutils literal"><span class="pre">AttributeSet</span></tt> is also a uniqued and immutable object. You create an
+<tt class="docutils literal"><span class="pre">AttributeSet</span></tt> through the <tt class="docutils literal"><span class="pre">AttributeSet::get</span></tt> methods. You can add and
+remove attributes, which result in the creation of a new <tt class="docutils literal"><span class="pre">AttributeSet</span></tt>.</p>
+<p>An <tt class="docutils literal"><span class="pre">AttributeSet</span></tt> object is designed to be passed around by value.</p>
+<p>Note: It is advised that you do <em>not</em> use the <tt class="docutils literal"><span class="pre">AttributeSet</span></tt> “introspection”
+methods (e.g. <tt class="docutils literal"><span class="pre">Raw</span></tt>, <tt class="docutils literal"><span class="pre">getRawPointer</span></tt>, etc.). These methods break
+encapsulation, and may be removed in a future release (i.e. LLVM 4.0).</p>
+</div>
+<div class="section" id="attrbuilder">
+<h2><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">AttrBuilder</span></tt></a><a class="headerlink" href="#attrbuilder" title="Permalink to this headline">¶</a></h2>
+<p>Lastly, we have a “builder” class to help create the <tt class="docutils literal"><span class="pre">AttributeSet</span></tt> object
+without having to create several different intermediate uniqued
+<tt class="docutils literal"><span class="pre">AttributeSet</span></tt> objects. The <tt class="docutils literal"><span class="pre">AttrBuilder</span></tt> class allows you to add and
+remove attributes at will. The attributes won’t be uniqued until you call the
+appropriate <tt class="docutils literal"><span class="pre">AttributeSet::get</span></tt> method.</p>
+<p>An <tt class="docutils literal"><span class="pre">AttrBuilder</span></tt> object is <em>not</em> designed to be passed around by value. It
+should be passed by reference.</p>
+<p>Note: It is advised that you do <em>not</em> use the <tt class="docutils literal"><span class="pre">AttrBuilder::addRawValue()</span></tt>
+method or the <tt class="docutils literal"><span class="pre">AttrBuilder(uint64_t</span> <span class="pre">Val)</span></tt> constructor. These are for
+backwards compatibility and may be removed in a future release (i.e. LLVM 4.0).</p>
+<p>And that’s basically it! A lot of functionality is hidden behind these classes,
+but the interfaces are pretty straight forward.</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="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TableGen/LangRef.html" title="TableGen Language Reference"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/HowToUseInstrMappings.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/HowToUseInstrMappings.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/HowToUseInstrMappings.html (added)
+++ www-releases/trunk/3.4.1/docs/HowToUseInstrMappings.html Wed May 7 15:09:32 2014
@@ -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>How To Use Instruction Mappings — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="up" title="Writing an LLVM Backend" href="WritingAnLLVMBackend.html" />
+ <link rel="next" title="Accurate Garbage Collection with LLVM" href="GarbageCollection.html" />
+ <link rel="prev" title="Writing an LLVM Backend" href="WritingAnLLVMBackend.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="GarbageCollection.html" title="Accurate Garbage Collection with LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ 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="WritingAnLLVMBackend.html" accesskey="U">Writing an LLVM Backend</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="how-to-use-instruction-mappings">
+<h1>How To Use Instruction Mappings<a class="headerlink" href="#how-to-use-instruction-mappings" 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="#instrmapping-class-overview" id="id2"><tt class="docutils literal"><span class="pre">InstrMapping</span></tt> Class Overview</a><ul>
+<li><a class="reference internal" href="#sample-example" id="id3">Sample Example</a></li>
+</ul>
+</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 contains information about adding instruction mapping support
+for a target. The motivation behind this feature comes from the need to switch
+between different instruction formats during various optimizations. One approach
+could be to use switch cases which list all the instructions along with formats
+they can transition to. However, it has large maintenance overhead
+because of the hardcoded instruction names. Also, whenever a new instruction is
+added in the .td files, all the relevant switch cases should be modified
+accordingly. Instead, the same functionality could be achieved with TableGen and
+some support from the .td files for a fraction of maintenance cost.</p>
+</div>
+<div class="section" id="instrmapping-class-overview">
+<h2><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">InstrMapping</span></tt> Class Overview</a><a class="headerlink" href="#instrmapping-class-overview" title="Permalink to this headline">¶</a></h2>
+<p>TableGen uses relationship models to map instructions with each other. These
+models are described using <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class as a base. Each model sets
+various fields of the <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class such that they can uniquely
+describe all the instructions using that model. TableGen parses all the relation
+models and uses the information to construct relation tables which relate
+instructions with each other. These tables are emitted in the
+<tt class="docutils literal"><span class="pre">XXXInstrInfo.inc</span></tt> file along with the functions to query them. Following
+is the definition of <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class definied in Target.td file:</p>
+<div class="highlight-llvm"><pre>class InstrMapping {
+ // Used to reduce search space only to the instructions using this
+ // relation model.
+ string FilterClass;
+
+ // List of fields/attributes that should be same for all the instructions in
+ // a row of the relation table. Think of this as a set of properties shared
+ // by all the instructions related by this relationship.
+ list<string> RowFields = [];
+
+ // List of fields/attributes that are same for all the instructions
+ // in a column of the relation table.
+ list<string> ColFields = [];
+
+ // Values for the fields/attributes listed in 'ColFields' corresponding to
+ // the key instruction. This is the instruction that will be transformed
+ // using this relation model.
+ list<string> KeyCol = [];
+
+ // List of values for the fields/attributes listed in 'ColFields', one for
+ // each column in the relation table. These are the instructions a key
+ // instruction will be transformed into.
+ list<list<string> > ValueCols = [];
+}</pre>
+</div>
+<div class="section" id="sample-example">
+<h3><a class="toc-backref" href="#id3">Sample Example</a><a class="headerlink" href="#sample-example" title="Permalink to this headline">¶</a></h3>
+<p>Let’s say that we want to have a function
+<tt class="docutils literal"><span class="pre">int</span> <span class="pre">getPredOpcode(uint16_t</span> <span class="pre">Opcode,</span> <span class="pre">enum</span> <span class="pre">PredSense</span> <span class="pre">inPredSense)</span></tt> which
+takes a non-predicated instruction and returns its predicated true or false form
+depending on some input flag, <tt class="docutils literal"><span class="pre">inPredSense</span></tt>. The first step in the process is
+to define a relationship model that relates predicated instructions to their
+non-predicated form by assigning appropriate values to the <tt class="docutils literal"><span class="pre">InstrMapping</span></tt>
+fields. For this relationship, non-predicated instructions are treated as key
+instruction since they are the one used to query the interface function.</p>
+<div class="highlight-llvm"><pre>def getPredOpcode : InstrMapping {
+ // Choose a FilterClass that is used as a base class for all the
+ // instructions modeling this relationship. This is done to reduce the
+ // search space only to these set of instructions.
+ let FilterClass = "PredRel";
+
+ // Instructions with same values for all the fields in RowFields form a
+ // row in the resulting relation table.
+ // For example, if we want to relate 'ADD' (non-predicated) with 'Add_pt'
+ // (predicated true) and 'Add_pf' (predicated false), then all 3
+ // instructions need to have same value for BaseOpcode field. It can be any
+ // unique value (Ex: XYZ) and should not be shared with any other
+ // instruction not related to 'add'.
+ let RowFields = ["BaseOpcode"];
+
+ // List of attributes that can be used to define key and column instructions
+ // for a relation. Key instruction is passed as an argument
+ // to the function used for querying relation tables. Column instructions
+ // are the instructions they (key) can transform into.
+ //
+ // Here, we choose 'PredSense' as ColFields since this is the unique
+ // attribute of the key (non-predicated) and column (true/false)
+ // instructions involved in this relationship model.
+ let ColFields = ["PredSense"];
+
+ // The key column contains non-predicated instructions.
+ let KeyCol = ["none"];
+
+ // Two value columns - first column contains instructions with
+ // PredSense=true while second column has instructions with PredSense=false.
+ let ValueCols = [["true"], ["false"]];
+}</pre>
+</div>
+<p>TableGen uses the above relationship model to emit relation table that maps
+non-predicated instructions with their predicated forms. It also outputs the
+interface function
+<tt class="docutils literal"><span class="pre">int</span> <span class="pre">getPredOpcode(uint16_t</span> <span class="pre">Opcode,</span> <span class="pre">enum</span> <span class="pre">PredSense</span> <span class="pre">inPredSense)</span></tt> to query
+the table. Here, Function <tt class="docutils literal"><span class="pre">getPredOpcode</span></tt> takes two arguments, opcode of the
+current instruction and PredSense of the desired instruction, and returns
+predicated form of the instruction, if found in the relation table.
+In order for an instruction to be added into the relation table, it needs
+to include relevant information in its definition. For example, consider
+following to be the current definitions of ADD, ADD_pt (true) and ADD_pf (false)
+instructions:</p>
+<div class="highlight-llvm"><pre>def ADD : ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
+ "$dst = add($a, $b)",
+ [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a),
+ (i32 IntRegs:$b)))]>;
+
+def ADD_Pt : ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if ($p) $dst = add($a, $b)",
+ []>;
+
+def ADD_Pf : ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if (!$p) $dst = add($a, $b)",
+ []>;</pre>
+</div>
+<p>In this step, we modify these instructions to include the information
+required by the relationship model, <tt>getPredOpcode</tt>, so that they can
+be related.</p>
+<div class="highlight-llvm"><pre>def ADD : PredRel, ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
+ "$dst = add($a, $b)",
+ [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a),
+ (i32 IntRegs:$b)))]> {
+ let BaseOpcode = "ADD";
+ let PredSense = "none";
+}
+
+def ADD_Pt : PredRel, ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if ($p) $dst = add($a, $b)",
+ []> {
+ let BaseOpcode = "ADD";
+ let PredSense = "true";
+}
+
+def ADD_Pf : PredRel, ALU32_rr<(outs IntRegs:$dst),
+ (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+ "if (!$p) $dst = add($a, $b)",
+ []> {
+ let BaseOpcode = "ADD";
+ let PredSense = "false";
+}</pre>
+</div>
+<p>Please note that all the above instructions use <tt class="docutils literal"><span class="pre">PredRel</span></tt> as a base class.
+This is extremely important since TableGen uses it as a filter for selecting
+instructions for <tt class="docutils literal"><span class="pre">getPredOpcode</span></tt> model. Any instruction not derived from
+<tt class="docutils literal"><span class="pre">PredRel</span></tt> is excluded from the analysis. <tt class="docutils literal"><span class="pre">BaseOpcode</span></tt> is another important
+field. Since it’s selected as a <tt class="docutils literal"><span class="pre">RowFields</span></tt> of the model, it is required
+to have the same value for all 3 instructions in order to be related. Next,
+<tt class="docutils literal"><span class="pre">PredSense</span></tt> is used to determine their column positions by comparing its value
+with <tt class="docutils literal"><span class="pre">KeyCol</span></tt> and <tt class="docutils literal"><span class="pre">ValueCols</span></tt>. If an instruction sets its <tt class="docutils literal"><span class="pre">PredSense</span></tt>
+value to something not used in the relation model, it will not be assigned
+a column in the relation table.</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="GarbageCollection.html" title="Accurate Garbage Collection with LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li><a href="WritingAnLLVMBackend.html" >Writing an LLVM Backend</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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/3.4.1/docs/LLVMBuild.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.4.1/docs/LLVMBuild.html?rev=208244&view=auto
==============================================================================
--- www-releases/trunk/3.4.1/docs/LLVMBuild.html (added)
+++ www-releases/trunk/3.4.1/docs/LLVMBuild.html Wed May 7 15:09:32 2014
@@ -0,0 +1,383 @@
+
+
+<!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>LLVMBuild Guide — LLVM 3.4 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: '3.4',
+ 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 3.4 documentation" href="index.html" />
+ <link rel="next" title="How To Release LLVM To The Public" href="HowToReleaseLLVM.html" />
+ <link rel="prev" title="Creating an LLVM Project" href="Projects.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="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Projects.html" title="Creating an LLVM Project"
+ 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="llvmbuild-guide">
+<h1>LLVMBuild Guide<a class="headerlink" href="#llvmbuild-guide" 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="#project-organization" id="id2">Project Organization</a></li>
+<li><a class="reference internal" href="#build-integration" id="id3">Build Integration</a></li>
+<li><a class="reference internal" href="#component-overview" id="id4">Component Overview</a></li>
+<li><a class="reference internal" href="#llvmbuild-format-reference" id="id5">LLVMBuild Format Reference</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 the <tt class="docutils literal"><span class="pre">LLVMBuild</span></tt> organization and files which
+we use to describe parts of the LLVM ecosystem. For description of
+specific LLVMBuild related tools, please see the command guide.</p>
+<p>LLVM is designed to be a modular set of libraries which can be flexibly
+mixed together in order to build a variety of tools, like compilers,
+JITs, custom code generators, optimization passes, interpreters, and so
+on. Related projects in the LLVM system like Clang and LLDB also tend to
+follow this philosophy.</p>
+<p>In order to support this usage style, LLVM has a fairly strict structure
+as to how the source code and various components are organized. The
+<tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> files are the explicit specification of that
+structure, and are used by the build systems and other tools in order to
+develop the LLVM project.</p>
+</div>
+<div class="section" id="project-organization">
+<h2><a class="toc-backref" href="#id2">Project Organization</a><a class="headerlink" href="#project-organization" title="Permalink to this headline">¶</a></h2>
+<p>The source code for LLVM projects using the LLVMBuild system (LLVM,
+Clang, and LLDB) is organized into <em>components</em>, which define the
+separate pieces of functionality that make up the project. These
+projects may consist of many libraries, associated tools, build tools,
+or other utility tools (for example, testing tools).</p>
+<p>For the most part, the project contents are organized around defining
+one main component per each subdirectory. Each such directory contains
+an <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> which contains the component definitions.</p>
+<p>The component descriptions for the project as a whole are automatically
+gathered by the LLVMBuild tools. The tools automatically traverse the
+source directory structure to find all of the component description
+files. NOTE: For performance/sanity reasons, we only traverse into
+subdirectories when the parent itself contains an <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt>
+description file.</p>
+</div>
+<div class="section" id="build-integration">
+<h2><a class="toc-backref" href="#id3">Build Integration</a><a class="headerlink" href="#build-integration" title="Permalink to this headline">¶</a></h2>
+<p>The LLVMBuild files themselves are just a declarative way to describe
+the project structure. The actual building of the LLVM project is
+handled by another build system (currently we support both
+<a class="reference internal" href="MakefileGuide.html"><em>Makefiles</em></a> and <a class="reference internal" href="CMake.html"><em>CMake</em></a>).</p>
+<p>The build system implementation will load the relevant contents of the
+LLVMBuild files and use that to drive the actual project build.
+Typically, the build system will only need to load this information at
+“configure” time, and use it to generative native information. Build
+systems will also handle automatically reconfiguring their information
+when the contents of the <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> files change.</p>
+<p>Developers generally are not expected to need to be aware of the details
+of how the LLVMBuild system is integrated into their build. Ideally,
+LLVM developers who are not working on the build system would only ever
+need to modify the contents of the <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> description files
+(although we have not reached this goal yet).</p>
+<p>For more information on the utility tool we provide to help interfacing
+with the build system, please see the <a class="reference internal" href="CommandGuide/llvm-build.html"><em>llvm-build</em></a> documentation.</p>
+</div>
+<div class="section" id="component-overview">
+<h2><a class="toc-backref" href="#id4">Component Overview</a><a class="headerlink" href="#component-overview" title="Permalink to this headline">¶</a></h2>
+<p>As mentioned earlier, LLVM projects are organized into logical
+<em>components</em>. Every component is typically grouped into its own
+subdirectory. Generally, a component is organized around a coherent
+group of sources which have some kind of clear API separation from other
+parts of the code.</p>
+<p>LLVM primarily uses the following types of components:</p>
+<ul class="simple">
+<li><em>Libraries</em> - Library components define a distinct API which can be
+independently linked into LLVM client applications. Libraries typically
+have private and public header files, and may specify a link of required
+libraries that they build on top of.</li>
+<li><em>Build Tools</em> - Build tools are applications which are designed to be run
+as part of the build process (typically to generate other source files).
+Currently, LLVM uses one main build tool called <a class="reference internal" href="TableGenFundamentals.html"><em>TableGen</em></a> to generate a variety of source files.</li>
+<li><em>Tools</em> - Command line applications which are built using the LLVM
+component libraries. Most LLVM tools are small and are primarily
+frontends to the library interfaces.</li>
+</ul>
+<p>Components are described using <tt class="docutils literal"><span class="pre">LLVMBuild.txt</span></tt> files in the directories
+that define the component. See the <a class="reference internal" href="#llvmbuild-format-reference">LLVMBuild Format Reference</a> section
+for information on the exact format of these files.</p>
+</div>
+<div class="section" id="llvmbuild-format-reference">
+<h2><a class="toc-backref" href="#id5">LLVMBuild Format Reference</a><a class="headerlink" href="#llvmbuild-format-reference" title="Permalink to this headline">¶</a></h2>
+<p>LLVMBuild files are written in a simple variant of the INI or configuration
+file format (<a class="reference external" href="http://en.wikipedia.org/wiki/INI_file">Wikipedia entry</a>). The format defines a list of sections
+each of which may contain some number of properties. A simple example of
+the file format is below:</p>
+<div class="highlight-ini"><div class="highlight"><pre><span class="c1">; Comments start with a semi-colon.</span>
+
+<span class="c1">; Sections are declared using square brackets.</span>
+<span class="k">[component_0]</span>
+
+<span class="c1">; Properties are declared using '=' and are contained in the previous section.</span>
+<span class="c1">;</span>
+<span class="c1">; We support simple string and boolean scalar values and list values, where</span>
+<span class="c1">; items are separated by spaces. There is no support for quoting, and so</span>
+<span class="c1">; property values may not contain spaces.</span>
+<span class="na">property_name</span> <span class="o">=</span> <span class="s">property_value</span>
+<span class="na">list_property_name</span> <span class="o">=</span> <span class="s">value_1 value_2 ... value_n</span>
+<span class="na">boolean_property_name</span> <span class="o">=</span> <span class="s">1 (or 0)</span>
+</pre></div>
+</div>
+<p>LLVMBuild files are expected to define a strict set of sections and
+properties. A typical component description file for a library
+component would look like the following example:</p>
+<div class="highlight-ini"><div class="highlight"><pre><span class="k">[component_0]</span>
+<span class="na">type</span> <span class="o">=</span> <span class="s">Library</span>
+<span class="na">name</span> <span class="o">=</span> <span class="s">Linker</span>
+<span class="na">parent</span> <span class="o">=</span> <span class="s">Libraries</span>
+<span class="na">required_libraries</span> <span class="o">=</span> <span class="s">Archive BitReader Core Support TransformUtils</span>
+</pre></div>
+</div>
+<p>A full description of the exact sections and properties which are
+allowed follows.</p>
+<p>Each file may define exactly one common component, named <tt class="docutils literal"><span class="pre">common</span></tt>. The
+common component may define the following properties:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">subdirectories</span></tt> <strong>[optional]</strong></p>
+<p>If given, a list of the names of the subdirectories from the current
+subpath to search for additional LLVMBuild files.</p>
+</li>
+</ul>
+<p>Each file may define multiple components. Each component is described by a
+section who name starts with <tt class="docutils literal"><span class="pre">component</span></tt>. The remainder of the section
+name is ignored, but each section name must be unique. Typically components
+are just number in order for files with multiple components
+(<tt class="docutils literal"><span class="pre">component_0</span></tt>, <tt class="docutils literal"><span class="pre">component_1</span></tt>, and so on).</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Section names not matching this format (or the <tt class="docutils literal"><span class="pre">common</span></tt> section) are
+currently unused and are disallowed.</p>
+</div>
+<p>Every component is defined by the properties in the section. The exact
+list of properties that are allowed depends on the component type.
+Components <strong>may not</strong> define any properties other than those expected
+by the component type.</p>
+<p>Every component must define the following properties:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span></tt> <strong>[required]</strong></p>
+<p>The type of the component. Supported component types are detailed
+below. Most components will define additional properties which may be
+required or optional.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">name</span></tt> <strong>[required]</strong></p>
+<p>The name of the component. Names are required to be unique across the
+entire project.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">parent</span></tt> <strong>[required]</strong></p>
+<p>The name of the logical parent of the component. Components are
+organized into a logical tree to make it easier to navigate and
+organize groups of components. The parents have no semantics as far
+as the project build is concerned, however. Typically, the parent
+will be the main component of the parent directory.</p>
+<p>Components may reference the root pseudo component using <tt class="docutils literal"><span class="pre">$ROOT</span></tt> to
+indicate they should logically be grouped at the top-level.</p>
+</li>
+</ul>
+<p>Components may define the following properties:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">dependencies</span></tt> <strong>[optional]</strong></p>
+<p>If specified, a list of names of components which <em>must</em> be built
+prior to this one. This should only be exactly those components which
+produce some tool or source code required for building the component.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last"><tt class="docutils literal"><span class="pre">Group</span></tt> and <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> components have no semantics for the
+actual build, and are not allowed to specify dependencies.</p>
+</div>
+</li>
+</ul>
+<p>The following section lists the available component types, as well as
+the properties which are associated with that component.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Group</span></tt></p>
+<p>Group components exist purely to allow additional arbitrary structuring
+of the logical components tree. For example, one might define a
+<tt class="docutils literal"><span class="pre">Libraries</span></tt> group to hold all of the root library components.</p>
+<p><tt class="docutils literal"><span class="pre">Group</span></tt> components have no additionally properties.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Library</span></tt></p>
+<p>Library components define an individual library which should be built
+from the source code in the component directory.</p>
+<p>Components with this type use the following properties:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">library_name</span></tt> <strong>[optional]</strong></p>
+<p>If given, the name to use for the actual library file on disk. If
+not given, the name is derived from the component name itself.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">required_libraries</span></tt> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <tt class="docutils literal"><span class="pre">Library</span></tt> or <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt>
+components which must also be linked in whenever this library is
+used. That is, the link time dependencies for this component. When
+tools are built, the build system will include the transitive closure
+of all <tt class="docutils literal"><span class="pre">required_libraries</span></tt> for the components the tool needs.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">add_to_library_groups</span></tt> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> components which
+this component is also part of. This allows nesting groups of
+components. For example, the <tt class="docutils literal"><span class="pre">X86</span></tt> target might define a library
+group for all of the <tt class="docutils literal"><span class="pre">X86</span></tt> components. That library group might
+then be included in the <tt class="docutils literal"><span class="pre">all-targets</span></tt> library group.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">installed</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this library is installed. Libraries that are not installed
+are only reported by <tt class="docutils literal"><span class="pre">llvm-config</span></tt> when it is run as part of a
+development directory.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">LibraryGroup</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> components are a mechanism to allow easy definition of
+useful sets of related components. In particular, we use them to easily
+specify things like “all targets”, or “all assembly printers”.</p>
+<p>Components with this type use the following properties:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">required_libraries</span></tt> <strong>[optional]</strong></p>
+<p>See the <tt class="docutils literal"><span class="pre">Library</span></tt> type for a description of this property.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">add_to_library_groups</span></tt> <strong>[optional]</strong></p>
+<p>See the <tt class="docutils literal"><span class="pre">Library</span></tt> type for a description of this property.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">TargetGroup</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">TargetGroup</span></tt> components are an extension of <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt>s,
+specifically for defining LLVM targets (which are handled specially in a
+few places).</p>
+<p>The name of the component should always be the name of the target.</p>
+<p>Components with this type use the <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt> properties in
+addition to:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_asmparser</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines an assembly parser.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_asmprinter</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines an assembly printer.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_disassembler</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target defines a disassembler.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">has_jit</span></tt> <strong>[optional]</strong> <strong>[boolean]</strong></p>
+<p>Whether this target supports JIT compilation.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">Tool</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">Tool</span></tt> components define standalone command line tools which should be
+built from the source code in the component directory and linked.</p>
+<p>Components with this type use the following properties:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">required_libraries</span></tt> <strong>[optional]</strong></p>
+<p>If given, a list of the names of <tt class="docutils literal"><span class="pre">Library</span></tt> or <tt class="docutils literal"><span class="pre">LibraryGroup</span></tt>
+components which this tool is required to be linked with.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The values should be the component names, which may not always
+match up with the actual library names on disk.</p>
+</div>
+<p>Build systems are expected to properly include all of the libraries
+required by the linked components (i.e., the transitive closure of
+<tt class="docutils literal"><span class="pre">required_libraries</span></tt>).</p>
+<p>Build systems are also expected to understand that those library
+components must be built prior to linking – they do not also need
+to be listed under <tt class="docutils literal"><span class="pre">dependencies</span></tt>.</p>
+</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">type</span> <span class="pre">=</span> <span class="pre">BuildTool</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">BuildTool</span></tt> components are like <tt class="docutils literal"><span class="pre">Tool</span></tt> components, except that the
+tool is supposed to be built for the platform where the build is running
+(instead of that platform being targetted). Build systems are expected
+to handle the fact that required libraries may need to be built for
+multiple platforms in order to be able to link this tool.</p>
+<p><tt class="docutils literal"><span class="pre">BuildTool</span></tt> components currently use the exact same properties as
+<tt class="docutils literal"><span class="pre">Tool</span></tt> components, the type distinction is only used to differentiate
+what the tool is built for.</p>
+</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="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Projects.html" title="Creating an LLVM Project"
+ >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-2013, LLVM Project.
+ Last updated on 2014-05-06.
+ 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