blob: 0f5d3592a259ff31120d9330c770258902e80642 [file] [log] [blame]
Anton Korobeynikov4167db92008-06-09 04:15:49 +00001<?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">
Reid Spencerd5c0ccb2004-08-09 03:08:29 +00004<head>
Anton Korobeynikov4167db92008-06-09 04:15:49 +00005<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Mikhail Glushenkov06655d42011-04-24 14:17:37 +00006<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
Anton Korobeynikov4167db92008-06-09 04:15:49 +00007<title>Customizing LLVMC: Reference Manual</title>
Mikhail Glushenkov60279922008-12-13 17:50:58 +00008<link rel="stylesheet" href="llvm.css" type="text/css" />
Reid Spencerd5c0ccb2004-08-09 03:08:29 +00009</head>
10<body>
Anton Korobeynikov4167db92008-06-09 04:15:49 +000011<div class="document" id="customizing-llvmc-reference-manual">
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +000012<h1 class="title">Customizing LLVMC: Reference Manual</h1>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +000013
Mikhail Glushenkove04b5bf2008-12-13 17:51:47 +000014<!-- This file was automatically generated by rst2html.
15Please do not edit directly!
16The ReST source lives in the directory 'tools/llvmc/doc'. -->
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +000017<div class="contents topic" id="contents">
18<p class="topic-title first">Contents</p>
Mikhail Glushenkovc0363fc2008-12-13 02:28:58 +000019<ul class="simple">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000020<li><a class="reference internal" href="#introduction" id="id7">Introduction</a></li>
21<li><a class="reference internal" href="#compiling-with-llvmc" id="id8">Compiling with <tt class="docutils literal">llvmc</tt></a></li>
22<li><a class="reference internal" href="#predefined-options" id="id9">Predefined options</a></li>
23<li><a class="reference internal" href="#compiling-llvmc-based-drivers" id="id10">Compiling LLVMC-based drivers</a></li>
24<li><a class="reference internal" href="#customizing-llvmc-the-compilation-graph" id="id11">Customizing LLVMC: the compilation graph</a></li>
25<li><a class="reference internal" href="#describing-options" id="id12">Describing options</a></li>
26<li><a class="reference internal" href="#conditional-evaluation" id="id13">Conditional evaluation</a></li>
27<li><a class="reference internal" href="#writing-a-tool-description" id="id14">Writing a tool description</a><ul>
28<li><a class="reference internal" href="#id4" id="id15">Actions</a></li>
Mikhail Glushenkovc0363fc2008-12-13 02:28:58 +000029</ul>
30</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000031<li><a class="reference internal" href="#language-map" id="id16">Language map</a></li>
32<li><a class="reference internal" href="#option-preprocessor" id="id17">Option preprocessor</a></li>
33<li><a class="reference internal" href="#more-advanced-topics" id="id18">More advanced topics</a><ul>
34<li><a class="reference internal" href="#hooks-and-environment-variables" id="id19">Hooks and environment variables</a></li>
35<li><a class="reference internal" href="#debugging" id="id20">Debugging</a></li>
36<li><a class="reference internal" href="#conditioning-on-the-executable-name" id="id21">Conditioning on the executable name</a></li>
Mikhail Glushenkovc0363fc2008-12-13 02:28:58 +000037</ul>
38</li>
39</ul>
40</div>
41<div class="doc_author">
42<p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +000043</div><div class="section" id="introduction">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000044<h1><a class="toc-backref" href="#id7">Introduction</a></h1>
Anton Korobeynikov4167db92008-06-09 04:15:49 +000045<p>LLVMC is a generic compiler driver, designed to be customizable and
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000046extensible. It plays the same role for LLVM as the <tt class="docutils literal">gcc</tt> program does for
47GCC - LLVMC's job is essentially to transform a set of input files into a set of
48targets depending on configuration rules and user options. What makes LLVMC
49different is that these transformation rules are completely customizable - in
50fact, LLVMC knows nothing about the specifics of transformation (even the
51command-line options are mostly not hard-coded) and regards the transformation
52structure as an abstract graph. The structure of this graph is described in
53high-level TableGen code, from which an efficient C++ representation is
54automatically derived. This makes it possible to adapt LLVMC for other
55purposes - for example, as a build tool for game resources.</p>
Mikhail Glushenkov7af1d242009-06-17 02:56:48 +000056<p>Because LLVMC employs <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a> as its configuration language, you
Anton Korobeynikov4167db92008-06-09 04:15:49 +000057need to be familiar with it to customize LLVMC.</p>
Reid Spencerd5c0ccb2004-08-09 03:08:29 +000058</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +000059<div class="section" id="compiling-with-llvmc">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000060<h1><a class="toc-backref" href="#id8">Compiling with <tt class="docutils literal">llvmc</tt></a></h1>
61<p>LLVMC tries hard to be as compatible with <tt class="docutils literal">gcc</tt> as possible,
Anton Korobeynikov4167db92008-06-09 04:15:49 +000062although there are some small differences. Most of the time, however,
63you shouldn't be able to notice them:</p>
64<pre class="literal-block">
65$ # This works as expected:
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +000066$ llvmc -O3 -Wall hello.cpp
Anton Korobeynikov4167db92008-06-09 04:15:49 +000067$ ./a.out
68hello
69</pre>
Mikhail Glushenkov7af1d242009-06-17 02:56:48 +000070<p>One nice feature of LLVMC is that one doesn't have to distinguish between
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000071different compilers for different languages (think <tt class="docutils literal">g++</tt> vs. <tt class="docutils literal">gcc</tt>) - the
Mikhail Glushenkov7af1d242009-06-17 02:56:48 +000072right toolchain is chosen automatically based on input language names (which
73are, in turn, determined from file extensions). If you want to force files
74ending with &quot;.c&quot; to compile as C++, use the <tt class="docutils literal"><span class="pre">-x</span></tt> option, just like you would
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000075do it with <tt class="docutils literal">gcc</tt>:</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +000076<pre class="literal-block">
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +000077$ # hello.c is really a C++ file
78$ llvmc -x c++ hello.c
Anton Korobeynikov4167db92008-06-09 04:15:49 +000079$ ./a.out
80hello
81</pre>
82<p>On the other hand, when using LLVMC as a linker to combine several C++
83object files you should provide the <tt class="docutils literal"><span class="pre">--linker</span></tt> option since it's
84impossible for LLVMC to choose the right linker in that case:</p>
85<pre class="literal-block">
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +000086$ llvmc -c hello.cpp
87$ llvmc hello.o
Anton Korobeynikov4167db92008-06-09 04:15:49 +000088[A lot of link-time errors skipped]
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +000089$ llvmc --linker=c++ hello.o
Anton Korobeynikov4167db92008-06-09 04:15:49 +000090$ ./a.out
91hello
92</pre>
Mikhail Glushenkov7b366b52009-06-30 00:16:43 +000093<p>By default, LLVMC uses <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> to compile the source code. It is also
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000094possible to choose the <tt class="docutils literal">clang</tt> compiler with the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p>
Reid Spencerd5c0ccb2004-08-09 03:08:29 +000095</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +000096<div class="section" id="predefined-options">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +000097<h1><a class="toc-backref" href="#id9">Predefined options</a></h1>
98<p>LLVMC has some built-in options that can't be overridden in the TableGen code:</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +000099<ul class="simple">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000100<li><tt class="docutils literal"><span class="pre">-o</span> FILE</tt> - Output file name.</li>
101<li><tt class="docutils literal"><span class="pre">-x</span> LANGUAGE</tt> - Specify the language of the following input files
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000102until the next -x option.</li>
103<li><tt class="docutils literal"><span class="pre">-v</span></tt> - Enable verbose mode, i.e. print out all executed commands.</li>
Mikhail Glushenkov2b4a7dc2009-06-25 18:21:10 +0000104<li><tt class="docutils literal"><span class="pre">--save-temps</span></tt> - Write temporary files to the current directory and do not
105delete them on exit. This option can also take an argument: the
106<tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> switch will write files into the directory specified with
107the <tt class="docutils literal"><span class="pre">-o</span></tt> option. The <tt class="docutils literal"><span class="pre">--save-temps=cwd</span></tt> and <tt class="docutils literal"><span class="pre">--save-temps</span></tt> switches are
108both synonyms for the default behaviour.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000109<li><tt class="docutils literal"><span class="pre">--temp-dir</span> DIRECTORY</tt> - Store temporary files in the given directory. This
Mikhail Glushenkov0decbb22009-07-11 19:28:00 +0000110directory is deleted on exit unless <tt class="docutils literal"><span class="pre">--save-temps</span></tt> is specified. If
111<tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> is also specified, <tt class="docutils literal"><span class="pre">--temp-dir</span></tt> is given the
112precedence.</li>
Mikhail Glushenkov0f78c272009-03-27 12:58:29 +0000113<li><tt class="docutils literal"><span class="pre">--check-graph</span></tt> - Check the compilation for common errors like mismatched
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000114output/input language names, multiple default edges and cycles. Exit with code
115zero if no errors were found, and return the number of found errors
116otherwise. Hidden option, useful for debugging.</li>
Mikhail Glushenkov0f78c272009-03-27 12:58:29 +0000117<li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation graph
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000118and exit. Requires that you have <tt class="docutils literal">dot</tt> and <tt class="docutils literal">gv</tt> programs installed. Hidden
119option, useful for debugging.</li>
Mikhail Glushenkov0f78c272009-03-27 12:58:29 +0000120<li><tt class="docutils literal"><span class="pre">--write-graph</span></tt> - Write a <tt class="docutils literal"><span class="pre">compilation-graph.dot</span></tt> file in the current
121directory with the compilation graph description in Graphviz format (identical
Mikhail Glushenkovb4b44ea2009-06-16 00:14:20 +0000122to the file used by the <tt class="docutils literal"><span class="pre">--view-graph</span></tt> option). The <tt class="docutils literal"><span class="pre">-o</span></tt> option can be
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000123used to set the output file name. Hidden option, useful for debugging.</li>
124<li><tt class="docutils literal"><span class="pre">--help</span></tt>, <tt class="docutils literal"><span class="pre">--help-hidden</span></tt>, <tt class="docutils literal"><span class="pre">--version</span></tt> - These options have
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000125their standard meaning.</li>
126</ul>
Reid Spencerd5c0ccb2004-08-09 03:08:29 +0000127</div>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000128<div class="section" id="compiling-llvmc-based-drivers">
129<h1><a class="toc-backref" href="#id10">Compiling LLVMC-based drivers</a></h1>
130<p>It's easiest to start working on your own LLVMC driver by copying the skeleton
131project which lives under <tt class="docutils literal">$LLVMC_DIR/examples/Skeleton</tt>:</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000132<pre class="literal-block">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000133$ cd $LLVMC_DIR/examples
134$ cp -r Skeleton MyDriver
135$ cd MyDriver
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000136$ ls
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000137AutoGenerated.td Hooks.cpp Main.cpp Makefile
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000138</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000139<p>As you can see, our basic driver consists of only three files (not counting the
140build script). <tt class="docutils literal">AutoGenerated.td</tt> contains TableGen description of the
141compilation graph; its format is documented in the following
142sections. <tt class="docutils literal">Hooks.cpp</tt> is an empty file that should be used for hook
143definitions (see <a class="reference internal" href="#hooks">below</a>). <tt class="docutils literal">Main.cpp</tt> is just a helper used to compile the
144auto-generated C++ code produced from TableGen source.</p>
145<p>The first thing that you should do is to change the <tt class="docutils literal">LLVMC_BASED_DRIVER</tt>
146variable in the <tt class="docutils literal">Makefile</tt>:</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000147<pre class="literal-block">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000148LLVMC_BASED_DRIVER=MyDriver
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000149</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000150<p>It can also be a good idea to put your TableGen code into a file with a less
151generic name:</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000152<pre class="literal-block">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000153$ touch MyDriver.td
154$ vim AutoGenerated.td
Mikhail Glushenkovb4b44ea2009-06-16 00:14:20 +0000155[...]
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000156include &quot;MyDriver.td&quot;
Mikhail Glushenkovb4b44ea2009-06-16 00:14:20 +0000157</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000158<p>If you have more than one TableGen source file, they all should be included from
159<tt class="docutils literal">AutoGenerated.td</tt>, since this file is used by the build system to generate
160C++ code.</p>
161<p>To build your driver, just <tt class="docutils literal">cd</tt> to its source directory and run <tt class="docutils literal">make</tt>. The
162resulting executable will be put into <tt class="docutils literal"><span class="pre">$LLVM_OBJ_DIR/$(BuildMode)/bin</span></tt>.</p>
Mikhail Glushenkovb4b44ea2009-06-16 00:14:20 +0000163<p>If you're compiling LLVM with different source and object directories, then you
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000164must perform the following additional steps before running <tt class="docutils literal">make</tt>:</p>
Mikhail Glushenkovb4b44ea2009-06-16 00:14:20 +0000165<pre class="literal-block">
166# LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/
167# LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000168$ mkdir $LLVMC_OBJ_DIR/examples/MyDriver/
169$ cp $LLVMC_SRC_DIR/examples/MyDriver/Makefile \
170 $LLVMC_OBJ_DIR/examples/MyDriver/
171$ cd $LLVMC_OBJ_DIR/examples/MyDriver
Mikhail Glushenkovb4b44ea2009-06-16 00:14:20 +0000172$ make
173</pre>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000174</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000175<div class="section" id="customizing-llvmc-the-compilation-graph">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000176<h1><a class="toc-backref" href="#id11">Customizing LLVMC: the compilation graph</a></h1>
177<p>Each TableGen configuration file should include the common definitions:</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000178<pre class="literal-block">
179include &quot;llvm/CompilerDriver/Common.td&quot;
180</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000181<p>Internally, LLVMC stores information about possible source transformations in
182form of a graph. Nodes in this graph represent tools, and edges between two
183nodes represent a transformation path. A special &quot;root&quot; node is used to mark
184entry points for the transformations. LLVMC also assigns a weight to each edge
185(more on this later) to choose between several alternative edges.</p>
186<p>The definition of the compilation graph (see file <tt class="docutils literal">llvmc/src/Base.td</tt> for an
187example) is just a list of edges:</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000188<pre class="literal-block">
189def CompilationGraph : CompilationGraph&lt;[
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000190 Edge&lt;&quot;root&quot;, &quot;llvm_gcc_c&quot;&gt;,
191 Edge&lt;&quot;root&quot;, &quot;llvm_gcc_assembler&quot;&gt;,
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000192 ...
193
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000194 Edge&lt;&quot;llvm_gcc_c&quot;, &quot;llc&quot;&gt;,
195 Edge&lt;&quot;llvm_gcc_cpp&quot;, &quot;llc&quot;&gt;,
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000196 ...
197
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000198 OptionalEdge&lt;&quot;llvm_gcc_c&quot;, &quot;opt&quot;, (case (switch_on &quot;opt&quot;),
199 (inc_weight))&gt;,
200 OptionalEdge&lt;&quot;llvm_gcc_cpp&quot;, &quot;opt&quot;, (case (switch_on &quot;opt&quot;),
201 (inc_weight))&gt;,
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000202 ...
203
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000204 OptionalEdge&lt;&quot;llvm_gcc_assembler&quot;, &quot;llvm_gcc_cpp_linker&quot;,
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000205 (case (input_languages_contain &quot;c++&quot;), (inc_weight),
206 (or (parameter_equals &quot;linker&quot;, &quot;g++&quot;),
207 (parameter_equals &quot;linker&quot;, &quot;c++&quot;)), (inc_weight))&gt;,
208 ...
209
210 ]&gt;;
211</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000212<p>As you can see, the edges can be either default or optional, where optional
213edges are differentiated by an additional <tt class="docutils literal">case</tt> expression used to calculate
214the weight of this edge. Notice also that we refer to tools via their names (as
215strings). This makes it possible to add edges to an existing compilation graph
216without having to know about all tool definitions used in the graph.</p>
217<p>The default edges are assigned a weight of 1, and optional edges get a weight of
2180 + 2*N where N is the number of tests that evaluated to true in the <tt class="docutils literal">case</tt>
219expression. It is also possible to provide an integer parameter to
220<tt class="docutils literal">inc_weight</tt> and <tt class="docutils literal">dec_weight</tt> - in this case, the weight is increased (or
221decreased) by the provided value instead of the default 2. Default weight of an
222optional edge can be changed by using the <tt class="docutils literal">default</tt> clause of the <tt class="docutils literal">case</tt>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000223construct.</p>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000224<p>When passing an input file through the graph, LLVMC picks the edge with the
225maximum weight. To avoid ambiguity, there should be only one default edge
226between two nodes (with the exception of the root node, which gets a special
227treatment - there you are allowed to specify one default edge <em>per language</em>).</p>
228<p>When multiple compilation graphs are defined, they are merged together. Multiple
229edges with the same end nodes are not allowed (i.e. the graph is not a
230multigraph), and will lead to a compile-time error.</p>
231<p>To get a visual representation of the compilation graph (useful for debugging),
232run <tt class="docutils literal">llvmc <span class="pre">--view-graph</span></tt>. You will need <tt class="docutils literal">dot</tt> and <tt class="docutils literal">gsview</tt> installed for
233this to work properly.</p>
Reid Spencerd5c0ccb2004-08-09 03:08:29 +0000234</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000235<div class="section" id="describing-options">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000236<h1><a class="toc-backref" href="#id12">Describing options</a></h1>
237<p>Command-line options supported by the driver are defined by using an
238<tt class="docutils literal">OptionList</tt>:</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000239<pre class="literal-block">
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000240def Options : OptionList&lt;[
241(switch_option &quot;E&quot;, (help &quot;Help string&quot;)),
242(alias_option &quot;quiet&quot;, &quot;q&quot;)
243...
244]&gt;;
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000245</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000246<p>As you can see, the option list is just a list of DAGs, where each DAG is an
247option description consisting of the option name and some properties. More than
248one option list can be defined (they are all merged together in the end), which
249can be handy if one wants to separate option groups syntactically.</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000250<ul>
251<li><p class="first">Possible option types:</p>
252<blockquote>
253<ul class="simple">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000254<li><tt class="docutils literal">switch_option</tt> - a simple boolean switch without arguments, for example
255<tt class="docutils literal"><span class="pre">-O2</span></tt> or <tt class="docutils literal"><span class="pre">-time</span></tt>. At most one occurrence is allowed by default.</li>
256<li><tt class="docutils literal">parameter_option</tt> - option that takes one argument, for example
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000257<tt class="docutils literal"><span class="pre">-std=c99</span></tt>. It is also allowed to use spaces instead of the equality
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000258sign: <tt class="docutils literal"><span class="pre">-std</span> c99</tt>. At most one occurrence is allowed.</li>
259<li><tt class="docutils literal">parameter_list_option</tt> - same as the above, but more than one option
Chris Lattner0ab5e2c2011-04-15 05:18:47 +0000260occurrence is allowed.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000261<li><tt class="docutils literal">prefix_option</tt> - same as the parameter_option, but the option name and
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000262argument do not have to be separated. Example: <tt class="docutils literal"><span class="pre">-ofile</span></tt>. This can be also
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000263specified as <tt class="docutils literal"><span class="pre">-o</span> file</tt>; however, <tt class="docutils literal"><span class="pre">-o=file</span></tt> will be parsed incorrectly
264(<tt class="docutils literal">=file</tt> will be interpreted as option value). At most one occurrence is
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000265allowed.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000266<li><tt class="docutils literal">prefix_list_option</tt> - same as the above, but more than one occurrence of
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000267the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000268<li><tt class="docutils literal">alias_option</tt> - a special option type for creating aliases. Unlike other
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000269option types, aliases are not allowed to have any properties besides the
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000270aliased option name.
271Usage example: <tt class="docutils literal">(alias_option &quot;preprocess&quot;, &quot;E&quot;)</tt></li>
272<li><tt class="docutils literal">switch_list_option</tt> - like <tt class="docutils literal">switch_option</tt> with the <tt class="docutils literal">zero_or_more</tt>
273property, but remembers how many times the switch was turned on. Useful
274mostly for forwarding. Example: when <tt class="docutils literal"><span class="pre">-foo</span></tt> is a switch option (with the
275<tt class="docutils literal">zero_or_more</tt> property), the command <tt class="docutils literal">driver <span class="pre">-foo</span> <span class="pre">-foo</span></tt> is forwarded
276as <tt class="docutils literal"><span class="pre">some-tool</span> <span class="pre">-foo</span></tt>, but when <tt class="docutils literal"><span class="pre">-foo</span></tt> is a switch list, the same command
277is forwarded as <tt class="docutils literal"><span class="pre">some-tool</span> <span class="pre">-foo</span> <span class="pre">-foo</span></tt>.</li>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000278</ul>
279</blockquote>
280</li>
281<li><p class="first">Possible option properties:</p>
282<blockquote>
283<ul class="simple">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000284<li><tt class="docutils literal">help</tt> - help string associated with this option. Used for <tt class="docutils literal"><span class="pre">--help</span></tt>
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000285output.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000286<li><tt class="docutils literal">required</tt> - this option must be specified exactly once (or, in case of
287the list options without the <tt class="docutils literal">multi_val</tt> property, at least
288once). Incompatible with <tt class="docutils literal">optional</tt> and <tt class="docutils literal">one_or_more</tt>.</li>
289<li><tt class="docutils literal">optional</tt> - the option can be specified either zero times or exactly
290once. The default for switch options. Useful only for list options in
291conjunction with <tt class="docutils literal">multi_val</tt>. Incompatible with <tt class="docutils literal">required</tt>,
292<tt class="docutils literal">zero_or_more</tt> and <tt class="docutils literal">one_or_more</tt>.</li>
293<li><tt class="docutils literal">one_or_more</tt> - the option must be specified at least once. Can be useful
294to allow switch options be both obligatory and be specified multiple
295times. For list options is useful only in conjunction with <tt class="docutils literal">multi_val</tt>;
296for ordinary it is synonymous with <tt class="docutils literal">required</tt>. Incompatible with
297<tt class="docutils literal">required</tt>, <tt class="docutils literal">optional</tt> and <tt class="docutils literal">zero_or_more</tt>.</li>
298<li><tt class="docutils literal">zero_or_more</tt> - the option can be specified zero or more times. Useful
299to allow a single switch option to be specified more than
300once. Incompatible with <tt class="docutils literal">required</tt>, <tt class="docutils literal">optional</tt> and <tt class="docutils literal">one_or_more</tt>.</li>
301<li><tt class="docutils literal">hidden</tt> - the description of this option will not appear in
302the <tt class="docutils literal"><span class="pre">--help</span></tt> output (but will appear in the <tt class="docutils literal"><span class="pre">--help-hidden</span></tt>
Mikhail Glushenkovbc39dff2009-01-15 02:42:40 +0000303output).</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000304<li><tt class="docutils literal">really_hidden</tt> - the option will not be mentioned in any help
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000305output.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000306<li><tt class="docutils literal">comma_separated</tt> - Indicates that any commas specified for an option's
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000307value should be used to split the value up into multiple values for the
308option. This property is valid only for list options. In conjunction with
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000309<tt class="docutils literal">forward_value</tt> can be used to implement option forwarding in style of
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000310gcc's <tt class="docutils literal"><span class="pre">-Wa,</span></tt>.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000311<li><tt class="docutils literal">multi_val n</tt> - this option takes <em>n</em> arguments (can be useful in some
312special cases). Usage example: <tt class="docutils literal">(parameter_list_option &quot;foo&quot;, (multi_val
3133))</tt>; the command-line syntax is '-foo a b c'. Only list options can have
314this attribute; you can, however, use the <tt class="docutils literal">one_or_more</tt>, <tt class="docutils literal">optional</tt>
315and <tt class="docutils literal">required</tt> properties.</li>
316<li><tt class="docutils literal">init</tt> - this option has a default value, either a string (if it is a
Mikhail Glushenkov108b0682009-12-17 07:49:26 +0000317parameter), or a boolean (if it is a switch; as in C++, boolean constants
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000318are called <tt class="docutils literal">true</tt> and <tt class="docutils literal">false</tt>). List options can't have <tt class="docutils literal">init</tt>
Mikhail Glushenkov108b0682009-12-17 07:49:26 +0000319attribute.
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000320Usage examples: <tt class="docutils literal">(switch_option &quot;foo&quot;, (init true))</tt>; <tt class="docutils literal">(prefix_option
321&quot;bar&quot;, (init <span class="pre">&quot;baz&quot;))</span></tt>.</li>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000322</ul>
323</blockquote>
324</li>
325</ul>
Reid Spencerd5c0ccb2004-08-09 03:08:29 +0000326</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000327<div class="section" id="conditional-evaluation">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000328<span id="case"></span><h1><a class="toc-backref" href="#id13">Conditional evaluation</a></h1>
329<p>The 'case' construct is the main means by which programmability is achieved in
330LLVMC. It can be used to calculate edge weights, program actions and modify the
331shell commands to be executed. The 'case' expression is designed after the
332similarly-named construct in functional languages and takes the form <tt class="docutils literal">(case
333(test_1), statement_1, (test_2), statement_2, ... (test_N), statement_N)</tt>. The
334statements are evaluated only if the corresponding tests evaluate to true.</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000335<p>Examples:</p>
336<pre class="literal-block">
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000337// Edge weight calculation
338
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000339// Increases edge weight by 5 if &quot;-A&quot; is provided on the
340// command-line, and by 5 more if &quot;-B&quot; is also provided.
341(case
342 (switch_on &quot;A&quot;), (inc_weight 5),
343 (switch_on &quot;B&quot;), (inc_weight 5))
344
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000345
346// Tool command line specification
347
348// Evaluates to &quot;cmdline1&quot; if the option &quot;-A&quot; is provided on the
349// command line; to &quot;cmdline2&quot; if &quot;-B&quot; is provided;
350// otherwise to &quot;cmdline3&quot;.
351
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000352(case
353 (switch_on &quot;A&quot;), &quot;cmdline1&quot;,
354 (switch_on &quot;B&quot;), &quot;cmdline2&quot;,
355 (default), &quot;cmdline3&quot;)
356</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000357<p>Note the slight difference in 'case' expression handling in contexts of edge
358weights and command line specification - in the second example the value of the
359<tt class="docutils literal">&quot;B&quot;</tt> switch is never checked when switch <tt class="docutils literal">&quot;A&quot;</tt> is enabled, and the whole
360expression always evaluates to <tt class="docutils literal">&quot;cmdline1&quot;</tt> in that case.</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000361<p>Case expressions can also be nested, i.e. the following is legal:</p>
362<pre class="literal-block">
363(case (switch_on &quot;E&quot;), (case (switch_on &quot;o&quot;), ..., (default), ...)
364 (default), ...)
365</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000366<p>You should, however, try to avoid doing that because it hurts readability. It is
367usually better to split tool descriptions and/or use TableGen inheritance
368instead.</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000369<ul class="simple">
370<li>Possible tests are:<ul>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000371<li><tt class="docutils literal">switch_on</tt> - Returns true if a given command-line switch is provided by
372the user. Can be given multiple arguments, in that case <tt class="docutils literal">(switch_on &quot;foo&quot;,
373&quot;bar&quot;, &quot;baz&quot;)</tt> is equivalent to <tt class="docutils literal">(and (switch_on <span class="pre">&quot;foo&quot;),</span> (switch_on
374<span class="pre">&quot;bar&quot;),</span> (switch_on <span class="pre">&quot;baz&quot;))</span></tt>.
375Example: <tt class="docutils literal">(switch_on &quot;opt&quot;)</tt>.</li>
376<li><tt class="docutils literal">any_switch_on</tt> - Given a number of switch options, returns true if any of
Mikhail Glushenkov964020b2009-10-25 01:44:24 +0000377the switches is turned on.
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000378Example: <tt class="docutils literal">(any_switch_on &quot;foo&quot;, &quot;bar&quot;, &quot;baz&quot;)</tt> is equivalent to <tt class="docutils literal">(or
379(switch_on <span class="pre">&quot;foo&quot;),</span> (switch_on <span class="pre">&quot;bar&quot;),</span> (switch_on <span class="pre">&quot;baz&quot;))</span></tt>.</li>
380<li><tt class="docutils literal">parameter_equals</tt> - Returns true if a command-line parameter (first
381argument) equals a given value (second argument).
382Example: <tt class="docutils literal">(parameter_equals &quot;W&quot;, &quot;all&quot;)</tt>.</li>
383<li><tt class="docutils literal">element_in_list</tt> - Returns true if a command-line parameter list (first
384argument) contains a given value (second argument).
385Example: <tt class="docutils literal">(element_in_list &quot;l&quot;, &quot;pthread&quot;)</tt>.</li>
386<li><tt class="docutils literal">input_languages_contain</tt> - Returns true if a given language
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000387belongs to the current input language set.
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000388Example: <tt class="docutils literal">(input_languages_contain <span class="pre">&quot;c++&quot;)</span></tt>.</li>
389<li><tt class="docutils literal">in_language</tt> - Evaluates to true if the input file language is equal to
390the argument. At the moment works only with <tt class="docutils literal">command</tt> and <tt class="docutils literal">actions</tt> (on
Mikhail Glushenkov964020b2009-10-25 01:44:24 +0000391non-join nodes).
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000392Example: <tt class="docutils literal">(in_language <span class="pre">&quot;c++&quot;)</span></tt>.</li>
393<li><tt class="docutils literal">not_empty</tt> - Returns true if a given option (which should be either a
394parameter or a parameter list) is set by the user. Like <tt class="docutils literal">switch_on</tt>, can
395be also given multiple arguments.
396Examples: <tt class="docutils literal">(not_empty &quot;o&quot;)</tt>, <tt class="docutils literal">(not_empty &quot;o&quot;, &quot;l&quot;)</tt>.</li>
397<li><tt class="docutils literal">any_not_empty</tt> - Returns true if <tt class="docutils literal">not_empty</tt> returns true for any of
398the provided options.
399Example: <tt class="docutils literal">(any_not_empty &quot;foo&quot;, &quot;bar&quot;, &quot;baz&quot;)</tt> is equivalent to <tt class="docutils literal">(or
400(not_empty <span class="pre">&quot;foo&quot;),</span> (not_empty <span class="pre">&quot;bar&quot;),</span> (not_empty <span class="pre">&quot;baz&quot;))</span></tt>.</li>
401<li><tt class="docutils literal">empty</tt> - The opposite of <tt class="docutils literal">not_empty</tt>. Equivalent to <tt class="docutils literal">(not (not_empty
402X))</tt>. Can be given multiple arguments.</li>
403<li><tt class="docutils literal">any_not_empty</tt> - Returns true if <tt class="docutils literal">not_empty</tt> returns true for any of
404the provided options.
405Example: <tt class="docutils literal">(any_empty &quot;foo&quot;, &quot;bar&quot;, &quot;baz&quot;)</tt> is equivalent to <tt class="docutils literal">(or
406(not_empty <span class="pre">&quot;foo&quot;),</span> (not_empty <span class="pre">&quot;bar&quot;),</span> (not_empty <span class="pre">&quot;baz&quot;))</span></tt>.</li>
407<li><tt class="docutils literal">single_input_file</tt> - Returns true if there was only one input file
Mikhail Glushenkov89cbdf02009-09-28 01:28:26 +0000408provided on the command-line. Used without arguments:
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000409<tt class="docutils literal">(single_input_file)</tt>.</li>
410<li><tt class="docutils literal">multiple_input_files</tt> - Equivalent to <tt class="docutils literal">(not (single_input_file))</tt> (the
Mikhail Glushenkov89cbdf02009-09-28 01:28:26 +0000411case of zero input files is considered an error).</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000412<li><tt class="docutils literal">default</tt> - Always evaluates to true. Should always be the last
413test in the <tt class="docutils literal">case</tt> expression.</li>
414<li><tt class="docutils literal">and</tt> - A standard logical combinator that returns true iff all of
415its arguments return true. Used like this: <tt class="docutils literal">(and (test1), (test2),
416... (testN))</tt>. Nesting of <tt class="docutils literal">and</tt> and <tt class="docutils literal">or</tt> is allowed, but not
Mikhail Glushenkov89cbdf02009-09-28 01:28:26 +0000417encouraged.</li>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000418<li><tt class="docutils literal">or</tt> - A logical combinator that returns true iff any of its arguments
419return true.
420Example: <tt class="docutils literal">(or (test1), (test2), ... (testN))</tt>.</li>
421<li><tt class="docutils literal">not</tt> - Standard unary logical combinator that negates its
422argument.
423Example: <tt class="docutils literal">(not (or (test1), (test2), ... <span class="pre">(testN)))</span></tt>.</li>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000424</ul>
425</li>
426</ul>
Reid Spencera6288562004-08-22 18:06:59 +0000427</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000428<div class="section" id="writing-a-tool-description">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000429<h1><a class="toc-backref" href="#id14">Writing a tool description</a></h1>
430<p>As was said earlier, nodes in the compilation graph represent tools, which are
431described separately. A tool definition looks like this (taken from the
432<tt class="docutils literal">llvmc/src/Base.td</tt> file):</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000433<pre class="literal-block">
434def llvm_gcc_cpp : Tool&lt;[
435 (in_language &quot;c++&quot;),
436 (out_language &quot;llvm-assembler&quot;),
437 (output_suffix &quot;bc&quot;),
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000438 (command &quot;llvm-g++ -c -emit-llvm&quot;),
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000439 (sink)
440 ]&gt;;
441</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000442<p>This defines a new tool called <tt class="docutils literal">llvm_gcc_cpp</tt>, which is an alias for
443<tt class="docutils literal"><span class="pre">llvm-g++</span></tt>. As you can see, a tool definition is just a list of properties;
444most of them should be self-explanatory. The <tt class="docutils literal">sink</tt> property means that this
445tool should be passed all command-line options that aren't mentioned in the
446option list.</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000447<p>The complete list of all currently implemented tool properties follows.</p>
448<ul class="simple">
449<li>Possible tool properties:<ul>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000450<li><tt class="docutils literal">in_language</tt> - input language name. Can be given multiple arguments, in
451case the tool supports multiple input languages. Used for typechecking and
452mapping file extensions to tools.</li>
453<li><tt class="docutils literal">out_language</tt> - output language name. Multiple output languages are
454allowed. Used for typechecking the compilation graph.</li>
455<li><tt class="docutils literal">output_suffix</tt> - output file suffix. Can also be changed dynamically, see
456documentation on <a class="reference internal" href="#actions">actions</a>.</li>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000457</ul>
458</li>
459</ul>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000460<blockquote>
461<ul class="simple">
462<li><tt class="docutils literal">command</tt> - the actual command used to run the tool. You can use output
463redirection with <tt class="docutils literal">&gt;</tt>, hook invocations (<tt class="docutils literal">$CALL</tt>), environment variables
464(via <tt class="docutils literal">$ENV</tt>) and the <tt class="docutils literal">case</tt> construct.</li>
465<li><tt class="docutils literal">join</tt> - this tool is a &quot;join node&quot; in the graph, i.e. it gets a list of
466input files and joins them together. Used for linkers.</li>
467<li><tt class="docutils literal">sink</tt> - all command-line options that are not handled by other tools are
468passed to this tool.</li>
469<li><tt class="docutils literal">actions</tt> - A single big <tt class="docutils literal">case</tt> expression that specifies how this tool
470reacts on command-line options (described in more detail <a class="reference internal" href="#actions">below</a>).</li>
471</ul>
472</blockquote>
473<blockquote>
474<ul class="simple">
475<li><tt class="docutils literal">out_file_option</tt>, <tt class="docutils literal">in_file_option</tt> - Options appended to the
476<tt class="docutils literal">command</tt> string to designate output and input files. Default values are
477<tt class="docutils literal"><span class="pre">&quot;-o&quot;</span></tt> and <tt class="docutils literal">&quot;&quot;</tt>, respectively.</li>
478</ul>
479</blockquote>
480<div class="section" id="id4">
481<span id="actions"></span><h2><a class="toc-backref" href="#id15">Actions</a></h2>
482<p>A tool often needs to react to command-line options, and this is precisely what
483the <tt class="docutils literal">actions</tt> property is for. The next example illustrates this feature:</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000484<pre class="literal-block">
485def llvm_gcc_linker : Tool&lt;[
486 (in_language &quot;object-code&quot;),
487 (out_language &quot;executable&quot;),
488 (output_suffix &quot;out&quot;),
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000489 (command &quot;llvm-gcc&quot;),
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000490 (join),
491 (actions (case (not_empty &quot;L&quot;), (forward &quot;L&quot;),
492 (not_empty &quot;l&quot;), (forward &quot;l&quot;),
493 (not_empty &quot;dummy&quot;),
494 [(append_cmd &quot;-dummy1&quot;), (append_cmd &quot;-dummy2&quot;)])
495 ]&gt;;
496</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000497<p>The <tt class="docutils literal">actions</tt> tool property is implemented on top of the omnipresent <tt class="docutils literal">case</tt>
498expression. It associates one or more different <em>actions</em> with given
499conditions - in the example, the actions are <tt class="docutils literal">forward</tt>, which forwards a given
500option unchanged, and <tt class="docutils literal">append_cmd</tt>, which appends a given string to the tool
501execution command. Multiple actions can be associated with a single condition by
502using a list of actions (used in the example to append some dummy options). The
503same <tt class="docutils literal">case</tt> construct can also be used in the <tt class="docutils literal">cmd_line</tt> property to modify
504the tool command line.</p>
505<p>The &quot;join&quot; property used in the example means that this tool behaves like a
506linker.</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000507<p>The list of all possible actions follows.</p>
508<ul>
509<li><p class="first">Possible actions:</p>
510<blockquote>
511<ul class="simple">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000512<li><tt class="docutils literal">append_cmd</tt> - Append a string to the tool invocation command.
513Example: <tt class="docutils literal">(case (switch_on <span class="pre">&quot;pthread&quot;),</span> (append_cmd <span class="pre">&quot;-lpthread&quot;))</span></tt>.</li>
514<li><tt class="docutils literal">error</tt> - Exit with error.
515Example: <tt class="docutils literal">(error &quot;Mixing <span class="pre">-c</span> and <span class="pre">-S</span> is not <span class="pre">allowed!&quot;)</span></tt>.</li>
516<li><tt class="docutils literal">warning</tt> - Print a warning.
517Example: <tt class="docutils literal">(warning &quot;Specifying both <span class="pre">-O1</span> and <span class="pre">-O2</span> is <span class="pre">meaningless!&quot;)</span></tt>.</li>
518<li><tt class="docutils literal">forward</tt> - Forward the option unchanged.
519Example: <tt class="docutils literal">(forward &quot;Wall&quot;)</tt>.</li>
520<li><tt class="docutils literal">forward_as</tt> - Change the option's name, but forward the argument
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000521unchanged.
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000522Example: <tt class="docutils literal">(forward_as &quot;O0&quot;, <span class="pre">&quot;--disable-optimization&quot;)</span></tt>.</li>
523<li><tt class="docutils literal">forward_value</tt> - Forward only option's value. Cannot be used with switch
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000524options (since they don't have values), but works fine with lists.
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000525Example: <tt class="docutils literal">(forward_value <span class="pre">&quot;Wa,&quot;)</span></tt>.</li>
526<li><tt class="docutils literal">forward_transformed_value</tt> - As above, but applies a hook to the
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000527option's value before forwarding (see <a class="reference internal" href="#hooks">below</a>). When
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000528<tt class="docutils literal">forward_transformed_value</tt> is applied to a list
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000529option, the hook must have signature
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000530<tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::HookName</span> (const <span class="pre">std::vector&lt;std::string&gt;&amp;)</span></tt>.
531Example: <tt class="docutils literal">(forward_transformed_value &quot;m&quot;, &quot;ConvertToMAttr&quot;)</tt>.</li>
532<li><tt class="docutils literal">output_suffix</tt> - Modify the output suffix of this tool.
533Example: <tt class="docutils literal">(output_suffix &quot;i&quot;)</tt>.</li>
534<li><tt class="docutils literal">stop_compilation</tt> - Stop compilation after this tool processes its
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000535input. Used without arguments.
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000536Example: <tt class="docutils literal">(stop_compilation)</tt>.</li>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000537</ul>
538</blockquote>
539</li>
540</ul>
541</div>
542</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000543<div class="section" id="language-map">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000544<h1><a class="toc-backref" href="#id16">Language map</a></h1>
545<p>If you are adding support for a new language to LLVMC, you'll need to modify the
546language map, which defines mappings from file extensions to language names. It
547is used to choose the proper toolchain(s) for a given input file set. Language
548map definition looks like this:</p>
Anton Korobeynikov4167db92008-06-09 04:15:49 +0000549<pre class="literal-block">
550def LanguageMap : LanguageMap&lt;
551 [LangToSuffixes&lt;&quot;c++&quot;, [&quot;cc&quot;, &quot;cp&quot;, &quot;cxx&quot;, &quot;cpp&quot;, &quot;CPP&quot;, &quot;c++&quot;, &quot;C&quot;]&gt;,
552 LangToSuffixes&lt;&quot;c&quot;, [&quot;c&quot;]&gt;,
553 ...
554 ]&gt;;
555</pre>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000556<p>For example, without those definitions the following command wouldn't work:</p>
557<pre class="literal-block">
558$ llvmc hello.cpp
559llvmc: Unknown suffix: cpp
560</pre>
Mikhail Glushenkov108b0682009-12-17 07:49:26 +0000561<p>The language map entries are needed only for the tools that are linked from the
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000562root node. A tool can have multiple output languages.</p>
Reid Spencera6288562004-08-22 18:06:59 +0000563</div>
Mikhail Glushenkov964020b2009-10-25 01:44:24 +0000564<div class="section" id="option-preprocessor">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000565<h1><a class="toc-backref" href="#id17">Option preprocessor</a></h1>
Mikhail Glushenkov964020b2009-10-25 01:44:24 +0000566<p>It is sometimes useful to run error-checking code before processing the
567compilation graph. For example, if optimization options &quot;-O1&quot; and &quot;-O2&quot; are
568implemented as switches, we might want to output a warning if the user invokes
569the driver with both of these options enabled.</p>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000570<p>The <tt class="docutils literal">OptionPreprocessor</tt> feature is reserved specially for these
571occasions. Example (adapted from <tt class="docutils literal">llvm/src/Base.td.in</tt>):</p>
Mikhail Glushenkov964020b2009-10-25 01:44:24 +0000572<pre class="literal-block">
573def Preprocess : OptionPreprocessor&lt;
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000574(case (not (any_switch_on &quot;O0&quot;, &quot;O1&quot;, &quot;O2&quot;, &quot;O3&quot;)),
Mikhail Glushenkov108b0682009-12-17 07:49:26 +0000575 (set_option &quot;O2&quot;),
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000576 (and (switch_on &quot;O3&quot;), (any_switch_on &quot;O0&quot;, &quot;O1&quot;, &quot;O2&quot;)),
577 (unset_option &quot;O0&quot;, &quot;O1&quot;, &quot;O2&quot;),
578 (and (switch_on &quot;O2&quot;), (any_switch_on &quot;O0&quot;, &quot;O1&quot;)),
579 (unset_option &quot;O0&quot;, &quot;O1&quot;),
Mikhail Glushenkov964020b2009-10-25 01:44:24 +0000580 (and (switch_on &quot;O1&quot;), (switch_on &quot;O0&quot;)),
581 (unset_option &quot;O0&quot;))
582&gt;;
583</pre>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000584<p>Here, <tt class="docutils literal">OptionPreprocessor</tt> is used to unset all spurious <tt class="docutils literal"><span class="pre">-O</span></tt> options so
Mikhail Glushenkov108b0682009-12-17 07:49:26 +0000585that they are not forwarded to the compiler. If no optimization options are
586specified, <tt class="docutils literal"><span class="pre">-O2</span></tt> is enabled.</p>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000587<p><tt class="docutils literal">OptionPreprocessor</tt> is basically a single big <tt class="docutils literal">case</tt> expression, which is
588evaluated only once right after the driver is started. The only allowed actions
589in <tt class="docutils literal">OptionPreprocessor</tt> are <tt class="docutils literal">error</tt>, <tt class="docutils literal">warning</tt>, and two special actions:
590<tt class="docutils literal">unset_option</tt> and <tt class="docutils literal">set_option</tt>. As their names suggest, they can be used to
591set or unset a given option. To set an option with <tt class="docutils literal">set_option</tt>, use the
592two-argument form: <tt class="docutils literal">(set_option &quot;parameter&quot;, VALUE)</tt>. Here, <tt class="docutils literal">VALUE</tt> can be
Mikhail Glushenkov4429e702009-12-23 12:49:51 +0000593either a string, a string list, or a boolean constant.</p>
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000594<p>For convenience, <tt class="docutils literal">set_option</tt> and <tt class="docutils literal">unset_option</tt> also work with multiple
595arguments. That is, instead of <tt class="docutils literal">[(unset_option <span class="pre">&quot;A&quot;),</span> (unset_option <span class="pre">&quot;B&quot;)]</span></tt> you
596can use <tt class="docutils literal">(unset_option &quot;A&quot;, &quot;B&quot;)</tt>. Obviously, <tt class="docutils literal">(set_option &quot;A&quot;, &quot;B&quot;)</tt> is
597only valid if both <tt class="docutils literal">A</tt> and <tt class="docutils literal">B</tt> are switches.</p>
Mikhail Glushenkov964020b2009-10-25 01:44:24 +0000598</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000599<div class="section" id="more-advanced-topics">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000600<h1><a class="toc-backref" href="#id18">More advanced topics</a></h1>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000601<div class="section" id="hooks-and-environment-variables">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000602<span id="hooks"></span><h2><a class="toc-backref" href="#id19">Hooks and environment variables</a></h2>
603<p>Normally, LLVMC searches for programs in the system <tt class="docutils literal">PATH</tt>. Sometimes, this is
604not sufficient: for example, we may want to specify tool paths or names in the
605configuration file. This can be achieved via the hooks mechanism. To write your
606own hooks, add their definitions to the <tt class="docutils literal">Hooks.cpp</tt> or drop a <tt class="docutils literal">.cpp</tt> file
607into your driver directory. Hooks should live in the <tt class="docutils literal">hooks</tt> namespace and
608have the signature <tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::MyHookName</span> ([const char* Arg0 [ const
609char* Arg2 [, <span class="pre">...]]])</span></tt>. They can be used from the <tt class="docutils literal">command</tt> tool property:</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000610<pre class="literal-block">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000611(command &quot;$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)&quot;)
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000612</pre>
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000613<p>To pass arguments to hooks, use the following syntax:</p>
614<pre class="literal-block">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000615(command &quot;$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2&quot;)
Mikhail Glushenkov84172f72009-01-28 03:47:38 +0000616</pre>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000617<p>It is also possible to use environment variables in the same manner:</p>
618<pre class="literal-block">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000619(command &quot;$ENV(VAR1)/path/to/file -o $ENV(VAR2)&quot;)
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000620</pre>
621<p>To change the command line string based on user-provided options use
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000622the <tt class="docutils literal">case</tt> expression (documented <a class="reference internal" href="#case">above</a>):</p>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000623<pre class="literal-block">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000624(command
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000625 (case
626 (switch_on &quot;E&quot;),
627 &quot;llvm-g++ -E -x c $INFILE -o $OUTFILE&quot;,
628 (default),
629 &quot;llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm&quot;))
630</pre>
631</div>
Mikhail Glushenkov4707bf42009-05-06 01:41:47 +0000632<div class="section" id="debugging">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000633<h2><a class="toc-backref" href="#id20">Debugging</a></h2>
634<p>When writing LLVMC-based drivers, it can be useful to get a visual view of the
635resulting compilation graph. This can be achieved via the command line option
636<tt class="docutils literal"><span class="pre">--view-graph</span></tt> (which assumes that <a class="reference external" href="http://www.graphviz.org/">Graphviz</a> and <a class="reference external" href="http://pages.cs.wisc.edu/~ghost/">Ghostview</a> are
637installed). There is also a <tt class="docutils literal"><span class="pre">--write-graph</span></tt> option that creates a Graphviz
638source file (<tt class="docutils literal"><span class="pre">compilation-graph.dot</span></tt>) in the current directory.</p>
639<p>Another useful <tt class="docutils literal">llvmc</tt> option is <tt class="docutils literal"><span class="pre">--check-graph</span></tt>. It checks the compilation
640graph for common errors like mismatched output/input language names, multiple
641default edges and cycles. When invoked with <tt class="docutils literal"><span class="pre">--check-graph</span></tt>, <tt class="docutils literal">llvmc</tt> doesn't
642perform any compilation tasks and returns the number of encountered errors as
643its status code. In the future, these checks will be performed at compile-time
644and this option will disappear.</p>
Mikhail Glushenkov7b366b52009-06-30 00:16:43 +0000645</div>
646<div class="section" id="conditioning-on-the-executable-name">
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000647<h2><a class="toc-backref" href="#id21">Conditioning on the executable name</a></h2>
648<p>For now, the executable name (the value passed to the driver in <tt class="docutils literal">argv[0]</tt>) is
Mikhail Glushenkov7b366b52009-06-30 00:16:43 +0000649accessible only in the C++ code (i.e. hooks). Use the following code:</p>
650<pre class="literal-block">
651namespace llvmc {
652extern const char* ProgramName;
653}
654
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000655namespace hooks {
656
Mikhail Glushenkov7b366b52009-06-30 00:16:43 +0000657std::string MyHook() {
658//...
659if (strcmp(ProgramName, &quot;mydriver&quot;) == 0) {
660 //...
661
662}
Mikhail Glushenkov0bdfb532009-12-07 18:26:24 +0000663
664} // end namespace hooks
Mikhail Glushenkov7b366b52009-06-30 00:16:43 +0000665</pre>
666<p>In general, you're encouraged not to make the behaviour dependent on the
667executable file name, and use command-line switches instead. See for example how
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000668the <tt class="docutils literal">llvmc</tt> program behaves when it needs to choose the correct linker options
669(think <tt class="docutils literal">g++</tt> vs. <tt class="docutils literal">gcc</tt>).</p>
Mikhail Glushenkov6932e2f2008-12-11 23:43:14 +0000670<hr />
Anton Korobeynikov2a67ecb2008-06-09 04:17:51 +0000671<address>
Mikhail Glushenkovc0363fc2008-12-13 02:28:58 +0000672<a href="http://jigsaw.w3.org/css-validator/check/referer">
673<img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
674 alt="Valid CSS" /></a>
675<a href="http://validator.w3.org/check?uri=referer">
676<img src="http://www.w3.org/Icons/valid-xhtml10-blue"
677 alt="Valid XHTML 1.0 Transitional"/></a>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000678
Mikhail Glushenkovc0363fc2008-12-13 02:28:58 +0000679<a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
Mikhail Glushenkov06655d42011-04-24 14:17:37 +0000680<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000681
Akira Hatanakacbb7fa62011-05-06 22:11:29 +0000682Last modified: $Date$
Mikhail Glushenkovc0363fc2008-12-13 02:28:58 +0000683</address></div>
Mikhail Glushenkov6fd55132008-12-11 23:24:40 +0000684</div>
685</div>
Reid Spencerd5c0ccb2004-08-09 03:08:29 +0000686</body>
687</html>