Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 43f51aeca8367ea35adad963c00bd2bc5b8d1391 / . / docs / CompilerDriverTutorial.html
blob: 4ed373aa160ac07e1bb24880b981d841f3f4bd10 [file] [log] [blame]
Mikhail Glushenkov68319f82008-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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]6<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame]7<title>Tutorial - Using LLVMC</title>
Mikhail Glushenkov8cc82882008-12-13 17:50:58 +0000[diff] [blame]8<link rel="stylesheet" href="llvm.css" type="text/css" />
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]9</head>
10<body>
Mikhail Glushenkov99a3a2c2008-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 Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]13
Mikhail Glushenkov23f522a2008-12-13 17:51:47 +0000[diff] [blame]14<!-- This file was automatically generated by rst2html.
15Please do not edit directly!
16The ReST source lives in the directory 'tools/llvmc/doc'. -->
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]17<div class="contents topic" id="contents">
18<p class="topic-title first">Contents</p>
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]19<ul class="simple">
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]20<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
Mikhail Glushenkovfb886652011-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 Glushenkovd6d2efc2009-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 Glushenkovd5652032008-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 Glushenkovd6d2efc2009-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 Glushenkovfb886652011-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
31more adaptable and easier to customize. Most of LLVMC functionality is
32implemented via high-level TableGen code, from which a corresponding C++ source
33file is automatically generated. This tutorial describes the basic usage and
34configuration of LLVMC.</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]35</div>
Mikhail Glushenkovfb886652011-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
39as possible, so most of the familiar options work:</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]40<pre class="literal-block">
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]41$ llvmc -O3 -Wall hello.cpp
42$ ./a.out
43hello
44</pre>
Mikhail Glushenkovfb886652011-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
46executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on command-line LLVMC
47usage, refer to the <tt class="docutils literal">llvmc <span class="pre">--help</span></tt> output.</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]48</div>
Mikhail Glushenkovd6d2efc2009-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 Glushenkovfb886652011-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
52familiar 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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]55<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]56$ cd $LLVM_OBJ_DIR/tools/examples/Simple
57$ make
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame]58$ cat &gt; hello.c
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]59#include &lt;stdio.h&gt;
60int main() { printf(&quot;Hello\n&quot;); }
61$ $LLVM_BIN_DIR/Simple -v hello.c
62gcc hello.c -o hello.out
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame]63$ ./hello.out
64Hello
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]65</pre>
Mikhail Glushenkovfb886652011-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
67the input TableGen file <tt class="docutils literal">Simple.td</tt>. The <tt class="docutils literal">llvmc</tt> program itself is generated
68using a similar process (see <tt class="docutils literal">llvmc/src</tt>). Contents of the file <tt class="docutils literal">Simple.td</tt>
69look like this:</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]70<pre class="literal-block">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame]71// Include common definitions
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]72include &quot;llvm/CompilerDriver/Common.td&quot;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]73
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame]74// Tool descriptions
75def gcc : Tool&lt;
76[(in_language &quot;c&quot;),
77 (out_language &quot;executable&quot;),
78 (output_suffix &quot;out&quot;),
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]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;)
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]85]&gt;;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]86
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame]87// Language map
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]88def LanguageMap : LanguageMap&lt;[(lang_to_suffixes &quot;c&quot;, &quot;c&quot;)]&gt;;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]89
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame]90// Compilation graph
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]91def CompilationGraph : CompilationGraph&lt;[(edge &quot;root&quot;, &quot;gcc&quot;)]&gt;;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]92</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]93<p>As you can see, this file consists of three parts: tool descriptions, language
94map, and the compilation graph definition.</p>
95<p>At the heart of LLVMC is the idea of a compilation graph: vertices in this graph
96are tools, and edges represent a transformation path between two tools (for
97example, assembly source produced by the compiler can be transformed into
98executable code by an assembler). The compilation graph is basically a list of
99edges; 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
101example above should be self-explanatory; the <tt class="docutils literal">sink</tt> property means that all
102options 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
104used 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
106manual and examples in the <tt class="docutils literal">examples</tt> directory. Of a particular interest is
107the <tt class="docutils literal">Skeleton</tt> example, which can serve as a template for your LLVMC-based
108drivers.</p>
Mikhail Glushenkov90531542008-12-11 23:43:14 +0000[diff] [blame]109<hr />
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]110<address>
Mikhail Glushenkovd5652032008-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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]117
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]118<a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]119<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]120
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]121Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
122</address></div>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]123</div>
124</body>
125</html>