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