docs/CompilerDriverTutorial.html

   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.4.1: http://docutils.sourceforge.net/" />
   7 <title>Tutorial - Using LLVMC</title>
   8 <meta name="author" content="Mikhail Glushenkov &lt;foldr&#64;codedegers.com&gt;" />
   9 <link rel="stylesheet" href="llvm-rst.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document" id="tutorial-using-llvmc">
  13 <h1 class="title">Tutorial - Using LLVMC</h1>
  14 <table class="docinfo" frame="void" rules="none">
  15 <col class="docinfo-name" />
  16 <col class="docinfo-content" />
  17 <tbody valign="top">
  18 <tr><th class="docinfo-name">Author:</th>
  19 <td>Mikhail Glushenkov &lt;<a class="reference" href="mailto:foldr&#64;codedegers.com">foldr&#64;codedegers.com</a>&gt;</td></tr>
  20 </tbody>
  21 </table>
  22 <p>LLVMC is a generic compiler driver, which plays the same role for LLVM
  23 as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program does for GCC - the difference being that LLVMC
  24 is designed to be more adaptable and easier to customize. Most of
  25 LLVMC functionality is implemented via plugins, which can be loaded
  26 dynamically or compiled in. This tutorial describes the basic usage
  27 and configuration of LLVMC.</p>
  28 <div class="contents topic">
  29 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
  30 <ul class="simple">
  31 <li><a class="reference" href="#compiling-with-llvmc" id="id3" name="id3">Compiling with LLVMC</a></li>
  32 <li><a class="reference" href="#using-llvmc-to-generate-toolchain-drivers" id="id4" name="id4">Using LLVMC to generate toolchain drivers</a></li>
  33 <li><a class="reference" href="#references" id="id5" name="id5">References</a></li>
  34 </ul>
  35 </div>
  36 <div class="section">
  37 <h1><a class="toc-backref" href="#id3" id="compiling-with-llvmc" name="compiling-with-llvmc">Compiling with LLVMC</a></h1>
  38 <p>In general, LLVMC tries to be command-line compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as
  39 much 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
  46 commands are executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on
  47 command-line LLVMC usage, refer to the <tt class="docutils literal"><span class="pre">llvmc</span> <span class="pre">--help</span></tt> output.</p>
  48 </div>
  49 <div class="section">
  50 <h1><a class="toc-backref" href="#id4" id="using-llvmc-to-generate-toolchain-drivers" name="using-llvmc-to-generate-toolchain-drivers">Using LLVMC to generate toolchain drivers</a></h1>
  51 <p>LLVMC plugins are written mostly using TableGen <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>, so you need to
  52 be familiar with it to get anything done.</p>
  53 <p>Start by compiling <tt class="docutils literal"><span class="pre">plugins/Simple/Simple.td</span></tt>, which is a primitive
  54 wrapper for <tt class="docutils literal"><span class="pre">gcc</span></tt>:</p>
  55 <pre class="literal-block">
  56 $ cd $LLVM_DIR/tools/llvmc
  57 $ make DRIVER_NAME=mygcc BUILTIN_PLUGINS=Simple
  58 $ cat &gt; hello.c
  59 [...]
  60 $ mygcc hello.c
  61 $ ./hello.out
  62 Hello
  63 </pre>
  64 <p>Here we link our plugin with the LLVMC core statically to form an
  65 executable file called <tt class="docutils literal"><span class="pre">mygcc</span></tt>. It is also possible to build our
  66 plugin as a standalone dynamic library; this is described in the
  67 reference manual.</p>
  68 <p>Contents of the file <tt class="docutils literal"><span class="pre">Simple.td</span></tt> look like this:</p>
  69 <pre class="literal-block">
  70 // Include common definitions
  71 include &quot;llvm/CompilerDriver/Common.td&quot;
  72
  73 // Tool descriptions
  74 def gcc : Tool&lt;
  75 [(in_language &quot;c&quot;),
  76  (out_language &quot;executable&quot;),
  77  (output_suffix &quot;out&quot;),
  78  (cmd_line &quot;gcc $INFILE -o $OUTFILE&quot;),
  79  (sink)
  80 ]&gt;;
  81
  82 // Language map
  83 def LanguageMap : LanguageMap&lt;[LangToSuffixes&lt;&quot;c&quot;, [&quot;c&quot;]&gt;]&gt;;
  84
  85 // Compilation graph
  86 def CompilationGraph : CompilationGraph&lt;[Edge&lt;&quot;root&quot;, &quot;gcc&quot;&gt;]&gt;;
  87 </pre>
  88 <p>As you can see, this file consists of three parts: tool descriptions,
  89 language map, and the compilation graph definition.</p>
  90 <p>At the heart of LLVMC is the idea of a compilation graph: vertices in
  91 this graph are tools, and edges represent a transformation path
  92 between two tools (for example, assembly source produced by the
  93 compiler can be transformed into executable code by an assembler). The
  94 compilation graph is basically a list of edges; a special node named
  95 <tt class="docutils literal"><span class="pre">root</span></tt> is used to mark graph entry points.</p>
  96 <p>Tool descriptions are represented as property lists: most properties
  97 in the example above should be self-explanatory; the <tt class="docutils literal"><span class="pre">sink</span></tt> property
  98 means that all options lacking an explicit description should be
  99 forwarded to this tool.</p>
 100 <p>The <tt class="docutils literal"><span class="pre">LanguageMap</span></tt> associates a language name with a list of suffixes
 101 and is used for deciding which toolchain corresponds to a given input
 102 file.</p>
 103 <p>To learn more about LLVMC customization, refer to the reference
 104 manual and plugin source code in the <tt class="docutils literal"><span class="pre">plugins</span></tt> directory.</p>
 105 </div>
 106 <div class="section">
 107 <h1><a class="toc-backref" href="#id5" id="references" name="references">References</a></h1>
 108 <table class="docutils footnote" frame="void" id="id2" rules="none">
 109 <colgroup><col class="label" /><col /></colgroup>
 110 <tbody valign="top">
 111 <tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>TableGen Fundamentals
 112 <a class="reference" href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html</a></td></tr>
 113 </tbody>
 114 </table>
 115 <hr />
 116 <address>
 117   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
 118   alt="Valid CSS" /></a>
 119   <a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10-blue"
 120   alt="Valid XHTML 1.0 Transitional"/></a>
 121
 122   <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
 123   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
 124
 125   Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
 126 </address>
 127 </div>
 128 </div>
 129 </body>
 130 </html>