<div class="doc_section"> <a name="introduction">Introduction</a></div>
<!-- *********************************************************************** -->
<div class="doc_text">
- <p>The <tt>llvmc</tt> <a href="def_tool">tool</a> is a configurable compiler
- <a href="def_driver">driver</a>. As such, it isn't a compiler, optimizer,
+ <p>The <tt>llvmc</tt> <a href="#def_tool">tool</a> is a configurable compiler
+ <a href="#def_driver">driver</a>. As such, it isn't a compiler, optimizer,
or a linker itself but it drives (invokes) other software that perform those
tasks. If you are familiar with the GNU Compiler Collection's <tt>gcc</tt>
tool, <tt>llvmc</tt> is very similar.</p>
llvmc -O2 x.c y.c z.c -o xyz</code>
<p>must produce <i>exactly</i> the same results as:</p>
<pre><tt>
- llvmc -O2 x.c
- llvmc -O2 y.c
- llvmc -O2 z.c
+ llvmc -O2 x.c -o x.o
+ llvmc -O2 y.c -o y.o
+ llvmc -O2 z.c -o z.o
llvmc -O2 x.o y.o z.o -o xyz</tt></pre>
<p>To accomplish this, <tt>llvmc</tt> uses a very simple goal oriented
procedure to do its work. The overall goal is to produce a functioning
program.</dd>
</dl>
<p>The following table shows the inputs, outputs, and command line options
- applicabe to each phase.</p>
+ applicable to each phase.</p>
<table>
<tr>
<th style="width: 10%">Phase</th>
</ul></td>
<td class="td_left"><ul>
<li>LLVM Assembly</li>
- <li>LLVM Bytecode</li>
+ <li>LLVM Bitcode</li>
<li>LLVM C++ IR</li>
</ul></td>
<td class="td_left"><dl>
<td><b>Optimization</b></td>
<td class="td_left"><ul>
<li>LLVM Assembly</li>
- <li>LLVM Bytecode</li>
+ <li>LLVM Bitcode</li>
</ul></td>
<td class="td_left"><ul>
- <li>LLVM Bytecode</li>
+ <li>LLVM Bitcode</li>
</ul></td>
<td class="td_left"><dl>
<dt><tt>-Ox</tt>
<tr>
<td><b>Linking</b></td>
<td class="td_left"><ul>
- <li>LLVM Bytecode</li>
+ <li>LLVM Bitcode</li>
<li>Native Object Code</li>
<li>LLVM Library</li>
<li>Native Library</li>
</ul></td>
<td class="td_left"><ul>
- <li>LLVM Bytecode Executable</li>
+ <li>LLVM Bitcode Executable</li>
<li>Native Executable</li>
</ul></td>
<td class="td_left"><dl>
available command line options for those programs regardless of whether they
were written for LLVM or not. Furthermore, not all compiler tools will
have the same capabilities. Some compiler tools will simply generate LLVM assembly
-code, others will be able to generate fully optimized byte code. In general,
+code, others will be able to generate fully optimized bitcode. In general,
<tt>llvmc</tt> doesn't make any assumptions about the capabilities or command
line options of a sub-tool. It simply uses the details found in the
configuration files and leaves it to the compiler writer to specify the
<p>This approach means that new compiler tools can be up and working very
quickly. As a first cut, a tool can simply compile its source to raw
-(unoptimized) bytecode or LLVM assembly and <tt>llvmc</tt> can be configured
-to pick up the slack (translate LLVM assembly to bytecode, optimize the
-bytecode, generate native assembly, link, etc.). In fact, the compiler tools
+(unoptimized) bitcode or LLVM assembly and <tt>llvmc</tt> can be configured
+to pick up the slack (translate LLVM assembly to bitcode, optimize the
+bitcode, generate native assembly, link, etc.). In fact, the compiler tools
need not use any LLVM libraries, and it could be written in any language
(instead of C++). The configuration data will allow the full range of
optimization, assembly, and linking capabilities that LLVM provides to be added
of the primary goals of <tt>llvmc</tt>.</p>
<p>As a compiler tool matures, it may utilize the LLVM libraries and tools
-to more efficiently produce optimized bytecode directly in a single compilation
+to more efficiently produce optimized bitcode directly in a single compilation
and optimization program. In these cases, multiple tools would not be needed
and the configuration data for the compiler would change.</p>
and linker. Note that a given source language needn't provide all these tools
as many of them exist in llvm currently.</p>
</div>
+
+<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"><a name="dirsearch">Directory Search</a></div>
<div class="doc_text">
<p><tt>llvmc</tt> always looks for files of a specific name. It uses the
<th>Description</th>
<th>Default</th>
</tr>
+ <tr><td colspan="4"><h4>LLVMC ITEMS</h4></td></tr>
+ <tr>
+ <td><b>version</b></td>
+ <td>string</td>
+ <td class="td_left">Provides the version string for the contents of this
+ configuration file. What is accepted as a legal configuration file
+ will change over time and this item tells <tt>llvmc</tt> which version
+ should be expected.</td>
+ <td><i>b</i></td>
+ </tr>
<tr><td colspan="4"><h4>LANG ITEMS</h4></td></tr>
<tr>
<td><b>lang.name</b></td>
</tr>
<tr>
<td><b>translator.output</b></td>
- <td><tt>native</tt>, <tt>bytecode</tt> or <tt>assembly</tt></td>
+ <td><tt>bitcode</tt> or <tt>assembly</tt></td>
<td class="td_left">This item specifies the kind of output the language's
translator generates.</td>
- <td><tt>bytecode</tt></td>
+ <td><tt>bitcode</tt></td>
</tr>
<tr>
<td><b>translator.preprocesses</b></td>
whenever the final phase is not pre-processing.</td>
<td><tt>false</tt></td>
</tr>
- <tr>
- <td><b>translator.optimizes</b></td>
- <td>boolean</td>
- <td class="td_left">Indicates that the translator also optimizes. If
- this is true, then <tt>llvmc</tt> will skip the optimization phase
- whenever the final phase is optimization or later.</td>
- <td><tt>false</tt></td>
- </tr>
- <tr>
- <td><b>translator.groks_dash_o</b></td>
- <td>boolean</td>
- <td class="td_left">Indicates that the translator understands the
- <i>intent</i> of the various <tt>-O</tt><i>n</i> options to
- <tt>llvmc</tt>. This will cause the <tt>-O</tt><i>n</i> option to be
- given to the translator instead of the equivalent options provided by
- <tt>lang.opt</tt><i>n</i>.</td>
- <td><tt>false</tt></td>
- </tr>
<tr><td colspan="4"><h4>OPTIMIZER ITEMS</h4></td></tr>
<tr>
<td><b>optimizer.command</b></td>
</tr>
<tr>
<td><b>optimizer.output</b></td>
- <td><tt>native</tt>, <tt>bytecode</tt> or <tt>assembly</tt></td>
+ <td><tt>bitcode</tt> or <tt>assembly</tt></td>
<td class="td_left">This item specifies the kind of output the language's
- optimizer generates.</td>
- <td><tt>bytecode</tt></td>
+ optimizer generates. Valid values are "assembly" and "bitcode"</td>
+ <td><tt>bitcode</tt></td>
</tr>
<tr>
<td><b>optimizer.preprocesses</b></td>
whenever the final phase is optimization or later.</td>
<td><tt>false</tt></td>
</tr>
- <tr>
- <td><b>optimizer.groks_dash_o</b></td>
- <td>boolean</td>
- <td class="td_left">Indicates that the translator understands the
- <i>intent</i> of the various <tt>-O</tt><i>n</i> options to
- <tt>llvmc</tt>. This will cause the <tt>-O</tt><i>n</i> option to be
- given to the translator instead of the equivalent options provided by
- <tt>lang.opt</tt><i>n</i>.</td>
- <td><tt>false</tt></td>
- </tr>
<tr><td colspan="4"><h4>ASSEMBLER ITEMS</h4></td></tr>
<tr>
<td><b>assembler.command</b></td>
input file and <tt>%out%</tt> for the output file.</td>
<td><blank></td>
</tr>
- <tr><td colspan="4"><h4>LINKER ITEMS</h4></td></tr>
- <tr>
- <td><b>linker.libs</b></td>
- <td>library names</td>
- <td class="td_left">This provides the list of runtime libraries that the
- source language <i>could</i> link with. In general, the libraries
- needed will be encoded into the LLVM Assembly or bytecode file.
- However, this list tells <tt>llvmc</tt> the names of the ones that
- apply to this source language. The names provided here should be
- unadorned with no suffix and no "lib" prefix.
- </td>
- <td><blank></td>
- </tr>
- <tr>
- <td><b>linker.lib_paths</b></td>
- <td>Fully qualifed local path names</td>
- <td class="td_left">This item provides a list of potential directories
- in which the source language's runtime libraries might be located. If
- a given object file compiled with this language's translator is linked
- then those libraries will be given as <tt>-L</tt> options to the
- linker.</td>
- <td><tt><blank></tt></td>
- </tr>
- <tr>
- <td><b>linker.output</b></td>
- <td><tt>native</tt>, <tt>bytecode</tt> or <tt>assembly</tt></td>
- <td class="td_left">This item specifies the kind of output the language's
- translator generates.</td>
- <td><tt>bytecode</tt></td>
- </tr>
</tbody>
</table>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsection"><a name="substitutions">Substitutions</a></div>
<div class="doc_text">
- <p>On any configruation item that ends in <tt>command</tt>, you must
+ <p>On any configuration item that ends in <tt>command</tt>, you must
specify substitution tokens. Substitution tokens begin and end with a percent
sign (<tt>%</tt>) and are replaced by the corresponding text. Any substitution
token may be given on any <tt>command</tt> line but some are more useful than
others. In particular each command <em>should</em> have both an <tt>%in%</tt>
- and an <tt>%out%</tt> substittution. The table below provides definitions of
+ and an <tt>%out%</tt> substitution. The table below provides definitions of
each of the allowed substitution tokens.</p>
<table>
<tbody>
then you are explicitly disallowing the <tt>-T</tt> option for your
tool.
</td>
+ <tr>
+ <td><tt>%force%</tt></td>
+ <td class="td_left">Replaced with the <tt>-f</tt> option if it was
+ specified on the <tt>llvmc</tt> command line. This is intended to tell
+ the compiler tool to force the overwrite of output files.
+ </td>
+ </tr>
<tr>
<td><tt>%in%</tt></td>
<td class="td_left">Replaced with the full path of the input file. You
# To compile stacker source, we just run the stacker
# compiler with a default stack size of 2048 entries.
translator.command=stkrc -s 2048 %in% -o %out% %time% \
- %stats% %args%
+ %stats% %force% %args%
# stkrc doesn't preprocess but we set this to true so
# that we don't run the cp command by default.
# The translator is required to run.
translator.required=true
- # stkrc doesn't do any optimization, it just translates
- translator.optimizes=no
-
# stkrc doesn't handle the -On options
- translator.groks_dash_O=no
+ translator.output=bitcode
##########################################################
# Optimizer definitions
# For optimization, we use the LLVM "opt" program
optimizer.command=opt %in% -o %out% %opt% %time% %stats% \
- %args%
+ %force% %args%
- # opt doesn't (yet) grok -On
- optimizer.groks_dash_O=no
+ optimizer.required = true
# opt doesn't translate
optimizer.translates = no
# opt doesn't preprocess
optimizer.preprocesses=no
-##########################################################
-# Assembler definitions
-##########################################################
- assembler.command=llc %in% -o %out% %target% \
- "-regalloc=linearscan" %time% %stats%
+ # opt produces bitcode
+ optimizer.output = bc
##########################################################
-# Linker definitions
+# Assembler definitions
##########################################################
- linker.libs=stkr_runtime
- linker.paths=
+ assembler.command=llc %in% -o %out% %target% %time% %stats%
</tt></pre>
-
+</div>
<!-- *********************************************************************** -->
<div class="doc_section"><a name="glossary">Glossary</a></div>
defined below.</p>
<dl>
<dt><a name="def_assembly"><b>assembly</b></a></dt>
- <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode or
+ <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bitcode or
LLVM assembly code is assembled to a native code format (either target
specific aseembly language or the platform's native object file format).
</dd>
<dd>Refers to <tt>llvmc</tt> itself.</dd>
<dt><a name="def_linking"><b>linking</b></a></dt>
- <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode files
+ <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bitcode files
and (optionally) native system libraries are combined to form a complete
executable program.</dd>
<dt><a name="def_optimization"><b>optimization</b></a></dt>
- <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode is
+ <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bitcode is
optimized.</dd>
<dt><a name="def_phase"><b>phase</b></a></dt>
<dt><a name="def_translation"><b>translation</b></a></dt>
<dd>A compilation <a href="#def_phase">phase</a> in which
<a href="#def_sourcelanguage">source language</a> code is translated into
- either LLVM assembly language or LLVM bytecode.</dd>
+ either LLVM assembly language or LLVM bitcode.</dd>
</dl>
</div>
<!-- *********************************************************************** -->
href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a><a
href="mailto:rspencer@x10sys.com">Reid Spencer</a><br>
-<a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+<a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
<!-- vim: sw=2
projects / oota-llvm.git / blobdiff