Fix typos.

[oota-llvm.git] / docs / CompilerDriver.html

diff --git a/docs/CompilerDriver.html b/docs/CompilerDriver.html
index 927ed766ca6972eac8272386f9ab8b7cec12a349..c73723efd08b83e6e68053b56406e93c6cb942b1 100644 (file)
--- a/docs/CompilerDriver.html
+++ b/docs/CompilerDriver.html
@@ -4,15 +4,7 @@
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <title>The LLVM Compiler Driver (llvmc)</title>
   <link rel="stylesheet" href="llvm.css" type="text/css">
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <title>The LLVM Compiler Driver (llvmc)</title>
   <link rel="stylesheet" href="llvm.css" type="text/css">

-  <style type="text/css">
-    TR, TD { border: 2px solid gray; padding: 4pt 4pt 2pt 2pt; }
-    TH { border: 2px solid gray; font-weight: bold; font-size: 105%; }
-    TABLE { text-align: center; border: 2px solid black; 
-      border-collapse: collapse; margin-top: 1em; margin-left: 1em; 
-      margin-right: 1em; margin-bottom: 1em; }
-    .td_left { border: 2px solid gray; text-align: left; }
-  </style>
-  <meta name="author" content="Reid Spencer" name="author">
+  <meta name="author" content="Reid Spencer">

   <meta name="description" 
   content="A description of the use and design of the LLVM Compiler Driver.">
 </head>
   <meta name="description" 
   content="A description of the use and design of the LLVM Compiler Driver.">
 </head>


@@ -29,8 +21,14 @@
       <li><a href="#actions">Actions</a></li>
     </ol>
   </li>
       <li><a href="#actions">Actions</a></li>
     </ol>
   </li>

-  <li><a href="#details">Details</a>

   <li><a href="#configuration">Configuration</a>
   <li><a href="#configuration">Configuration</a>

+    <ol>
+      <li><a href="#overview">Overview</a></li>
+      <li><a href="#filetypes">Configuration Files</a></li>
+      <li><a href="#syntax">Syntax</a></li>
+      <li><a href="#substitutions">Substitutions</a></li>
+      <li><a href="#sample">Sample Config File</a></li>
+    </ol>

   <li><a href="#glossary">Glossary</a>
 </ol>
 <div class="doc_author">
   <li><a href="#glossary">Glossary</a>
 </ol>
 <div class="doc_author">


@@ -56,9 +54,9 @@
 <div class="doc_section"> <a name="introduction">Introduction</a></div>
 <!-- *********************************************************************** -->
 <div class="doc_text">
 <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 the compiler, optimizer, 
-  or linker itself but it drives (invokes) other software that perform those 
+  <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>
   <p>The following introductory sections will help you understand why this tool
   tasks. If you are familiar with the GNU Compiler Collection's <tt>gcc</tt> 
   tool, <tt>llvmc</tt> is very similar.</p>
   <p>The following introductory sections will help you understand why this tool


@@ -68,8 +66,8 @@
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsection"><a name="purpose">Purpose</a></div>
 <div class="doc_text">
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsection"><a name="purpose">Purpose</a></div>
 <div class="doc_text">

-  <p><tt>llvmc</tt> was invented to make compilation with LLVM based compilers 
-  easier. To accomplish this, <tt>llvmc</tt> strives to:</p>
+  <p><tt>llvmc</tt> was invented to make compilation of user programs with 
+  LLVM-based tools easier. To accomplish this, <tt>llvmc</tt> strives to:</p>

   <ul>
     <li>Be the single point of access to most of the LLVM tool set.</li>
     <li>Hide the complexities of the LLVM tools through a single interface.</li>
   <ul>
     <li>Be the single point of access to most of the LLVM tool set.</li>
     <li>Hide the complexities of the LLVM tools through a single interface.</li>


@@ -79,15 +77,14 @@
   with LLVM, because it:</p>
   <ul>
     <li>Makes integration of existing non-LLVM tools simple.</li>
   with LLVM, because it:</p>
   <ul>
     <li>Makes integration of existing non-LLVM tools simple.</li>

-    <li>Extends the capabilities of minimal front ends by optimizing their
+    <li>Extends the capabilities of minimal compiler tools by optimizing their

     output.</li>
     <li>Reduces the number of interfaces a compiler writer must know about
     before a working compiler can be completed (essentially only the VMCore
     interfaces need to be understood).</li>
     <li>Supports source language translator invocation via both dynamically
     loadable shared objects and invocation of an executable.</li>
     output.</li>
     <li>Reduces the number of interfaces a compiler writer must know about
     before a working compiler can be completed (essentially only the VMCore
     interfaces need to be understood).</li>
     <li>Supports source language translator invocation via both dynamically
     loadable shared objects and invocation of an executable.</li>

-  </ol>
-</p>
+  </ul>

 </div>
 
 <!-- _______________________________________________________________________ -->
 </div>
 
 <!-- _______________________________________________________________________ -->


@@ -96,7 +93,7 @@
   <p>At a high level, <tt>llvmc</tt> operation is very simple.  The basic action
   taken by <tt>llvmc</tt> is to simply invoke some tool or set of tools to fill 
   the user's request for compilation. Every execution of <tt>llvmc</tt>takes the 
   <p>At a high level, <tt>llvmc</tt> operation is very simple.  The basic action
   taken by <tt>llvmc</tt> is to simply invoke some tool or set of tools to fill 
   the user's request for compilation. Every execution of <tt>llvmc</tt>takes the 

-  following sequence of steps:<br/>
+  following sequence of steps:</p>

   <dl>
     <dt><b>Collect Command Line Options</b></dt>
     <dd>The command line options provide the marching orders to <tt>llvmc</tt> 
   <dl>
     <dt><b>Collect Command Line Options</b></dt>
     <dd>The command line options provide the marching orders to <tt>llvmc</tt> 


@@ -107,10 +104,11 @@
     <dt><b>Read Configuration Files</b></dt>
     <dd>Based on the options and the suffixes of the filenames presented, a set 
     of configuration files are read to configure the actions <tt>llvmc</tt> will 
     <dt><b>Read Configuration Files</b></dt>
     <dd>Based on the options and the suffixes of the filenames presented, a set 
     of configuration files are read to configure the actions <tt>llvmc</tt> will 

-    take.  Configuration files are provided by either LLVM or the front end 
-    compiler tools that B<llvmc> invokes. These files determine what actions
-    <tt>llvmc</tt> will take in response to the user's request. See the section 
-    on <a href="#configuration">configuration</a> for more details.</dd>
+    take.  Configuration files are provided by either LLVM or the 
+    compiler tools that <tt>llvmc</tt> invokes. These files determine what 
+    actions <tt>llvmc</tt> will take in response to the user's request. See 
+    the section on <a href="#configuration">configuration</a> for more details.
+    </dd>

     <dt><b>Determine Phases To Execute</b></dt>
     <dd>Based on the command line options and configuration files,
     <tt>llvmc</tt> determines the compilation <a href="#phases">phases</a> that
     <dt><b>Determine Phases To Execute</b></dt>
     <dd>Based on the command line options and configuration files,
     <tt>llvmc</tt> determines the compilation <a href="#phases">phases</a> that


@@ -132,18 +130,18 @@
     <dd>If any action fails (returns a non-zero result code), <tt>llvmc</tt>
     also fails and returns the result code from the failing action. If
     everything succeeds, <tt>llvmc</tt> will return a zero result code.</dd>
     <dd>If any action fails (returns a non-zero result code), <tt>llvmc</tt>
     also fails and returns the result code from the failing action. If
     everything succeeds, <tt>llvmc</tt> will return a zero result code.</dd>

-  </dl></p>
+  </dl>

   <p><tt>llvmc</tt>'s operation must be simple, regular and predictable. 
   Developers need to be able to rely on it to take a consistent approach to
   compilation. For example, the invocation:</p>
   <p><tt>llvmc</tt>'s operation must be simple, regular and predictable. 
   Developers need to be able to rely on it to take a consistent approach to
   compilation. For example, the invocation:</p>

-  <tt><pre>
-   llvmc -O2 x.c y.c z.c -o xyz</pre></tt>
+  <code>
+    llvmc -O2 x.c y.c z.c -o xyz</code>

   <p>must produce <i>exactly</i> the same results as:</p>
   <p>must produce <i>exactly</i> the same results as:</p>

-  <tt><pre>
-   llvmc -O2 x.c
-   llvmc -O2 y.c
-   llvmc -O2 z.c
-   llvmc -O2 x.o y.o z.o -o xyz</pre></tt>
+  <pre><tt>
+    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
   executable. To accomplish this, <tt>llvmc</tt> always attempts to execute a 
   <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
   executable. To accomplish this, <tt>llvmc</tt> always attempts to execute a 


@@ -178,7 +176,7 @@
     program.</dd>
   </dl>
   <p>The following table shows the inputs, outputs, and command line options
     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>
   <table>
     <tr>
       <th style="width: 10%">Phase</th>


@@ -224,7 +222,7 @@
       </ul></td>
       <td class="td_left"><dl>
           <dt><tt>-Ox</tt>
       </ul></td>
       <td class="td_left"><dl>
           <dt><tt>-Ox</tt>

-          <dd>This group of options affects the amount of optimization 
+          <dd>This group of options controls the amount of optimization 

           performed.</dd>
       </dl></td>
     </tr>
           performed.</dd>
       </dl></td>
     </tr>


@@ -254,16 +252,11 @@
   <p>An action, with regard to <tt>llvmc</tt> is a basic operation that it takes
   in order to fulfill the user's request. Each phase of compilation will invoke
   zero or more actions in order to accomplish that phase.</p>
   <p>An action, with regard to <tt>llvmc</tt> is a basic operation that it takes
   in order to fulfill the user's request. Each phase of compilation will invoke
   zero or more actions in order to accomplish that phase.</p>

-  <p>Actions come in two forms:<ol>
+  <p>Actions come in two forms:</p>
+  <ul>

     <li>Invokable Executables</li>
     <li>Functions in a shared library</li>
     <li>Invokable Executables</li>
     <li>Functions in a shared library</li>

-  </ul></p>
-</div>
-
-<!-- *********************************************************************** -->
-<div class="doc_section"><a name="details">Details</a></div>
-<!-- *********************************************************************** -->
-<div class="doc_text">
+  </ul>

 </div>
 
 <!-- *********************************************************************** -->
 </div>
 
 <!-- *********************************************************************** -->


@@ -272,11 +265,11 @@
 <div class="doc_text">
   <p>This section of the document describes the configuration files used by
   <tt>llvmc</tt>.  Configuration information is relatively static for a 
 <div class="doc_text">
   <p>This section of the document describes the configuration files used by
   <tt>llvmc</tt>.  Configuration information is relatively static for a 

-  given release of LLVM and a front end compiler. However, the details may 
+  given release of LLVM and a compiler tool. However, the details may 

   change from release to release of either.  Users are encouraged to simply use 
   change from release to release of either.  Users are encouraged to simply use 

-  the various options of the B<llvmc> command and ignore the configuration of 
-  the tool. These configuration files are for compiler writers and LLVM 
-  developers. Those wishing to simply use B<llvmc> don't need to understand 
+  the various options of the <tt>llvmc</tt> command and ignore the configuration 
+  of the tool. These configuration files are for compiler writers and LLVM 
+  developers. Those wishing to simply use <tt>llvmc</tt> don't need to understand 

   this section but it may be instructive on how the tool works.</p>
 </div>
 
   this section but it may be instructive on how the tool works.</p>
 </div>
 


@@ -296,32 +289,32 @@ should be invoked. Users may but are not advised to alter the compiler's
 
 <p>Because <tt>llvmc</tt> just invokes other programs, it must deal with the
 available command line options for those programs regardless of whether they
 
 <p>Because <tt>llvmc</tt> just invokes other programs, it must deal with the
 available command line options for those programs regardless of whether they

-were written for LLVM or not. Furthermore, not all compilation front ends will
-have the same capabilities. Some front ends will simply generate LLVM assembly
+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,
 <tt>llvmc</tt> doesn't make any assumptions about the capabilities or command 
 code, others will be able to generate fully optimized byte code. 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 configuration
-correctly.</p>
+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 
+configuration correctly.</p>

 
 

-<p>This approach means that new compiler front ends can be up and working very
-quickly. As a first cut, a front end can simply compile its source to raw
+<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 
 (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 front end 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 to these kinds
-of tools.  Enabling the rapid development of front-ends is one of the primary 
-goals of <tt>llvmc</tt>.</p>
-
-<p>As a compiler front end matures, it may utilize the LLVM libraries and tools 
+bytecode, 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 
+to these kinds of tools.  Enabling the rapid development of front-ends is one 
+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 
 and optimization program. In these cases, multiple tools would not be needed 
 and the configuration data for the compiler would change.</p>
 
 <p>Configuring <tt>llvmc</tt> to the needs and capabilities of a source language 
 to more efficiently produce optimized bytecode 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>
 
 <p>Configuring <tt>llvmc</tt> to the needs and capabilities of a source language 

-compiler is relatively straight forward.  A compiler writer must provide a 
+compiler is relatively straight-forward.  A compiler writer must provide a 

 definition of what to do for each of the five compilation phases for each of 
 the optimization levels. The specification consists simply of prototypical 
 command lines into which <tt>llvmc</tt> can substitute command line
 definition of what to do for each of the five compilation phases for each of 
 the optimization levels. The specification consists simply of prototypical 
 command lines into which <tt>llvmc</tt> can substitute command line


@@ -334,24 +327,24 @@ optimization.</p>
 </div>
 
 <!-- _______________________________________________________________________ -->
 </div>
 
 <!-- _______________________________________________________________________ -->

-<div class="doc_subsection"><a name="filetypes"></a>Configuration Files</div>
+<div class="doc_subsection"><a name="filetypes">Configuration Files</a></div>
+<div class="doc_subsubsection"><a name="filecontents">File Contents</a></div>
+<div class="doc_text">
+  <p>Each configuration file provides the details for a single source language
+  that is to be compiled.  This configuration information tells <tt>llvmc</tt> 
+  how to invoke the language's pre-processor, translator, optimizer, assembler
+  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">
 <div class="doc_text">

-  <h3>File Types</h3>
-  <p>There are two types of configuration files: the master configuration file
-  and the language specific configuration file.  The master configuration file 
-  contains the general configuration of <tt>llvmc</tt> itself and is supplied
-  with the tool.  It contains information that is source language agnostic.  
-  Language specific configuration files tell <tt>llvmc</tt> how to invoke the 
-  language's compiler for a variety of different tasks and what other tools 
-  are needed to backfill the compiler's missing features (e.g.
-  optimization).</p>
-
-  <h3>Directory Search</h3>

   <p><tt>llvmc</tt> always looks for files of a specific name. It uses the
   first file with the name its looking for by searching directories in the
   following order:<br/>
   <ol>
   <p><tt>llvmc</tt> always looks for files of a specific name. It uses the
   first file with the name its looking for by searching directories in the
   following order:<br/>
   <ol>

-    <li>Any directory specified by the <tt>--config-dir</tt> option will be
+    <li>Any directory specified by the <tt>-config-dir</tt> option will be

     checked first.</li>
     <li>If the environment variable LLVM_CONFIG_DIR is set, and it contains
     the name of a valid directory, that directory will be searched next.</li>
     checked first.</li>
     <li>If the environment variable LLVM_CONFIG_DIR is set, and it contains
     the name of a valid directory, that directory will be searched next.</li>


@@ -362,83 +355,403 @@ optimization.</p>
     <li>If the LLVM installation directory (typically <tt>/usr/local/llvm</tt>
     contains a sub-directory named <tt>etc</tt> then that directory will be
     tried last.</li>
     <li>If the LLVM installation directory (typically <tt>/usr/local/llvm</tt>
     contains a sub-directory named <tt>etc</tt> then that directory will be
     tried last.</li>

+    <li>A standard "system" directory will be searched next. This is typically
+    <tt>/etc/llvm</tt> on UNIX&trade; and <tt>C:\WINNT</tt> on Microsoft
+    Windows&trade;.</li>

     <li>If the configuration file sought still can't be found, <tt>llvmc</tt>
     will print an error message and exit.</li>
   </ol>
     <li>If the configuration file sought still can't be found, <tt>llvmc</tt>
     will print an error message and exit.</li>
   </ol>

-  The first file found in this search will be used. Other files with the same
-  name will be ignored even if they exist in one of the subsequent search
+  <p>The first file found in this search will be used. Other files with the 
+  same name will be ignored even if they exist in one of the subsequent search

   locations.</p>
   locations.</p>

+</div>
+
+<div class="doc_subsubsection"><a name="filenames">File Names</a></div>
+<div class="doc_text">
+  <p>In the directories searched, each configuration file is given a specific
+  name to foster faster lookup (so llvmc doesn't have to do directory searches).
+  The name of a given language specific configuration file is simply the same 
+  as the suffix used to identify files containing source in that language. 
+  For example, a configuration file for C++ source might be named 
+  <tt>cpp</tt>, <tt>C</tt>, or <tt>cxx</tt>. For languages that support multiple
+  file suffixes, multiple (probably identical) files (or symbolic links) will
+  need to be provided.</p>
+</div>

 
 

-  <h3>File Names</h3>
-  <p>In the directories searched, a file named <tt>master</tt> will be
-  recognized as the master configuration file for <tt>llvmc</tt>.  Note that 
-  users <i>may</i> override the master file with a copy in their home directory 
-  but they are advised not to. This capability is only useful for compiler 
-  implementers needing to alter the master configuration while developing 
-  their compiler front end.  When reading the configuration files, the master 
-  files are always read first.</p>
-  <p>Language specific configuration files are given specific names to foster 
-  faster lookup. The name of a given language specific configuration file is 
-  the same as the suffix used to identify files containing source in that 
-  language. For example, a configuration file for C++ source might be named 
-  <tt>cpp</tt>, <tt>C</tt>, or <tt>cxx</tt>.</p>
-
-  <h3>What Gets Read</h3>
-  <p>The master configuration file is always read. Which language specific
-  configuration files are read depends on the command line options and the
-  suffixes of the file names provided on <tt>llvmc</tt>'s command line. Note
-  that the <tt>--x LANGUAGE</tt> option alters the language that <tt>llvmc</tt>
-  uses for the subsequent files on the command line.  Only the language 
-  specific configuration files actually needed to complete <tt>llvmc</tt>'s 
-  task are read. Other language specific files will be ignored.</p>
+<div class="doc_subsubsection"><a name="whatgetsread">What Gets Read</a></div>
+<div class="doc_text">
+  <p>Which configuration files are read depends on the command line options and 
+  the suffixes of the file names provided on <tt>llvmc</tt>'s command line. Note
+  that the <tt>-x LANGUAGE</tt> option alters the language that <tt>llvmc</tt>
+  uses for the subsequent files on the command line.  Only the configuration 
+  files actually needed to complete <tt>llvmc</tt>'s task are read. Other 
+  language specific files will be ignored.</p>

 </div>
 
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsection"><a name="syntax"></a>Syntax</div>
 <div class="doc_text">
 </div>
 
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsection"><a name="syntax"></a>Syntax</div>
 <div class="doc_text">

-  <p>The syntax of the configuration files is yet to be determined. There are
-  two viable options remaining:<br/>
+  <p>The syntax of the configuration files is very simple and somewhat
+  compatible with Java's property files. Here are the syntax rules:</p>

   <ul>
   <ul>

-    <li>XML DTD Specific To <tt>llvmc</tt></li>
-    <li>Windows .ini style file with numerous sections</li>
-  </ul></p>
+    <li>The file encoding is ASCII.</li>
+    <li>The file is line oriented. There should be one configuration definition 
+    per line. Lines are terminated by the newline (0x0A) and/or carriage return
+    characters (0x0D)</li>
+    <li>A backslash (<tt>\</tt>) before a newline causes the newline to be
+    ignored. This is useful for line continuation of long definitions. A
+    backslash anywhere else is recognized as a backslash.</li>
+    <li>A configuration item consists of a name, an <tt>=</tt> and a value.</li>
+    <li>A name consists of a sequence of identifiers separated by period.</li>
+    <li>An identifier consists of specific keywords made up of only lower case
+    and upper case letters (e.g. <tt>lang.name</tt>).</li>
+    <li>Values come in four flavors: booleans, integers, commands and 
+    strings.</li>
+    <li>Valid "false" boolean values are <tt>false False FALSE no No NO
+      off Off</tt> and <tt>OFF</tt>.</li>
+    <li>Valid "true" boolean values are <tt>true True TRUE yes Yes YES
+      on On</tt> and <tt>ON</tt>.</li>
+    <li>Integers are simply sequences of digits.</li>
+    <li>Commands start with a program name and are followed by a sequence of
+    words that are passed to that program as command line arguments. Program
+    arguments that begin and end with the <tt>%</tt> sign will have their value
+    substituted. Program names beginning with <tt>/</tt> are considered to be
+    absolute. Otherwise the <tt>PATH</tt> will be applied to find the program to
+    execute.</li>
+    <li>Strings are composed of multiple sequences of characters from the
+    character class <tt>[-A-Za-z0-9_:%+/\\|,]</tt> separated by white
+    space.</li>
+    <li>White space on a line is folded. Multiple blanks or tabs will be
+    reduced to a single blank.</li>
+    <li>White space before the configuration item's name is ignored.</li>
+    <li>White space on either side of the <tt>=</tt> is ignored.</li>
+    <li>White space in a string value is used to separate the individual
+    components of the string value but otherwise ignored.</li>
+    <li>Comments are introduced by the <tt>#</tt> character. Everything after a
+    <tt>#</tt> and before the end of line is ignored.</li>
+  </ul>

 </div>
 
 <!-- _______________________________________________________________________ -->
 </div>
 
 <!-- _______________________________________________________________________ -->

-<div class="doc_subsection"><a name="master_items">Configuration Items</a></div>
+<div class="doc_subsection"><a name="items">Configuration Items</a></div>

 <div class="doc_text">
 <div class="doc_text">

-  <p>The following description of configuration items is syntax-less and simply
-  uses a naming hierarchy to describe the configuration items. Whatever
-  syntax is chosen will need to map the hierarchy to the given syntax.</p>
+  <p>The table below provides definitions of the allowed configuration items
+  that may appear in a configuration file. Every item has a default value and
+  does not need to appear in the configuration file. Missing items will have the 
+  default value. Each identifier may appear as all lower case, first letter
+  capitalized or all upper case.</p>

   <table>
   <table>

-    <tr>
-      <th>Name</th>
-      <th>Value Type</th>
-      <th>Description</th>
-    </tr>
-    <tr>
-      <td><b>Capabilities.hasPreProcessor</b></td>
-      <td>boolean</td>
-      <td class="td_left">This item specifies whether the language has a 
-        pre-processing phase or not. This controls whether the B<-E> option works 
-        for the language or not.</td>
-    </tr>
-    <tr>
-      <td><b>Capabilities.outputFormat</b></td>
-      <td>"bc" or "ll"</td>
-      <td class="td_left">This item specifies the kind of output the language's 
-        compiler generates. The choices are either bytecode (<tt>bc</tt>) or LLVM 
-        assembly (<tt>ll</tt>).</td>
-    </tr>
-    <tr>
-      <td><b>Capabilities.understandsOptimization</b></td>
-      <td>boolean</td>
-      <td>Indicates whether the compiler for this language understands the
-        <tt>-O</tt> options or not</td>
-    </tr>
+    <tbody>
+      <tr>
+        <th>Name</th>
+        <th>Value Type</th>
+        <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>
+        <td>string</td>
+        <td class="td_left">Provides the common name for a language definition. 
+          For example "C++", "Pascal", "FORTRAN", etc.</td>
+        <td><i>blank</i></td>
+      </tr>
+      <tr>
+        <td><b>lang.opt1</b></td>
+        <td>string</td>
+        <td class="td_left">Specifies the parameters to give the optimizer when
+          <tt>-O1</tt> is specified on the <tt>llvmc</tt> command line.</td>
+        <td><tt>-simplifycfg -instcombine -mem2reg</tt></td>
+      </tr>
+      <tr>
+        <td><b>lang.opt2</b></td>
+        <td>string</td>
+        <td class="td_left">Specifies the parameters to give the optimizer when
+          <tt>-O2</tt> is specified on the <tt>llvmc</tt> command line.</td>
+        <td><i>TBD</i></td>
+      </tr>
+      <tr>
+        <td><b>lang.opt3</b></td>
+        <td>string</td>
+        <td class="td_left">Specifies the parameters to give the optimizer when
+          <tt>-O3</tt> is specified on the <tt>llvmc</tt> command line.</td>
+        <td><i>TBD</i></td>
+      </tr>
+      <tr>
+        <td><b>lang.opt4</b></td>
+        <td>string</td>
+        <td class="td_left">Specifies the parameters to give the optimizer when
+          <tt>-O4</tt> is specified on the <tt>llvmc</tt> command line.</td>
+        <td><i>TBD</i></td>
+      </tr>
+      <tr>
+        <td><b>lang.opt5</b></td>
+        <td>string</td>
+        <td class="td_left">Specifies the parameters to give the optimizer when 
+          <tt>-O5</tt> is specified on the <tt>llvmc</tt> command line.</td>
+        <td><i>TBD</i></td>
+      </tr>
+      <tr><td colspan="4"><h4>PREPROCESSOR ITEMS</h4></td></tr>
+      <tr>
+        <td><b>preprocessor.command</b></td>
+        <td>command</td>
+        <td class="td_left">This provides the command prototype that will be used
+          to run the preprocessor.  This is generally only used with the 
+          <tt>-E</tt> option.</td>
+        <td>&lt;blank&gt;</td>
+      </tr>
+      <tr>
+        <td><b>preprocessor.required</b></td>
+        <td>boolean</td>
+        <td class="td_left">This item specifies whether the pre-processing phase
+          is required by the language. If the value is true, then the
+          <tt>preprocessor.command</tt> value must not be blank. With this option,
+          <tt>llvmc</tt> will always run the preprocessor as it assumes that the
+          translation and optimization phases don't know how to pre-process their
+          input.</td>
+        <td>false</td>
+      </tr>
+      <tr><td colspan="4"><h4>TRANSLATOR ITEMS</h4></td></tr>
+      <tr>
+        <td><b>translator.command</b></td>
+        <td>command</td>
+        <td class="td_left">This provides the command prototype that will be used 
+          to run the translator. Valid substitutions are <tt>%in%</tt> for the 
+          input file and <tt>%out%</tt> for the output file.</td>
+        <td>&lt;blank&gt;</td>
+      </tr>
+      <tr>
+        <td><b>translator.output</b></td>
+        <td><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>
+      <tr>
+        <td><b>translator.preprocesses</b></td>
+        <td>boolean</td>
+        <td class="td_left">Indicates that the translator also preprocesses. If
+          this is true, then <tt>llvmc</tt> will skip the pre-processing phase
+          whenever the final phase is not pre-processing.</td>
+        <td><tt>false</tt></td>
+      </tr>
+      <tr><td colspan="4"><h4>OPTIMIZER ITEMS</h4></td></tr>
+      <tr>
+        <td><b>optimizer.command</b></td>
+        <td>command</td>
+        <td class="td_left">This provides the command prototype that will be used 
+          to run the optimizer. Valid substitutions are <tt>%in%</tt> for the 
+          input file and <tt>%out%</tt> for the output file.</td>
+        <td>&lt;blank&gt;</td>
+      </tr>
+      <tr>
+        <td><b>optimizer.output</b></td>
+        <td><tt>bytecode</tt> or <tt>assembly</tt></td>
+        <td class="td_left">This item specifies the kind of output the language's 
+          optimizer generates. Valid values are "assembly" and "bytecode"</td>
+        <td><tt>bytecode</tt></td>
+      </tr>
+      <tr>
+        <td><b>optimizer.preprocesses</b></td>
+        <td>boolean</td>
+        <td class="td_left">Indicates that the optimizer also preprocesses. If
+          this is true, then <tt>llvmc</tt> will skip the pre-processing phase
+          whenever the final phase is optimization or later.</td>
+        <td><tt>false</tt></td>
+      </tr>
+      <tr>
+        <td><b>optimizer.translates</b></td>
+        <td>boolean</td>
+        <td class="td_left">Indicates that the optimizer also translates. If
+          this is true, then <tt>llvmc</tt> will skip the translation phase
+          whenever the final phase is optimization or later.</td>
+        <td><tt>false</tt></td>
+      </tr>
+      <tr><td colspan="4"><h4>ASSEMBLER ITEMS</h4></td></tr>
+      <tr>
+        <td><b>assembler.command</b></td>
+        <td>command</td>
+        <td class="td_left">This provides the command prototype that will be used 
+          to run the assembler. Valid substitutions are <tt>%in%</tt> for the 
+          input file and <tt>%out%</tt> for the output file.</td>
+        <td>&lt;blank&gt;</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsection"><a name="substitutions">Substitutions</a></div>
+<div class="doc_text">
+  <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> substitution. The table below provides definitions of
+  each of the allowed substitution tokens.</p>
+  <table>
+    <tbody>
+      <tr>
+        <th>Substitution Token</th>
+        <th>Replacement Description</th>
+      </tr>
+      <tr>
+        <td><tt>%args%</tt></td>
+        <td class="td_left">Replaced with all the tool-specific arguments given
+          to <tt>llvmc</tt> via the <tt>-T</tt> set of options. This just allows
+          you to place these arguments in the correct place on the command line.
+          If the <tt>%args%</tt> option does not appear on your command line, 
+          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
+          needn't worry about the cascading of file names. <tt>llvmc</tt> will
+          create temporary files and ensure that the output of one phase is the
+          input to the next phase.</td>
+      </tr>
+      <tr>
+        <td><tt>%opt%</tt></td>
+        <td class="td_left">Replaced with the optimization options for the
+          tool. If the tool understands the <tt>-O</tt> options then that will
+          be passed. Otherwise, the <tt>lang.optN</tt> series of configuration
+          items will specify which arguments are to be given.</td>
+      </tr>
+      <tr>
+        <td><tt>%out%</tt></td>
+        <td class="td_left">Replaced with the full path of the output file.
+          Note that this is not necessarily the output file specified with the
+          <tt>-o</tt> option on <tt>llvmc</tt>'s command line. It might be a
+          temporary file that will be passed to a subsequent phase's input.
+        </td>
+      </tr>
+      <tr>
+        <td><tt>%stats%</tt></td>
+        <td class="td_left">If your command accepts the <tt>-stats</tt> option,
+          use this substitution token. If the user requested <tt>-stats</tt> 
+          from the <tt>llvmc</tt> command line then this token will be replaced
+          with <tt>-stats</tt>, otherwise it will be ignored.
+        </td>
+      </tr>
+      <tr>
+        <td><tt>%target%</tt></td>
+        <td class="td_left">Replaced with the name of the target "machine" for 
+          which code should be generated. The value used here is taken from the
+          <tt>llvmc</tt> option <tt>-march</tt>.
+        </td>
+      </tr>
+      <tr>
+        <td><tt>%time%</tt></td>
+        <td class="td_left">If your command accepts the <tt>-time-passes</tt> 
+          option, use this substitution token. If the user requested 
+          <tt>-time-passes</tt> from the <tt>llvmc</tt> command line then this 
+          token will be replaced with <tt>-time-passes</tt>, otherwise it will 
+          be ignored.
+        </td>
+      </tr>
+    </tbody>

   </table>
 </div>
 
   </table>
 </div>
 

+<!-- _______________________________________________________________________ -->
+<div class="doc_subsection"><a name="sample">Sample Config File</a></div>
+<div class="doc_text">
+  <p>Since an example is always instructive, here's how the Stacker language
+  configuration file looks.</p>
+  <pre><tt>
+# Stacker Configuration File For llvmc
+
+##########################################################
+# Language definitions
+##########################################################
+  lang.name=Stacker 
+  lang.opt1=-simplifycfg -instcombine -mem2reg
+  lang.opt2=-simplifycfg -instcombine -mem2reg -load-vn \
+    -gcse -dse -scalarrepl -sccp 
+  lang.opt3=-simplifycfg -instcombine -mem2reg -load-vn \
+    -gcse -dse -scalarrepl -sccp -branch-combine -adce \
+    -globaldce -inline -licm 
+  lang.opt4=-simplifycfg -instcombine -mem2reg -load-vn \
+    -gcse -dse -scalarrepl -sccp -ipconstprop \
+    -branch-combine -adce -globaldce -inline -licm 
+  lang.opt5=-simplifycfg -instcombine -mem2reg --load-vn \
+    -gcse -dse scalarrepl -sccp -ipconstprop \
+    -branch-combine -adce -globaldce -inline -licm \
+    -block-placement
+
+##########################################################
+# Pre-processor definitions
+##########################################################
+
+  # Stacker doesn't have a preprocessor but the following
+  # allows the -E option to be supported
+  preprocessor.command=cp %in% %out%
+  preprocessor.required=false
+
+##########################################################
+# Translator definitions
+##########################################################
+
+  # 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% %force% %args%
+
+  # stkrc doesn't preprocess but we set this to true so
+  # that we don't run the cp command by default.
+  translator.preprocesses=true
+
+  # The translator is required to run.
+  translator.required=true
+
+  # stkrc doesn't handle the -On options
+  translator.output=bytecode
+
+##########################################################
+# Optimizer definitions
+##########################################################
+  
+  # For optimization, we use the LLVM "opt" program
+  optimizer.command=opt %in% -o %out% %opt% %time% %stats% \
+    %force% %args%
+
+  optimizer.required = true
+
+  # opt doesn't translate
+  optimizer.translates = no
+
+  # opt doesn't preprocess
+  optimizer.preprocesses=no
+
+  # opt produces bytecode
+  optimizer.output = bc
+
+##########################################################
+# Assembler definitions
+##########################################################
+  assembler.command=llc %in% -o %out% %target% %time% %stats%
+</tt></pre>
+</div> 
+

 <!-- *********************************************************************** -->
 <div class="doc_section"><a name="glossary">Glossary</a></div>
 <!-- *********************************************************************** -->
 <!-- *********************************************************************** -->
 <div class="doc_section"><a name="glossary">Glossary</a></div>
 <!-- *********************************************************************** -->


@@ -501,7 +814,7 @@ optimization.</p>
  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>
  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
 Last modified: $Date$
 </address>
 <!-- vim: sw=2