<p>Because LLVMC employs <aclass="reference"href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">TableGen</a> as its configuration language, you
<p>One nice feature of LLVMC is that one doesn't have to distinguish
between different compilers for different languages (think <ttclass="docutils literal"><spanclass="pre">g++</span></tt> and
<ttclass="docutils literal"><spanclass="pre">gcc</span></tt>) - the right toolchain is chosen automatically based on input
language names (which are, in turn, determined from file
extensions). If you want to force files ending with ".c" to compile as
C++, use the <ttclass="docutils literal"><spanclass="pre">-x</span></tt> option, just like you would do it with <ttclass="docutils literal"><spanclass="pre">gcc</span></tt>:</p>
graph. Requires that you have <ttclass="docutils literal"><spanclass="pre">dot</span></tt> and <ttclass="docutils literal"><spanclass="pre">gv</span></tt> programs
installed. Hidden option, useful for debugging.</li>
<li><ttclass="docutils literal"><spanclass="pre">--write-graph</span></tt> - Write a <ttclass="docutils literal"><spanclass="pre">compilation-graph.dot</span></tt> file in the
current directory with the compilation graph description in the
Graphviz format. Hidden option, useful for debugging.</li>
<li><ttclass="docutils literal"><spanclass="pre">--save-temps</span></tt> - Write temporary files to the current directory
and do not delete them on exit. Hidden option, useful for debugging.</li>
<li><ttclass="docutils literal"><spanclass="pre">--help</span></tt>, <ttclass="docutils literal"><spanclass="pre">--help-hidden</span></tt>, <ttclass="docutils literal"><spanclass="pre">--version</span></tt> - These options have
<h1><aclass="toc-backref"href="#id8"id="customizing-llvmc-the-compilation-graph"name="customizing-llvmc-the-compilation-graph">Customizing LLVMC: the compilation graph</a></h1>
<p>The default edges are assigned a weight of 1, and optional edges get a
weight of 0 + 2*N where N is the number of tests that evaluated to
true in the <ttclass="docutils literal"><spanclass="pre">case</span></tt> expression. It is also possible to provide an
integer parameter to <ttclass="docutils literal"><spanclass="pre">inc_weight</span></tt> and <ttclass="docutils literal"><spanclass="pre">dec_weight</span></tt> - in this case,
the weight is increased (or decreased) by the provided value instead
of the default 2. It is also possible to change the default weight of
an optional edge by using the <ttclass="docutils literal"><spanclass="pre">default</span></tt> clause of the <ttclass="docutils literal"><spanclass="pre">case</span></tt>
debugging), run <ttclass="docutils literal"><spanclass="pre">llvmc</span><spanclass="pre">--view-graph</span></tt>. You will need <ttclass="docutils literal"><spanclass="pre">dot</span></tt> and
<li><ttclass="docutils literal"><spanclass="pre">prefix_option</span></tt> - same as the parameter_option, but the option
name and argument do not have to be separated. Example:
<ttclass="docutils literal"><spanclass="pre">-ofile</span></tt>. This can be also specified as <ttclass="docutils literal"><spanclass="pre">-o</span><spanclass="pre">file</span></tt>; however,
<ttclass="docutils literal"><spanclass="pre">-o=file</span></tt> will be parsed incorrectly (<ttclass="docutils literal"><spanclass="pre">=file</span></tt> will be
<li><ttclass="docutils literal"><spanclass="pre">hidden</span></tt> - this option should not appear in the <ttclass="docutils literal"><spanclass="pre">--help</span></tt>
output (but should appear in the <ttclass="docutils literal"><spanclass="pre">--help-hidden</span></tt> output).</li>
<li><ttclass="docutils literal"><spanclass="pre">really_hidden</span></tt> - the option should not appear in any help
output.</li>
<li><ttclass="docutils literal"><spanclass="pre">extern</span></tt> - this option is defined in some other plugin, see below.</li>
<p>Sometimes, when linking several plugins together, one plugin needs to
access options defined in some other plugin. Because of the way
options are implemented, such options should be marked as
<ttclass="docutils literal"><spanclass="pre">extern</span></tt>. This is what the <ttclass="docutils literal"><spanclass="pre">extern</span></tt> option property is
<p>The 'case' construct is the main means by which programmability is
achieved in LLVMC. It can be used to calculate edge weights, program
actions and modify the shell commands to be executed. The 'case'
expression is designed after the similarly-named construct in
functional languages and takes the form <ttclass="docutils literal"><spanclass="pre">(case</span><spanclass="pre">(test_1),</span><spanclass="pre">statement_1,</span>
<spanclass="pre">(test_2),</span><spanclass="pre">statement_2,</span><spanclass="pre">...</span><spanclass="pre">(test_N),</span><spanclass="pre">statement_N)</span></tt>. The statements
are evaluated only if the corresponding tests evaluate to true.</p>
<p>Note the slight difference in 'case' expression handling in contexts
of edge weights and command line specification - in the second example
the value of the <ttclass="docutils literal"><spanclass="pre">"B"</span></tt> switch is never checked when switch <ttclass="docutils literal"><spanclass="pre">"A"</span></tt> is
enabled, and the whole expression always evaluates to <ttclass="docutils literal"><spanclass="pre">"cmdline1"</span></tt> in
that case.</p>
<p>Case expressions can also be nested, i.e. the following is legal:</p>
<li><ttclass="docutils literal"><spanclass="pre">empty</span></tt> - The opposite of <ttclass="docutils literal"><spanclass="pre">not_empty</span></tt>. Equivalent to <ttclass="docutils literal"><spanclass="pre">(not</span><spanclass="pre">(not_empty</span>
<spanclass="pre">X))</span></tt>. Provided for convenience.</li>
<li><ttclass="docutils literal"><spanclass="pre">default</span></tt> - Always evaluates to true. Should always be the last
test in the <ttclass="docutils literal"><spanclass="pre">case</span></tt> expression.</li>
<li><ttclass="docutils literal"><spanclass="pre">and</span></tt> - A standard logical combinator that returns true iff all
of its arguments return true. Used like this: <ttclass="docutils literal"><spanclass="pre">(and</span><spanclass="pre">(test1),</span>
<spanclass="pre">(test2),</span><spanclass="pre">...</span><spanclass="pre">(testN))</span></tt>. Nesting of <ttclass="docutils literal"><spanclass="pre">and</span></tt> and <ttclass="docutils literal"><spanclass="pre">or</span></tt> is allowed,
but not encouraged.</li>
<li><ttclass="docutils literal"><spanclass="pre">or</span></tt> - Another logical combinator that returns true only if any
one of its arguments returns true. Example: <ttclass="docutils literal"><spanclass="pre">(or</span><spanclass="pre">(test1),</span>
<p>This defines a new tool called <ttclass="docutils literal"><spanclass="pre">llvm_gcc_cpp</span></tt>, which is an alias for
<ttclass="docutils literal"><spanclass="pre">llvm-g++</span></tt>. As you can see, a tool definition is just a list of
properties; most of them should be self-explanatory. The <ttclass="docutils literal"><spanclass="pre">sink</span></tt>
property means that this tool should be passed all command-line
options that aren't mentioned in the option list.</p>
<p>The complete list of all currently implemented tool properties follows.</p>
<ulclass="simple">
<li>Possible tool properties:<ul>
<li><ttclass="docutils literal"><spanclass="pre">in_language</span></tt> - input language name. Can be either a string or a
list, in case the tool supports multiple input languages.</li>
<li><ttclass="docutils literal"><spanclass="pre">out_language</span></tt> - output language name. Tools are not allowed to
have multiple output languages.</li>
<li><ttclass="docutils literal"><spanclass="pre">output_suffix</span></tt> - output file suffix. Can also be changed
dynamically, see documentation on actions.</li>
<li><ttclass="docutils literal"><spanclass="pre">cmd_line</span></tt> - the actual command used to run the tool. You can
use <ttclass="docutils literal"><spanclass="pre">$INFILE</span></tt> and <ttclass="docutils literal"><spanclass="pre">$OUTFILE</span></tt> variables, output redirection
with <ttclass="docutils literal"><spanclass="pre">></span></tt>, hook invocations (<ttclass="docutils literal"><spanclass="pre">$CALL</span></tt>), environment variables
(via <ttclass="docutils literal"><spanclass="pre">$ENV</span></tt>) and the <ttclass="docutils literal"><spanclass="pre">case</span></tt> construct.</li>
<li><ttclass="docutils literal"><spanclass="pre">join</span></tt> - this tool is a "join node" in the graph, i.e. it gets a
list of input files and joins them together. Used for linkers.</li>
<li><ttclass="docutils literal"><spanclass="pre">sink</span></tt> - all command-line options that are not handled by other
tools are passed to this tool.</li>
<li><ttclass="docutils literal"><spanclass="pre">actions</span></tt> - A single big <ttclass="docutils literal"><spanclass="pre">case</span></tt> expression that specifies how
this tool reacts on command-line options (described in more detail
<h2><aclass="toc-backref"href="#id16"id="hooks-and-environment-variables"name="hooks-and-environment-variables"><spanid="hooks"></span>Hooks and environment variables</a></h2>
<p>Normally, LLVMC executes programs from the system <ttclass="docutils literal"><spanclass="pre">PATH</span></tt>. Sometimes,
this is not sufficient: for example, we may want to specify tool names
in the configuration file. This can be achieved via the mechanism of
hooks - to write your own hooks, just add their definitions to the
<ttclass="docutils literal"><spanclass="pre">PluginMain.cpp</span></tt> or drop a <ttclass="docutils literal"><spanclass="pre">.cpp</span></tt> file into the
<ttclass="docutils literal"><spanclass="pre">$LLVMC_DIR/driver</span></tt> directory. Hooks should live in the <ttclass="docutils literal"><spanclass="pre">hooks</span></tt>
namespace and have the signature <ttclass="docutils literal"><spanclass="pre">std::string</span><spanclass="pre">hooks::MyHookName</span>
<spanclass="pre">(void)</span></tt>. They can be used from the <ttclass="docutils literal"><spanclass="pre">cmd_line</span></tt> tool property:</p>
<h2><aclass="toc-backref"href="#id17"id="how-plugins-are-loaded"name="how-plugins-are-loaded"><spanid="priorities"></span>How plugins are loaded</a></h2>
line option <ttclass="docutils literal"><spanclass="pre">--view-graph</span></tt>. This command assumes that <aclass="reference"href="http://www.graphviz.org/">Graphviz</a> and
<aclass="reference"href="http://pages.cs.wisc.edu/~ghost/">Ghostview</a> are installed. There is also a <ttclass="docutils literal"><spanclass="pre">--dump-graph</span></tt> option that
creates a Graphviz source file (<ttclass="docutils literal"><spanclass="pre">compilation-graph.dot</span></tt>) in the
<p>Another useful option is <ttclass="docutils literal"><spanclass="pre">--check-graph</span></tt>. It checks the compilation
graph for common errors like mismatched output/input language names,
multiple default edges and cycles. These checks can't be performed at
compile-time because the plugins can load code dynamically. When
invoked with <ttclass="docutils literal"><spanclass="pre">--check-graph</span></tt>, <ttclass="docutils literal"><spanclass="pre">llvmc</span></tt> doesn't perform any
compilation tasks and returns the number of encountered errors as its
