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