Home | History | Annotate | Download | only in docs
      1 <?xml version="1.0" encoding="utf-8" ?>
      2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
      4 <head>
      5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
      6 <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
      7 <title>Tutorial - Using LLVMC</title>
      8 <link rel="stylesheet" href="llvm.css" type="text/css" />
      9 </head>
     10 <body>
     11 <div class="document" id="tutorial-using-llvmc">
     12 <h1 class="title">Tutorial - Using LLVMC</h1>
     13 
     14 <!-- This file was automatically generated by rst2html.
     15 Please do not edit directly!
     16 The ReST source lives in the directory 'tools/llvmc/doc'. -->
     17 <div class="contents topic" id="contents">
     18 <p class="topic-title first">Contents</p>
     19 <ul class="simple">
     20 <li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
     21 <li><a class="reference internal" href="#using-the-llvmc-program" id="id2">Using the <tt class="docutils literal">llvmc</tt> program</a></li>
     22 <li><a class="reference internal" href="#using-llvmc-to-generate-toolchain-drivers" id="id3">Using LLVMC to generate toolchain drivers</a></li>
     23 </ul>
     24 </div>
     25 <div class="doc_author">
     26 <p>Written by <a href="mailto:foldr (a] codedgers.com">Mikhail Glushenkov</a></p>
     27 </div><div class="section" id="introduction">
     28 <h1><a class="toc-backref" href="#id1">Introduction</a></h1>
     29 <p>LLVMC is a generic compiler driver, which plays the same role for LLVM as the
     30 <tt class="docutils literal">gcc</tt> program does for GCC - the difference being that LLVMC is designed to be
     31 more adaptable and easier to customize. Most of LLVMC functionality is
     32 implemented via high-level TableGen code, from which a corresponding C++ source
     33 file is automatically generated. This tutorial describes the basic usage and
     34 configuration of LLVMC.</p>
     35 </div>
     36 <div class="section" id="using-the-llvmc-program">
     37 <h1><a class="toc-backref" href="#id2">Using the <tt class="docutils literal">llvmc</tt> program</a></h1>
     38 <p>In general, <tt class="docutils literal">llvmc</tt> tries to be command-line compatible with <tt class="docutils literal">gcc</tt> as much
     39 as possible, so most of the familiar options work:</p>
     40 <pre class="literal-block">
     41 $ llvmc -O3 -Wall hello.cpp
     42 $ ./a.out
     43 hello
     44 </pre>
     45 <p>This will invoke <tt class="docutils literal"><span class="pre">llvm-g++</span></tt> under the hood (you can see which commands are
     46 executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on command-line LLVMC
     47 usage, refer to the <tt class="docutils literal">llvmc <span class="pre">--help</span></tt> output.</p>
     48 </div>
     49 <div class="section" id="using-llvmc-to-generate-toolchain-drivers">
     50 <h1><a class="toc-backref" href="#id3">Using LLVMC to generate toolchain drivers</a></h1>
     51 <p>LLVMC-based drivers are written mostly using <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a>, so you need to be
     52 familiar with it to get anything done.</p>
     53 <p>Start by compiling <tt class="docutils literal">example/Simple</tt>, which is a primitive wrapper for
     54 <tt class="docutils literal">gcc</tt>:</p>
     55 <pre class="literal-block">
     56 $ cd $LLVM_OBJ_DIR/tools/examples/Simple
     57 $ make
     58 $ cat &gt; hello.c
     59 #include &lt;stdio.h&gt;
     60 int main() { printf(&quot;Hello\n&quot;); }
     61 $ $LLVM_BIN_DIR/Simple -v hello.c
     62 gcc hello.c -o hello.out
     63 $ ./hello.out
     64 Hello
     65 </pre>
     66 <p>We have thus produced a simple driver called, appropriately, <tt class="docutils literal">Simple</tt>, from
     67 the input TableGen file <tt class="docutils literal">Simple.td</tt>. The <tt class="docutils literal">llvmc</tt> program itself is generated
     68 using a similar process (see <tt class="docutils literal">llvmc/src</tt>). Contents of the file <tt class="docutils literal">Simple.td</tt>
     69 look like this:</p>
     70 <pre class="literal-block">
     71 // Include common definitions
     72 include &quot;llvm/CompilerDriver/Common.td&quot;
     73 
     74 // Tool descriptions
     75 def gcc : Tool&lt;
     76 [(in_language &quot;c&quot;),
     77  (out_language &quot;executable&quot;),
     78  (output_suffix &quot;out&quot;),
     79  (command &quot;gcc&quot;),
     80  (sink),
     81 
     82  // -o is what is used by default, out_file_option here is included for
     83  // instructive purposes.
     84  (out_file_option &quot;-o&quot;)
     85 ]&gt;;
     86 
     87 // Language map
     88 def LanguageMap : LanguageMap&lt;[(lang_to_suffixes &quot;c&quot;, &quot;c&quot;)]&gt;;
     89 
     90 // Compilation graph
     91 def CompilationGraph : CompilationGraph&lt;[(edge &quot;root&quot;, &quot;gcc&quot;)]&gt;;
     92 </pre>
     93 <p>As you can see, this file consists of three parts: tool descriptions, language
     94 map, and the compilation graph definition.</p>
     95 <p>At the heart of LLVMC is the idea of a compilation graph: vertices in this graph
     96 are tools, and edges represent a transformation path between two tools (for
     97 example, assembly source produced by the compiler can be transformed into
     98 executable code by an assembler). The compilation graph is basically a list of
     99 edges; a special node named <tt class="docutils literal">root</tt> is used to mark graph entry points.</p>
    100 <p>Tool descriptions are represented as property lists: most properties in the
    101 example above should be self-explanatory; the <tt class="docutils literal">sink</tt> property means that all
    102 options lacking an explicit description should be forwarded to this tool.</p>
    103 <p>The <tt class="docutils literal">LanguageMap</tt> associates a language name with a list of suffixes and is
    104 used for deciding which toolchain corresponds to a given input file.</p>
    105 <p>To learn more about writing your own drivers with LLVMC, refer to the reference
    106 manual and examples in the <tt class="docutils literal">examples</tt> directory. Of a particular interest is
    107 the <tt class="docutils literal">Skeleton</tt> example, which can serve as a template for your LLVMC-based
    108 drivers.</p>
    109 <hr />
    110 <address>
    111 <a href="http://jigsaw.w3.org/css-validator/check/referer">
    112 <img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
    113    alt="Valid CSS" /></a>
    114 <a href="http://validator.w3.org/check?uri=referer">
    115 <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
    116    alt="Valid XHTML 1.0 Transitional"/></a>
    117 
    118 <a href="mailto:foldr (a] codedgers.com">Mikhail Glushenkov</a><br />
    119 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
    120 
    121 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
    122 </address></div>
    123 </div>
    124 </body>
    125 </html>
    126