Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 99a3a2c44c7735cafab8d60fef16c63b7187e76a / . / docs / CompilerDriverTutorial.html
blob: cc4707506e39b83fb9ee6f727f05dd93ea991cb3 [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" />
6<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]7<title>Tutorial - Using LLVMC</title>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]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>
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]12<div class="document" id="tutorial-using-llvmc">
13<h1 class="title">Tutorial - Using LLVMC</h1>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]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>
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]22<p>LLVMC is a generic compiler driver, which plays the same role for LLVM
23as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program does for GCC - the difference being that LLVMC
24is designed to be more adaptable and easier to customize. Most of
25LLVMC functionality is implemented via plugins, which can be loaded
26dynamically or compiled in. This tutorial describes the basic usage
27and configuration of LLVMC.</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]28<div class="contents topic">
29<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
30<ul class="simple">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]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>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]34</ul>
35</div>
36<div class="section">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]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
39much as 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 Glushenkov99a3a2c2008-12-11 23:33:33 +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
46commands are executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on
47command-line LLVMC usage, refer to the <tt class="docutils literal"><span class="pre">llvmc</span> <span class="pre">--help</span></tt> output.</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]48</div>
49<div class="section">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]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
52be 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
54wrapper for <tt class="docutils literal"><span class="pre">gcc</span></tt>:</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]55<pre class="literal-block">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]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
62Hello
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]63</pre>
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]64<p>Here we link our plugin with the LLVMC core statically to form an
65executable file called <tt class="docutils literal"><span class="pre">mygcc</span></tt>. It is also possible to build our
66plugin as a standalone dynamic library; this is described in the
67reference manual.</p>
68<p>Contents of the file <tt class="docutils literal"><span class="pre">Simple.td</span></tt> look like this:</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]69<pre class="literal-block">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]70// Include common definitions
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]71include &quot;llvm/CompilerDriver/Common.td&quot;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]72
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]73// Tool descriptions
74def 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)
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]80]&gt;;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]81
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]82// Language map
83def LanguageMap : LanguageMap&lt;[LangToSuffixes&lt;&quot;c&quot;, [&quot;c&quot;]&gt;]&gt;;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]84
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]85// Compilation graph
86def CompilationGraph : CompilationGraph&lt;[Edge&lt;&quot;root&quot;, &quot;gcc&quot;&gt;]&gt;;
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]87</pre>
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]88<p>As you can see, this file consists of three parts: tool descriptions,
89language map, and the compilation graph definition.</p>
90<p>At the heart of LLVMC is the idea of a compilation graph: vertices in
91this graph are tools, and edges represent a transformation path
92between two tools (for example, assembly source produced by the
93compiler can be transformed into executable code by an assembler). The
94compilation 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
97in the example above should be self-explanatory; the <tt class="docutils literal"><span class="pre">sink</span></tt> property
98means that all options lacking an explicit description should be
99forwarded 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
101and is used for deciding which toolchain corresponds to a given input
102file.</p>
103<p>To learn more about LLVMC customization, refer to the reference
104manual and plugin source code in the <tt class="docutils literal"><span class="pre">plugins</span></tt> directory.</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]105</div>
106<div class="section">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]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">
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]109<colgroup><col class="label" /><col /></colgroup>
110<tbody valign="top">
Mikhail Glushenkov99a3a2c2008-12-11 23:33:33 +0000[diff] [blame^]111<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>TableGen Fundamentals
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]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>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]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" alt="Valid CSS"></a>
118 <a href="http://validator.w3.org/check/referer"><img src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
119
120 <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br>
121 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
122
123 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
124</address>
125</div>
126</div>
127</body>
128</html>