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