docs/CompilerDriver.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   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" />
   9 </head>
  10 <body>
  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>
  18 </div>
  19
  20 <p>LLVMC is a generic compiler driver, designed to be customizable and
  21 extensible. It plays the same role for LLVM as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program
  22 does for GCC - LLVMC's job is essentially to transform a set of input
  23 files into a set of targets depending on configuration rules and user
  24 options. What makes LLVMC different is that these transformation rules
  25 are completely customizable - in fact, LLVMC knows nothing about the
  26 specifics of transformation (even the command-line options are mostly
  27 not hard-coded) and regards the transformation structure as an
  28 abstract graph. This makes it possible to adapt LLVMC for other
  29 purposes - 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
  31 need 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>
  44 </div>
  45
  46 <div class="doc_author">Written by Mikhail Glushenkov</div>
  47
  48 <div class="doc_text">
  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,
  51 although there are some small differences. Most of the time, however,
  52 you 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
  57 hello
  58 </pre>
  59 <p>One nice feature of LLVMC is that one doesn't have to distinguish
  60 between 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
  62 language names (which are, in turn, determined from file
  63 extensions). If you want to force files ending with &quot;.c&quot; to compile as
  64 C++, 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
  69 hello
  70 </pre>
  71 <p>On the other hand, when using LLVMC as a linker to combine several C++
  72 object files you should provide the <tt class="docutils literal"><span class="pre">--linker</span></tt> option since it's
  73 impossible 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
  80 hello
  81 </pre>
  82 </div>
  83 <div class="doc_text">
  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
  86 configuration 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
  90 until 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
  93 graph. 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
  94 installed. 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
  96 current directory with the compilation graph description in the
  97 Graphviz 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
  99 and 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
 101 their standard meaning.</li>
 102 </ul>
 103 </div>
 104 <div class="doc_text">
 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
 107 configuration, so to customize LLVMC you'll have to recompile the
 108 source code (which lives under <tt class="docutils literal"><span class="pre">$LLVM_DIR/tools/llvmc2</span></tt>). The
 109 default configuration files are <tt class="docutils literal"><span class="pre">Common.td</span></tt> (contains common
 110 definitions, don't forget to <tt class="docutils literal"><span class="pre">include</span></tt> it in your configuration
 111 files), <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
 112 graph definition).</p>
 113 <p>To compile LLVMC with your own configuration file (say,``MyGraph.td``),
 114 run <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
 120 several sample configuration files in the <tt class="docutils literal"><span class="pre">llvmc2/examples</span></tt>
 121 subdirectory that should help to get you started.</p>
 122 <p>Internally, LLVMC stores information about possible source
 123 transformations in form of a graph. Nodes in this graph represent
 124 tools, and edges between two nodes represent a transformation path. A
 125 special &quot;root&quot; node is used to mark entry points for the
 126 transformations. LLVMC also assigns a weight to each edge (more on
 127 this 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
 129 just a list of edges:</p>
 130 <pre class="literal-block">
 131 def 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
 153 optional edges are differentiated by sporting a <tt class="docutils literal"><span class="pre">case</span></tt> expression
 154 used to calculate the edge's weight.</p>
 155 <p>The default edges are assigned a weight of 1, and optional edges get a
 156 weight of 0 + 2*N where N is the number of tests that evaluated to
 157 true in the <tt class="docutils literal"><span class="pre">case</span></tt> expression. It is also possible to provide an
 158 integer 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,
 159 the weight is increased (or decreased) by the provided value instead
 160 of the default 2.</p>
 161 <p>When passing an input file through the graph, LLVMC picks the edge
 162 with the maximum weight. To avoid ambiguity, there should be only one
 163 default edge between two nodes (with the exception of the root node,
 164 which gets a special treatment - there you are allowed to specify one
 165 default edge <em>per language</em>).</p>
 166 <p>To get a visual representation of the compilation graph (useful for
 167 debugging), 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>
 169 </div>
 170 <div class="doc_text">
 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,
 173 which 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">
 176 def 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
 186 properties; most of them should be self-explanatory. The <tt class="docutils literal"><span class="pre">sink</span></tt>
 187 property means that this tool should be passed all command-line
 188 options 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
 196 use <tt class="docutils literal"><span class="pre">$INFILE</span></tt> and <tt class="docutils literal"><span class="pre">$OUTFILE</span></tt> variables, output redirection
 197 with <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
 200 list 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
 202 tools 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">
 208 def 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
 223 linker. 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
 225 attributes: a name and a (possibly empty) list of properties. All
 226 currently 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
 235 occurence 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
 237 and 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
 239 occurence 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
 241 aliases. Unlike other option types, aliases are not allowed to
 242 have any properties besides the aliased option name. Usage
 243 example: <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
 253 tool. 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
 256 comma-separated lists of options, e.g. <tt class="docutils literal"><span class="pre">-Wa,-foo=bar,-baz</span></tt> is
 257 converted to <tt class="docutils literal"><span class="pre">-foo=bar</span> <span class="pre">-baz</span></tt> and appended to the tool invocation
 258 command.</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>
 266 </div>
 267 <div class="doc_text">
 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
 270 single place to provide an overview. This can be achieved by using a
 271 so-called <tt class="docutils literal"><span class="pre">OptionList</span></tt>:</p>
 272 <pre class="literal-block">
 273 def 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)
 281 no meaning in the context of <tt class="docutils literal"><span class="pre">OptionList</span></tt>, so the only properties
 282 allowed 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>
 285 </div>
 286 <div class="doc_text">
 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,
 289 this is not sufficient: for example, we may want to specify tool names
 290 in the configuration file. This can be achieved via the mechanism of
 291 hooks - 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>
 293 namespace 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
 303 the <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>
 312 </div>
 313 <div class="doc_text">
 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
 316 edges and to choose between several alternative command line strings
 317 in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property. It is designed after the
 318 similarly-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
 321 tests 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
 338 of edge weights and command line specification - in the second example
 339 the 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
 340 enabled, and the whole expression always evaluates to <tt class="docutils literal"><span class="pre">&quot;cmdline1&quot;</span></tt> in
 341 that 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
 348 readability. It is usually better to split tool descriptions and/or
 349 use 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
 353 provided by the user. Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">&quot;opt&quot;)</span></tt>. Note that
 354 you have to define all possible command-line options separately in
 355 the tool descriptions. See the next doc_text for the discussion of
 356 different 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
 358 a 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
 360 includes 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
 362 belongs 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
 365 file equals to the argument. Valid only when using <tt class="docutils literal"><span class="pre">case</span></tt>
 366 expression 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
 369 either a parameter or a parameter list) is set by the
 370 user. 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
 372 test 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
 374 of 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,
 376 but not encouraged.</li>
 377 <li><tt class="docutils literal"><span class="pre">or</span></tt> - Another logical combinator that returns true only if any
 378 one 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>
 383 </div>
 384 <div class="doc_text">
 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
 387 new language to LLVMC is the language map, which defines mappings from
 388 file extensions to language names. It is used to choose the proper
 389 toolchain(s) for a given input file set. Language map definition is
 390 located in the file <tt class="docutils literal"><span class="pre">Tools.td</span></tt> and looks like this:</p>
 391 <pre class="literal-block">
 392 def 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>
 398 </div>
 399 <div class="doc_text">
 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>
 408 </div>
 409 </div>
 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-xhtml10" alt="Valid XHTML 1.0!" /></a>
 416   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br/>
 417   Last modified: $Date$
 418 </address>
 419 </body>
 420 </html>