Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 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" /> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 6 | <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 7 | <title>Tutorial - Using LLVMC</title> |
Mikhail Glushenkov | 8cc8288 | 2008-12-13 17:50:58 +0000 | [diff] [blame] | 8 | <link rel="stylesheet" href="llvm.css" type="text/css" /> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 9 | </head> |
| 10 | <body> |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 11 | <div class="document" id="tutorial-using-llvmc"> |
| 12 | <h1 class="title">Tutorial - Using LLVMC</h1> |
Mikhail Glushenkov | d6d2efc | 2009-05-06 01:41:47 +0000 | [diff] [blame] | 13 | |
Mikhail Glushenkov | 23f522a | 2008-12-13 17:51:47 +0000 | [diff] [blame] | 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'. --> |
Mikhail Glushenkov | d6d2efc | 2009-05-06 01:41:47 +0000 | [diff] [blame] | 17 | <div class="contents topic" id="contents"> |
| 18 | <p class="topic-title first">Contents</p> |
Mikhail Glushenkov | d565203 | 2008-12-13 02:28:58 +0000 | [diff] [blame] | 19 | <ul class="simple"> |
Mikhail Glushenkov | d6d2efc | 2009-05-06 01:41:47 +0000 | [diff] [blame] | 20 | <li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 21 | <li><a class="reference internal" href="#using-the-llvmc-program" id="id2">Using the <tt class="docutils literal">llvmc</tt> program</a></li> |
Mikhail Glushenkov | d6d2efc | 2009-05-06 01:41:47 +0000 | [diff] [blame] | 22 | <li><a class="reference internal" href="#using-llvmc-to-generate-toolchain-drivers" id="id3">Using LLVMC to generate toolchain drivers</a></li> |
Mikhail Glushenkov | d565203 | 2008-12-13 02:28:58 +0000 | [diff] [blame] | 23 | </ul> |
| 24 | </div> |
| 25 | <div class="doc_author"> |
| 26 | <p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p> |
Mikhail Glushenkov | d6d2efc | 2009-05-06 01:41:47 +0000 | [diff] [blame] | 27 | </div><div class="section" id="introduction"> |
| 28 | <h1><a class="toc-backref" href="#id1">Introduction</a></h1> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 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> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 35 | </div> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 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> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 40 | <pre class="literal-block"> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 41 | $ llvmc -O3 -Wall hello.cpp |
| 42 | $ ./a.out |
| 43 | hello |
| 44 | </pre> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 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> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 48 | </div> |
Mikhail Glushenkov | d6d2efc | 2009-05-06 01:41:47 +0000 | [diff] [blame] | 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> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 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> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 55 | <pre class="literal-block"> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 56 | $ cd $LLVM_OBJ_DIR/tools/examples/Simple |
| 57 | $ make |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 58 | $ cat > hello.c |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 59 | #include <stdio.h> |
| 60 | int main() { printf("Hello\n"); } |
| 61 | $ $LLVM_BIN_DIR/Simple -v hello.c |
| 62 | gcc hello.c -o hello.out |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 63 | $ ./hello.out |
| 64 | Hello |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 65 | </pre> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 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> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 70 | <pre class="literal-block"> |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 71 | // Include common definitions |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 72 | include "llvm/CompilerDriver/Common.td" |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 73 | |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 74 | // Tool descriptions |
| 75 | def gcc : Tool< |
| 76 | [(in_language "c"), |
| 77 | (out_language "executable"), |
| 78 | (output_suffix "out"), |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 79 | (command "gcc"), |
| 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 "-o") |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 85 | ]>; |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 86 | |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 87 | // Language map |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 88 | def LanguageMap : LanguageMap<[(lang_to_suffixes "c", "c")]>; |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 89 | |
Mikhail Glushenkov | 99a3a2c | 2008-12-11 23:33:33 +0000 | [diff] [blame] | 90 | // Compilation graph |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 91 | def CompilationGraph : CompilationGraph<[(edge "root", "gcc")]>; |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 92 | </pre> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 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> |
Mikhail Glushenkov | 9053154 | 2008-12-11 23:43:14 +0000 | [diff] [blame] | 109 | <hr /> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 110 | <address> |
Mikhail Glushenkov | d565203 | 2008-12-13 02:28:58 +0000 | [diff] [blame] | 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> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 117 | |
Mikhail Glushenkov | d565203 | 2008-12-13 02:28:58 +0000 | [diff] [blame] | 118 | <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br /> |
Mikhail Glushenkov | fb88665 | 2011-04-24 14:17:37 +0000 | [diff] [blame^] | 119 | <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br /> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 120 | |
Mikhail Glushenkov | d565203 | 2008-12-13 02:28:58 +0000 | [diff] [blame] | 121 | Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $ |
| 122 | </address></div> |
Mikhail Glushenkov | 68319f8 | 2008-12-11 23:24:40 +0000 | [diff] [blame] | 123 | </div> |
| 124 | </body> |
| 125 | </html> |