diff options
| author | Mikhail Glushenkov <foldr@codedgers.com> | 2011-04-24 14:17:37 +0000 |
|---|---|---|
| committer | Mikhail Glushenkov <foldr@codedgers.com> | 2011-04-24 14:17:37 +0000 |
| commit | fb88665d97fffff7d212619fe8d1a77d670b5159 (patch) | |
| tree | a0bab818839920d64adb1e4bf95a437930e7318f | |
| parent | 834b93b51de05fba014c63f6d05baeb0e80975dd (diff) | |
Regenerate.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@130091 91177308-0d34-0410-b5e6-96231b3b80d8
| -rw-r--r-- | docs/CompilerDriver.html | 771 | ||||
| -rw-r--r-- | docs/CompilerDriverTutorial.html | 109 |
2 files changed, 405 insertions, 475 deletions
diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html index 42e69b61b7..f9782d3261 100644 --- a/docs/CompilerDriver.html +++ b/docs/CompilerDriver.html @@ -3,7 +3,7 @@ <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.5: http://docutils.sourceforge.net/" /> +<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <title>Customizing LLVMC: Reference Manual</title> <link rel="stylesheet" href="llvm.css" type="text/css" /> </head> @@ -17,28 +17,23 @@ 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 internal" href="#introduction" id="id8">Introduction</a></li> -<li><a class="reference internal" href="#compiling-with-llvmc" id="id9">Compiling with LLVMC</a></li> -<li><a class="reference internal" href="#predefined-options" id="id10">Predefined options</a></li> -<li><a class="reference internal" href="#compiling-llvmc-plugins" id="id11">Compiling LLVMC plugins</a></li> -<li><a class="reference internal" href="#compiling-standalone-llvmc-based-drivers" id="id12">Compiling standalone LLVMC-based drivers</a></li> -<li><a class="reference internal" href="#customizing-llvmc-the-compilation-graph" id="id13">Customizing LLVMC: the compilation graph</a></li> -<li><a class="reference internal" href="#describing-options" id="id14">Describing options</a><ul> -<li><a class="reference internal" href="#external-options" id="id15">External options</a></li> +<li><a class="reference internal" href="#introduction" id="id7">Introduction</a></li> +<li><a class="reference internal" href="#compiling-with-llvmc" id="id8">Compiling with <tt class="docutils literal">llvmc</tt></a></li> +<li><a class="reference internal" href="#predefined-options" id="id9">Predefined options</a></li> +<li><a class="reference internal" href="#compiling-llvmc-based-drivers" id="id10">Compiling LLVMC-based drivers</a></li> +<li><a class="reference internal" href="#customizing-llvmc-the-compilation-graph" id="id11">Customizing LLVMC: the compilation graph</a></li> +<li><a class="reference internal" href="#describing-options" id="id12">Describing options</a></li> +<li><a class="reference internal" href="#conditional-evaluation" id="id13">Conditional evaluation</a></li> +<li><a class="reference internal" href="#writing-a-tool-description" id="id14">Writing a tool description</a><ul> +<li><a class="reference internal" href="#id4" id="id15">Actions</a></li> </ul> </li> -<li><a class="reference internal" href="#conditional-evaluation" id="id16">Conditional evaluation</a></li> -<li><a class="reference internal" href="#writing-a-tool-description" id="id17">Writing a tool description</a><ul> -<li><a class="reference internal" href="#id5" id="id18">Actions</a></li> -</ul> -</li> -<li><a class="reference internal" href="#language-map" id="id19">Language map</a></li> -<li><a class="reference internal" href="#option-preprocessor" id="id20">Option preprocessor</a></li> -<li><a class="reference internal" href="#more-advanced-topics" id="id21">More advanced topics</a><ul> -<li><a class="reference internal" href="#hooks-and-environment-variables" id="id22">Hooks and environment variables</a></li> -<li><a class="reference internal" href="#how-plugins-are-loaded" id="id23">How plugins are loaded</a></li> -<li><a class="reference internal" href="#debugging" id="id24">Debugging</a></li> -<li><a class="reference internal" href="#conditioning-on-the-executable-name" id="id25">Conditioning on the executable name</a></li> +<li><a class="reference internal" href="#language-map" id="id16">Language map</a></li> +<li><a class="reference internal" href="#option-preprocessor" id="id17">Option preprocessor</a></li> +<li><a class="reference internal" href="#more-advanced-topics" id="id18">More advanced topics</a><ul> +<li><a class="reference internal" href="#hooks-and-environment-variables" id="id19">Hooks and environment variables</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> @@ -46,25 +41,24 @@ The ReST source lives in the directory 'tools/llvmc/doc'. --> <div class="doc_author"> <p>Written by <a href="mailto:foldr@codedgers.com">Mikhail Glushenkov</a></p> </div><div class="section" id="introduction"> -<h1><a class="toc-backref" href="#id8">Introduction</a></h1> +<h1><a class="toc-backref" href="#id7">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 -files into a set of targets depending on configuration rules and user -options. What makes LLVMC different is that these transformation rules -are completely customizable - in fact, LLVMC knows nothing about the -specifics of transformation (even the command-line options are mostly -not hard-coded) and regards the transformation structure as an -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> +extensible. It plays the same role for LLVM as the <tt class="docutils literal">gcc</tt> program does for +GCC - LLVMC's job is essentially to transform a set of input files into a set of +targets depending on configuration rules and user options. What makes LLVMC +different is that these transformation rules are completely customizable - in +fact, LLVMC knows nothing about the specifics of transformation (even the +command-line options are mostly not hard-coded) and regards the transformation +structure as an abstract graph. The structure of this graph is described in +high-level TableGen code, from which an efficient C++ representation is +automatically derived. This makes it possible to adapt LLVMC for other +purposes - for example, as a build tool for game resources.</p> <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" id="compiling-with-llvmc"> -<h1><a class="toc-backref" href="#id9">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, +<h1><a class="toc-backref" href="#id8">Compiling with <tt class="docutils literal">llvmc</tt></a></h1> +<p>LLVMC tries hard to be as compatible with <tt class="docutils literal">gcc</tt> as possible, although there are some small differences. Most of the time, however, you shouldn't be able to notice them:</p> <pre class="literal-block"> @@ -74,11 +68,11 @@ $ ./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> vs. <tt class="docutils literal"><span class="pre">gcc</span></tt>) - the +different compilers for different languages (think <tt class="docutils literal">g++</tt> vs. <tt class="docutils literal">gcc</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 <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> +do it with <tt class="docutils literal">gcc</tt>:</p> <pre class="literal-block"> $ # hello.c is really a C++ file $ llvmc -x c++ hello.c @@ -97,138 +91,100 @@ $ ./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 <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> +possible to choose the <tt class="docutils literal">clang</tt> compiler with the <tt class="docutils literal"><span class="pre">-clang</span></tt> option.</p> </div> <div class="section" id="predefined-options"> -<h1><a class="toc-backref" href="#id10">Predefined options</a></h1> -<p>LLVMC has some built-in options that can't be overridden in the -configuration libraries:</p> +<h1><a class="toc-backref" href="#id9">Predefined options</a></h1> +<p>LLVMC has some built-in options that can't be overridden in the TableGen code:</p> <ul class="simple"> -<li><tt class="docutils literal"><span class="pre">-o</span> <span class="pre">FILE</span></tt> - Output file name.</li> -<li><tt class="docutils literal"><span class="pre">-x</span> <span class="pre">LANGUAGE</span></tt> - Specify the language of the following input files +<li><tt class="docutils literal"><span class="pre">-o</span> FILE</tt> - Output file name.</li> +<li><tt class="docutils literal"><span class="pre">-x</span> LANGUAGE</tt> - Specify the language of the following input files 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">--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 +<li><tt class="docutils literal"><span class="pre">--temp-dir</span> DIRECTORY</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> +output/input language names, multiple default edges and cycles. Exit with code +zero if no errors were found, and return the number of found errors +otherwise. Hidden option, useful for debugging.</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> +and exit. Requires that you have <tt class="docutils literal">dot</tt> and <tt class="docutils literal">gv</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 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 +used to set the output file name. Hidden option, useful for debugging.</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" id="compiling-llvmc-plugins"> -<h1><a class="toc-backref" href="#id11">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> +<div class="section" id="compiling-llvmc-based-drivers"> +<h1><a class="toc-backref" href="#id10">Compiling LLVMC-based drivers</a></h1> +<p>It's easiest to start working on your own LLVMC driver by copying the skeleton +project which lives under <tt class="docutils literal">$LLVMC_DIR/examples/Skeleton</tt>:</p> <pre class="literal-block"> -$ cd $LLVMC_DIR/plugins -$ cp -r Simple MyPlugin -$ cd MyPlugin +$ cd $LLVMC_DIR/examples +$ cp -r Skeleton MyDriver +$ cd MyDriver $ ls -Makefile PluginMain.cpp Simple.td -</pre> -<p>As you can see, our basic plugin consists of only two files (not -counting the build script). <tt class="docutils literal"><span class="pre">Simple.td</span></tt> contains TableGen -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 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> -<pre class="literal-block"> -LLVMC_PLUGIN=MyPlugin +AutoGenerated.td Hooks.cpp Main.cpp Makefile </pre> -<p>It is also a good idea to rename <tt class="docutils literal"><span class="pre">Simple.td</span></tt> to something less -generic:</p> +<p>As you can see, our basic driver consists of only three files (not counting the +build script). <tt class="docutils literal">AutoGenerated.td</tt> contains TableGen description of the +compilation graph; its format is documented in the following +sections. <tt class="docutils literal">Hooks.cpp</tt> is an empty file that should be used for hook +definitions (see <a class="reference internal" href="#hooks">below</a>). <tt class="docutils literal">Main.cpp</tt> is just a helper used to compile the +auto-generated C++ code produced from TableGen source.</p> +<p>The first thing that you should do is to change the <tt class="docutils literal">LLVMC_BASED_DRIVER</tt> +variable in the <tt class="docutils literal">Makefile</tt>:</p> <pre class="literal-block"> -$ mv Simple.td MyPlugin.td +LLVMC_BASED_DRIVER=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">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/plugin_llvmc_Simple.so -</pre> -</div> -<div class="section" id="compiling-standalone-llvmc-based-drivers"> -<h1><a class="toc-backref" href="#id12">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> +<p>It can also be a good idea to put your TableGen code into a file with a less +generic name:</p> <pre class="literal-block"> -$ cd $LLVMC_DIR/example/ -$ cp -r Skeleton mydriver -$ cd mydriver -$ vim Makefile +$ touch MyDriver.td +$ vim AutoGenerated.td [...] -$ make +include "MyDriver.td" </pre> +<p>If you have more than one TableGen source file, they all should be included from +<tt class="docutils literal">AutoGenerated.td</tt>, since this file is used by the build system to generate +C++ code.</p> +<p>To build your driver, just <tt class="docutils literal">cd</tt> to its source directory and run <tt class="docutils literal">make</tt>. The +resulting executable will be put into <tt class="docutils literal"><span class="pre">$LLVM_OBJ_DIR/$(BuildMode)/bin</span></tt>.</p> <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> +must perform the following additional steps before running <tt class="docutils literal">make</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 +$ mkdir $LLVMC_OBJ_DIR/examples/MyDriver/ +$ cp $LLVMC_SRC_DIR/examples/MyDriver/Makefile \ + $LLVMC_OBJ_DIR/examples/MyDriver/ +$ cd $LLVMC_OBJ_DIR/examples/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 LLVMC_BUILTIN_PLUGINS="" -</pre> </div> <div class="section" id="customizing-llvmc-the-compilation-graph"> -<h1><a class="toc-backref" href="#id13">Customizing LLVMC: the compilation graph</a></h1> -<p>Each TableGen configuration file should include the common -definitions:</p> +<h1><a class="toc-backref" href="#id11">Customizing LLVMC: the compilation graph</a></h1> +<p>Each TableGen configuration file should include the common definitions:</p> <pre class="literal-block"> include "llvm/CompilerDriver/Common.td" </pre> -<p>Internally, LLVMC stores information about possible source -transformations in form of a graph. Nodes in this graph represent -tools, and edges between two nodes represent a transformation path. A -special "root" node is used to mark entry points for the -transformations. LLVMC also assigns a weight to each edge (more on -this later) to choose between several alternative edges.</p> -<p>The definition of the compilation graph (see file -<tt class="docutils literal"><span class="pre">plugins/Base/Base.td</span></tt> for an example) is just a list of edges:</p> +<p>Internally, LLVMC stores information about possible source transformations in +form of a graph. Nodes in this graph represent tools, and edges between two +nodes represent a transformation path. A special "root" node is used to mark +entry points for the transformations. LLVMC also assigns a weight to each edge +(more on this later) to choose between several alternative edges.</p> +<p>The definition of the compilation graph (see file <tt class="docutils literal">llvmc/src/Base.td</tt> for an +example) is just a list of edges:</p> <pre class="literal-block"> def CompilationGraph : CompilationGraph<[ Edge<"root", "llvm_gcc_c">, @@ -253,39 +209,33 @@ def CompilationGraph : CompilationGraph<[ ]>; </pre> -<p>As you can see, the edges can be either default or optional, where -optional edges are differentiated by an additional <tt class="docutils literal"><span class="pre">case</span></tt> expression -used to calculate the weight of this edge. Notice also that we refer -to tools via their names (as strings). This makes it possible to add -edges to an existing compilation graph in plugins without having to -know about all tool definitions used in the graph.</p> -<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 <tt class="docutils literal"><span class="pre">case</span></tt> expression. It is also possible to provide an -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, -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 <tt class="docutils literal"><span class="pre">default</span></tt> clause of the <tt class="docutils literal"><span class="pre">case</span></tt> +<p>As you can see, the edges can be either default or optional, where optional +edges are differentiated by an additional <tt class="docutils literal">case</tt> expression used to calculate +the weight of this edge. Notice also that we refer to tools via their names (as +strings). This makes it possible to add edges to an existing compilation graph +without having to know about all tool definitions used in the graph.</p> +<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 <tt class="docutils literal">case</tt> +expression. It is also possible to provide an integer parameter to +<tt class="docutils literal">inc_weight</tt> and <tt class="docutils literal">dec_weight</tt> - in this case, the weight is increased (or +decreased) by the provided value instead of the default 2. Default weight of an +optional edge can be changed by using the <tt class="docutils literal">default</tt> clause of the <tt class="docutils literal">case</tt> construct.</p> -<p>When passing an input file through the graph, LLVMC picks the edge -with the maximum weight. To avoid ambiguity, there should be only one -default edge between two nodes (with the exception of the root node, -which gets a special treatment - there you are allowed to specify one -default edge <em>per language</em>).</p> -<p>When multiple plugins are loaded, their compilation graphs are merged -together. Since multiple edges that have the same end nodes are not -allowed (i.e. the graph is not a multigraph), an edge defined in -several plugins will be replaced by the definition from the plugin -that was loaded last. Plugin load order can be controlled by using the -plugin priority feature described above.</p> -<p>To get a visual representation of the compilation graph (useful for -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> +<p>When passing an input file through the graph, LLVMC picks the edge with the +maximum weight. To avoid ambiguity, there should be only one default edge +between two nodes (with the exception of the root node, which gets a special +treatment - there you are allowed to specify one default edge <em>per language</em>).</p> +<p>When multiple compilation graphs are defined, they are merged together. Multiple +edges with the same end nodes are not allowed (i.e. the graph is not a +multigraph), and will lead to a compile-time error.</p> +<p>To get a visual representation of the compilation graph (useful for debugging), +run <tt class="docutils literal">llvmc <span class="pre">--view-graph</span></tt>. You will need <tt class="docutils literal">dot</tt> and <tt class="docutils literal">gsview</tt> installed for +this to work properly.</p> </div> <div class="section" id="describing-options"> -<h1><a class="toc-backref" href="#id14">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> +<h1><a class="toc-backref" href="#id12">Describing options</a></h1> +<p>Command-line options supported by the driver are defined by using an +<tt class="docutils literal">OptionList</tt>:</p> <pre class="literal-block"> def Options : OptionList<[ (switch_option "E", (help "Help string")), @@ -293,101 +243,95 @@ def Options : OptionList<[ ... ]>; </pre> -<p>As you can see, the option list is just a list of DAGs, where each DAG -is an option description consisting of the option name and some -properties. A plugin can define more than one option list (they are -all merged together in the end), which can be handy if one wants to -separate option groups syntactically.</p> +<p>As you can see, the option list is just a list of DAGs, where each DAG is an +option description consisting of the option name and some properties. More than +one option list can be defined (they are all merged together in the end), which +can be handy if one wants to separate option groups syntactically.</p> <ul> <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 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 +<li><tt class="docutils literal">switch_option</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 by default.</li> +<li><tt class="docutils literal">parameter_option</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 +sign: <tt class="docutils literal"><span class="pre">-std</span> c99</tt>. At most one occurrence is allowed.</li> +<li><tt class="docutils literal">parameter_list_option</tt> - same as the above, but more than one option occurrence 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 +<li><tt class="docutils literal">prefix_option</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 +specified as <tt class="docutils literal"><span class="pre">-o</span> file</tt>; however, <tt class="docutils literal"><span class="pre">-o=file</span></tt> will be parsed incorrectly +(<tt class="docutils literal">=file</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 occurrence of +<li><tt class="docutils literal">prefix_list_option</tt> - same as the above, but more than one occurrence 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 +<li><tt class="docutils literal">alias_option</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">"preprocess",</span> <span class="pre">"E")</span></tt></li> +aliased option name. +Usage example: <tt class="docutils literal">(alias_option "preprocess", "E")</tt></li> +<li><tt class="docutils literal">switch_list_option</tt> - like <tt class="docutils literal">switch_option</tt> with the <tt class="docutils literal">zero_or_more</tt> +property, but remembers how many times the switch was turned on. Useful +mostly for forwarding. Example: when <tt class="docutils literal"><span class="pre">-foo</span></tt> is a switch option (with the +<tt class="docutils literal">zero_or_more</tt> property), the command <tt class="docutils literal">driver <span class="pre">-foo</span> <span class="pre">-foo</span></tt> is forwarded +as <tt class="docutils literal"><span class="pre">some-tool</span> <span class="pre">-foo</span></tt>, but when <tt class="docutils literal"><span class="pre">-foo</span></tt> is a switch list, the same command +is forwarded as <tt class="docutils literal"><span class="pre">some-tool</span> <span class="pre">-foo</span> <span class="pre">-foo</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> +<li><tt class="docutils literal">help</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">optional</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> +<li><tt class="docutils literal">required</tt> - this option must be specified exactly once (or, in case of +the list options without the <tt class="docutils literal">multi_val</tt> property, at least +once). Incompatible with <tt class="docutils literal">optional</tt> and <tt class="docutils literal">one_or_more</tt>.</li> +<li><tt class="docutils literal">optional</tt> - the option can be specified either zero times or exactly +once. The default for switch options. Useful only for list options in +conjunction with <tt class="docutils literal">multi_val</tt>. Incompatible with <tt class="docutils literal">required</tt>, +<tt class="docutils literal">zero_or_more</tt> and <tt class="docutils literal">one_or_more</tt>.</li> +<li><tt class="docutils literal">one_or_more</tt> - the option must be specified at least once. Can be useful +to allow switch options be both obligatory and be specified multiple +times. For list options is useful only in conjunction with <tt class="docutils literal">multi_val</tt>; +for ordinary it is synonymous with <tt class="docutils literal">required</tt>. Incompatible with +<tt class="docutils literal">required</tt>, <tt class="docutils literal">optional</tt> and <tt class="docutils literal">zero_or_more</tt>.</li> +<li><tt class="docutils literal">zero_or_more</tt> - the option can be specified zero or more times. Useful +to allow a single switch option to be specified more than +once. Incompatible with <tt class="docutils literal">required</tt>, <tt class="docutils literal">optional</tt> and <tt class="docutils literal">one_or_more</tt>.</li> +<li><tt class="docutils literal">hidden</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 +<li><tt class="docutils literal">really_hidden</tt> - the option will not be mentioned in any help output.</li> -<li><tt class="docutils literal"><span class="pre">comma_separated</span></tt> - Indicates that any commas specified for an option's +<li><tt class="docutils literal">comma_separated</tt> - Indicates that any commas specified for an option's value should be used to split the value up into multiple values for the option. This property is valid only for list options. In conjunction with -<tt class="docutils literal"><span class="pre">forward_value</span></tt> can be used to implement option forwarding in style of +<tt class="docutils literal">forward_value</tt> can be used to implement option forwarding in style of gcc's <tt class="docutils literal"><span class="pre">-Wa,</span></tt>.</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">"foo",</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">optional</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 +<li><tt class="docutils literal">multi_val n</tt> - this option takes <em>n</em> arguments (can be useful in some +special cases). Usage example: <tt class="docutils literal">(parameter_list_option "foo", (multi_val +3))</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">one_or_more</tt>, <tt class="docutils literal">optional</tt> +and <tt class="docutils literal">required</tt> properties.</li> +<li><tt class="docutils literal">init</tt> - this option has a default value, either a string (if it is a parameter), or a boolean (if it is a switch; as in C++, 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 <tt class="docutils literal"><span class="pre">init</span></tt> +are called <tt class="docutils literal">true</tt> and <tt class="docutils literal">false</tt>). List options can't have <tt class="docutils literal">init</tt> attribute. -Usage examples: <tt class="docutils literal"><span class="pre">(switch_option</span> <span class="pre">"foo",</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">"bar",</span> <span class="pre">(init</span> <span class="pre">"baz"))</span></tt>.</li> -<li><tt class="docutils literal"><span class="pre">extern</span></tt> - this option is defined in some other plugin, see <a class="reference internal" href="#extern">below</a>.</li> +Usage examples: <tt class="docutils literal">(switch_option "foo", (init true))</tt>; <tt class= |