rename indbr -> indirectbr to appease the residents of #llvm.
[oota-llvm.git] / docs / CompilerDriver.html
index 9d87c05081c6cf9653520e56451b39d086b6b554..761d6ee6810db1da1eaff7e5a4d9988e045278b5 100644 (file)
@@ -3,43 +3,50 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title>Customizing LLVMC: Reference Manual</title>
 <link rel="stylesheet" href="llvm.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="customizing-llvmc-reference-manual">
 <h1 class="title">Customizing LLVMC: Reference Manual</h1>
-<div class="contents topic">
-<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
+
+<!-- This file was automatically generated by rst2html.
+Please do not edit directly!
+The ReST source lives in the directory 'tools/llvmc/doc'. -->
+<div class="contents topic" id="contents">
+<p class="topic-title first">Contents</p>
 <ul class="simple">
-<li><a class="reference" href="#introduction" id="id4" name="id4">Introduction</a></li>
-<li><a class="reference" href="#compiling-with-llvmc" id="id5" name="id5">Compiling with LLVMC</a></li>
-<li><a class="reference" href="#predefined-options" id="id6" name="id6">Predefined options</a></li>
-<li><a class="reference" href="#compiling-llvmc-plugins" id="id7" name="id7">Compiling LLVMC plugins</a></li>
-<li><a class="reference" href="#customizing-llvmc-the-compilation-graph" id="id8" name="id8">Customizing LLVMC: the compilation graph</a></li>
-<li><a class="reference" href="#describing-options" id="id9" name="id9">Describing options</a><ul>
-<li><a class="reference" href="#external-options" id="id10" name="id10">External options</a></li>
+<li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li>
+<li><a class="reference internal" href="#compiling-with-llvmc" id="id5">Compiling with LLVMC</a></li>
+<li><a class="reference internal" href="#predefined-options" id="id6">Predefined options</a></li>
+<li><a class="reference internal" href="#compiling-llvmc-plugins" id="id7">Compiling LLVMC plugins</a></li>
+<li><a class="reference internal" href="#compiling-standalone-llvmc-based-drivers" id="id8">Compiling standalone LLVMC-based drivers</a></li>
+<li><a class="reference internal" href="#customizing-llvmc-the-compilation-graph" id="id9">Customizing LLVMC: the compilation graph</a></li>
+<li><a class="reference internal" href="#describing-options" id="id10">Describing options</a><ul>
+<li><a class="reference internal" href="#external-options" id="id11">External options</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#conditional-evaluation" id="id11" name="id11">Conditional evaluation</a></li>
-<li><a class="reference" href="#writing-a-tool-description" id="id12" name="id12">Writing a tool description</a><ul>
-<li><a class="reference" href="#actions" id="id13" name="id13">Actions</a></li>
+<li><a class="reference internal" href="#conditional-evaluation" id="id12">Conditional evaluation</a></li>
+<li><a class="reference internal" href="#writing-a-tool-description" id="id13">Writing a tool description</a><ul>
+<li><a class="reference internal" href="#actions" id="id14">Actions</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#language-map" id="id14" name="id14">Language map</a></li>
-<li><a class="reference" href="#more-advanced-topics" id="id15" name="id15">More advanced topics</a><ul>
-<li><a class="reference" href="#hooks-and-environment-variables" id="id16" name="id16">Hooks and environment variables</a></li>
-<li><a class="reference" href="#how-plugins-are-loaded" id="id17" name="id17">How plugins are loaded</a></li>
-<li><a class="reference" href="#debugging" id="id18" name="id18">Debugging</a></li>
+<li><a class="reference internal" href="#language-map" id="id15">Language map</a></li>
+<li><a class="reference internal" href="#option-preprocessor" id="id16">Option preprocessor</a></li>
+<li><a class="reference internal" href="#more-advanced-topics" id="id17">More advanced topics</a><ul>
+<li><a class="reference internal" href="#hooks-and-environment-variables" id="id18">Hooks and environment variables</a></li>
+<li><a class="reference internal" href="#how-plugins-are-loaded" id="id19">How plugins are loaded</a></li>
+<li><a class="reference internal" href="#debugging" id="id20">Debugging</a></li>
+<li><a class="reference internal" href="#conditioning-on-the-executable-name" id="id21">Conditioning on the executable name</a></li>
 </ul>
 </li>
 </ul>
 </div>
 <div class="doc_author">
 <p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p>
-</div><div class="section">
-<h1><a class="toc-backref" href="#id4" id="introduction" name="introduction">Introduction</a></h1>
+</div><div class="section" id="introduction">
+<h1><a class="toc-backref" href="#id4">Introduction</a></h1>
 <p>LLVMC is a generic compiler driver, designed to be customizable and
 extensible. It plays the same role for LLVM as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program
 does for GCC - LLVMC's job is essentially to transform a set of input
@@ -52,11 +59,11 @@ abstract graph. The structure of this graph is completely determined
 by plugins, which can be either statically or dynamically linked. This
 makes it possible to easily adapt LLVMC for other purposes - for
 example, as a build tool for game resources.</p>
-<p>Because LLVMC employs <a class="reference" href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">TableGen</a> as its configuration language, you
+<p>Because LLVMC employs <a class="reference external" href="http://llvm.org/docs/TableGenFundamentals.html">TableGen</a> as its configuration language, you
 need to be familiar with it to customize LLVMC.</p>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id5" id="compiling-with-llvmc" name="compiling-with-llvmc">Compiling with LLVMC</a></h1>
+<div class="section" id="compiling-with-llvmc">
+<h1><a class="toc-backref" href="#id5">Compiling with LLVMC</a></h1>
 <p>LLVMC tries hard to be as compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as possible,
 although there are some small differences. Most of the time, however,
 you shouldn't be able to notice them:</p>
@@ -66,12 +73,12 @@ $ llvmc -O3 -Wall hello.cpp
 $ ./a.out
 hello
 </pre>
-<p>One nice feature of LLVMC is that one doesn't have to distinguish
-between different compilers for different languages (think <tt class="docutils literal"><span class="pre">g++</span></tt> and
-<tt class="docutils literal"><span class="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 &quot;.c&quot; to compile as
-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>
+<p>One nice feature of LLVMC is that one doesn't have to distinguish between
+different compilers for different languages (think <tt class="docutils literal"><span class="pre">g++</span></tt> vs.  <tt class="docutils literal"><span class="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 &quot;.c&quot; to compile as 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>
 <pre class="literal-block">
 $ # hello.c is really a C++ file
 $ llvmc -x c++ hello.c
@@ -89,12 +96,11 @@ $ llvmc --linker=c++ hello.o
 $ ./a.out
 hello
 </pre>
-<p>By default, LLVMC uses <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> to compile the source code. It is
-also possible to choose the work-in-progress <tt class="docutils literal"><span class="pre">clang</span></tt> compiler with
-the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p>
+<p>By default, LLVMC uses <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> to compile the source code. It is also
+possible to choose the <tt class="docutils literal"><span class="pre">clang</span></tt> compiler with the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id6" id="predefined-options" name="predefined-options">Predefined options</a></h1>
+<div class="section" id="predefined-options">
+<h1><a class="toc-backref" href="#id6">Predefined options</a></h1>
 <p>LLVMC has some built-in options that can't be overridden in the
 configuration libraries:</p>
 <ul class="simple">
@@ -104,20 +110,34 @@ until the next -x option.</li>
 <li><tt class="docutils literal"><span class="pre">-load</span> <span class="pre">PLUGIN_NAME</span></tt> - Load the specified plugin DLL. Example:
 <tt class="docutils literal"><span class="pre">-load</span> <span class="pre">$LLVM_DIR/Release/lib/LLVMCSimple.so</span></tt>.</li>
 <li><tt class="docutils literal"><span class="pre">-v</span></tt> - Enable verbose mode, i.e. print out all executed commands.</li>
-<li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation
-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
-installed. Hidden option, useful for debugging.</li>
-<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
-current directory with the compilation graph description in the
-Graphviz format. Hidden option, useful for debugging.</li>
-<li><tt class="docutils literal"><span class="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><tt class="docutils literal"><span class="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
+<tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> switch will write files into the directory specified with
+the <tt class="docutils literal"><span class="pre">-o</span></tt> option. The <tt class="docutils literal"><span class="pre">--save-temps=cwd</span></tt> and <tt class="docutils literal"><span class="pre">--save-temps</span></tt> switches are
+both synonyms for the default behaviour.</li>
+<li><tt class="docutils literal"><span class="pre">--temp-dir</span> <span class="pre">DIRECTORY</span></tt> - Store temporary files in the given directory. This
+directory is deleted on exit unless <tt class="docutils literal"><span class="pre">--save-temps</span></tt> is specified. If
+<tt class="docutils literal"><span class="pre">--save-temps=obj</span></tt> is also specified, <tt class="docutils literal"><span class="pre">--temp-dir</span></tt> is given the
+precedence.</li>
+<li><tt class="docutils literal"><span class="pre">--check-graph</span></tt> - Check the compilation for common errors like mismatched
+output/input language names, multiple default edges and cycles. Because of
+plugins, these checks can't be performed at compile-time. Exit with code zero
+if no errors were found, and return the number of found errors
+otherwise. Hidden option, useful for debugging LLVMC plugins.</li>
+<li><tt class="docutils literal"><span class="pre">--view-graph</span></tt> - Show a graphical representation of the compilation graph
+and exit. 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 installed. Hidden
+option, useful for debugging LLVMC plugins.</li>
+<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 current
+directory with the compilation graph description in Graphviz format (identical
+to the file used by the <tt class="docutils literal"><span class="pre">--view-graph</span></tt> option). The <tt class="docutils literal"><span class="pre">-o</span></tt> option can be
+used to set the output file name. Hidden option, useful for debugging LLVMC
+plugins.</li>
 <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
 their standard meaning.</li>
 </ul>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id7" id="compiling-llvmc-plugins" name="compiling-llvmc-plugins">Compiling LLVMC plugins</a></h1>
+<div class="section" id="compiling-llvmc-plugins">
+<h1><a class="toc-backref" href="#id7">Compiling LLVMC plugins</a></h1>
 <p>It's easiest to start working on your own LLVMC plugin by copying the
 skeleton project which lives under <tt class="docutils literal"><span class="pre">$LLVMC_DIR/plugins/Simple</span></tt>:</p>
 <pre class="literal-block">
@@ -132,7 +152,7 @@ counting the build script). <tt class="docutils literal"><span class="pre">Simpl
 description of the compilation graph; its format is documented in the
 following sections. <tt class="docutils literal"><span class="pre">PluginMain.cpp</span></tt> is just a helper file used to
 compile the auto-generated C++ code produced from TableGen source. It
-can also contain hook definitions (see <a class="reference" href="#hooks">below</a>).</p>
+can also contain hook definitions (see <a class="reference internal" href="#hooks">below</a>).</p>
 <p>The first thing that you should do is to change the <tt class="docutils literal"><span class="pre">LLVMC_PLUGIN</span></tt>
 variable in the <tt class="docutils literal"><span class="pre">Makefile</span></tt> to avoid conflicts (since this variable
 is used to name the resulting library):</p>
@@ -144,33 +164,58 @@ generic:</p>
 <pre class="literal-block">
 $ mv Simple.td MyPlugin.td
 </pre>
-<p>Note that the plugin source directory must be placed under
-<tt class="docutils literal"><span class="pre">$LLVMC_DIR/plugins</span></tt> to make use of the existing build
-infrastructure. To build a version of the LLVMC executable called
-<tt class="docutils literal"><span class="pre">mydriver</span></tt> with your plugin compiled in, use the following command:</p>
-<pre class="literal-block">
-$ cd $LLVMC_DIR
-$ make BUILTIN_PLUGINS=MyPlugin DRIVER_NAME=mydriver
-</pre>
 <p>To build your plugin as a dynamic library, just <tt class="docutils literal"><span class="pre">cd</span></tt> to its source
 directory and run <tt class="docutils literal"><span class="pre">make</span></tt>. The resulting file will be called
-<tt class="docutils literal"><span class="pre">LLVMC$(LLVMC_PLUGIN).$(DLL_EXTENSION)</span></tt> (in our case,
-<tt class="docutils literal"><span class="pre">LLVMCMyPlugin.so</span></tt>). This library can be then loaded in with the
+<tt class="docutils literal"><span class="pre">plugin_llvmc_$(LLVMC_PLUGIN).$(DLL_EXTENSION)</span></tt> (in our case,
+<tt class="docutils literal"><span class="pre">plugin_llvmc_MyPlugin.so</span></tt>). This library can be then loaded in with the
 <tt class="docutils literal"><span class="pre">-load</span></tt> option. Example:</p>
 <pre class="literal-block">
 $ cd $LLVMC_DIR/plugins/Simple
 $ make
-$ llvmc -load $LLVM_DIR/Release/lib/LLVMCSimple.so
+$ llvmc -load $LLVM_DIR/Release/lib/plugin_llvmc_Simple.so
 </pre>
+</div>
+<div class="section" id="compiling-standalone-llvmc-based-drivers">
+<h1><a class="toc-backref" href="#id8">Compiling standalone LLVMC-based drivers</a></h1>
+<p>By default, the <tt class="docutils literal"><span class="pre">llvmc</span></tt> executable consists of a driver core plus several
+statically linked plugins (<tt class="docutils literal"><span class="pre">Base</span></tt> and <tt class="docutils literal"><span class="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
+<tt class="docutils literal"><span class="pre">Skeleton</span></tt> example (<tt class="docutils literal"><span class="pre">$LLVMC_DIR/example/Skeleton</span></tt>):</p>
+<pre class="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 <tt class="docutils literal"><span class="pre">make</span></tt>:</p>
+<pre class="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>
+<pre class="literal-block">
+$ cd $LLVMC_DIR
+$ make LLVMC_BUILTIN_PLUGINS=MyPlugin LLVMC_BASED_DRIVER_NAME=mydriver
+</pre>
+<p>This works with both srcdir == objdir and srcdir != objdir, but assumes that the
+plugin source directory was placed under <tt class="docutils literal"><span class="pre">$LLVMC_DIR/plugins</span></tt>.</p>
 <p>Sometimes, you will want a 'bare-bones' version of LLVMC that has no
 built-in plugins. It can be compiled with the following command:</p>
 <pre class="literal-block">
 $ cd $LLVMC_DIR
-$ make BUILTIN_PLUGINS=&quot;&quot;
+$ make LLVMC_BUILTIN_PLUGINS=&quot;&quot;
 </pre>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id8" id="customizing-llvmc-the-compilation-graph" name="customizing-llvmc-the-compilation-graph">Customizing LLVMC: the compilation graph</a></h1>
+<div class="section" id="customizing-llvmc-the-compilation-graph">
+<h1><a class="toc-backref" href="#id9">Customizing LLVMC: the compilation graph</a></h1>
 <p>Each TableGen configuration file should include the common
 definitions:</p>
 <pre class="literal-block">
@@ -237,8 +282,8 @@ plugin priority feature described above.</p>
 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
 <tt class="docutils literal"><span class="pre">gsview</span></tt> installed for this to work properly.</p>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id9" id="describing-options" name="describing-options">Describing options</a></h1>
+<div class="section" id="describing-options">
+<h1><a class="toc-backref" href="#id10">Describing options</a></h1>
 <p>Command-line options that the plugin supports are defined by using an
 <tt class="docutils literal"><span class="pre">OptionList</span></tt>:</p>
 <pre class="literal-block">
@@ -257,42 +302,66 @@ separate option groups syntactically.</p>
 <li><p class="first">Possible option types:</p>
 <blockquote>
 <ul class="simple">
-<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>
-<li><tt class="docutils literal"><span class="pre">parameter_option</span></tt> - option that takes an argument, for example
-<tt class="docutils literal"><span class="pre">-std=c99</span></tt>;</li>
-<li><tt class="docutils literal"><span class="pre">parameter_list_option</span></tt> - same as the above, but more than one
-occurence of the option is allowed.</li>
-<li><tt class="docutils literal"><span class="pre">prefix_option</span></tt> - same as the parameter_option, but the option name
-and parameter value are not separated.</li>
-<li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one
-occurence of the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
-<li><tt class="docutils literal"><span class="pre">alias_option</span></tt> - a special option type for creating
-aliases. Unlike other option types, aliases are not allowed to
-have any properties besides the aliased option name. Usage
-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>
+<li><tt class="docutils literal"><span class="pre">switch_option</span></tt> - a simple boolean switch without arguments, for example
+<tt class="docutils literal"><span class="pre">-O2</span></tt> or <tt class="docutils literal"><span class="pre">-time</span></tt>. At most one occurrence is allowed.</li>
+<li><tt class="docutils literal"><span class="pre">parameter_option</span></tt> - option that takes one argument, for example
+<tt class="docutils literal"><span class="pre">-std=c99</span></tt>. It is also allowed to use spaces instead of the equality
+sign: <tt class="docutils literal"><span class="pre">-std</span> <span class="pre">c99</span></tt>. At most one occurrence is allowed.</li>
+<li><tt class="docutils literal"><span class="pre">parameter_list_option</span></tt> - same as the above, but more than one option
+occurence is allowed.</li>
+<li><tt class="docutils literal"><span class="pre">prefix_option</span></tt> - same as the parameter_option, but the option name and
+argument do not have to be separated. Example: <tt class="docutils literal"><span class="pre">-ofile</span></tt>. This can be also
+specified as <tt class="docutils literal"><span class="pre">-o</span> <span class="pre">file</span></tt>; however, <tt class="docutils literal"><span class="pre">-o=file</span></tt> will be parsed incorrectly
+(<tt class="docutils literal"><span class="pre">=file</span></tt> will be interpreted as option value). At most one occurrence is
+allowed.</li>
+<li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one occurence of
+the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">alias_option</span></tt> - a special option type for creating aliases. Unlike other
+option types, aliases are not allowed to have any properties besides the
+aliased option name. Usage 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>
 </ul>
 </blockquote>
 </li>
 <li><p class="first">Possible option properties:</p>
 <blockquote>
 <ul class="simple">
-<li><tt class="docutils literal"><span class="pre">help</span></tt> - help string associated with this option. Used for
-<tt class="docutils literal"><span class="pre">--help</span></tt> output.</li>
-<li><tt class="docutils literal"><span class="pre">required</span></tt> - this option is obligatory.</li>
-<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>
-output (but should appear in the <tt class="docutils literal"><span class="pre">--help-hidden</span></tt> output).</li>
-<li><tt class="docutils literal"><span class="pre">really_hidden</span></tt> - the option should not appear in any help
+<li><tt class="docutils literal"><span class="pre">help</span></tt> - help string associated with this option. Used for <tt class="docutils literal"><span class="pre">--help</span></tt>
+output.</li>
+<li><tt class="docutils literal"><span class="pre">required</span></tt> - this option must be specified exactly once (or, in case of
+the list options without the <tt class="docutils literal"><span class="pre">multi_val</span></tt> property, at least
+once). Incompatible with <tt class="docutils literal"><span class="pre">zero_or_one</span></tt> and <tt class="docutils literal"><span class="pre">one_or_more</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">one_or_more</span></tt> - the option must be specified at least one time. Useful
+only for list options in conjunction with <tt class="docutils literal"><span class="pre">multi_val</span></tt>; for ordinary lists
+it is synonymous with <tt class="docutils literal"><span class="pre">required</span></tt>. Incompatible with <tt class="docutils literal"><span class="pre">required</span></tt> and
+<tt class="docutils literal"><span class="pre">zero_or_one</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">zero_or_one</span></tt> - the option can be specified zero or one times. Useful
+only for list options in conjunction with <tt class="docutils literal"><span class="pre">multi_val</span></tt>. Incompatible with
+<tt class="docutils literal"><span class="pre">required</span></tt> and <tt class="docutils literal"><span class="pre">one_or_more</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">hidden</span></tt> - the description of this option will not appear in
+the <tt class="docutils literal"><span class="pre">--help</span></tt> output (but will appear in the <tt class="docutils literal"><span class="pre">--help-hidden</span></tt>
+output).</li>
+<li><tt class="docutils literal"><span class="pre">really_hidden</span></tt> - the option will not be mentioned in any help
 output.</li>
+<li><tt class="docutils literal"><span class="pre">multi_val</span> <span class="pre">n</span></tt> - this option takes <em>n</em> arguments (can be useful in some
+special cases). Usage example: <tt class="docutils literal"><span class="pre">(parameter_list_option</span> <span class="pre">&quot;foo&quot;,</span> <span class="pre">(multi_val</span>
+<span class="pre">3))</span></tt>; the command-line syntax is '-foo a b c'. Only list options can have
+this attribute; you can, however, use the <tt class="docutils literal"><span class="pre">one_or_more</span></tt>, <tt class="docutils literal"><span class="pre">zero_or_one</span></tt>
+and <tt class="docutils literal"><span class="pre">required</span></tt> properties.</li>
+<li><tt class="docutils literal"><span class="pre">init</span></tt> - this option has a default value, either a string (if it is a
+parameter), or a boolean (if it is a switch; boolean constants are called
+<tt class="docutils literal"><span class="pre">true</span></tt> and <tt class="docutils literal"><span class="pre">false</span></tt>). List options can't have this attribute. Usage
+examples: <tt class="docutils literal"><span class="pre">(switch_option</span> <span class="pre">&quot;foo&quot;,</span> <span class="pre">(init</span> <span class="pre">true))</span></tt>; <tt class="docutils literal"><span class="pre">(prefix_option</span> <span class="pre">&quot;bar&quot;,</span>
+<span class="pre">(init</span> <span class="pre">&quot;baz&quot;))</span></tt>.</li>
 <li><tt class="docutils literal"><span class="pre">extern</span></tt> - this option is defined in some other plugin, see below.</li>
 </ul>
 </blockquote>
 </li>
 </ul>
-<div class="section">
-<h2><a class="toc-backref" href="#id10" id="external-options" name="external-options">External options</a></h2>
+<div class="section" id="external-options">
+<h2><a class="toc-backref" href="#id11">External options</a></h2>
 <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
+options are implemented, such options must be marked as
 <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
 for. Example:</p>
 <pre class="literal-block">
@@ -300,11 +369,12 @@ for. Example:</p>
 (switch_option &quot;E&quot;, (extern))
 ...
 </pre>
-<p>See also the section on plugin <a class="reference" href="#priorities">priorities</a>.</p>
+<p>If an external option has additional attributes besides 'extern', they are
+ignored. See also the section on plugin <a class="reference internal" href="#priorities">priorities</a>.</p>
 </div>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id11" id="conditional-evaluation" name="conditional-evaluation"><span id="case"></span>Conditional evaluation</a></h1>
+<div class="section" id="conditional-evaluation">
+<span id="case"></span><h1><a class="toc-backref" href="#id12">Conditional evaluation</a></h1>
 <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'
@@ -349,8 +419,15 @@ readability. It is usually better to split tool descriptions and/or
 use TableGen inheritance instead.</p>
 <ul class="simple">
 <li>Possible tests are:<ul>
-<li><tt class="docutils literal"><span class="pre">switch_on</span></tt> - Returns true if a given command-line switch is
-provided by the user. Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">&quot;opt&quot;)</span></tt>.</li>
+<li><tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">[&quot;foo&quot;,</span>
+<span class="pre">&quot;bar&quot;,</span> <span class="pre">&quot;baz&quot;])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(switch_on</span> <span class="pre">&quot;foo&quot;),</span> <span class="pre">(switch_on</span>
+<span class="pre">&quot;bar&quot;),</span> <span class="pre">(switch_on</span> <span class="pre">&quot;baz&quot;))</span></tt>.
+Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">&quot;opt&quot;)</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">any_switch_on</span></tt> - Given a list of switch options, returns true if any of
+the switches is turned on.
+Example: <tt class="docutils literal"><span class="pre">(any_switch_on</span> <span class="pre">[&quot;foo&quot;,</span> <span class="pre">&quot;bar&quot;,</span> <span class="pre">&quot;baz&quot;])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(or</span>
+<span class="pre">(switch_on</span> <span class="pre">&quot;foo&quot;),</span> <span class="pre">(switch_on</span> <span class="pre">&quot;bar&quot;),</span> <span class="pre">(switch_on</span> <span class="pre">&quot;baz&quot;))</span></tt>.</li>
 <li><tt class="docutils literal"><span class="pre">parameter_equals</span></tt> - Returns true if a command-line parameter equals
 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>
@@ -360,29 +437,45 @@ Example: <tt class="docutils literal"><span class="pre">(parameter_in_list</span
 <li><tt class="docutils literal"><span class="pre">input_languages_contain</span></tt> - Returns true if a given language
 belongs to the current input language set.
 Example: <tt class="docutils literal"><span class="pre">(input_languages_contain</span> <span class="pre">&quot;c++&quot;)</span></tt>.</li>
-<li><tt class="docutils literal"><span class="pre">in_language</span></tt> - Evaluates to true if the input file language
-equals to the argument. At the moment works only with <tt class="docutils literal"><span class="pre">cmd_line</span></tt>
-and <tt class="docutils literal"><span class="pre">actions</span></tt> (on non-join nodes).
+<li><tt class="docutils literal"><span class="pre">in_language</span></tt> - Evaluates to true if the input file language is equal to
+the argument. At the moment works only with <tt class="docutils literal"><span class="pre">cmd_line</span></tt> and <tt class="docutils literal"><span class="pre">actions</span></tt> (on
+non-join nodes).
 Example: <tt class="docutils literal"><span class="pre">(in_language</span> <span class="pre">&quot;c++&quot;)</span></tt>.</li>
-<li><tt class="docutils literal"><span class="pre">not_empty</span></tt> - Returns true if a given option (which should be
-either a parameter or a parameter list) is set by the
-user.
+<li><tt class="docutils literal"><span class="pre">not_empty</span></tt> - Returns true if a given option (which should be either a
+parameter or a parameter list) is set by the user. Like <tt class="docutils literal"><span class="pre">switch_on</span></tt>, can
+be also given a list as argument.
 Example: <tt class="docutils literal"><span class="pre">(not_empty</span> <span class="pre">&quot;o&quot;)</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">any_not_empty</span></tt> - Returns true if <tt class="docutils literal"><span class="pre">not_empty</span></tt> returns true for any of
+the options in the list.
+Example: <tt class="docutils literal"><span class="pre">(any_not_empty</span> <span class="pre">[&quot;foo&quot;,</span> <span class="pre">&quot;bar&quot;,</span> <span class="pre">&quot;baz&quot;])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(or</span>
+<span class="pre">(not_empty</span> <span class="pre">&quot;foo&quot;),</span> <span class="pre">(not_empty</span> <span class="pre">&quot;bar&quot;),</span> <span class="pre">(not_empty</span> <span class="pre">&quot;baz&quot;))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">empty</span></tt> - The opposite of <tt class="docutils literal"><span class="pre">not_empty</span></tt>. Equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(not_empty</span>
+<span class="pre">X))</span></tt>. Provided for convenience. Can be given a list as argument.</li>
+<li><tt class="docutils literal"><span class="pre">any_not_empty</span></tt> - Returns true if <tt class="docutils literal"><span class="pre">not_empty</span></tt> returns true for any of
+the options in the list.
+Example: <tt class="docutils literal"><span class="pre">(any_empty</span> <span class="pre">[&quot;foo&quot;,</span> <span class="pre">&quot;bar&quot;,</span> <span class="pre">&quot;baz&quot;])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(and</span>
+<span class="pre">(not_empty</span> <span class="pre">&quot;foo&quot;),</span> <span class="pre">(not_empty</span> <span class="pre">&quot;bar&quot;),</span> <span class="pre">(not_empty</span> <span class="pre">&quot;baz&quot;)))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">single_input_file</span></tt> - Returns true if there was only one input file
+provided on the command-line. Used without arguments:
+<tt class="docutils literal"><span class="pre">(single_input_file)</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">multiple_input_files</span></tt> - Equivalent to <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(single_input_file))</span></tt> (the
+case of zero input files is considered an error).</li>
 <li><tt class="docutils literal"><span class="pre">default</span></tt> - Always evaluates to true. Should always be the last
 test in the <tt class="docutils literal"><span class="pre">case</span></tt> expression.</li>
-<li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard logical combinator that returns true iff all
-of its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span>
-<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,
-but not encouraged.</li>
-<li><tt class="docutils literal"><span class="pre">or</span></tt> - Another logical combinator that returns true only if any
-one of its arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span>
-<span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">and</span></tt> - A standard binary logical combinator that returns true iff all of
+its arguments return true. Used like this: <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(test1),</span> <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, but not
+encouraged.</li>
+<li><tt class="docutils literal"><span class="pre">or</span></tt> - A binary logical combinator that returns true iff any of its
+arguments returns true. Example: <tt class="docutils literal"><span class="pre">(or</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN))</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">not</span></tt> - Standard unary logical combinator that negates its
+argument. Example: <tt class="docutils literal"><span class="pre">(not</span> <span class="pre">(or</span> <span class="pre">(test1),</span> <span class="pre">(test2),</span> <span class="pre">...</span> <span class="pre">(testN)))</span></tt>.</li>
 </ul>
 </li>
 </ul>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id12" id="writing-a-tool-description" name="writing-a-tool-description">Writing a tool description</a></h1>
+<div class="section" id="writing-a-tool-description">
+<h1><a class="toc-backref" href="#id13">Writing a tool description</a></h1>
 <p>As was said earlier, nodes in the compilation graph represent tools,
 which are described separately. A tool definition looks like this
 (taken from the <tt class="docutils literal"><span class="pre">include/llvm/CompilerDriver/Tools.td</span></tt> file):</p>
@@ -405,8 +498,8 @@ options that aren't mentioned in the option list.</p>
 <li>Possible tool properties:<ul>
 <li><tt class="docutils literal"><span class="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><tt class="docutils literal"><span class="pre">out_language</span></tt> - output language name. Tools are not allowed to
-have multiple output languages.</li>
+<li><tt class="docutils literal"><span class="pre">out_language</span></tt> - output language name. Multiple output languages are not
+allowed.</li>
 <li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - output file suffix. Can also be changed
 dynamically, see documentation on actions.</li>
 <li><tt class="docutils literal"><span class="pre">cmd_line</span></tt> - the actual command used to run the tool. You can
@@ -423,8 +516,8 @@ below).</li>
 </ul>
 </li>
 </ul>
-<div class="section">
-<h2><a class="toc-backref" href="#id13" id="actions" name="actions">Actions</a></h2>
+<div class="section" id="actions">
+<h2><a class="toc-backref" href="#id14">Actions</a></h2>
 <p>A tool often needs to react to command-line options, and this is
 precisely what the <tt class="docutils literal"><span class="pre">actions</span></tt> property is for. The next example
 illustrates this feature:</p>
@@ -459,12 +552,16 @@ like a linker.</p>
 <ul class="simple">
 <li><tt class="docutils literal"><span class="pre">append_cmd</span></tt> - append a string to the tool invocation
 command.
-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>
-<li><tt class="docutils literal"><span class="pre">forward</span></tt> - forward an option unchanged.
-Example: <tt class="docutils literal"><span class="pre">(forward</span> <span class="pre">&quot;Wall&quot;)</span></tt>.</li>
+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>
+<li><tt class="docutils literal"><span class="pre">error</span></tt> - exit with error.
+Example: <tt class="docutils literal"><span class="pre">(error</span> <span class="pre">&quot;Mixing</span> <span class="pre">-c</span> <span class="pre">and</span> <span class="pre">-S</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">allowed!&quot;)</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">warning</span></tt> - print a warning.
+Example: <tt class="docutils literal"><span class="pre">(warning</span> <span class="pre">&quot;Specifying</span> <span class="pre">both</span> <span class="pre">-O1</span> <span class="pre">and</span> <span class="pre">-O2</span> <span class="pre">is</span> <span class="pre">meaningless!&quot;)</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">forward</span></tt> - forward an option unchanged.  Example: <tt class="docutils literal"><span class="pre">(forward</span> <span class="pre">&quot;Wall&quot;)</span></tt>.</li>
 <li><tt class="docutils literal"><span class="pre">forward_as</span></tt> - Change the name of an option, but forward the
 argument unchanged.
-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>
+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>
 <li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - modify the output suffix of this
 tool.
 Example: <tt class="docutils literal"><span class="pre">(output_suffix</span> <span class="pre">&quot;i&quot;)</span></tt>.</li>
@@ -481,8 +578,8 @@ Example: <tt class="docutils literal"><span class="pre">(unpack_values</span> <s
 </ul>
 </div>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id14" id="language-map" name="language-map">Language map</a></h1>
+<div class="section" id="language-map">
+<h1><a class="toc-backref" href="#id15">Language map</a></h1>
 <p>If you are adding support for a new language to LLVMC, you'll need to
 modify the language map, which defines mappings from file extensions
 to language names. It is used to choose the proper toolchain(s) for a
@@ -504,27 +601,59 @@ linked with the root node. Since tools are not allowed to have
 multiple output languages, for nodes &quot;inside&quot; the graph the input and
 output languages should match. This is enforced at compile-time.</p>
 </div>
-<div class="section">
-<h1><a class="toc-backref" href="#id15" id="more-advanced-topics" name="more-advanced-topics">More advanced topics</a></h1>
-<div class="section">
-<h2><a class="toc-backref" href="#id16" id="hooks-and-environment-variables" name="hooks-and-environment-variables"><span id="hooks"></span>Hooks and environment variables</a></h2>
+<div class="section" id="option-preprocessor">
+<h1><a class="toc-backref" href="#id16">Option preprocessor</a></h1>
+<p>It is sometimes useful to run error-checking code before processing the
+compilation graph. For example, if optimization options &quot;-O1&quot; and &quot;-O2&quot; are
+implemented as switches, we might want to output a warning if the user invokes
+the driver with both of these options enabled.</p>
+<p>The <tt class="docutils literal"><span class="pre">OptionPreprocessor</span></tt> feature is reserved specially for these
+occasions. Example (adapted from the built-in Base plugin):</p>
+<pre class="literal-block">
+def Preprocess : OptionPreprocessor&lt;
+(case (and (switch_on &quot;O3&quot;), (any_switch_on [&quot;O0&quot;, &quot;O1&quot;, &quot;O2&quot;])),
+           [(unset_option [&quot;O0&quot;, &quot;O1&quot;, &quot;O2&quot;]),
+            (warning &quot;Multiple -O options specified, defaulted to -O3.&quot;)],
+      (and (switch_on &quot;O2&quot;), (any_switch_on [&quot;O0&quot;, &quot;O1&quot;])),
+           (unset_option [&quot;O0&quot;, &quot;O1&quot;]),
+      (and (switch_on &quot;O1&quot;), (switch_on &quot;O0&quot;)),
+           (unset_option &quot;O0&quot;))
+&gt;;
+</pre>
+<p>Here, <tt class="docutils literal"><span class="pre">OptionPreprocessor</span></tt> is used to unset all spurious optimization options
+(so that they are not forwarded to the compiler).</p>
+<p><tt class="docutils literal"><span class="pre">OptionPreprocessor</span></tt> is basically a single big <tt class="docutils literal"><span class="pre">case</span></tt> expression, which is
+evaluated only once right after the plugin is loaded. The only allowed actions
+in <tt class="docutils literal"><span class="pre">OptionPreprocessor</span></tt> are <tt class="docutils literal"><span class="pre">error</span></tt>, <tt class="docutils literal"><span class="pre">warning</span></tt> and a special action
+<tt class="docutils literal"><span class="pre">unset_option</span></tt>, which, as the name suggests, unsets a given option. For
+convenience, <tt class="docutils literal"><span class="pre">unset_option</span></tt> also works on lists.</p>
+</div>
+<div class="section" id="more-advanced-topics">
+<h1><a class="toc-backref" href="#id17">More advanced topics</a></h1>
+<div class="section" id="hooks-and-environment-variables">
+<span id="hooks"></span><h2><a class="toc-backref" href="#id18">Hooks and environment variables</a></h2>
 <p>Normally, LLVMC executes programs from the system <tt class="docutils literal"><span class="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
-<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
-<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>
-namespace and have the signature <tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::MyHookName</span>
-<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>
+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 <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
+your plugin directory. Hooks should live in the <tt class="docutils literal"><span class="pre">hooks</span></tt> namespace
+and have the signature <tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">hooks::MyHookName</span> <span class="pre">([const</span> <span class="pre">char*</span>
+<span class="pre">Arg0</span> <span class="pre">[</span> <span class="pre">const</span> <span class="pre">char*</span> <span class="pre">Arg2</span> <span class="pre">[,</span> <span class="pre">...]]])</span></tt>. They can be used from the
+<tt class="docutils literal"><span class="pre">cmd_line</span></tt> tool property:</p>
 <pre class="literal-block">
 (cmd_line &quot;$CALL(MyHook)/path/to/file -o $CALL(AnotherHook)&quot;)
 </pre>
+<p>To pass arguments to hooks, use the following syntax:</p>
+<pre class="literal-block">
+(cmd_line &quot;$CALL(MyHook, 'Arg1', 'Arg2', 'Arg # 3')/path/to/file -o1 -o2&quot;)
+</pre>
 <p>It is also possible to use environment variables in the same manner:</p>
 <pre class="literal-block">
 (cmd_line &quot;$ENV(VAR1)/path/to/file -o $ENV(VAR2)&quot;)
 </pre>
 <p>To change the command line string based on user-provided options use
-the <tt class="docutils literal"><span class="pre">case</span></tt> expression (documented <a class="reference" href="#case">above</a>):</p>
+the <tt class="docutils literal"><span class="pre">case</span></tt> expression (documented <a class="reference internal" href="#case">above</a>):</p>
 <pre class="literal-block">
 (cmd_line
   (case
@@ -534,8 +663,8 @@ the <tt class="docutils literal"><span class="pre">case</span></tt> expression (
        &quot;llvm-g++ -c -x c $INFILE -o $OUTFILE -emit-llvm&quot;))
 </pre>
 </div>
-<div class="section">
-<h2><a class="toc-backref" href="#id17" id="how-plugins-are-loaded" name="how-plugins-are-loaded"><span id="priorities"></span>How plugins are loaded</a></h2>
+<div class="section" id="how-plugins-are-loaded">
+<span id="priorities"></span><h2><a class="toc-backref" href="#id19">How plugins are loaded</a></h2>
 <p>It is possible for LLVMC plugins to depend on each other. For example,
 one can create edges between nodes defined in some other plugin. To
 make this work, however, that plugin should be loaded first. To
@@ -550,14 +679,42 @@ def Priority : PluginPriority&lt;$PRIORITY_VALUE&gt;;
 with 0. Therefore, the plugin with the highest priority value will be
 loaded last.</p>
 </div>
-<div class="section">
-<h2><a class="toc-backref" href="#id18" id="debugging" name="debugging">Debugging</a></h2>
+<div class="section" id="debugging">
+<h2><a class="toc-backref" href="#id20">Debugging</a></h2>
 <p>When writing LLVMC plugins, it can be useful to get a visual view of
 the resulting compilation graph. This can be achieved via the command
-line option <tt class="docutils literal"><span class="pre">--view-graph</span></tt>. This command assumes that <a class="reference" href="http://www.graphviz.org/">Graphviz</a> and
-<a class="reference" href="http://pages.cs.wisc.edu/~ghost/">Ghostview</a> are installed. There is also a <tt class="docutils literal"><span class="pre">--dump-graph</span></tt> option that
+line option <tt class="docutils literal"><span class="pre">--view-graph</span></tt>. This command assumes that <a class="reference external" href="http://www.graphviz.org/">Graphviz</a> and
+<a class="reference external" href="http://pages.cs.wisc.edu/~ghost/">Ghostview</a> are installed. There is also a <tt class="docutils literal"><span class="pre">--write-graph</span></tt> option that
 creates a Graphviz source file (<tt class="docutils literal"><span class="pre">compilation-graph.dot</span></tt>) in the
 current directory.</p>
+<p>Another useful <tt class="docutils literal"><span class="pre">llvmc</span></tt> option is <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="pre">--check-graph</span></tt>, <tt class="docutils literal"><span class="pre">llvmc</span></tt> doesn't
+perform any compilation tasks and returns the number of encountered
+errors as its status code.</p>
+</div>
+<div class="section" id="conditioning-on-the-executable-name">
+<h2><a class="toc-backref" href="#id21">Conditioning on the executable name</a></h2>
+<p>For now, the executable name (the value passed to the driver in <tt class="docutils literal"><span class="pre">argv[0]</span></tt>) is
+accessible only in the C++ code (i.e. hooks). Use the following code:</p>
+<pre class="literal-block">
+namespace llvmc {
+extern const char* ProgramName;
+}
+
+std::string MyHook() {
+//...
+if (strcmp(ProgramName, &quot;mydriver&quot;) == 0) {
+   //...
+
+}
+</pre>
+<p>In general, you're encouraged not to make the behaviour dependent on the
+executable file name, and use command-line switches instead. See for example how
+the <tt class="docutils literal"><span class="pre">Base</span></tt> plugin behaves when it needs to choose the correct linker options
+(think <tt class="docutils literal"><span class="pre">g++</span></tt> vs. <tt class="docutils literal"><span class="pre">gcc</span></tt>).</p>
 <hr />
 <address>
 <a href="http://jigsaw.w3.org/css-validator/check/referer">
@@ -570,7 +727,7 @@ current directory.</p>
 <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a><br />
 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
 
-Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
+Last modified: $Date$
 </address></div>
 </div>
 </div>