[llvm-commits] [llvm] r85031 - /llvm/trunk/docs/CompilerDriver.html
Mikhail Glushenkov
foldr at codedgers.com
Sat Oct 24 18:44:24 PDT 2009
Author: foldr
Date: Sat Oct 24 20:44:24 2009
New Revision: 85031
URL: http://llvm.org/viewvc/llvm-project?rev=85031&view=rev
Log:
Regenerate.
Modified:
llvm/trunk/docs/CompilerDriver.html
Modified: llvm/trunk/docs/CompilerDriver.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CompilerDriver.html?rev=85031&r1=85030&r2=85031&view=diff
==============================================================================
--- llvm/trunk/docs/CompilerDriver.html (original)
+++ llvm/trunk/docs/CompilerDriver.html Sat Oct 24 20:44:24 2009
@@ -33,11 +33,12 @@
</ul>
</li>
<li><a class="reference internal" href="#language-map" id="id15">Language map</a></li>
-<li><a class="reference internal" href="#more-advanced-topics" id="id16">More advanced topics</a><ul>
-<li><a class="reference internal" href="#hooks-and-environment-variables" id="id17">Hooks and environment variables</a></li>
-<li><a class="reference internal" href="#how-plugins-are-loaded" id="id18">How plugins are loaded</a></li>
-<li><a class="reference internal" href="#debugging" id="id19">Debugging</a></li>
-<li><a class="reference internal" href="#conditioning-on-the-executable-name" id="id20">Conditioning on the executable name</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>
@@ -307,13 +308,13 @@
<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
-occurrence is allowed.</li>
+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 occurrence of
+<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
@@ -343,8 +344,9 @@
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">"foo",</span> <span class="pre">(multi_val</span>
-<span class="pre">3))</span></tt>. Only list options can have this attribute; you can, however, use
-the <tt class="docutils literal"><span class="pre">one_or_more</span></tt> and <tt class="docutils literal"><span class="pre">zero_or_one</span></tt> properties.</li>
+<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
@@ -417,8 +419,15 @@
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">"opt")</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">["foo",</span>
+<span class="pre">"bar",</span> <span class="pre">"baz"])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(and</span> <span class="pre">(switch_on</span> <span class="pre">"foo"),</span> <span class="pre">(switch_on</span>
+<span class="pre">"bar"),</span> <span class="pre">(switch_on</span> <span class="pre">"baz"))</span></tt>.
+Example: <tt class="docutils literal"><span class="pre">(switch_on</span> <span class="pre">"opt")</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">["foo",</span> <span class="pre">"bar",</span> <span class="pre">"baz"])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(or</span>
+<span class="pre">(switch_on</span> <span class="pre">"foo"),</span> <span class="pre">(switch_on</span> <span class="pre">"bar"),</span> <span class="pre">(switch_on</span> <span class="pre">"baz"))</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">"W",</span> <span class="pre">"all")</span></tt>.</li>
@@ -428,16 +437,24 @@
<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">"c++")</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">"c++")</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">"o")</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">["foo",</span> <span class="pre">"bar",</span> <span class="pre">"baz"])</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">(or</span>
+<span class="pre">(not_empty</span> <span class="pre">"foo"),</span> <span class="pre">(not_empty</span> <span class="pre">"bar"),</span> <span class="pre">(not_empty</span> <span class="pre">"baz"))</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.</li>
+<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">["foo",</span> <span class="pre">"bar",</span> <span class="pre">"baz"])</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">"foo"),</span> <span class="pre">(not_empty</span> <span class="pre">"bar"),</span> <span class="pre">(not_empty</span> <span class="pre">"baz")))</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>
@@ -481,8 +498,8 @@
<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
@@ -537,10 +554,11 @@
command.
Example: <tt class="docutils literal"><span class="pre">(case</span> <span class="pre">(switch_on</span> <span class="pre">"pthread"),</span> <span class="pre">(append_cmd</span>
<span class="pre">"-lpthread"))</span></tt></li>
-<li><tt class="docutils literal"><span class="pre">error`</span> <span class="pre">-</span> <span class="pre">exit</span> <span class="pre">with</span> <span class="pre">error.</span>
-<span class="pre">Example:</span> <span class="pre">``(error</span> <span class="pre">"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!")</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">"Wall")</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">"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!")</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">"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!")</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">"Wall")</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">"O0",</span> <span class="pre">"--disable-optimization")</span></tt>.</li>
@@ -583,10 +601,37 @@
multiple output languages, for nodes "inside" the graph the input and
output languages should match. This is enforced at compile-time.</p>
</div>
+<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 "-O1" and "-O2" 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<
+(case (and (switch_on "O3"), (any_switch_on ["O0", "O1", "O2"])),
+ [(unset_option ["O0", "O1", "O2"]),
+ (warning "Multiple -O options specified, defaulted to -O3.")],
+ (and (switch_on "O2"), (any_switch_on ["O0", "O1"])),
+ (unset_option ["O0", "O1"]),
+ (and (switch_on "O1"), (switch_on "O0")),
+ (unset_option "O0"))
+>;
+</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="#id16">More advanced topics</a></h1>
+<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="#id17">Hooks and environment variables</a></h2>
+<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 paths
or names in the configuration file. This can be easily achieved via
@@ -619,7 +664,7 @@
</pre>
</div>
<div class="section" id="how-plugins-are-loaded">
-<span id="priorities"></span><h2><a class="toc-backref" href="#id18">How plugins are loaded</a></h2>
+<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
@@ -635,7 +680,7 @@
loaded last.</p>
</div>
<div class="section" id="debugging">
-<h2><a class="toc-backref" href="#id19">Debugging</a></h2>
+<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 external" href="http://www.graphviz.org/">Graphviz</a> and
@@ -651,7 +696,7 @@
errors as its status code.</p>
</div>
<div class="section" id="conditioning-on-the-executable-name">
-<h2><a class="toc-backref" href="#id20">Conditioning on the executable name</a></h2>
+<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">
@@ -682,7 +727,7 @@
<a href="mailto:foldr at codedgers.com">Mikhail Glushenkov</a><br />
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br />
-Last modified: $Date$
+Last modified: $Date: 2008-12-11 11:34:48 -0600 (Thu, 11 Dec 2008) $
</address></div>
</div>
</div>
More information about the llvm-commits
mailing list