6502/llvm-6502
1
0
Fork 0
mirror of https://github.com/c64scene-ar/llvm-6502.git synced 2025-01-04 21:30:49 +00:00
Code Issues Projects Releases Wiki Activity

Regenerate.

Browse Source 
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@85031 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Mikhail Glushenkov 2009-10-25 01:44:24 +00:00
parent 3e4102e94c
commit 0a018d3d8c
1 changed files with 75 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
docs/CompilerDriver.html
View File

@ -33,11 +33,12 @@ The ReST source lives in the directory 'tools/llvmc/doc'. -->
</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 @@ separate option groups syntactically.</p>
<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>
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>. 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 @@ 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>
@ -428,16 +437,24 @@ 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.</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">[&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>
@ -481,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
@ -537,10 +554,11 @@ like a linker.</p>
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">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">&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">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">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>
@ -583,10 +601,37 @@ 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" 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="#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 @@ the <tt class="docutils literal"><span class="pre">case</span></tt> expression (
</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 @@ with 0. Therefore, the plugin with the highest priority value will be
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 @@ 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="#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 @@ the <tt class="docutils literal"><span class="pre">Base</span></tt> plugin behav
<a href="mailto:foldr@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>