<p>Because LLVMC employs <aclass="reference external"href="http://llvm.org/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> vs. <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>
<p>By default, LLVMC uses <ttclass="docutils literal"><spanclass="pre">llvm-gcc</span></tt> to compile the source code. It is also
possible to choose the <ttclass="docutils literal"><spanclass="pre">clang</span></tt> compiler with the <ttclass="docutils literal"><spanclass="pre">-clang</span></tt> option.</p>
<li><ttclass="docutils literal"><spanclass="pre">--save-temps</span></tt> - Write temporary files to the current directory and do not
delete them on exit. This option can also take an argument: the
<ttclass="docutils literal"><spanclass="pre">--save-temps=obj</span></tt> switch will write files into the directory specified with
the <ttclass="docutils literal"><spanclass="pre">-o</span></tt> option. The <ttclass="docutils literal"><spanclass="pre">--save-temps=cwd</span></tt> and <ttclass="docutils literal"><spanclass="pre">--save-temps</span></tt> switches are
<li><ttclass="docutils literal"><spanclass="pre">--temp-dir</span><spanclass="pre">DIRECTORY</span></tt> - Store temporary files in the given directory. This
directory is deleted on exit unless <ttclass="docutils literal"><spanclass="pre">--save-temps</span></tt> is specified. If
<ttclass="docutils literal"><spanclass="pre">--save-temps=obj</span></tt> is also specified, <ttclass="docutils literal"><spanclass="pre">--temp-dir</span></tt> is given the
<li><ttclass="docutils literal"><spanclass="pre">--view-graph</span></tt> - Show a graphical representation of the compilation graph
and exit. 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 LLVMC plugins.</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 Graphviz format (identical
to the file used by the <ttclass="docutils literal"><spanclass="pre">--view-graph</span></tt> option). The <ttclass="docutils literal"><spanclass="pre">-o</span></tt> option can be
used to set the output file name. Hidden option, useful for debugging LLVMC
<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
<p>By default, the <ttclass="docutils literal"><spanclass="pre">llvmc</span></tt> executable consists of a driver core plus several
statically linked plugins (<ttclass="docutils literal"><spanclass="pre">Base</span></tt> and <ttclass="docutils literal"><spanclass="pre">Clang</span></tt> at the moment). You can
produce a standalone LLVMC-based driver executable by linking the core with your
own plugins. The recommended way to do this is by starting with the provided
<ttclass="docutils literal"><spanclass="pre">Skeleton</span></tt> example (<ttclass="docutils literal"><spanclass="pre">$LLVMC_DIR/example/Skeleton</span></tt>):</p>
<preclass="literal-block">
$ cd $LLVMC_DIR/example/
$ cp -r Skeleton mydriver
$ cd mydriver
$ vim Makefile
[...]
$ make
</pre>
<p>If you're compiling LLVM with different source and object directories, then you
must perform the following additional steps before running <ttclass="docutils literal"><spanclass="pre">make</span></tt>:</p>
<preclass="literal-block">
# LLVMC_SRC_DIR = $LLVM_SRC_DIR/tools/llvmc/
# LLVMC_OBJ_DIR = $LLVM_OBJ_DIR/tools/llvmc/
$ cp $LLVMC_SRC_DIR/example/mydriver/Makefile \
$LLVMC_OBJ_DIR/example/mydriver/
$ cd $LLVMC_OBJ_DIR/example/mydriver
$ make
</pre>
<p>Another way to do the same thing is by using the following command:</p>
<preclass="literal-block">
$ cd $LLVMC_DIR
$ make LLVMC_BUILTIN_PLUGINS=MyPlugin LLVMC_BASED_DRIVER_NAME=mydriver
<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">switch_option</span></tt> - a simple boolean switch without arguments, for example
<ttclass="docutils literal"><spanclass="pre">-O2</span></tt> or <ttclass="docutils literal"><spanclass="pre">-time</span></tt>. At most one occurrence is allowed.</li>
<li><ttclass="docutils literal"><spanclass="pre">parameter_option</span></tt> - option that takes one argument, for example
<ttclass="docutils literal"><spanclass="pre">-std=c99</span></tt>. It is also allowed to use spaces instead of the equality
sign: <ttclass="docutils literal"><spanclass="pre">-std</span><spanclass="pre">c99</span></tt>. At most one occurrence is allowed.</li>
<li><ttclass="docutils literal"><spanclass="pre">parameter_list_option</span></tt> - same as the above, but more than one option
<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 interpreted as option value). At most one occurrence is
<li><ttclass="docutils literal"><spanclass="pre">help</span></tt> - help string associated with this option. Used for <ttclass="docutils literal"><spanclass="pre">--help</span></tt>
output.</li>
<li><ttclass="docutils literal"><spanclass="pre">required</span></tt> - this option must be specified exactly once (or, in case of
the list options without the <ttclass="docutils literal"><spanclass="pre">multi_val</span></tt> property, at least
once). Incompatible with <ttclass="docutils literal"><spanclass="pre">zero_or_one</span></tt> and <ttclass="docutils literal"><spanclass="pre">one_or_more</span></tt>.</li>
<li><ttclass="docutils literal"><spanclass="pre">one_or_more</span></tt> - the option must be specified at least one time. Useful
only for list options in conjunction with <ttclass="docutils literal"><spanclass="pre">multi_val</span></tt>; for ordinary lists
it is synonymous with <ttclass="docutils literal"><spanclass="pre">required</span></tt>. Incompatible with <ttclass="docutils literal"><spanclass="pre">required</span></tt> and
<li><ttclass="docutils literal"><spanclass="pre">hidden</span></tt> - the description of this option will not appear in
the <ttclass="docutils literal"><spanclass="pre">--help</span></tt> output (but will 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 will not be mentioned in any help
<li><ttclass="docutils literal"><spanclass="pre">multi_val</span><spanclass="pre">n</span></tt> - this option takes <em>n</em> arguments (can be useful in some
special cases). Usage example: <ttclass="docutils literal"><spanclass="pre">(parameter_list_option</span><spanclass="pre">"foo",</span><spanclass="pre">(multi_val</span>
this attribute; you can, however, use the <ttclass="docutils literal"><spanclass="pre">one_or_more</span></tt>, <ttclass="docutils literal"><spanclass="pre">optional</span></tt>
parameter), or a boolean (if it is a switch; as in C++, boolean constants
are called <ttclass="docutils literal"><spanclass="pre">true</span></tt> and <ttclass="docutils literal"><spanclass="pre">false</span></tt>). List options can't have <ttclass="docutils literal"><spanclass="pre">init</span></tt>
<li><ttclass="docutils literal"><spanclass="pre">extern</span></tt> - this option is defined in some other plugin, see <aclass="reference internal"href="#extern">below</a>.</li>
<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">switch_on</span></tt> - Returns true if a given command-line switch is provided by
the user. Can be given a list as argument, in that case <ttclass="docutils literal"><spanclass="pre">(switch_on</span><spanclass="pre">["foo",</span>
<spanclass="pre">"bar",</span><spanclass="pre">"baz"])</span></tt> is equivalent to <ttclass="docutils literal"><spanclass="pre">(and</span><spanclass="pre">(switch_on</span><spanclass="pre">"foo"),</span><spanclass="pre">(switch_on</span>
<li><ttclass="docutils literal"><spanclass="pre">any_switch_on</span></tt> - Given a list of switch options, returns true if any of
the switches is turned on.
Example: <ttclass="docutils literal"><spanclass="pre">(any_switch_on</span><spanclass="pre">["foo",</span><spanclass="pre">"bar",</span><spanclass="pre">"baz"])</span></tt> is equivalent to <ttclass="docutils literal"><spanclass="pre">(or</span>
<li><ttclass="docutils literal"><spanclass="pre">in_language</span></tt> - Evaluates to true if the input file language is equal to
the argument. At the moment works only with <ttclass="docutils literal"><spanclass="pre">cmd_line</span></tt> and <ttclass="docutils literal"><spanclass="pre">actions</span></tt> (on
<li><ttclass="docutils literal"><spanclass="pre">any_not_empty</span></tt> - Returns true if <ttclass="docutils literal"><spanclass="pre">not_empty</span></tt> returns true for any of
the options in the list.
Example: <ttclass="docutils literal"><spanclass="pre">(any_not_empty</span><spanclass="pre">["foo",</span><spanclass="pre">"bar",</span><spanclass="pre">"baz"])</span></tt> is equivalent to <ttclass="docutils literal"><spanclass="pre">(or</span>
<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. Can be given a list as argument.</li>
<li><ttclass="docutils literal"><spanclass="pre">any_not_empty</span></tt> - Returns true if <ttclass="docutils literal"><spanclass="pre">not_empty</span></tt> returns true for any of
the options in the list.
Example: <ttclass="docutils literal"><spanclass="pre">(any_empty</span><spanclass="pre">["foo",</span><spanclass="pre">"bar",</span><spanclass="pre">"baz"])</span></tt> is equivalent to <ttclass="docutils literal"><spanclass="pre">(not</span><spanclass="pre">(and</span>
<li><ttclass="docutils literal"><spanclass="pre">multiple_input_files</span></tt> - Equivalent to <ttclass="docutils literal"><spanclass="pre">(not</span><spanclass="pre">(single_input_file))</span></tt> (the
case of zero input files is considered an error).</li>
<li><ttclass="docutils literal"><spanclass="pre">and</span></tt> - A standard binary 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> - A binary logical combinator that returns true iff any of its
<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
<p>Here, <ttclass="docutils literal"><spanclass="pre">OptionPreprocessor</span></tt> is used to unset all spurious <ttclass="docutils literal"><spanclass="pre">-O</span></tt> options so
that they are not forwarded to the compiler. If no optimization options are
specified, <ttclass="docutils literal"><spanclass="pre">-O2</span></tt> is enabled.</p>
<p><ttclass="docutils literal"><spanclass="pre">OptionPreprocessor</span></tt> is basically a single big <ttclass="docutils literal"><spanclass="pre">case</span></tt> expression, which is
evaluated only once right after the plugin is loaded. The only allowed actions
in <ttclass="docutils literal"><spanclass="pre">OptionPreprocessor</span></tt> are <ttclass="docutils literal"><spanclass="pre">error</span></tt>, <ttclass="docutils literal"><spanclass="pre">warning</span></tt> and two special actions:
<ttclass="docutils literal"><spanclass="pre">unset_option</span></tt> and <ttclass="docutils literal"><spanclass="pre">set_option</span></tt>. As their names suggest, they can be used to
set or unset a given option. To set a parameter option with <ttclass="docutils literal"><spanclass="pre">set_option</span></tt>, use
the two-argument form: <ttclass="docutils literal"><spanclass="pre">(set_option</span><spanclass="pre">"parameter",</span><spanclass="pre">"value")</span></tt>. For convenience,
<ttclass="docutils literal"><spanclass="pre">set_option</span></tt> and <ttclass="docutils literal"><spanclass="pre">unset_option</span></tt> also work on lists (that is, instead of
<ttclass="docutils literal"><spanclass="pre">[(unset_option</span><spanclass="pre">"A"),</span><spanclass="pre">(unset_option</span><spanclass="pre">"B")]</span></tt> you can use <ttclass="docutils literal"><spanclass="pre">(unset_option</span><spanclass="pre">["A",</span>
this is not sufficient: for example, we may want to specify tool paths
or names in the configuration file. This can be easily achieved via
the hooks mechanism. 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
your plugin 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">([const</span><spanclass="pre">char*</span>
<spanclass="pre">Arg0</span><spanclass="pre">[</span><spanclass="pre">const</span><spanclass="pre">char*</span><spanclass="pre">Arg2</span><spanclass="pre">[,</span><spanclass="pre">...]]])</span></tt>. They can be used from the
line option <ttclass="docutils literal"><spanclass="pre">--view-graph</span></tt>. This command assumes that <aclass="reference external"href="http://www.graphviz.org/">Graphviz</a> and
<aclass="reference external"href="http://pages.cs.wisc.edu/~ghost/">Ghostview</a> are installed. There is also a <ttclass="docutils literal"><spanclass="pre">--write-graph</span></tt> option that
<p>Another useful <ttclass="docutils literal"><spanclass="pre">llvmc</span></tt> 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
