Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 28b6670064b9aa7989ded22845c011f47af6980a / . / docs / CompilerDriver.html
blob: 7fe58dcf7ca46a78444c7196944d3856bcadc2d0 [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" />
6<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
7<title>Customizing LLVMC: Reference Manual</title>
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">
12
13<div class="doc_title">Customizing LLVMC: Reference Manual</div>
14
15<div class="doc_warning">
16 <p>Note: This document is a work-in-progress. Additions and clarifications
17 are welcome.</p>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]18</div>
19
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]20<p>LLVMC is a generic compiler driver, designed to be customizable and
21extensible. It plays the same role for LLVM as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program
22does for GCC - LLVMC's job is essentially to transform a set of input
23files into a set of targets depending on configuration rules and user
24options. What makes LLVMC different is that these transformation rules
25are completely customizable - in fact, LLVMC knows nothing about the
26specifics of transformation (even the command-line options are mostly
27not hard-coded) and regards the transformation structure as an
28abstract graph. This makes it possible to adapt LLVMC for other
29purposes - for example, as a build tool for game resources.</p>
30<p>Because LLVMC employs TableGen <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a> as its configuration language, you
31need to be familiar with it to customize LLVMC.</p>
32<div class="contents topic">
33<ul class="simple">
34<li><a class="reference" href="#compiling-with-llvmc" id="id3" name="id3">Compiling with LLVMC</a></li>
35<li><a class="reference" href="#predefined-options" id="id4" name="id4">Predefined options</a></li>
36<li><a class="reference" href="#customizing-llvmc-the-compilation-graph" id="id5" name="id5">Customizing LLVMC: the compilation graph</a></li>
37<li><a class="reference" href="#writing-a-tool-description" id="id6" name="id6">Writing a tool description</a></li>
38<li><a class="reference" href="#option-list-specifying-all-options-in-a-single-place" id="id7" name="id7">Option list - specifying all options in a single place</a></li>
39<li><a class="reference" href="#using-hooks-and-environment-variables-in-the-cmd-line-property" id="id8" name="id8">Using hooks and environment variables in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> property</a></li>
40<li><a class="reference" href="#conditional-evaluation-the-case-expression" id="id9" name="id9">Conditional evaluation: the <tt class="docutils literal"><span class="pre">case</span></tt> expression</a></li>
41<li><a class="reference" href="#language-map" id="id10" name="id10">Language map</a></li>
42<li><a class="reference" href="#references" id="id11" name="id11">References</a></li>
43</ul>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]44</div>
45
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]46<div class="doc_author">Written by Mikhail Glushenkov</div>
47
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]48<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]49<div class="doc_section"><a class="toc-backref" href="#id3" id="compiling-with-llvmc" name="compiling-with-llvmc">Compiling with LLVMC</a></div>
50<p>LLVMC tries hard to be as compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as possible,
51although there are some small differences. Most of the time, however,
52you shouldn't be able to notice them:</p>
53<pre class="literal-block">
54$ # This works as expected:
55$ llvmc2 -O3 -Wall hello.cpp
56$ ./a.out
57hello
58</pre>
59<p>One nice feature of LLVMC is that one doesn't have to distinguish
60between different compilers for different languages (think <tt class="docutils literal"><span class="pre">g++</span></tt> and
61<tt class="docutils literal"><span class="pre">gcc</span></tt>) - the right toolchain is chosen automatically based on input
62language names (which are, in turn, determined from file
63extensions). If you want to force files ending with &quot;.c&quot; to compile as
64C++, use the <tt class="docutils literal"><span class="pre">-x</span></tt> option, just like you would do it with <tt class="docutils literal"><span class="pre">gcc</span></tt>:</p>
65<pre class="literal-block">
66$ llvmc2 -x c hello.cpp
67$ # hello.cpp is really a C file
68$ ./a.out
69hello
70</pre>
71<p>On the other hand, when using LLVMC as a linker to combine several C++
72object files you should provide the <tt class="docutils literal"><span class="pre">--linker</span></tt> option since it's
73impossible for LLVMC to choose the right linker in that case:</p>
74<pre class="literal-block">
75$ llvmc2 -c hello.cpp
76$ llvmc2 hello.o
77[A lot of link-time errors skipped]
78$ llvmc2 --linker=c++ hello.o
79$ ./a.out
80hello
81</pre>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]82</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]83<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]84<div class="doc_section"><a class="toc-backref" href="#id4" id="predefined-options" name="predefined-options">Predefined options</a></div>
85<p>LLVMC has some built-in options that can't be overridden in the
86configuration files:</p>
87<ul class="simple">
88<li><tt class="docutils literal"><span class="pre">-o</span> <span class="pre">FILE</span></tt> - Output file name.</li>
89<li><tt class="docutils literal"><span class="pre">-x</span> <span class="pre">LANGUAGE</span></tt> - Specify the language of the following input files
90until the next -x option.</li>
91<li><tt class="docutils literal"><span class="pre">-v</span></tt> - Enable verbose mode, i.e. print out all executed commands.</li>
92<li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation
93graph. Requires that you have <tt class="docutils literal"><span class="pre">dot</span></tt> and <tt class="docutils literal"><span class="pre">gv</span></tt> commands
94installed. Hidden option, useful for debugging.</li>
95<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
96current directory with the compilation graph description in the
97Graphviz format. Hidden option, useful for debugging.</li>
98<li><tt class="docutils literal"><span class="pre">--save-temps</span></tt> - Write temporary files to the current directory
99and do not delete them on exit. Hidden option, useful for debugging.</li>
100<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
101their standard meaning.</li>
102</ul>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]103</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]104<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]105<div class="doc_section"><a class="toc-backref" href="#id5" id="customizing-llvmc-the-compilation-graph" name="customizing-llvmc-the-compilation-graph">Customizing LLVMC: the compilation graph</a></div>
106<p>At the time of writing LLVMC does not support on-the-fly reloading of
107configuration, so to customize LLVMC you'll have to recompile the
108source code (which lives under <tt class="docutils literal"><span class="pre">$LLVM_DIR/tools/llvmc2</span></tt>). The
109default configuration files are <tt class="docutils literal"><span class="pre">Common.td</span></tt> (contains common
110definitions, don't forget to <tt class="docutils literal"><span class="pre">include</span></tt> it in your configuration
111files), <tt class="docutils literal"><span class="pre">Tools.td</span></tt> (tool descriptions) and <tt class="docutils literal"><span class="pre">Graph.td</span></tt> (compilation
112graph definition).</p>
113<p>To compile LLVMC with your own configuration file (say,``MyGraph.td``),
114run <tt class="docutils literal"><span class="pre">make</span></tt> like this:</p>
115<pre class="literal-block">
116$ cd $LLVM_DIR/tools/llvmc2
117$ make GRAPH=MyGraph.td TOOLNAME=my_llvmc
118</pre>
119<p>This will build an executable named <tt class="docutils literal"><span class="pre">my_llvmc</span></tt>. There are also
120several sample configuration files in the <tt class="docutils literal"><span class="pre">llvmc2/examples</span></tt>
121subdirectory that should help to get you started.</p>
122<p>Internally, LLVMC stores information about possible source
123transformations in form of a graph. Nodes in this graph represent
124tools, and edges between two nodes represent a transformation path. A
125special &quot;root&quot; node is used to mark entry points for the
126transformations. LLVMC also assigns a weight to each edge (more on
127this later) to choose between several alternative edges.</p>
128<p>The definition of the compilation graph (see file <tt class="docutils literal"><span class="pre">Graph.td</span></tt>) is
129just a list of edges:</p>
130<pre class="literal-block">
131def CompilationGraph : CompilationGraph&lt;[
132 Edge&lt;root, llvm_gcc_c&gt;,
133 Edge&lt;root, llvm_gcc_assembler&gt;,
134 ...
135
136 Edge&lt;llvm_gcc_c, llc&gt;,
137 Edge&lt;llvm_gcc_cpp, llc&gt;,
138 ...
139
140 OptionalEdge&lt;llvm_gcc_c, opt, [(switch_on &quot;opt&quot;)]&gt;,
141 OptionalEdge&lt;llvm_gcc_cpp, opt, [(switch_on &quot;opt&quot;)]&gt;,
142 ...
143
144 OptionalEdge&lt;llvm_gcc_assembler, llvm_gcc_cpp_linker,
145 (case (input_languages_contain &quot;c++&quot;), (inc_weight),
146 (or (parameter_equals &quot;linker&quot;, &quot;g++&quot;),
147 (parameter_equals &quot;linker&quot;, &quot;c++&quot;)), (inc_weight))&gt;,
148 ...
149
150 ]&gt;;
151</pre>
152<p>As you can see, the edges can be either default or optional, where
153optional edges are differentiated by sporting a <tt class="docutils literal"><span class="pre">case</span></tt> expression
154used to calculate the edge's weight.</p>
155<p>The default edges are assigned a weight of 1, and optional edges get a
156weight of 0 + 2*N where N is the number of tests that evaluated to
157true in the <tt class="docutils literal"><span class="pre">case</span></tt> expression. It is also possible to provide an
158integer parameter to <tt class="docutils literal"><span class="pre">inc_weight</span></tt> and <tt class="docutils literal"><span class="pre">dec_weight</span></tt> - in this case,
159the weight is increased (or decreased) by the provided value instead
160of the default 2.</p>
161<p>When passing an input file through the graph, LLVMC picks the edge
162with the maximum weight. To avoid ambiguity, there should be only one
163default edge between two nodes (with the exception of the root node,
164which gets a special treatment - there you are allowed to specify one
165default edge <em>per language</em>).</p>
166<p>To get a visual representation of the compilation graph (useful for
167debugging), run <tt class="docutils literal"><span class="pre">llvmc2</span> <span class="pre">--view-graph</span></tt>. You will need <tt class="docutils literal"><span class="pre">dot</span></tt> and
168<tt class="docutils literal"><span class="pre">gsview</span></tt> installed for this to work properly.</p>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]169</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]170<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]171<div class="doc_section"><a class="toc-backref" href="#id6" id="writing-a-tool-description" name="writing-a-tool-description">Writing a tool description</a></div>
172<p>As was said earlier, nodes in the compilation graph represent tools,
173which are described separately. A tool definition looks like this
174(taken from the <tt class="docutils literal"><span class="pre">Tools.td</span></tt> file):</p>
175<pre class="literal-block">
176def llvm_gcc_cpp : Tool&lt;[
177 (in_language &quot;c++&quot;),
178 (out_language &quot;llvm-assembler&quot;),
179 (output_suffix &quot;bc&quot;),
180 (cmd_line &quot;llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm&quot;),
181 (sink)
182 ]&gt;;
183</pre>
184<p>This defines a new tool called <tt class="docutils literal"><span class="pre">llvm_gcc_cpp</span></tt>, which is an alias for
185<tt class="docutils literal"><span class="pre">llvm-g++</span></tt>. As you can see, a tool definition is just a list of
186properties; most of them should be self-explanatory. The <tt class="docutils literal"><span class="pre">sink</span></tt>
187property means that this tool should be passed all command-line
188options that lack explicit descriptions.</p>
189<p>The complete list of the currently implemented tool properties follows:</p>
190<ul class="simple">
191<li>Possible tool properties:<ul>
192<li><tt class="docutils literal"><span class="pre">in_language</span></tt> - input language name.</li>
193<li><tt class="docutils literal"><span class="pre">out_language</span></tt> - output language name.</li>
194<li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - output file suffix.</li>
195<li><tt class="docutils literal"><span class="pre">cmd_line</span></tt> - the actual command used to run the tool. You can
196use <tt class="docutils literal"><span class="pre">$INFILE</span></tt> and <tt class="docutils literal"><span class="pre">$OUTFILE</span></tt> variables, output redirection
197with <tt class="docutils literal"><span class="pre">&gt;</span></tt>, hook invocations (<tt class="docutils literal"><span class="pre">$CALL</span></tt>), environment variables
198(via <tt class="docutils literal"><span class="pre">$ENV</span></tt>) and the <tt class="docutils literal"><span class="pre">case</span></tt> construct (more on this below).</li>
199<li><tt class="docutils literal"><span class="pre">join</span></tt> - this tool is a &quot;join node&quot; in the graph, i.e. it gets a
200list of input files and joins them together. Used for linkers.</li>
201<li><tt class="docutils literal"><span class="pre">sink</span></tt> - all command-line options that are not handled by other
202tools are passed to this tool.</li>
203</ul>
204</li>
205</ul>
206<p>The next tool definition is slightly more complex:</p>
207<pre class="literal-block">
208def llvm_gcc_linker : Tool&lt;[
209 (in_language &quot;object-code&quot;),
210 (out_language &quot;executable&quot;),
211 (output_suffix &quot;out&quot;),
212 (cmd_line &quot;llvm-gcc $INFILE -o $OUTFILE&quot;),
213 (join),
214 (prefix_list_option &quot;L&quot;, (forward),
215 (help &quot;add a directory to link path&quot;)),
216 (prefix_list_option &quot;l&quot;, (forward),
217 (help &quot;search a library when linking&quot;)),
218 (prefix_list_option &quot;Wl&quot;, (unpack_values),
219 (help &quot;pass options to linker&quot;))
220 ]&gt;;
221</pre>
222<p>This tool has a &quot;join&quot; property, which means that it behaves like a
223linker. This tool also defines several command-line options: <tt class="docutils literal"><span class="pre">-l</span></tt>,
224<tt class="docutils literal"><span class="pre">-L</span></tt> and <tt class="docutils literal"><span class="pre">-Wl</span></tt> which have their usual meaning. An option has two
225attributes: a name and a (possibly empty) list of properties. All
226currently implemented option types and properties are described below:</p>
227<ul>
228<li><p class="first">Possible option types:</p>
229<blockquote>
230<ul class="simple">
231<li><tt class="docutils literal"><span class="pre">switch_option</span></tt> - a simple boolean switch, for example <tt class="docutils literal"><span class="pre">-time</span></tt>.</li>
232<li><tt class="docutils literal"><span class="pre">parameter_option</span></tt> - option that takes an argument, for example
233<tt class="docutils literal"><span class="pre">-std=c99</span></tt>;</li>
234<li><tt class="docutils literal"><span class="pre">parameter_list_option</span></tt> - same as the above, but more than one
235occurence of the option is allowed.</li>
236<li><tt class="docutils literal"><span class="pre">prefix_option</span></tt> - same as the parameter_option, but the option name
237and parameter value are not separated.</li>
238<li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one
239occurence of the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
240<li><tt class="docutils literal"><span class="pre">alias_option</span></tt> - a special option type for creating
241aliases. Unlike other option types, aliases are not allowed to
242have any properties besides the aliased option name. Usage
243example: <tt class="docutils literal"><span class="pre">(alias_option</span> <span class="pre">&quot;preprocess&quot;,</span> <span class="pre">&quot;E&quot;)</span></tt></li>
244</ul>
245</blockquote>
246</li>
247<li><p class="first">Possible option properties:</p>
248<blockquote>
249<ul class="simple">
250<li><tt class="docutils literal"><span class="pre">append_cmd</span></tt> - append a string to the tool invocation command.</li>
251<li><tt class="docutils literal"><span class="pre">forward</span></tt> - forward this option unchanged.</li>
252<li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - modify the output suffix of this
253tool. Example : <tt class="docutils literal"><span class="pre">(switch</span> <span class="pre">&quot;E&quot;,</span> <span class="pre">(output_suffix</span> <span class="pre">&quot;i&quot;)</span></tt>.</li>
254<li><tt class="docutils literal"><span class="pre">stop_compilation</span></tt> - stop compilation after this phase.</li>
255<li><tt class="docutils literal"><span class="pre">unpack_values</span></tt> - used for for splitting and forwarding
256comma-separated lists of options, e.g. <tt class="docutils literal"><span class="pre">-Wa,-foo=bar,-baz</span></tt> is
257converted to <tt class="docutils literal"><span class="pre">-foo=bar</span> <span class="pre">-baz</span></tt> and appended to the tool invocation
258command.</li>
259<li><tt class="docutils literal"><span class="pre">help</span></tt> - help string associated with this option. Used for
260<tt class="docutils literal"><span class="pre">--help</span></tt> output.</li>
261<li><tt class="docutils literal"><span class="pre">required</span></tt> - this option is obligatory.</li>
262</ul>
263</blockquote>
264</li>
265</ul>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]266</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]267<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]268<div class="doc_section"><a class="toc-backref" href="#id7" id="option-list-specifying-all-options-in-a-single-place" name="option-list-specifying-all-options-in-a-single-place">Option list - specifying all options in a single place</a></div>
269<p>It can be handy to have all information about options gathered in a
270single place to provide an overview. This can be achieved by using a
271so-called <tt class="docutils literal"><span class="pre">OptionList</span></tt>:</p>
272<pre class="literal-block">
273def Options : OptionList&lt;[
274(switch_option &quot;E&quot;, (help &quot;Help string&quot;)),
275(alias_option &quot;quiet&quot;, &quot;q&quot;)
276...
277]&gt;;
278</pre>
279<p><tt class="docutils literal"><span class="pre">OptionList</span></tt> is also a good place to specify option aliases.</p>
280<p>Tool-specific option properties like <tt class="docutils literal"><span class="pre">append_cmd</span></tt> have (obviously)
281no meaning in the context of <tt class="docutils literal"><span class="pre">OptionList</span></tt>, so the only properties
282allowed there are <tt class="docutils literal"><span class="pre">help</span></tt> and <tt class="docutils literal"><span class="pre">required</span></tt>.</p>
283<p>Option lists are used at the file scope. See file
284<tt class="docutils literal"><span class="pre">examples/Clang.td</span></tt> for an example of <tt class="docutils literal"><span class="pre">OptionList</span></tt> usage.</p>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]285</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]286<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]287<div class="doc_section"><a class="toc-backref" href="#id8" id="using-hooks-and-environment-variables-in-the-cmd-line-property" name="using-hooks-and-environment-variables-in-the-cmd-line-property">Using hooks and environment variables in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> property</a></div>
288<p>Normally, LLVMC executes programs from the system <tt class="docutils literal"><span class="pre">PATH</span></tt>. Sometimes,
289this is not sufficient: for example, we may want to specify tool names
290in the configuration file. This can be achieved via the mechanism of
291hooks - to compile LLVMC with your hooks, just drop a .cpp file into
292<tt class="docutils literal"><span class="pre">tools/llvmc2</span></tt> directory. Hooks should live in the <tt class="docutils literal"><span class="pre">hooks</span></tt>
293namespace and have the signature <tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::MyHookName</span>
294<span class="pre">(void)</span></tt>. They can be used from the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property:</p>
295<pre class="literal-block">
296(cmd_line &quot;$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)&quot;)
297</pre>
298<p>It is also possible to use environment variables in the same manner:</p>
299<pre class="literal-block">
300(cmd_line &quot;$ENV(VAR1)/path/to/file -o $ENV(VAR2)&quot;)
301</pre>
302<p>To change the command line string based on user-provided options use
303the <tt class="docutils literal"><span class="pre">case</span></tt> expression (documented below):</p>
304<pre class="literal-block">
305(cmd_line
306 (case
307 (switch_on &quot;E&quot;),
308 &quot;llvm-g++ -E -x c $INFILE -o $OUTFILE&quot;,
309 (default),
310 &quot;llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm&quot;))
311</pre>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]312</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]313<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]314<div class="doc_section"><a class="toc-backref" href="#id9" id="conditional-evaluation-the-case-expression" name="conditional-evaluation-the-case-expression">Conditional evaluation: the <tt class="docutils literal"><span class="pre">case</span></tt> expression</a></div>
315<p>The 'case' construct can be used to calculate weights of the optional
316edges and to choose between several alternative command line strings
317in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property. It is designed after the
318similarly-named construct in functional languages and takes the form
319<tt class="docutils literal"><span class="pre">(case</span> <span class="pre">(test_1),</span> <span class="pre">statement_1,</span> <span class="pre">(test_2),</span> <span class="pre">statement_2,</span> <span class="pre">...</span> <span class="pre">(test_N),</span>
320<span class="pre">statement_N)</span></tt>. The statements are evaluated only if the corresponding
321tests evaluate to true.</p>
322<p>Examples:</p>
323<pre class="literal-block">
324// Increases edge weight by 5 if &quot;-A&quot; is provided on the
325// command-line, and by 5 more if &quot;-B&quot; is also provided.
326(case
327 (switch_on &quot;A&quot;), (inc_weight 5),
328 (switch_on &quot;B&quot;), (inc_weight 5))
329
330// Evaluates to &quot;cmdline1&quot; if option &quot;-A&quot; is provided on the
331// command line, otherwise to &quot;cmdline2&quot;
332(case
333 (switch_on &quot;A&quot;), &quot;cmdline1&quot;,
334 (switch_on &quot;B&quot;), &quot;cmdline2&quot;,
335 (default), &quot;cmdline3&quot;)
336</pre>
337<p>Note the slight difference in 'case' expression handling in contexts
338of edge weights and command line specification - in the second example
339the value of the <tt class="docutils literal"><span class="pre">&quot;B&quot;</span></tt> switch is never checked when switch <tt class="docutils literal"><span class="pre">&quot;A&quot;</span></tt> is
340enabled, and the whole expression always evaluates to <tt class="docutils literal"><span class="pre">&quot;cmdline1&quot;</span></tt> in
341that case.</p>
342<p>Case expressions can also be nested, i.e. the following is legal:</p>
343<pre class="literal-block">
344(case (switch_on &quot;E&quot;), (case (switch_on &quot;o&quot;), ..., (default), ...)
345 (default), ...)
346</pre>
347<p>You should, however, try to avoid doing that because it hurts
348readability. It is usually better to split tool descriptions and/or
349use TableGen inheritance instead.</p>
350<ul class="simple">
351<li>Possible tests are:<ul>
352<li><tt class="docutils literal"><span class="pre">switch_on</span></tt> - Returns true if a given command-line option is
353provided by the user. Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">&quot;opt&quot;)</span></tt>. Note that
354you have to define all possible command-line options separately in
355the tool descriptions. See the next doc_text for the discussion of
356different kinds of command-line options.</li>
357<li><tt class="docutils literal"><span class="pre">parameter_equals</span></tt> - Returns true if a command-line parameter equals
358a given value. Example: <tt class="docutils literal"><span class="pre">(parameter_equals</span> <span class="pre">&quot;W&quot;,</span> <span class="pre">&quot;all&quot;)</span></tt>.</li>
359<li><tt class="docutils literal"><span class="pre">element_in_list</span></tt> - Returns true if a command-line parameter list
360includes a given value. Example: <tt class="docutils literal"><span class="pre">(parameter_in_list</span> <span class="pre">&quot;l&quot;,</span> <span class="pre">&quot;pthread&quot;)</span></tt>.</li>
361<li><tt class="docutils literal"><span class="pre">input_languages_contain</span></tt> - Returns true if a given language
362belongs to the current input language set. Example:
363<tt class="docutils literal"><span class="pre">`(input_languages_contain</span> <span class="pre">&quot;c++&quot;)</span></tt>.</li>
364<li><tt class="docutils literal"><span class="pre">in_language</span></tt> - Evaluates to true if the language of the input
365file equals to the argument. Valid only when using <tt class="docutils literal"><span class="pre">case</span></tt>
366expression in a <tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property. Example:
367<tt class="docutils literal"><span class="pre">`(in_language</span> <span class="pre">&quot;c++&quot;)</span></tt>.</li>
368<li><tt class="docutils literal"><span class="pre">not_empty</span></tt> - Returns true if a given option (which should be
369either a parameter or a parameter list) is set by the
370user. Example: <tt class="docutils literal"><span class="pre">`(not_empty</span> <span class="pre">&quot;o&quot;)</span></tt>.</li>
371<li><tt class="docutils literal"><span class="pre">default</span></tt> - Always evaluates to true. Should always be the last
372test in the <tt class="docutils literal"><span class="pre">case</span></tt> expression.</li>
373<li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard logical combinator that returns true iff all
374of its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span>
375<span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>. Nesting of <tt class="docutils literal"><span class="pre">and</span></tt> and <tt class="docutils literal"><span class="pre">or</span></tt> is allowed,
376but not encouraged.</li>
377<li><tt class="docutils literal"><span class="pre">or</span></tt> - Another logical combinator that returns true only if any
378one of its arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span>
379<span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li>
380</ul>
381</li>
382</ul>
Reid Spencer46d21922004-08-22 18:06:59 +0000[diff] [blame]383</div>
Reid Spencer46d21922004-08-22 18:06:59 +0000[diff] [blame]384<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]385<div class="doc_section"><a class="toc-backref" href="#id10" id="language-map" name="language-map">Language map</a></div>
386<p>One last thing that you will need to modify when adding support for a
387new language to LLVMC is the language map, which defines mappings from
388file extensions to language names. It is used to choose the proper
389toolchain(s) for a given input file set. Language map definition is
390located in the file <tt class="docutils literal"><span class="pre">Tools.td</span></tt> and looks like this:</p>
391<pre class="literal-block">
392def LanguageMap : LanguageMap&lt;
393 [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;,
394 LangToSuffixes&lt;&quot;c&quot;, [&quot;c&quot;]&gt;,
395 ...
396 ]&gt;;
397</pre>
Reid Spencer46d21922004-08-22 18:06:59 +0000[diff] [blame]398</div>
Reid Spencer46d21922004-08-22 18:06:59 +0000[diff] [blame]399<div class="doc_text">
Anton Korobeynikov74120312008-06-09 04:15:49 +0000[diff] [blame]400<div class="doc_section"><a class="toc-backref" href="#id11" id="references" name="references">References</a></div>
401<table class="docutils footnote" frame="void" id="id2" rules="none">
402<colgroup><col class="label" /><col /></colgroup>
403<tbody valign="top">
404<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>TableGen Fundamentals
405<a class="reference" href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html</a></td></tr>
406</tbody>
407</table>
Reid Spencer46d21922004-08-22 18:06:59 +0000[diff] [blame]408</div>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]409</div>
Anton Korobeynikov28b66702008-06-09 04:17:51 +0000[diff] [blame^]410<hr>
411<address>
412 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
413 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
414 <a href="http://validator.w3.org/check/referer"><img
415 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
416 <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br/>
417 Last modified: $Date$
418</address>
Reid Spencerb1254a12004-08-09 03:08:29 +0000[diff] [blame]419</body>
420</html>