[www-releases] r275092 - Add 3.8.1 documentation
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Mon Jul 11 12:36:15 PDT 2016
Added: www-releases/trunk/3.8.1/docs/HowToUseAttributes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.8.1/docs/HowToUseAttributes.html?rev=275092&view=auto
==============================================================================
--- www-releases/trunk/3.8.1/docs/HowToUseAttributes.html (added)
+++ www-releases/trunk/3.8.1/docs/HowToUseAttributes.html Mon Jul 11 14:36:11 2016
@@ -0,0 +1,169 @@
+
+<!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.8 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.8',
+ 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.8 documentation" href="index.html" />
+ <link rel="next" title="User Guide for NVPTX Back-end" href="NVPTXUsage.html" />
+ <link rel="prev" title="Writing an LLVM Pass" href="WritingAnLLVMPass.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="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ 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="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ >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-2016, LLVM Project.
+ Last updated on 2016-07-11.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.8.1/docs/HowToUseInstrMappings.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.8.1/docs/HowToUseInstrMappings.html?rev=275092&view=auto
==============================================================================
--- www-releases/trunk/3.8.1/docs/HowToUseInstrMappings.html (added)
+++ www-releases/trunk/3.8.1/docs/HowToUseInstrMappings.html Mon Jul 11 14:36:11 2016
@@ -0,0 +1,269 @@
+
+<!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.8 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.8',
+ 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.8 documentation" href="index.html" />
+ <link rel="up" title="Writing an LLVM Backend" href="WritingAnLLVMBackend.html" />
+ <link rel="next" title="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="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"><div class="highlight"><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>
+<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"><div class="highlight"><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>
+</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"><div class="highlight"><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>
+</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"><div class="highlight"><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>
+</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="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-2016, LLVM Project.
+ Last updated on 2016-07-11.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.8.1/docs/InAlloca.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.8.1/docs/InAlloca.html?rev=275092&view=auto
==============================================================================
--- www-releases/trunk/3.8.1/docs/InAlloca.html (added)
+++ www-releases/trunk/3.8.1/docs/InAlloca.html Mon Jul 11 14:36:11 2016
@@ -0,0 +1,240 @@
+
+<!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>Design and Usage of the InAlloca Attribute — LLVM 3.8 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.8',
+ 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.8 documentation" href="index.html" />
+ <link rel="next" title="Using ARM NEON instructions in big endian mode" href="BigEndianNEON.html" />
+ <link rel="prev" title="Stack maps and patch points in LLVM" href="StackMaps.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="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="StackMaps.html" title="Stack maps and patch points in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="design-and-usage-of-the-inalloca-attribute">
+<h1>Design and Usage of the InAlloca Attribute<a class="headerlink" href="#design-and-usage-of-the-inalloca-attribute" 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>The <a class="reference internal" href="LangRef.html#attr-inalloca"><em>inalloca</em></a> attribute is designed to allow
+taking the address of an aggregate argument that is being passed by
+value through memory. Primarily, this feature is required for
+compatibility with the Microsoft C++ ABI. Under that ABI, class
+instances that are passed by value are constructed directly into
+argument stack memory. Prior to the addition of inalloca, calls in LLVM
+were indivisible instructions. There was no way to perform intermediate
+work, such as object construction, between the first stack adjustment
+and the final control transfer. With inalloca, all arguments passed in
+memory are modelled as a single alloca, which can be stored to prior to
+the call. Unfortunately, this complicated feature comes with a large
+set of restrictions designed to bound the lifetime of the argument
+memory around the call.</p>
+<p>For now, it is recommended that frontends and optimizers avoid producing
+this construct, primarily because it forces the use of a base pointer.
+This feature may grow in the future to allow general mid-level
+optimization, but for now, it should be regarded as less efficient than
+passing by value with a copy.</p>
+</div>
+<div class="section" id="intended-usage">
+<h2>Intended Usage<a class="headerlink" href="#intended-usage" title="Permalink to this headline">¶</a></h2>
+<p>The example below is the intended LLVM IR lowering for some C++ code
+that passes two default-constructed <tt class="docutils literal"><span class="pre">Foo</span></tt> objects to <tt class="docutils literal"><span class="pre">g</span></tt> in the
+32-bit Microsoft C++ ABI.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Foo is non-trivial.</span>
+<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">;</span> <span class="n">Foo</span><span class="p">();</span> <span class="o">~</span><span class="n">Foo</span><span class="p">();</span> <span class="n">Foo</span><span class="p">(</span><span class="k">const</span> <span class="n">Foo</span> <span class="o">&</span><span class="p">);</span> <span class="p">};</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="n">Foo</span> <span class="n">a</span><span class="p">,</span> <span class="n">Foo</span> <span class="n">b</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">g</span><span class="p">(</span><span class="n">Foo</span><span class="p">(),</span> <span class="n">Foo</span><span class="p">());</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-llvm"><div class="highlight"><pre>%struct.Foo = type { i32, i32 }
+declare void @Foo_ctor(%struct.Foo* %this)
+declare void @Foo_dtor(%struct.Foo* %this)
+declare void @g(<{ %struct.Foo, %struct.Foo }>* inalloca %memargs)
+
+define void @f() {
+entry:
+ %base = call i8* @llvm.stacksave()
+ %memargs = alloca <{ %struct.Foo, %struct.Foo }>
+ %b = getelementptr <{ %struct.Foo, %struct.Foo }>* %memargs, i32 1
+ call void @Foo_ctor(%struct.Foo* %b)
+
+ ; If a's ctor throws, we must destruct b.
+ %a = getelementptr <{ %struct.Foo, %struct.Foo }>* %memargs, i32 0
+ invoke void @Foo_ctor(%struct.Foo* %a)
+ to label %invoke.cont unwind %invoke.unwind
+
+invoke.cont:
+ call void @g(<{ %struct.Foo, %struct.Foo }>* inalloca %memargs)
+ call void @llvm.stackrestore(i8* %base)
+ ...
+
+invoke.unwind:
+ call void @Foo_dtor(%struct.Foo* %b)
+ call void @llvm.stackrestore(i8* %base)
+ ...
+}
+</pre></div>
+</div>
+<p>To avoid stack leaks, the frontend saves the current stack pointer with
+a call to <a class="reference internal" href="LangRef.html#int-stacksave"><em>llvm.stacksave</em></a>. Then, it allocates the
+argument stack space with alloca and calls the default constructor. The
+default constructor could throw an exception, so the frontend has to
+create a landing pad. The frontend has to destroy the already
+constructed argument <tt class="docutils literal"><span class="pre">b</span></tt> before restoring the stack pointer. If the
+constructor does not unwind, <tt class="docutils literal"><span class="pre">g</span></tt> is called. In the Microsoft C++ ABI,
+<tt class="docutils literal"><span class="pre">g</span></tt> will destroy its arguments, and then the stack is restored in
+<tt class="docutils literal"><span class="pre">f</span></tt>.</p>
+</div>
+<div class="section" id="design-considerations">
+<h2>Design Considerations<a class="headerlink" href="#design-considerations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="lifetime">
+<h3>Lifetime<a class="headerlink" href="#lifetime" title="Permalink to this headline">¶</a></h3>
+<p>The biggest design consideration for this feature is object lifetime.
+We cannot model the arguments as static allocas in the entry block,
+because all calls need to use the memory at the top of the stack to pass
+arguments. We cannot vend pointers to that memory at function entry
+because after code generation they will alias.</p>
+<p>The rule against allocas between argument allocations and the call site
+avoids this problem, but it creates a cleanup problem. Cleanup and
+lifetime is handled explicitly with stack save and restore calls. In
+the future, we may want to introduce a new construct such as <tt class="docutils literal"><span class="pre">freea</span></tt>
+or <tt class="docutils literal"><span class="pre">afree</span></tt> to make it clear that this stack adjusting cleanup is less
+powerful than a full stack save and restore.</p>
+</div>
+<div class="section" id="nested-calls-and-copy-elision">
+<h3>Nested Calls and Copy Elision<a class="headerlink" href="#nested-calls-and-copy-elision" title="Permalink to this headline">¶</a></h3>
+<p>We also want to be able to support copy elision into these argument
+slots. This means we have to support multiple live argument
+allocations.</p>
+<p>Consider the evaluation of:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Foo is non-trivial.</span>
+<span class="k">struct</span> <span class="n">Foo</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">;</span> <span class="n">Foo</span><span class="p">();</span> <span class="n">Foo</span><span class="p">(</span><span class="k">const</span> <span class="o">&</span><span class="n">Foo</span><span class="p">);</span> <span class="o">~</span><span class="n">Foo</span><span class="p">();</span> <span class="p">};</span>
+<span class="n">Foo</span> <span class="nf">bar</span><span class="p">(</span><span class="n">Foo</span> <span class="n">b</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bar</span><span class="p">(</span><span class="n">bar</span><span class="p">(</span><span class="n">Foo</span><span class="p">()));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case, we want to be able to elide copies into <tt class="docutils literal"><span class="pre">bar</span></tt>‘s argument
+slots. That means we need to have more than one set of argument frames
+active at the same time. First, we need to allocate the frame for the
+outer call so we can pass it in as the hidden struct return pointer to
+the middle call. Then we do the same for the middle call, allocating a
+frame and passing its address to <tt class="docutils literal"><span class="pre">Foo</span></tt>‘s default constructor. By
+wrapping the evaluation of the inner <tt class="docutils literal"><span class="pre">bar</span></tt> with stack save and
+restore, we can have multiple overlapping active call frames.</p>
+</div>
+<div class="section" id="callee-cleanup-calling-conventions">
+<h3>Callee-cleanup Calling Conventions<a class="headerlink" href="#callee-cleanup-calling-conventions" title="Permalink to this headline">¶</a></h3>
+<p>Another wrinkle is the existence of callee-cleanup conventions. On
+Windows, all methods and many other functions adjust the stack to clear
+the memory used to pass their arguments. In some sense, this means that
+the allocas are automatically cleared by the call. However, LLVM
+instead models this as a write of undef to all of the inalloca values
+passed to the call instead of a stack adjustment. Frontends should
+still restore the stack pointer to avoid a stack leak.</p>
+</div>
+<div class="section" id="exceptions">
+<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
+<p>There is also the possibility of an exception. If argument evaluation
+or copy construction throws an exception, the landing pad must do
+cleanup, which includes adjusting the stack pointer to avoid a stack
+leak. This means the cleanup of the stack memory cannot be tied to the
+call itself. There needs to be a separate IR-level instruction that can
+perform independent cleanup of arguments.</p>
+</div>
+<div class="section" id="efficiency">
+<h3>Efficiency<a class="headerlink" href="#efficiency" title="Permalink to this headline">¶</a></h3>
+<p>Eventually, it should be possible to generate efficient code for this
+construct. In particular, using inalloca should not require a base
+pointer. If the backend can prove that all points in the CFG only have
+one possible stack level, then it can address the stack directly from
+the stack pointer. While this is not yet implemented, the plan is that
+the inalloca attribute should not change much, but the frontend IR
+generation recommendations may change.</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="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="StackMaps.html" title="Stack maps and patch points in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2016, LLVM Project.
+ Last updated on 2016-07-11.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.8.1/docs/LLVMBuild.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.8.1/docs/LLVMBuild.html?rev=275092&view=auto
==============================================================================
--- www-releases/trunk/3.8.1/docs/LLVMBuild.html (added)
+++ www-releases/trunk/3.8.1/docs/LLVMBuild.html Mon Jul 11 14:36:11 2016
@@ -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.8 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.8',
+ 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.8 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="TableGen/index.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 targeted). 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-2016, LLVM Project.
+ Last updated on 2016-07-11.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list