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.1: http://docutils.sourceforge.net/" />
   7 <title>Customizing LLVMC: Reference Manual</title>
   8 <meta name="author" content="Mikhail Glushenkov &lt;foldr&#64;codedegers.com&gt;" />
   9 <link rel="stylesheet" href="llvm-rst.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document" id="customizing-llvmc-reference-manual">
  13 <h1 class="title">Customizing LLVMC: Reference Manual</h1>
  14 <table class="docinfo" frame="void" rules="none">
  15 <col class="docinfo-name" />
  16 <col class="docinfo-content" />
  17 <tbody valign="top">
  18 <tr><th class="docinfo-name">Author:</th>
  19 <td>Mikhail Glushenkov &lt;<a class="reference" href="mailto:foldr&#64;codedegers.com">foldr&#64;codedegers.com</a>&gt;</td></tr>
  20 </tbody>
  21 </table>
  22 <p>LLVMC is a generic compiler driver, designed to be customizable and
  23 extensible. It plays the same role for LLVM as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program
  24 does for GCC - LLVMC's job is essentially to transform a set of input
  25 files into a set of targets depending on configuration rules and user
  26 options. What makes LLVMC different is that these transformation rules
  27 are completely customizable - in fact, LLVMC knows nothing about the
  28 specifics of transformation (even the command-line options are mostly
  29 not hard-coded) and regards the transformation structure as an
  30 abstract graph. The structure of this graph is completely determined
  31 by plugins, which can be either statically or dynamically linked. This
  32 makes it possible to easily adapt LLVMC for other purposes - for
  33 example, as a build tool for game resources.</p>
  34 <p>Because LLVMC employs TableGen <a class="footnote-reference" href="#id7" id="id1" name="id1">[1]</a> as its configuration language, you
  35 need to be familiar with it to customize LLVMC.</p>
  36 <div class="contents topic">
  37 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
  38 <ul class="simple">
  39 <li><a class="reference" href="#compiling-with-llvmc" id="id10" name="id10">Compiling with LLVMC</a></li>
  40 <li><a class="reference" href="#predefined-options" id="id11" name="id11">Predefined options</a></li>
  41 <li><a class="reference" href="#compiling-llvmc-plugins" id="id12" name="id12">Compiling LLVMC plugins</a></li>
  42 <li><a class="reference" href="#customizing-llvmc-the-compilation-graph" id="id13" name="id13">Customizing LLVMC: the compilation graph</a></li>
  43 <li><a class="reference" href="#describing-options" id="id14" name="id14">Describing options</a><ul>
  44 <li><a class="reference" href="#external-options" id="id15" name="id15">External options</a></li>
  45 </ul>
  46 </li>
  47 <li><a class="reference" href="#conditional-evaluation" id="id16" name="id16">Conditional evaluation</a></li>
  48 <li><a class="reference" href="#writing-a-tool-description" id="id17" name="id17">Writing a tool description</a><ul>
  49 <li><a class="reference" href="#actions" id="id18" name="id18">Actions</a></li>
  50 </ul>
  51 </li>
  52 <li><a class="reference" href="#language-map" id="id19" name="id19">Language map</a></li>
  53 <li><a class="reference" href="#more-advanced-topics" id="id20" name="id20">More advanced topics</a><ul>
  54 <li><a class="reference" href="#hooks-and-environment-variables" id="id21" name="id21">Hooks and environment variables</a></li>
  55 <li><a class="reference" href="#how-plugins-are-loaded" id="id22" name="id22">How plugins are loaded</a></li>
  56 <li><a class="reference" href="#debugging" id="id23" name="id23">Debugging</a></li>
  57 </ul>
  58 </li>
  59 <li><a class="reference" href="#references" id="id24" name="id24">References</a></li>
  60 </ul>
  61 </div>
  62 <div class="section">
  63 <h1><a class="toc-backref" href="#id10" id="compiling-with-llvmc" name="compiling-with-llvmc">Compiling with LLVMC</a></h1>
  64 <p>LLVMC tries hard to be as compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as possible,
  65 although there are some small differences. Most of the time, however,
  66 you shouldn't be able to notice them:</p>
  67 <pre class="literal-block">
  68 $ # This works as expected:
  69 $ llvmc -O3 -Wall hello.cpp
  70 $ ./a.out
  71 hello
  72 </pre>
  73 <p>One nice feature of LLVMC is that one doesn't have to distinguish
  74 between different compilers for different languages (think <tt class="docutils literal"><span class="pre">g++</span></tt> and
  75 <tt class="docutils literal"><span class="pre">gcc</span></tt>) - the right toolchain is chosen automatically based on input
  76 language names (which are, in turn, determined from file
  77 extensions). If you want to force files ending with &quot;.c&quot; to compile as
  78 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>
  79 <pre class="literal-block">
  80 $ # hello.c is really a C++ file
  81 $ llvmc -x c++ hello.c
  82 $ ./a.out
  83 hello
  84 </pre>
  85 <p>On the other hand, when using LLVMC as a linker to combine several C++
  86 object files you should provide the <tt class="docutils literal"><span class="pre">--linker</span></tt> option since it's
  87 impossible for LLVMC to choose the right linker in that case:</p>
  88 <pre class="literal-block">
  89 $ llvmc -c hello.cpp
  90 $ llvmc hello.o
  91 [A lot of link-time errors skipped]
  92 $ llvmc --linker=c++ hello.o
  93 $ ./a.out
  94 hello
  95 </pre>
  96 <p>By default, LLVMC uses <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> to compile the source code. It is
  97 also possible to choose the work-in-progress <tt class="docutils literal"><span class="pre">clang</span></tt> compiler with
  98 the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p>
  99 </div>
 100 <div class="section">
 101 <h1><a class="toc-backref" href="#id11" id="predefined-options" name="predefined-options">Predefined options</a></h1>
 102 <p>LLVMC has some built-in options that can't be overridden in the
 103 configuration libraries:</p>
 104 <ul class="simple">
 105 <li><tt class="docutils literal"><span class="pre">-o</span> <span class="pre">FILE</span></tt> - Output file name.</li>
 106 <li><tt class="docutils literal"><span class="pre">-x</span> <span class="pre">LANGUAGE</span></tt> - Specify the language of the following input files
 107 until the next -x option.</li>
 108 <li><tt class="docutils literal"><span class="pre">-load</span> <span class="pre">PLUGIN_NAME</span></tt> - Load the specified plugin DLL. Example:
 109 <tt class="docutils literal"><span class="pre">-load</span> <span class="pre">$LLVM_DIR/Release/lib/LLVMCSimple.so</span></tt>.</li>
 110 <li><tt class="docutils literal"><span class="pre">-v</span></tt> - Enable verbose mode, i.e. print out all executed commands.</li>
 111 <li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation
 112 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> programs
 113 installed. Hidden option, useful for debugging.</li>
 114 <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
 115 current directory with the compilation graph description in the
 116 Graphviz format. Hidden option, useful for debugging.</li>
 117 <li><tt class="docutils literal"><span class="pre">--save-temps</span></tt> - Write temporary files to the current directory
 118 and do not delete them on exit. Hidden option, useful for debugging.</li>
 119 <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
 120 their standard meaning.</li>
 121 </ul>
 122 </div>
 123 <div class="section">
 124 <h1><a class="toc-backref" href="#id12" id="compiling-llvmc-plugins" name="compiling-llvmc-plugins">Compiling LLVMC plugins</a></h1>
 125 <p>It's easiest to start working on your own LLVMC plugin by copying the
 126 skeleton project which lives under <tt class="docutils literal"><span class="pre">$LLVMC_DIR/plugins/Simple</span></tt>:</p>
 127 <pre class="literal-block">
 128 $ cd $LLVMC_DIR/plugins
 129 $ cp -r Simple MyPlugin
 130 $ cd MyPlugin
 131 $ ls
 132 Makefile PluginMain.cpp Simple.td
 133 </pre>
 134 <p>As you can see, our basic plugin consists of only two files (not
 135 counting the build script). <tt class="docutils literal"><span class="pre">Simple.td</span></tt> contains TableGen
 136 description of the compilation graph; its format is documented in the
 137 following sections. <tt class="docutils literal"><span class="pre">PluginMain.cpp</span></tt> is just a helper file used to
 138 compile the auto-generated C++ code produced from TableGen source. It
 139 can also contain hook definitions (see <a class="reference" href="#hooks">below</a>).</p>
 140 <p>The first thing that you should do is to change the <tt class="docutils literal"><span class="pre">LLVMC_PLUGIN</span></tt>
 141 variable in the <tt class="docutils literal"><span class="pre">Makefile</span></tt> to avoid conflicts (since this variable
 142 is used to name the resulting library):</p>
 143 <pre class="literal-block">
 144 LLVMC_PLUGIN=MyPlugin
 145 </pre>
 146 <p>It is also a good idea to rename <tt class="docutils literal"><span class="pre">Simple.td</span></tt> to something less
 147 generic:</p>
 148 <pre class="literal-block">
 149 $ mv Simple.td MyPlugin.td
 150 </pre>
 151 <p>Note that the plugin source directory must be placed under
 152 <tt class="docutils literal"><span class="pre">$LLVMC_DIR/plugins</span></tt> to make use of the existing build
 153 infrastructure. To build a version of the LLVMC executable called
 154 <tt class="docutils literal"><span class="pre">mydriver</span></tt> with your plugin compiled in, use the following command:</p>
 155 <pre class="literal-block">
 156 $ cd $LLVMC_DIR
 157 $ make BUILTIN_PLUGINS=MyPlugin DRIVER_NAME=mydriver
 158 </pre>
 159 <p>To build your plugin as a dynamic library, just <tt class="docutils literal"><span class="pre">cd</span></tt> to its source
 160 directory and run <tt class="docutils literal"><span class="pre">make</span></tt>. The resulting file will be called
 161 <tt class="docutils literal"><span class="pre">LLVMC$(LLVMC_PLUGIN).$(DLL_EXTENSION)</span></tt> (in our case,
 162 <tt class="docutils literal"><span class="pre">LLVMCMyPlugin.so</span></tt>). This library can be then loaded in with the
 163 <tt class="docutils literal"><span class="pre">-load</span></tt> option. Example:</p>
 164 <pre class="literal-block">
 165 $ cd $LLVMC_DIR/plugins/Simple
 166 $ make
 167 $ llvmc -load $LLVM_DIR/Release/lib/LLVMCSimple.so
 168 </pre>
 169 <p>Sometimes, you will want a 'bare-bones' version of LLVMC that has no
 170 built-in plugins. It can be compiled with the following command:</p>
 171 <pre class="literal-block">
 172 $ cd $LLVMC_DIR
 173 $ make BUILTIN_PLUGINS=&quot;&quot;
 174 </pre>
 175 </div>
 176 <div class="section">
 177 <h1><a class="toc-backref" href="#id13" id="customizing-llvmc-the-compilation-graph" name="customizing-llvmc-the-compilation-graph">Customizing LLVMC: the compilation graph</a></h1>
 178 <p>Each TableGen configuration file should include the common
 179 definitions:</p>
 180 <pre class="literal-block">
 181 include &quot;llvm/CompilerDriver/Common.td&quot;
 182 </pre>
 183 <p>Internally, LLVMC stores information about possible source
 184 transformations in form of a graph. Nodes in this graph represent
 185 tools, and edges between two nodes represent a transformation path. A
 186 special &quot;root&quot; node is used to mark entry points for the
 187 transformations. LLVMC also assigns a weight to each edge (more on
 188 this later) to choose between several alternative edges.</p>
 189 <p>The definition of the compilation graph (see file
 190 <tt class="docutils literal"><span class="pre">plugins/Base/Base.td</span></tt> for an example) is just a list of edges:</p>
 191 <pre class="literal-block">
 192 def CompilationGraph : CompilationGraph&lt;[
 193     Edge&lt;&quot;root&quot;, &quot;llvm_gcc_c&quot;&gt;,
 194     Edge&lt;&quot;root&quot;, &quot;llvm_gcc_assembler&quot;&gt;,
 195     ...
 196
 197     Edge&lt;&quot;llvm_gcc_c&quot;, &quot;llc&quot;&gt;,
 198     Edge&lt;&quot;llvm_gcc_cpp&quot;, &quot;llc&quot;&gt;,
 199     ...
 200
 201     OptionalEdge&lt;&quot;llvm_gcc_c&quot;, &quot;opt&quot;, (case (switch_on &quot;opt&quot;),
 202                                       (inc_weight))&gt;,
 203     OptionalEdge&lt;&quot;llvm_gcc_cpp&quot;, &quot;opt&quot;, (case (switch_on &quot;opt&quot;),
 204                                               (inc_weight))&gt;,
 205     ...
 206
 207     OptionalEdge&lt;&quot;llvm_gcc_assembler&quot;, &quot;llvm_gcc_cpp_linker&quot;,
 208         (case (input_languages_contain &quot;c++&quot;), (inc_weight),
 209               (or (parameter_equals &quot;linker&quot;, &quot;g++&quot;),
 210                   (parameter_equals &quot;linker&quot;, &quot;c++&quot;)), (inc_weight))&gt;,
 211     ...
 212
 213     ]&gt;;
 214 </pre>
 215 <p>As you can see, the edges can be either default or optional, where
 216 optional edges are differentiated by an additional <tt class="docutils literal"><span class="pre">case</span></tt> expression
 217 used to calculate the weight of this edge. Notice also that we refer
 218 to tools via their names (as strings). This makes it possible to add
 219 edges to an existing compilation graph in plugins without having to
 220 know about all tool definitions used in the graph.</p>
 221 <p>The default edges are assigned a weight of 1, and optional edges get a
 222 weight of 0 + 2*N where N is the number of tests that evaluated to
 223 true in the <tt class="docutils literal"><span class="pre">case</span></tt> expression. It is also possible to provide an
 224 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,
 225 the weight is increased (or decreased) by the provided value instead
 226 of the default 2. It is also possible to change the default weight of
 227 an optional edge by using the <tt class="docutils literal"><span class="pre">default</span></tt> clause of the <tt class="docutils literal"><span class="pre">case</span></tt>
 228 construct.</p>
 229 <p>When passing an input file through the graph, LLVMC picks the edge
 230 with the maximum weight. To avoid ambiguity, there should be only one
 231 default edge between two nodes (with the exception of the root node,
 232 which gets a special treatment - there you are allowed to specify one
 233 default edge <em>per language</em>).</p>
 234 <p>When multiple plugins are loaded, their compilation graphs are merged
 235 together. Since multiple edges that have the same end nodes are not
 236 allowed (i.e. the graph is not a multigraph), an edge defined in
 237 several plugins will be replaced by the definition from the plugin
 238 that was loaded last. Plugin load order can be controlled by using the
 239 plugin priority feature described above.</p>
 240 <p>To get a visual representation of the compilation graph (useful for
 241 debugging), run <tt class="docutils literal"><span class="pre">llvmc</span> <span class="pre">--view-graph</span></tt>. You will need <tt class="docutils literal"><span class="pre">dot</span></tt> and
 242 <tt class="docutils literal"><span class="pre">gsview</span></tt> installed for this to work properly.</p>
 243 </div>
 244 <div class="section">
 245 <h1><a class="toc-backref" href="#id14" id="describing-options" name="describing-options">Describing options</a></h1>
 246 <p>Command-line options that the plugin supports are defined by using an
 247 <tt class="docutils literal"><span class="pre">OptionList</span></tt>:</p>
 248 <pre class="literal-block">
 249 def Options : OptionList&lt;[
 250 (switch_option &quot;E&quot;, (help &quot;Help string&quot;)),
 251 (alias_option &quot;quiet&quot;, &quot;q&quot;)
 252 ...
 253 ]&gt;;
 254 </pre>
 255 <p>As you can see, the option list is just a list of DAGs, where each DAG
 256 is an option description consisting of the option name and some
 257 properties. A plugin can define more than one option list (they are
 258 all merged together in the end), which can be handy if one wants to
 259 separate option groups syntactically.</p>
 260 <ul>
 261 <li><p class="first">Possible option types:</p>
 262 <blockquote>
 263 <ul class="simple">
 264 <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>
 265 <li><tt class="docutils literal"><span class="pre">parameter_option</span></tt> - option that takes an argument, for example
 266 <tt class="docutils literal"><span class="pre">-std=c99</span></tt>;</li>
 267 <li><tt class="docutils literal"><span class="pre">parameter_list_option</span></tt> - same as the above, but more than one
 268 occurence of the option is allowed.</li>
 269 <li><tt class="docutils literal"><span class="pre">prefix_option</span></tt> - same as the parameter_option, but the option name
 270 and parameter value are not separated.</li>
 271 <li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one
 272 occurence of the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
 273 <li><tt class="docutils literal"><span class="pre">alias_option</span></tt> - a special option type for creating
 274 aliases. Unlike other option types, aliases are not allowed to
 275 have any properties besides the aliased option name. Usage
 276 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>
 277 </ul>
 278 </blockquote>
 279 </li>
 280 <li><p class="first">Possible option properties:</p>
 281 <blockquote>
 282 <ul class="simple">
 283 <li><tt class="docutils literal"><span class="pre">help</span></tt> - help string associated with this option. Used for
 284 <tt class="docutils literal"><span class="pre">--help</span></tt> output.</li>
 285 <li><tt class="docutils literal"><span class="pre">required</span></tt> - this option is obligatory.</li>
 286 <li><tt class="docutils literal"><span class="pre">hidden</span></tt> - this option should not appear in the <tt class="docutils literal"><span class="pre">--help</span></tt>
 287 output (but should appear in the <tt class="docutils literal"><span class="pre">--help-hidden</span></tt> output).</li>
 288 <li><tt class="docutils literal"><span class="pre">really_hidden</span></tt> - the option should not appear in any help
 289 output.</li>
 290 <li><tt class="docutils literal"><span class="pre">extern</span></tt> - this option is defined in some other plugin, see below.</li>
 291 </ul>
 292 </blockquote>
 293 </li>
 294 </ul>
 295 <div class="section">
 296 <h2><a class="toc-backref" href="#id15" id="external-options" name="external-options">External options</a></h2>
 297 <p>Sometimes, when linking several plugins together, one plugin needs to
 298 access options defined in some other plugin. Because of the way
 299 options are implemented, such options should be marked as
 300 <tt class="docutils literal"><span class="pre">extern</span></tt>. This is what the <tt class="docutils literal"><span class="pre">extern</span></tt> option property is
 301 for. Example:</p>
 302 <pre class="literal-block">
 303 ...
 304 (switch_option &quot;E&quot;, (extern))
 305 ...
 306 </pre>
 307 <p>See also the section on plugin <a class="reference" href="#priorities">priorities</a>.</p>
 308 </div>
 309 </div>
 310 <div class="section">
 311 <h1><a class="toc-backref" href="#id16" id="conditional-evaluation" name="conditional-evaluation"><span id="case"></span>Conditional evaluation</a></h1>
 312 <p>The 'case' construct is the main means by which programmability is
 313 achieved in LLVMC. It can be used to calculate edge weights, program
 314 actions and modify the shell commands to be executed. The 'case'
 315 expression is designed after the similarly-named construct in
 316 functional languages and takes the form <tt class="docutils literal"><span class="pre">(case</span> <span class="pre">(test_1),</span> <span class="pre">statement_1,</span>
 317 <span class="pre">(test_2),</span> <span class="pre">statement_2,</span> <span class="pre">...</span> <span class="pre">(test_N),</span> <span class="pre">statement_N)</span></tt>. The statements
 318 are evaluated only if the corresponding tests evaluate to true.</p>
 319 <p>Examples:</p>
 320 <pre class="literal-block">
 321 // Edge weight calculation
 322
 323 // Increases edge weight by 5 if &quot;-A&quot; is provided on the
 324 // command-line, and by 5 more if &quot;-B&quot; is also provided.
 325 (case
 326     (switch_on &quot;A&quot;), (inc_weight 5),
 327     (switch_on &quot;B&quot;), (inc_weight 5))
 328
 329
 330 // Tool command line specification
 331
 332 // Evaluates to &quot;cmdline1&quot; if the option &quot;-A&quot; is provided on the
 333 // command line; to &quot;cmdline2&quot; if &quot;-B&quot; is provided;
 334 // otherwise to &quot;cmdline3&quot;.
 335
 336 (case
 337     (switch_on &quot;A&quot;), &quot;cmdline1&quot;,
 338     (switch_on &quot;B&quot;), &quot;cmdline2&quot;,
 339     (default), &quot;cmdline3&quot;)
 340 </pre>
 341 <p>Note the slight difference in 'case' expression handling in contexts
 342 of edge weights and command line specification - in the second example
 343 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
 344 enabled, and the whole expression always evaluates to <tt class="docutils literal"><span class="pre">&quot;cmdline1&quot;</span></tt> in
 345 that case.</p>
 346 <p>Case expressions can also be nested, i.e. the following is legal:</p>
 347 <pre class="literal-block">
 348 (case (switch_on &quot;E&quot;), (case (switch_on &quot;o&quot;), ..., (default), ...)
 349       (default), ...)
 350 </pre>
 351 <p>You should, however, try to avoid doing that because it hurts
 352 readability. It is usually better to split tool descriptions and/or
 353 use TableGen inheritance instead.</p>
 354 <ul class="simple">
 355 <li>Possible tests are:<ul>
 356 <li><tt class="docutils literal"><span class="pre">switch_on</span></tt> - Returns true if a given command-line switch is
 357 provided by the user. Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">&quot;opt&quot;)</span></tt>.</li>
 358 <li><tt class="docutils literal"><span class="pre">parameter_equals</span></tt> - Returns true if a command-line parameter equals
 359 a given value.
 360 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>
 361 <li><tt class="docutils literal"><span class="pre">element_in_list</span></tt> - Returns true if a command-line parameter
 362 list contains a given value.
 363 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>
 364 <li><tt class="docutils literal"><span class="pre">input_languages_contain</span></tt> - Returns true if a given language
 365 belongs to the current input language set.
 366 Example: <tt class="docutils literal"><span class="pre">(input_languages_contain</span> <span class="pre">&quot;c++&quot;)</span></tt>.</li>
 367 <li><tt class="docutils literal"><span class="pre">in_language</span></tt> - Evaluates to true if the input file language
 368 equals to the argument. At the moment works only with <tt class="docutils literal"><span class="pre">cmd_line</span></tt>
 369 and <tt class="docutils literal"><span class="pre">actions</span></tt> (on non-join nodes).
 370 Example: <tt class="docutils literal"><span class="pre">(in_language</span> <span class="pre">&quot;c++&quot;)</span></tt>.</li>
 371 <li><tt class="docutils literal"><span class="pre">not_empty</span></tt> - Returns true if a given option (which should be
 372 either a parameter or a parameter list) is set by the
 373 user.
 374 Example: <tt class="docutils literal"><span class="pre">(not_empty</span> <span class="pre">&quot;o&quot;)</span></tt>.</li>
 375 <li><tt class="docutils literal"><span class="pre">default</span></tt> - Always evaluates to true. Should always be the last
 376 test in the <tt class="docutils literal"><span class="pre">case</span></tt> expression.</li>
 377 <li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard logical combinator that returns true iff all
 378 of its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span>
 379 <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,
 380 but not encouraged.</li>
 381 <li><tt class="docutils literal"><span class="pre">or</span></tt> - Another logical combinator that returns true only if any
 382 one of its arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span>
 383 <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li>
 384 </ul>
 385 </li>
 386 </ul>
 387 </div>
 388 <div class="section">
 389 <h1><a class="toc-backref" href="#id17" id="writing-a-tool-description" name="writing-a-tool-description">Writing a tool description</a></h1>
 390 <p>As was said earlier, nodes in the compilation graph represent tools,
 391 which are described separately. A tool definition looks like this
 392 (taken from the <tt class="docutils literal"><span class="pre">include/llvm/CompilerDriver/Tools.td</span></tt> file):</p>
 393 <pre class="literal-block">
 394 def llvm_gcc_cpp : Tool&lt;[
 395     (in_language &quot;c++&quot;),
 396     (out_language &quot;llvm-assembler&quot;),
 397     (output_suffix &quot;bc&quot;),
 398     (cmd_line &quot;llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm&quot;),
 399     (sink)
 400     ]&gt;;
 401 </pre>
 402 <p>This defines a new tool called <tt class="docutils literal"><span class="pre">llvm_gcc_cpp</span></tt>, which is an alias for
 403 <tt class="docutils literal"><span class="pre">llvm-g++</span></tt>. As you can see, a tool definition is just a list of
 404 properties; most of them should be self-explanatory. The <tt class="docutils literal"><span class="pre">sink</span></tt>
 405 property means that this tool should be passed all command-line
 406 options that aren't mentioned in the option list.</p>
 407 <p>The complete list of all currently implemented tool properties follows.</p>
 408 <ul class="simple">
 409 <li>Possible tool properties:<ul>
 410 <li><tt class="docutils literal"><span class="pre">in_language</span></tt> - input language name. Can be either a string or a
 411 list, in case the tool supports multiple input languages.</li>
 412 <li><tt class="docutils literal"><span class="pre">out_language</span></tt> - output language name. Tools are not allowed to
 413 have multiple output languages.</li>
 414 <li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - output file suffix. Can also be changed
 415 dynamically, see documentation on actions.</li>
 416 <li><tt class="docutils literal"><span class="pre">cmd_line</span></tt> - the actual command used to run the tool. You can
 417 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
 418 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
 419 (via <tt class="docutils literal"><span class="pre">$ENV</span></tt>) and the <tt class="docutils literal"><span class="pre">case</span></tt> construct.</li>
 420 <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
 421 list of input files and joins them together. Used for linkers.</li>
 422 <li><tt class="docutils literal"><span class="pre">sink</span></tt> - all command-line options that are not handled by other
 423 tools are passed to this tool.</li>
 424 <li><tt class="docutils literal"><span class="pre">actions</span></tt> - A single big <tt class="docutils literal"><span class="pre">case</span></tt> expression that specifies how
 425 this tool reacts on command-line options (described in more detail
 426 below).</li>
 427 </ul>
 428 </li>
 429 </ul>
 430 <div class="section">
 431 <h2><a class="toc-backref" href="#id18" id="actions" name="actions">Actions</a></h2>
 432 <p>A tool often needs to react to command-line options, and this is
 433 precisely what the <tt class="docutils literal"><span class="pre">actions</span></tt> property is for. The next example
 434 illustrates this feature:</p>
 435 <pre class="literal-block">
 436 def llvm_gcc_linker : Tool&lt;[
 437     (in_language &quot;object-code&quot;),
 438     (out_language &quot;executable&quot;),
 439     (output_suffix &quot;out&quot;),
 440     (cmd_line &quot;llvm-gcc $INFILE -o $OUTFILE&quot;),
 441     (join),
 442     (actions (case (not_empty &quot;L&quot;), (forward &quot;L&quot;),
 443                    (not_empty &quot;l&quot;), (forward &quot;l&quot;),
 444                    (not_empty &quot;dummy&quot;),
 445                              [(append_cmd &quot;-dummy1&quot;), (append_cmd &quot;-dummy2&quot;)])
 446     ]&gt;;
 447 </pre>
 448 <p>The <tt class="docutils literal"><span class="pre">actions</span></tt> tool property is implemented on top of the omnipresent
 449 <tt class="docutils literal"><span class="pre">case</span></tt> expression. It associates one or more different <em>actions</em>
 450 with given conditions - in the example, the actions are <tt class="docutils literal"><span class="pre">forward</span></tt>,
 451 which forwards a given option unchanged, and <tt class="docutils literal"><span class="pre">append_cmd</span></tt>, which
 452 appends a given string to the tool execution command. Multiple actions
 453 can be associated with a single condition by using a list of actions
 454 (used in the example to append some dummy options). The same <tt class="docutils literal"><span class="pre">case</span></tt>
 455 construct can also be used in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> property to modify the
 456 tool command line.</p>
 457 <p>The &quot;join&quot; property used in the example means that this tool behaves
 458 like a linker.</p>
 459 <p>The list of all possible actions follows.</p>
 460 <ul>
 461 <li><p class="first">Possible actions:</p>
 462 <blockquote>
 463 <ul class="simple">
 464 <li><tt class="docutils literal"><span class="pre">append_cmd</span></tt> - append a string to the tool invocation
 465 command.
 466 Example: <tt class="docutils literal"><span class="pre">(case</span> <span class="pre">(switch_on</span> <span class="pre">&quot;pthread&quot;),</span> <span class="pre">(append_cmd</span> <span class="pre">&quot;-lpthread&quot;))</span></tt></li>
 467 <li><tt class="docutils literal"><span class="pre">forward</span></tt> - forward an option unchanged.
 468 Example: <tt class="docutils literal"><span class="pre">(forward</span> <span class="pre">&quot;Wall&quot;)</span></tt>.</li>
 469 <li><tt class="docutils literal"><span class="pre">forward_as</span></tt> - Change the name of an option, but forward the
 470 argument unchanged.
 471 Example: <tt class="docutils literal"><span class="pre">(forward_as</span> <span class="pre">&quot;O0&quot;</span> <span class="pre">&quot;--disable-optimization&quot;)</span></tt>.</li>
 472 <li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - modify the output suffix of this
 473 tool.
 474 Example: <tt class="docutils literal"><span class="pre">(output_suffix</span> <span class="pre">&quot;i&quot;)</span></tt>.</li>
 475 <li><tt class="docutils literal"><span class="pre">stop_compilation</span></tt> - stop compilation after this tool processes
 476 its input. Used without arguments.</li>
 477 <li><tt class="docutils literal"><span class="pre">unpack_values</span></tt> - used for for splitting and forwarding
 478 comma-separated lists of options, e.g. <tt class="docutils literal"><span class="pre">-Wa,-foo=bar,-baz</span></tt> is
 479 converted to <tt class="docutils literal"><span class="pre">-foo=bar</span> <span class="pre">-baz</span></tt> and appended to the tool invocation
 480 command.
 481 Example: <tt class="docutils literal"><span class="pre">(unpack_values</span> <span class="pre">&quot;Wa,&quot;)</span></tt>.</li>
 482 </ul>
 483 </blockquote>
 484 </li>
 485 </ul>
 486 </div>
 487 </div>
 488 <div class="section">
 489 <h1><a class="toc-backref" href="#id19" id="language-map" name="language-map">Language map</a></h1>
 490 <p>If you are adding support for a new language to LLVMC, you'll need to
 491 modify the language map, which defines mappings from file extensions
 492 to language names. It is used to choose the proper toolchain(s) for a
 493 given input file set. Language map definition looks like this:</p>
 494 <pre class="literal-block">
 495 def LanguageMap : LanguageMap&lt;
 496     [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;,
 497      LangToSuffixes&lt;&quot;c&quot;, [&quot;c&quot;]&gt;,
 498      ...
 499     ]&gt;;
 500 </pre>
 501 <p>For example, without those definitions the following command wouldn't work:</p>
 502 <pre class="literal-block">
 503 $ llvmc hello.cpp
 504 llvmc: Unknown suffix: cpp
 505 </pre>
 506 <p>The language map entries should be added only for tools that are
 507 linked with the root node. Since tools are not allowed to have
 508 multiple output languages, for nodes &quot;inside&quot; the graph the input and
 509 output languages should match. This is enforced at compile-time.</p>
 510 </div>
 511 <div class="section">
 512 <h1><a class="toc-backref" href="#id20" id="more-advanced-topics" name="more-advanced-topics">More advanced topics</a></h1>
 513 <div class="section">
 514 <h2><a class="toc-backref" href="#id21" id="hooks-and-environment-variables" name="hooks-and-environment-variables"><span id="hooks"></span>Hooks and environment variables</a></h2>
 515 <p>Normally, LLVMC executes programs from the system <tt class="docutils literal"><span class="pre">PATH</span></tt>. Sometimes,
 516 this is not sufficient: for example, we may want to specify tool names
 517 in the configuration file. This can be achieved via the mechanism of
 518 hooks - to write your own hooks, just add their definitions to the
 519 <tt class="docutils literal"><span class="pre">PluginMain.cpp</span></tt> or drop a <tt class="docutils literal"><span class="pre">.cpp</span></tt> file into the
 520 <tt class="docutils literal"><span class="pre">$LLVMC_DIR/driver</span></tt> directory. Hooks should live in the <tt class="docutils literal"><span class="pre">hooks</span></tt>
 521 namespace and have the signature <tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::MyHookName</span>
 522 <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>
 523 <pre class="literal-block">
 524 (cmd_line &quot;$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)&quot;)
 525 </pre>
 526 <p>It is also possible to use environment variables in the same manner:</p>
 527 <pre class="literal-block">
 528 (cmd_line &quot;$ENV(VAR1)/path/to/file -o $ENV(VAR2)&quot;)
 529 </pre>
 530 <p>To change the command line string based on user-provided options use
 531 the <tt class="docutils literal"><span class="pre">case</span></tt> expression (documented <a class="reference" href="#case">above</a>):</p>
 532 <pre class="literal-block">
 533 (cmd_line
 534   (case
 535     (switch_on &quot;E&quot;),
 536        &quot;llvm-g++ -E -x c $INFILE -o $OUTFILE&quot;,
 537     (default),
 538        &quot;llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm&quot;))
 539 </pre>
 540 </div>
 541 <div class="section">
 542 <h2><a class="toc-backref" href="#id22" id="how-plugins-are-loaded" name="how-plugins-are-loaded"><span id="priorities"></span>How plugins are loaded</a></h2>
 543 <p>It is possible for LLVMC plugins to depend on each other. For example,
 544 one can create edges between nodes defined in some other plugin. To
 545 make this work, however, that plugin should be loaded first. To
 546 achieve this, the concept of plugin priority was introduced. By
 547 default, every plugin has priority zero; to specify the priority
 548 explicitly, put the following line in your plugin's TableGen file:</p>
 549 <pre class="literal-block">
 550 def Priority : PluginPriority&lt;$PRIORITY_VALUE&gt;;
 551 # Where PRIORITY_VALUE is some integer &gt; 0
 552 </pre>
 553 <p>Plugins are loaded in order of their (increasing) priority, starting
 554 with 0. Therefore, the plugin with the highest priority value will be
 555 loaded last.</p>
 556 </div>
 557 <div class="section">
 558 <h2><a class="toc-backref" href="#id23" id="debugging" name="debugging">Debugging</a></h2>
 559 <p>When writing LLVMC plugins, it can be useful to get a visual view of
 560 the resulting compilation graph. This can be achieved via the command
 561 line option <tt class="docutils literal"><span class="pre">--view-graph</span></tt>. This command assumes that Graphviz <a class="footnote-reference" href="#id8" id="id5" name="id5">[2]</a> and
 562 Ghostview <a class="footnote-reference" href="#id9" id="id6" name="id6">[3]</a> are installed. There is also a <tt class="docutils literal"><span class="pre">--dump-graph</span></tt> option that
 563 creates a Graphviz source file(<tt class="docutils literal"><span class="pre">compilation-graph.dot</span></tt>) in the
 564 current directory.</p>
 565 </div>
 566 </div>
 567 <div class="section">
 568 <h1><a class="toc-backref" href="#id24" id="references" name="references">References</a></h1>
 569 <table class="docutils footnote" frame="void" id="id7" rules="none">
 570 <colgroup><col class="label" /><col /></colgroup>
 571 <tbody valign="top">
 572 <tr><td class="label"><a class="fn-backref" href="#id1" name="id7">[1]</a></td><td>TableGen Fundamentals
 573 <a class="reference" href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html</a></td></tr>
 574 </tbody>
 575 </table>
 576 <table class="docutils footnote" frame="void" id="id8" rules="none">
 577 <colgroup><col class="label" /><col /></colgroup>
 578 <tbody valign="top">
 579 <tr><td class="label"><a class="fn-backref" href="#id5" name="id8">[2]</a></td><td>Graphviz
 580 <a class="reference" href="http://www.graphviz.org/">http://www.graphviz.org/</a></td></tr>
 581 </tbody>
 582 </table>
 583 <table class="docutils footnote" frame="void" id="id9" rules="none">
 584 <colgroup><col class="label" /><col /></colgroup>
 585 <tbody valign="top">
 586 <tr><td class="label"><a class="fn-backref" href="#id6" name="id9">[3]</a></td><td>Ghostview
 587 <a class="reference" href="http://pages.cs.wisc.edu/~ghost/">http://pages.cs.wisc.edu/~ghost/</a></td></tr>
 588 </tbody>
 589 </table>
 590 <hr />
 591 <address>
 592   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
 593   alt="Valid CSS" /></a>
 594   <a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10-blue"
 595   alt="Valid XHTML 1.0 Transitional"/></a>
 596
 597   <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
 598   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
 599
 600   Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
 601 </address>
 602 </div>
 603 </div>
 604 </body>
 605 </html>