docs/CompilerDriverTutorial.html - llvm - Git at Google

 <?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title>Tutorial - Using LLVMC</title>
 <link rel="stylesheet" href="llvm.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="tutorial-using-llvmc">
 <h1 class="title">Tutorial - Using LLVMC</h1>

 <!-- This file was automatically generated by rst2html.
 Please do not edit directly!
 The ReST source lives in the directory 'tools/llvmc/doc'. -->
 <div class="contents topic" id="contents">
 <p class="topic-title first">Contents</p>
 <ul class="simple">
 <li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
 <li><a class="reference internal" href="#compiling-with-llvmc" id="id2">Compiling with LLVMC</a></li>
 <li><a class="reference internal" href="#using-llvmc-to-generate-toolchain-drivers" id="id3">Using LLVMC to generate toolchain drivers</a></li>
 </ul>
 </div>
 <div class="doc_author">
 <p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p>
 </div><div class="section" id="introduction">
 <h1><a class="toc-backref" href="#id1">Introduction</a></h1>
 <p>LLVMC is a generic compiler driver, which plays the same role for LLVM
 as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program does for GCC - the difference being that LLVMC
 is designed to be more adaptable and easier to customize. Most of
 LLVMC functionality is implemented via plugins, which can be loaded
 dynamically or compiled in. This tutorial describes the basic usage
 and configuration of LLVMC.</p>
 </div>
 <div class="section" id="compiling-with-llvmc">
 <h1><a class="toc-backref" href="#id2">Compiling with LLVMC</a></h1>
 <p>In general, LLVMC tries to be command-line compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as
 much as possible, so most of the familiar options work:</p>
 <pre class="literal-block">
 $ llvmc -O3 -Wall hello.cpp
 $ ./a.out
 hello
 </pre>
 <p>This will invoke <tt class="docutils literal"><span class="pre">llvm-g++</span></tt> under the hood (you can see which
 commands are executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on
 command-line LLVMC usage, refer to the <tt class="docutils literal"><span class="pre">llvmc</span> <span class="pre">--help</span></tt> output.</p>
 </div>
 <div class="section" id="using-llvmc-to-generate-toolchain-drivers">
 <h1><a class="toc-backref" href="#id3">Using LLVMC to generate toolchain drivers</a></h1>
 <p>LLVMC plugins are written mostly using <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a>, so you need to
 be familiar with it to get anything done.</p>
 <p>Start by compiling <tt class="docutils literal"><span class="pre">example/Simple</span></tt>, which is a primitive wrapper for
 <tt class="docutils literal"><span class="pre">gcc</span></tt>:</p>
 <pre class="literal-block">
 $ cd $LLVM_DIR/tools/llvmc
 $ cp -r example/Simple plugins/Simple

   # NB: A less verbose way to compile standalone LLVMC-based drivers is
   # described in the reference manual.

 $ make LLVMC_BASED_DRIVER_NAME=mygcc LLVMC_BUILTIN_PLUGINS=Simple
 $ cat &gt; hello.c
 [...]
 $ mygcc hello.c
 $ ./hello.out
 Hello
 </pre>
 <p>Here we link our plugin with the LLVMC core statically to form an executable
 file called <tt class="docutils literal"><span class="pre">mygcc</span></tt>. It is also possible to build our plugin as a dynamic
 library to be loaded by the <tt class="docutils literal"><span class="pre">llvmc</span></tt> executable (or any other LLVMC-based
 standalone driver); this is described in the reference manual.</p>
 <p>Contents of the file <tt class="docutils literal"><span class="pre">Simple.td</span></tt> look like this:</p>
 <pre class="literal-block">
 // Include common definitions
 include &quot;llvm/CompilerDriver/Common.td&quot;

 // Tool descriptions
 def gcc : Tool&lt;
 [(in_language &quot;c&quot;),
  (out_language &quot;executable&quot;),
  (output_suffix &quot;out&quot;),
  (cmd_line &quot;gcc $INFILE -o $OUTFILE&quot;),
  (sink)
 ]&gt;;

 // Language map
 def LanguageMap : LanguageMap&lt;[LangToSuffixes&lt;&quot;c&quot;, [&quot;c&quot;]&gt;]&gt;;

 // Compilation graph
 def CompilationGraph : CompilationGraph&lt;[Edge&lt;&quot;root&quot;, &quot;gcc&quot;&gt;]&gt;;
 </pre>
 <p>As you can see, this file consists of three parts: tool descriptions,
 language map, and the compilation graph definition.</p>
 <p>At the heart of LLVMC is the idea of a compilation graph: vertices in
 this graph are tools, and edges represent a transformation path
 between two tools (for example, assembly source produced by the
 compiler can be transformed into executable code by an assembler). The
 compilation graph is basically a list of edges; a special node named
 <tt class="docutils literal"><span class="pre">root</span></tt> is used to mark graph entry points.</p>
 <p>Tool descriptions are represented as property lists: most properties
 in the example above should be self-explanatory; the <tt class="docutils literal"><span class="pre">sink</span></tt> property
 means that all options lacking an explicit description should be
 forwarded to this tool.</p>
 <p>The <tt class="docutils literal"><span class="pre">LanguageMap</span></tt> associates a language name with a list of suffixes
 and is used for deciding which toolchain corresponds to a given input
 file.</p>
 <p>To learn more about LLVMC customization, refer to the reference
 manual and plugin source code in the <tt class="docutils literal"><span class="pre">plugins</span></tt> directory.</p>
 <hr />
 <address>
 <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>
 <a href="http://validator.w3.org/check?uri=referer">
 <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
    alt="Valid XHTML 1.0 Transitional"/></a>

 <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />

 Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
 </address></div>
 </div>
 </body>
 </html>
	<?xml version="1.0" encoding="utf-8" ?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
	<title>Tutorial - Using LLVMC</title>
	<link rel="stylesheet" href="llvm.css" type="text/css" />
	</head>
	<body>
	<div class="document" id="tutorial-using-llvmc">
	<h1 class="title">Tutorial - Using LLVMC</h1>

	<!-- This file was automatically generated by rst2html.
	Please do not edit directly!
	The ReST source lives in the directory 'tools/llvmc/doc'. -->
	<div class="contents topic" id="contents">
	<p class="topic-title first">Contents</p>
	<ul class="simple">
	<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
	<li><a class="reference internal" href="#compiling-with-llvmc" id="id2">Compiling with LLVMC</a></li>
	<li><a class="reference internal" href="#using-llvmc-to-generate-toolchain-drivers" id="id3">Using LLVMC to generate toolchain drivers</a></li>
	</ul>
	</div>
	<div class="doc_author">
	<p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p>
	</div><div class="section" id="introduction">
	<h1><a class="toc-backref" href="#id1">Introduction</a></h1>
	<p>LLVMC is a generic compiler driver, which plays the same role for LLVM
	as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program does for GCC - the difference being that LLVMC
	is designed to be more adaptable and easier to customize. Most of
	LLVMC functionality is implemented via plugins, which can be loaded
	dynamically or compiled in. This tutorial describes the basic usage
	and configuration of LLVMC.</p>
	</div>
	<div class="section" id="compiling-with-llvmc">
	<h1><a class="toc-backref" href="#id2">Compiling with LLVMC</a></h1>
	<p>In general, LLVMC tries to be command-line compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as
	much as possible, so most of the familiar options work:</p>
	<pre class="literal-block">
	$ llvmc -O3 -Wall hello.cpp
	$ ./a.out
	hello
	</pre>
	<p>This will invoke <tt class="docutils literal"><span class="pre">llvm-g++</span></tt> under the hood (you can see which
	commands are executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on
	command-line LLVMC usage, refer to the <tt class="docutils literal"><span class="pre">llvmc</span> <span class="pre">--help</span></tt> output.</p>
	</div>
	<div class="section" id="using-llvmc-to-generate-toolchain-drivers">
	<h1><a class="toc-backref" href="#id3">Using LLVMC to generate toolchain drivers</a></h1>
	<p>LLVMC plugins are written mostly using <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a>, so you need to
	be familiar with it to get anything done.</p>
	<p>Start by compiling <tt class="docutils literal"><span class="pre">example/Simple</span></tt>, which is a primitive wrapper for
	<tt class="docutils literal"><span class="pre">gcc</span></tt>:</p>
	<pre class="literal-block">
	$ cd $LLVM_DIR/tools/llvmc
	$ cp -r example/Simple plugins/Simple

	# NB: A less verbose way to compile standalone LLVMC-based drivers is
	# described in the reference manual.

	$ make LLVMC_BASED_DRIVER_NAME=mygcc LLVMC_BUILTIN_PLUGINS=Simple
	$ cat > hello.c
	[...]
	$ mygcc hello.c
	$ ./hello.out
	Hello
	</pre>
	<p>Here we link our plugin with the LLVMC core statically to form an executable
	file called <tt class="docutils literal"><span class="pre">mygcc</span></tt>. It is also possible to build our plugin as a dynamic
	library to be loaded by the <tt class="docutils literal"><span class="pre">llvmc</span></tt> executable (or any other LLVMC-based
	standalone driver); this is described in the reference manual.</p>
	<p>Contents of the file <tt class="docutils literal"><span class="pre">Simple.td</span></tt> look like this:</p>
	<pre class="literal-block">
	// Include common definitions
	include "llvm/CompilerDriver/Common.td"

	// Tool descriptions
	def gcc : Tool<
	[(in_language "c"),
	(out_language "executable"),
	(output_suffix "out"),
	(cmd_line "gcc $INFILE -o $OUTFILE"),
	(sink)
	]>;

	// Language map
	def LanguageMap : LanguageMap<[LangToSuffixes<"c", ["c"]>]>;

	// Compilation graph
	def CompilationGraph : CompilationGraph<[Edge<"root", "gcc">]>;
	</pre>
	<p>As you can see, this file consists of three parts: tool descriptions,
	language map, and the compilation graph definition.</p>
	<p>At the heart of LLVMC is the idea of a compilation graph: vertices in
	this graph are tools, and edges represent a transformation path
	between two tools (for example, assembly source produced by the
	compiler can be transformed into executable code by an assembler). The
	compilation graph is basically a list of edges; a special node named
	<tt class="docutils literal"><span class="pre">root</span></tt> is used to mark graph entry points.</p>
	<p>Tool descriptions are represented as property lists: most properties
	in the example above should be self-explanatory; the <tt class="docutils literal"><span class="pre">sink</span></tt> property
	means that all options lacking an explicit description should be
	forwarded to this tool.</p>
	<p>The <tt class="docutils literal"><span class="pre">LanguageMap</span></tt> associates a language name with a list of suffixes
	and is used for deciding which toolchain corresponds to a given input
	file.</p>
	<p>To learn more about LLVMC customization, refer to the reference
	manual and plugin source code in the <tt class="docutils literal"><span class="pre">plugins</span></tt> directory.</p>
	<hr />
	<address>
	<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>
	<a href="http://validator.w3.org/check?uri=referer">
	<img src="http://www.w3.org/Icons/valid-xhtml10-blue"
	alt="Valid XHTML 1.0 Transitional"/></a>

	<a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
	<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />

	Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
	</address></div>
	</div>
	</body>
	</html>