Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / llvm / 66bc5c602aec3a8bfd826699847fc936f7aa9acd / . / docs / CompilerDriver.html
blob: 0f5d3592a259ff31120d9330c770258902e80642 [file] [log] [blame]
Anton Korobeynikov74120312008-06-09 04:15:49 +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">
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]4<head>
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]6<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]7<title>Customizing LLVMC: Reference Manual</title>
Mikhail Glushenkov8cc82882008-12-13 17:50:58 +0000[diff] [blame]8<link rel="stylesheet" href="llvm.css" type="text/css" />
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]9</head>
10<body>
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]11<div class="document" id="customizing-llvmc-reference-manual">
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]12<h1 class="title">Customizing LLVMC: Reference Manual</h1>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]13
Mikhail Glushenkov23f522a2008-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 Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]17<div class="contents topic" id="contents">
18<p class="topic-title first">Contents</p>
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]19<ul class="simple">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]20<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 Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]29</ul>
30</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]31<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 Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]37</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 Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]43</div><div class="section" id="introduction">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]44<h1><a class="toc-backref" href="#id7">Introduction</a></h1>
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]45<p>LLVMC is a generic compiler driver, designed to be customizable and
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]46extensible. 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 Glushenkov63dc3182009-06-17 02:56:48 +0000[diff] [blame]56<p>Because LLVMC employs <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a> as its configuration language, you
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]57need to be familiar with it to customize LLVMC.</p>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]58</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]59<div class="section" id="compiling-with-llvmc">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]60<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]62although 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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]66$ llvmc -O3 -Wall hello.cpp
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]67$ ./a.out
68hello
69</pre>
Mikhail Glushenkov63dc3182009-06-17 02:56:48 +0000[diff] [blame]70<p>One nice feature of LLVMC is that one doesn't have to distinguish between
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]71different compilers for different languages (think <tt class="docutils literal">g++</tt> vs. <tt class="docutils literal">gcc</tt>) - the
Mikhail Glushenkov63dc3182009-06-17 02:56:48 +0000[diff] [blame]72right 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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]75do it with <tt class="docutils literal">gcc</tt>:</p>
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]76<pre class="literal-block">
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]77$ # hello.c is really a C++ file
78$ llvmc -x c++ hello.c
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]79$ ./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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]86$ llvmc -c hello.cpp
87$ llvmc hello.o
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]88[A lot of link-time errors skipped]
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]89$ llvmc --linker=c++ hello.o
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]90$ ./a.out
91hello
92</pre>
Mikhail Glushenkove25b8452009-06-30 00:16:43 +0000[diff] [blame]93<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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]94possible 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 Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]95</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]96<div class="section" id="predefined-options">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]97<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]99<ul class="simple">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]100<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]102until 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 Glushenkovd7acf732009-06-25 18:21:10 +0000[diff] [blame]104<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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]109<li><tt class="docutils literal"><span class="pre">--temp-dir</span> DIRECTORY</tt> - Store temporary files in the given directory. This
Mikhail Glushenkov4429aaf2009-07-11 19:28:00 +0000[diff] [blame]110directory 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 Glushenkov4ad0d572009-03-27 12:58:29 +0000[diff] [blame]113<li><tt class="docutils literal"><span class="pre">--check-graph</span></tt> - Check the compilation for common errors like mismatched
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]114output/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 Glushenkov4ad0d572009-03-27 12:58:29 +0000[diff] [blame]117<li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation graph
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]118and 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 Glushenkov4ad0d572009-03-27 12:58:29 +0000[diff] [blame]120<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 Glushenkov502106a2009-06-16 00:14:20 +0000[diff] [blame]122to 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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]123used 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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]125their standard meaning.</li>
126</ul>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]127</div>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]128<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]132<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]133$ cd $LLVMC_DIR/examples
134$ cp -r Skeleton MyDriver
135$ cd MyDriver
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]136$ ls
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]137AutoGenerated.td Hooks.cpp Main.cpp Makefile
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]138</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]139<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]147<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]148LLVMC_BASED_DRIVER=MyDriver
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]149</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]150<p>It can also be a good idea to put your TableGen code into a file with a less
151generic name:</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]152<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]153$ touch MyDriver.td
154$ vim AutoGenerated.td
Mikhail Glushenkov502106a2009-06-16 00:14:20 +0000[diff] [blame]155[...]
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]156include &quot;MyDriver.td&quot;
Mikhail Glushenkov502106a2009-06-16 00:14:20 +0000[diff] [blame]157</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]158<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 Glushenkov502106a2009-06-16 00:14:20 +0000[diff] [blame]163<p>If you're compiling LLVM with different source and object directories, then you
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]164must perform the following additional steps before running <tt class="docutils literal">make</tt>:</p>
Mikhail Glushenkov502106a2009-06-16 00:14:20 +0000[diff] [blame]165<pre class="literal-block">
166# LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/
167# LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]168$ 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 Glushenkov502106a2009-06-16 00:14:20 +0000[diff] [blame]172$ make
173</pre>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]174</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]175<div class="section" id="customizing-llvmc-the-compilation-graph">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]176<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]178<pre class="literal-block">
179include &quot;llvm/CompilerDriver/Common.td&quot;
180</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]181<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]188<pre class="literal-block">
189def CompilationGraph : CompilationGraph&lt;[
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]190 Edge&lt;&quot;root&quot;, &quot;llvm_gcc_c&quot;&gt;,
191 Edge&lt;&quot;root&quot;, &quot;llvm_gcc_assembler&quot;&gt;,
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]192 ...
193
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]194 Edge&lt;&quot;llvm_gcc_c&quot;, &quot;llc&quot;&gt;,
195 Edge&lt;&quot;llvm_gcc_cpp&quot;, &quot;llc&quot;&gt;,
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]196 ...
197
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]198 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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]202 ...
203
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]204 OptionalEdge&lt;&quot;llvm_gcc_assembler&quot;, &quot;llvm_gcc_cpp_linker&quot;,
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]205 (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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]212<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]223construct.</p>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]224<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 Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]234</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]235<div class="section" id="describing-options">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]236<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]239<pre class="literal-block">
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]240def 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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]245</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]246<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]250<ul>
251<li><p class="first">Possible option types:</p>
252<blockquote>
253<ul class="simple">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]254<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 Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]257<tt class="docutils literal"><span class="pre">-std=c99</span></tt>. It is also allowed to use spaces instead of the equality
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]258sign: <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 Lattner7a2bdde2011-04-15 05:18:47 +0000[diff] [blame]260occurrence is allowed.</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]261<li><tt class="docutils literal">prefix_option</tt> - same as the parameter_option, but the option name and
Mikhail Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]262argument do not have to be separated. Example: <tt class="docutils literal"><span class="pre">-ofile</span></tt>. This can be also
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]263specified 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 Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]265allowed.</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]266<li><tt class="docutils literal">prefix_list_option</tt> - same as the above, but more than one occurrence of
Mikhail Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]267the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]268<li><tt class="docutils literal">alias_option</tt> - a special option type for creating aliases. Unlike other
Mikhail Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]269option types, aliases are not allowed to have any properties besides the
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]270aliased 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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]278</ul>
279</blockquote>
280</li>
281<li><p class="first">Possible option properties:</p>
282<blockquote>
283<ul class="simple">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]284<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 Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]285output.</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]286<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 Glushenkovf9b1d792009-01-15 02:42:40 +0000[diff] [blame]303output).</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]304<li><tt class="docutils literal">really_hidden</tt> - the option will not be mentioned in any help
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]305output.</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]306<li><tt class="docutils literal">comma_separated</tt> - Indicates that any commas specified for an option's
Mikhail Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]307value 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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]309<tt class="docutils literal">forward_value</tt> can be used to implement option forwarding in style of
Mikhail Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]310gcc's <tt class="docutils literal"><span class="pre">-Wa,</span></tt>.</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]311<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 Glushenkov90b5d042009-12-17 07:49:26 +0000[diff] [blame]317parameter), or a boolean (if it is a switch; as in C++, boolean constants
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]318are 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 Glushenkov90b5d042009-12-17 07:49:26 +0000[diff] [blame]319attribute.
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]320Usage 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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]322</ul>
323</blockquote>
324</li>
325</ul>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]326</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]327<div class="section" id="conditional-evaluation">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]328<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]335<p>Examples:</p>
336<pre class="literal-block">
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]337// Edge weight calculation
338
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]339// 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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]345
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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]352(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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]357<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]361<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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]366<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]369<ul class="simple">
370<li>Possible tests are:<ul>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]371<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 Glushenkov0a018d32009-10-25 01:44:24 +0000[diff] [blame]377the switches is turned on.
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]378Example: <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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]387belongs to the current input language set.
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]388Example: <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 Glushenkov0a018d32009-10-25 01:44:24 +0000[diff] [blame]391non-join nodes).
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]392Example: <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 Glushenkov31280152009-09-28 01:28:26 +0000[diff] [blame]408provided on the command-line. Used without arguments:
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]409<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 Glushenkov31280152009-09-28 01:28:26 +0000[diff] [blame]411case of zero input files is considered an error).</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]412<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 Glushenkov31280152009-09-28 01:28:26 +0000[diff] [blame]417encouraged.</li>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]418<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]424</ul>
425</li>
426</ul>
Reid Spencer46d21922004-08-22 18:06:59 +0000[diff] [blame]427</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]428<div class="section" id="writing-a-tool-description">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]429<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]433<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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]438 (command &quot;llvm-g++ -c -emit-llvm&quot;),
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]439 (sink)
440 ]&gt;;
441</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]442<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]447<p>The complete list of all currently implemented tool properties follows.</p>
448<ul class="simple">
449<li>Possible tool properties:<ul>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]450<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]457</ul>
458</li>
459</ul>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]460<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]484<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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]489 (command &quot;llvm-gcc&quot;),
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]490 (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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]497<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]507<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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]512<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 Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]521unchanged.
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]522Example: <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 Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]524options (since they don't have values), but works fine with lists.
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]525Example: <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 Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]527option's value before forwarding (see <a class="reference internal" href="#hooks">below</a>). When
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]528<tt class="docutils literal">forward_transformed_value</tt> is applied to a list
Mikhail Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]529option, the hook must have signature
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]530<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 Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]535input. Used without arguments.
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]536Example: <tt class="docutils literal">(stop_compilation)</tt>.</li>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]537</ul>
538</blockquote>
539</li>
540</ul>
541</div>
542</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]543<div class="section" id="language-map">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]544<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 Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]549<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]556<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 Glushenkov90b5d042009-12-17 07:49:26 +0000[diff] [blame]561<p>The language map entries are needed only for the tools that are linked from the
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]562root node. A tool can have multiple output languages.</p>
Reid Spencer46d21922004-08-22 18:06:59 +0000[diff] [blame]563</div>
Mikhail Glushenkov0a018d32009-10-25 01:44:24 +0000[diff] [blame]564<div class="section" id="option-preprocessor">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]565<h1><a class="toc-backref" href="#id17">Option preprocessor</a></h1>
Mikhail Glushenkov0a018d32009-10-25 01:44:24 +0000[diff] [blame]566<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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]570<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 Glushenkov0a018d32009-10-25 01:44:24 +0000[diff] [blame]572<pre class="literal-block">
573def Preprocess : OptionPreprocessor&lt;
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]574(case (not (any_switch_on &quot;O0&quot;, &quot;O1&quot;, &quot;O2&quot;, &quot;O3&quot;)),
Mikhail Glushenkov90b5d042009-12-17 07:49:26 +0000[diff] [blame]575 (set_option &quot;O2&quot;),
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]576 (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 Glushenkov0a018d32009-10-25 01:44:24 +0000[diff] [blame]580 (and (switch_on &quot;O1&quot;), (switch_on &quot;O0&quot;)),
581 (unset_option &quot;O0&quot;))
582&gt;;
583</pre>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]584<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 Glushenkov90b5d042009-12-17 07:49:26 +0000[diff] [blame]585that 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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]587<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 Glushenkov0a9ff4b2009-12-23 12:49:51 +0000[diff] [blame]593either a string, a string list, or a boolean constant.</p>
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]594<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 Glushenkov0a018d32009-10-25 01:44:24 +0000[diff] [blame]598</div>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]599<div class="section" id="more-advanced-topics">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]600<h1><a class="toc-backref" href="#id18">More advanced topics</a></h1>
Mikhail Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]601<div class="section" id="hooks-and-environment-variables">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]602<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]610<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]611(command &quot;$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)&quot;)
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]612</pre>
Mikhail Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]613<p>To pass arguments to hooks, use the following syntax:</p>
614<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]615(command &quot;$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2&quot;)
Mikhail Glushenkov5303c752009-01-28 03:47:38 +0000[diff] [blame]616</pre>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]617<p>It is also possible to use environment variables in the same manner:</p>
618<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]619(command &quot;$ENV(VAR1)/path/to/file -o $ENV(VAR2)&quot;)
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]620</pre>
621<p>To change the command line string based on user-provided options use
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]622the <tt class="docutils literal">case</tt> expression (documented <a class="reference internal" href="#case">above</a>):</p>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]623<pre class="literal-block">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]624(command
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]625 (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 Glushenkovd6d2efc2009-05-06 01:41:47 +0000[diff] [blame]632<div class="section" id="debugging">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]633<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 Glushenkove25b8452009-06-30 00:16:43 +0000[diff] [blame]645</div>
646<div class="section" id="conditioning-on-the-executable-name">
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]647<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 Glushenkove25b8452009-06-30 00:16:43 +0000[diff] [blame]649accessible 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 Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]655namespace hooks {
656
Mikhail Glushenkove25b8452009-06-30 00:16:43 +0000[diff] [blame]657std::string MyHook() {
658//...
659if (strcmp(ProgramName, &quot;mydriver&quot;) == 0) {
660 //...
661
662}
Mikhail Glushenkovabf31b92009-12-07 18:26:24 +0000[diff] [blame]663
664} // end namespace hooks
Mikhail Glushenkove25b8452009-06-30 00:16:43 +0000[diff] [blame]665</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 Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]668the <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 Glushenkov90531542008-12-11 23:43:14 +0000[diff] [blame]670<hr />
Anton Korobeynikov28b66702008-06-09 04:17:51 +0000[diff] [blame]671<address>
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]672<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 Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]678
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]679<a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
Mikhail Glushenkovfb886652011-04-24 14:17:37 +0000[diff] [blame]680<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]681
Akira Hatanaka325e66d2011-05-06 22:11:29 +0000[diff] [blame]682Last modified: $Date$
Mikhail Glushenkovd5652032008-12-13 02:28:58 +0000[diff] [blame]683</address></div>
Mikhail Glushenkov68319f82008-12-11 23:24:40 +0000[diff] [blame]684</div>
685</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]686</body>
687</html>