6502/llvm-6502
1
0
Fork 0
mirror of https://github.com/c64scene-ar/llvm-6502.git synced 2024-12-29 10:32:47 +00:00
Code Issues Projects Releases Wiki Activity

Regenerate documentation.

Browse Source 
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@71055 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Mikhail Glushenkov 2009-05-06 01:41:47 +00:00
parent e89331b93d
commit d6d2efc4ce
3 changed files with 72 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
docs/CompilerDriver.html
View File

@ -3,46 +3,47 @@
<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>
<!-- 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">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<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="#customizing-llvmc-the-compilation-graph" id="id8">Customizing LLVMC: the compilation graph</a></li>
<li><a class="reference internal" href="#describing-options" id="id9">Describing options</a><ul>
<li><a class="reference internal" href="#external-options" id="id10">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="id11">Conditional evaluation</a></li>
<li><a class="reference internal" href="#writing-a-tool-description" id="id12">Writing a tool description</a><ul>
<li><a class="reference internal" href="#actions" id="id13">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="id14">Language map</a></li>
<li><a class="reference internal" href="#more-advanced-topics" id="id15">More advanced topics</a><ul>
<li><a class="reference internal" href="#hooks-and-environment-variables" id="id16">Hooks and environment variables</a></li>
<li><a class="reference internal" href="#how-plugins-are-loaded" id="id17">How plugins are loaded</a></li>
<li><a class="reference internal" href="#debugging" id="id18">Debugging</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
@ -55,11 +56,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.cs.uiuc.edu/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>
@ -96,8 +97,8 @@ hello
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>
</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">
@ -125,8 +126,8 @@ and do not delete them on exit. Hidden option, useful for debugging.</li>
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">
@ -141,7 +142,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>
@ -178,8 +179,8 @@ $ cd $LLVMC_DIR
$ make 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="#id8">Customizing LLVMC: the compilation graph</a></h1>
<p>Each TableGen configuration file should include the common
definitions:</p>
<pre class="literal-block">
@ -246,8 +247,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="#id9">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">
@ -315,8 +316,8 @@ the <tt class="docutils literal"><span class="pre">one_or_more</span></tt> and <
</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="#id10">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 must be marked as
@ -327,11 +328,11 @@ 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>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="#id11">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'
@ -410,8 +411,8 @@ one of its arguments returns true. Example: <tt class="docutils literal"><span c
</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="#id12">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>
@ -452,8 +453,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="#id13">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>
@ -496,7 +497,7 @@ Example: <tt class="docutils literal"><span class="pre">(case</span> <span class
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>
@ -513,8 +514,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="#id14">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
@ -536,10 +537,10 @@ 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="more-advanced-topics">
<h1><a class="toc-backref" href="#id15">More advanced topics</a></h1>
<div class="section" id="hooks-and-environment-variables">
<span id="hooks"></span><h2><a class="toc-backref" href="#id16">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
@ -561,7 +562,7 @@ and have the signature <tt class="docutils literal"><span class="pre">std::strin
(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
@ -571,8 +572,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="#id17">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
@ -587,12 +588,12 @@ 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="#id18">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">--write-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

27
docs/CompilerDriverTutorial.html
View File

@ -3,28 +3,29 @@
<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>Tutorial - Using LLVMC</title>
<link rel="stylesheet" href="llvm.css" type="text/css" />
</head>
<body>
<div class="document" id="tutorial-using-llvmc">
<h1 class="title">Tutorial - Using LLVMC</h1>
<!-- 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">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
<li><a class="reference" href="#compiling-with-llvmc" id="id2" name="id2">Compiling with LLVMC</a></li>
<li><a class="reference" href="#using-llvmc-to-generate-toolchain-drivers" id="id3" name="id3">Using LLVMC to generate toolchain drivers</a></li>
<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
<li><a class="reference internal" href="#compiling-with-llvmc" id="id2">Compiling with LLVMC</a></li>
<li><a class="reference internal" href="#using-llvmc-to-generate-toolchain-drivers" id="id3">Using LLVMC to generate toolchain drivers</a></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="#id1" id="introduction" name="introduction">Introduction</a></h1>
</div><div class="section" id="introduction">
<h1><a class="toc-backref" href="#id1">Introduction</a></h1>
<p>LLVMC is a generic compiler driver, which plays the same role for LLVM
as the <tt class="docutils literal"><span class="pre">gcc</span></tt> program does for GCC - the difference being that LLVMC
is designed to be more adaptable and easier to customize. Most of
@ -32,8 +33,8 @@ LLVMC functionality is implemented via plugins, which can be loaded
dynamically or compiled in. This tutorial describes the basic usage
and configuration of LLVMC.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" 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="#id2">Compiling with LLVMC</a></h1>
<p>In general, LLVMC tries to be command-line compatible with <tt class="docutils literal"><span class="pre">gcc</span></tt> as
much as possible, so most of the familiar options work:</p>
<pre class="literal-block">
@ -45,9 +46,9 @@ hello
commands are executed by using the <tt class="docutils literal"><span class="pre">-v</span></tt> option). For further help on
command-line LLVMC usage, refer to the <tt class="docutils literal"><span class="pre">llvmc</span> <span class="pre">--help</span></tt> output.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id3" id="using-llvmc-to-generate-toolchain-drivers" name="using-llvmc-to-generate-toolchain-drivers">Using LLVMC to generate toolchain drivers</a></h1>
<p>LLVMC plugins are written mostly using <a class="reference" href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">TableGen</a>, so you need to
<div class="section" id="using-llvmc-to-generate-toolchain-drivers">
<h1><a class="toc-backref" href="#id3">Using LLVMC to generate toolchain drivers</a></h1>
<p>LLVMC plugins are written mostly using <a class="reference external" href="http://llvm.cs.uiuc.edu/docs/TableGenFundamentals.html">TableGen</a>, so you need to
be familiar with it to get anything done.</p>
<p>Start by compiling <tt class="docutils literal"><span class="pre">plugins/Simple/Simple.td</span></tt>, which is a primitive
wrapper for <tt class="docutils literal"><span class="pre">gcc</span></tt>:</p>

4
docs/llvm.css
View File

@ -72,7 +72,7 @@ h3, .doc_subsubsection { margin: 2.0em 0.5em 0.5em 0.5em;
/* It is preferrable to use <pre class="doc_code"> everywhere instead of the
* <div class="doc_code"><pre>...</ptr></div> construct.
*
*
* Once all docs use <pre> for code regions, this style can be merged with the
* one above, and we can drop the [pre] qualifier.
*/
@ -95,6 +95,6 @@ th.layout { border: none; font-weight: bold; font-size: 105%;
/* ReST-specific */
.title { margin-top: 0 }
#contents { display: none }
.topic-title{ display: none }
div.contents ul { list-style-type: decimal }
.toc-backref { color: black; text-decoration: none; }