docs/CompilerDriver.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   5   <title>The LLVM Compiler Driver (llvmc)</title>
   6   <link rel="stylesheet" href="llvm.css" type="text/css">
   7   <meta name="author" content="Reid Spencer">
   8   <meta name="description"
   9   content="A description of the use and design of the LLVM Compiler Driver.">
  10 </head>
  11 <body>
  12 <div class="doc_title">The LLVM Compiler Driver (llvmc)</div>
  13 <p class="doc_warning">NOTE: This document is a work in progress!</p>
  14 <ol>
  15   <li><a href="#abstract">Abstract</a></li>
  16   <li><a href="#introduction">Introduction</a>
  17     <ol>
  18       <li><a href="#purpose">Purpose</a></li>
  19       <li><a href="#operation">Operation</a></li>
  20       <li><a href="#phases">Phases</a></li>
  21       <li><a href="#actions">Actions</a></li>
  22     </ol>
  23   </li>
  24   <li><a href="#configuration">Configuration</a>
  25     <ol>
  26       <li><a href="#overview">Overview</a></li>
  27       <li><a href="#filetypes">Configuration Files</a></li>
  28       <li><a href="#syntax">Syntax</a></li>
  29       <li><a href="#substitutions">Substitutions</a></li>
  30       <li><a href="#sample">Sample Config File</a></li>
  31     </ol>
  32   <li><a href="#glossary">Glossary</a>
  33 </ol>
  34 <div class="doc_author">
  35 <p>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a>
  36 </p>
  37 </div>
  38
  39 <!-- *********************************************************************** -->
  40 <div class="doc_section"> <a name="abstract">Abstract</a></div>
  41 <!-- *********************************************************************** -->
  42 <div class="doc_text">
  43   <p>This document describes the requirements, design, and configuration of the
  44   LLVM compiler driver, <tt>llvmc</tt>.  The compiler driver knows about LLVM's
  45   tool set and can be configured to know about a variety of compilers for
  46   source languages.  It uses this knowledge to execute the tools necessary
  47   to accomplish general compilation, optimization, and linking tasks. The main
  48   purpose of <tt>llvmc</tt> is to provide a simple and consistent interface to
  49   all compilation tasks. This reduces the burden on the end user who can just
  50   learn to use <tt>llvmc</tt> instead of the entire LLVM tool set and all the
  51   source language compilers compatible with LLVM.</p>
  52 </div>
  53 <!-- *********************************************************************** -->
  54 <div class="doc_section"> <a name="introduction">Introduction</a></div>
  55 <!-- *********************************************************************** -->
  56 <div class="doc_text">
  57   <p>The <tt>llvmc</tt> <a href="#def_tool">tool</a> is a configurable compiler
  58   <a href="#def_driver">driver</a>. As such, it isn't a compiler, optimizer,
  59   or a linker itself but it drives (invokes) other software that perform those
  60   tasks. If you are familiar with the GNU Compiler Collection's <tt>gcc</tt>
  61   tool, <tt>llvmc</tt> is very similar.</p>
  62   <p>The following introductory sections will help you understand why this tool
  63   is necessary and what it does.</p>
  64 </div>
  65
  66 <!-- _______________________________________________________________________ -->
  67 <div class="doc_subsection"><a name="purpose">Purpose</a></div>
  68 <div class="doc_text">
  69   <p><tt>llvmc</tt> was invented to make compilation of user programs with
  70   LLVM-based tools easier. To accomplish this, <tt>llvmc</tt> strives to:</p>
  71   <ul>
  72     <li>Be the single point of access to most of the LLVM tool set.</li>
  73     <li>Hide the complexities of the LLVM tools through a single interface.</li>
  74     <li>Provide a consistent interface for compiling all languages.</li>
  75   </ul>
  76   <p>Additionally, <tt>llvmc</tt> makes it easier to write a compiler for use
  77   with LLVM, because it:</p>
  78   <ul>
  79     <li>Makes integration of existing non-LLVM tools simple.</li>
  80     <li>Extends the capabilities of minimal compiler tools by optimizing their
  81     output.</li>
  82     <li>Reduces the number of interfaces a compiler writer must know about
  83     before a working compiler can be completed (essentially only the VMCore
  84     interfaces need to be understood).</li>
  85     <li>Supports source language translator invocation via both dynamically
  86     loadable shared objects and invocation of an executable.</li>
  87   </ul>
  88 </div>
  89
  90 <!-- _______________________________________________________________________ -->
  91 <div class="doc_subsection"><a name="operation">Operation</a></div>
  92 <div class="doc_text">
  93   <p>At a high level, <tt>llvmc</tt> operation is very simple.  The basic action
  94   taken by <tt>llvmc</tt> is to simply invoke some tool or set of tools to fill
  95   the user's request for compilation. Every execution of <tt>llvmc</tt>takes the
  96   following sequence of steps:</p>
  97   <dl>
  98     <dt><b>Collect Command Line Options</b></dt>
  99     <dd>The command line options provide the marching orders to <tt>llvmc</tt>
 100     on what actions it should perform. This is the request the user is making
 101     of <tt>llvmc</tt> and it is interpreted first. See the <tt>llvmc</tt>
 102     <a href="CommandGuide/html/llvmc.html">manual page</a> for details on the
 103     options.</dd>
 104     <dt><b>Read Configuration Files</b></dt>
 105     <dd>Based on the options and the suffixes of the filenames presented, a set
 106     of configuration files are read to configure the actions <tt>llvmc</tt> will
 107     take.  Configuration files are provided by either LLVM or the
 108     compiler tools that <tt>llvmc</tt> invokes. These files determine what
 109     actions <tt>llvmc</tt> will take in response to the user's request. See
 110     the section on <a href="#configuration">configuration</a> for more details.
 111     </dd>
 112     <dt><b>Determine Phases To Execute</b></dt>
 113     <dd>Based on the command line options and configuration files,
 114     <tt>llvmc</tt> determines the compilation <a href="#phases">phases</a> that
 115     must be executed by the user's request. This is the primary work of
 116     <tt>llvmc</tt>.</dd>
 117     <dt><b>Determine Actions To Execute</b></dt>
 118     <dd>Each <a href="#phases">phase</a> to be executed can result in the
 119     invocation of one or more <a href="#actions">actions</a>. An action is
 120     either a whole program or a function in a dynamically linked shared library.
 121     In this step, <tt>llvmc</tt> determines the sequence of actions that must be
 122     executed. Actions will always be executed in a deterministic order.</dd>
 123     <dt><b>Execute Actions</b></dt>
 124     <dd>The <a href="#actions">actions</a> necessary to support the user's
 125     original request are executed sequentially and deterministically. All
 126     actions result in either the invocation of a whole program to perform the
 127     action or the loading of a dynamically linkable shared library and invocation
 128     of a standard interface function within that library.</dd>
 129     <dt><b>Termination</b></dt>
 130     <dd>If any action fails (returns a non-zero result code), <tt>llvmc</tt>
 131     also fails and returns the result code from the failing action. If
 132     everything succeeds, <tt>llvmc</tt> will return a zero result code.</dd>
 133   </dl>
 134   <p><tt>llvmc</tt>'s operation must be simple, regular and predictable.
 135   Developers need to be able to rely on it to take a consistent approach to
 136   compilation. For example, the invocation:</p>
 137   <code>
 138     llvmc -O2 x.c y.c z.c -o xyz</code>
 139   <p>must produce <i>exactly</i> the same results as:</p>
 140   <pre><tt>
 141     llvmc -O2 x.c -o x.o
 142     llvmc -O2 y.c -o y.o
 143     llvmc -O2 z.c -o z.o
 144     llvmc -O2 x.o y.o z.o -o xyz</tt></pre>
 145   <p>To accomplish this, <tt>llvmc</tt> uses a very simple goal oriented
 146   procedure to do its work. The overall goal is to produce a functioning
 147   executable. To accomplish this, <tt>llvmc</tt> always attempts to execute a
 148   series of compilation <a href="#def_phase">phases</a> in the same sequence.
 149   However, the user's options to <tt>llvmc</tt> can cause the sequence of phases
 150   to start in the middle or finish early.</p>
 151 </div>
 152
 153 <!-- _______________________________________________________________________ -->
 154 <div class="doc_subsection"><a name="phases"></a>Phases </div>
 155 <div class="doc_text">
 156   <p><tt>llvmc</tt> breaks every compilation task into the following five
 157   distinct phases:</p>
 158   <dl><dt><b>Preprocessing</b></dt><dd>Not all languages support preprocessing;
 159     but for those that do, this phase can be invoked. This phase is for
 160     languages that provide combining, filtering, or otherwise altering with the
 161     source language input before the translator parses it. Although C and C++
 162     are the most common users of this phase, other languages may provide their
 163     own preprocessor (whether its the C pre-processor or not).</dd>
 164   </dl>
 165   <dl><dt><b>Translation</b></dt><dd>The translation phase converts the source
 166     language input into something that LLVM can interpret and use for
 167     downstream phases. The translation is essentially from "non-LLVM form" to
 168     "LLVM form".</dd>
 169   </dl>
 170   <dl><dt><b>Optimization</b></dt><dd>Once an LLVM Module has been obtained from
 171     the translation phase, the program enters the optimization phase. This phase
 172     attempts to optimize all of the input provided on the command line according
 173     to the options provided.</dd>
 174   </dl>
 175   <dl><dt><b>Linking</b></dt><dd>The inputs are combined to form a complete
 176     program.</dd>
 177   </dl>
 178   <p>The following table shows the inputs, outputs, and command line options
 179   applicabe to each phase.</p>
 180   <table>
 181     <tr>
 182       <th style="width: 10%">Phase</th>
 183       <th style="width: 25%">Inputs</th>
 184       <th style="width: 25%">Outputs</th>
 185       <th style="width: 40%">Options</th>
 186     </tr>
 187     <tr><td><b>Preprocessing</b></td>
 188       <td class="td_left"><ul><li>Source Language File</li></ul></td>
 189       <td class="td_left"><ul><li>Source Language File</li></ul></td>
 190       <td class="td_left"><dl>
 191           <dt><tt>-E</tt></dt>
 192           <dd>Stops the compilation after preprocessing</dd>
 193       </dl></td>
 194     </tr>
 195     <tr>
 196       <td><b>Translation</b></td>
 197       <td class="td_left"><ul>
 198           <li>Source Language File</li>
 199       </ul></td>
 200       <td class="td_left"><ul>
 201           <li>LLVM Assembly</li>
 202           <li>LLVM Bytecode</li>
 203           <li>LLVM C++ IR</li>
 204       </ul></td>
 205       <td class="td_left"><dl>
 206           <dt><tt>-c</tt></dt>
 207           <dd>Stops the compilation after translation so that optimization and
 208           linking are not done.</dd>
 209           <dt><tt>-S</tt></dt>
 210           <dd>Stops the compilation before object code is written so that only
 211           assembly code remains.</dd>
 212       </dl></td>
 213     </tr>
 214     <tr>
 215       <td><b>Optimization</b></td>
 216       <td class="td_left"><ul>
 217           <li>LLVM Assembly</li>
 218           <li>LLVM Bytecode</li>
 219       </ul></td>
 220       <td class="td_left"><ul>
 221           <li>LLVM Bytecode</li>
 222       </ul></td>
 223       <td class="td_left"><dl>
 224           <dt><tt>-Ox</tt>
 225           <dd>This group of options controls the amount of optimization
 226           performed.</dd>
 227       </dl></td>
 228     </tr>
 229     <tr>
 230       <td><b>Linking</b></td>
 231       <td class="td_left"><ul>
 232           <li>LLVM Bytecode</li>
 233           <li>Native Object Code</li>
 234           <li>LLVM Library</li>
 235           <li>Native Library</li>
 236       </ul></td>
 237       <td class="td_left"><ul>
 238           <li>LLVM Bytecode Executable</li>
 239           <li>Native Executable</li>
 240       </ul></td>
 241       <td class="td_left"><dl>
 242           <dt><tt>-L</tt></dt><dd>Specifies a path for library search.</dd>
 243           <dt><tt>-l</tt></dt><dd>Specifies a library to link in.</dd>
 244       </dl></td>
 245     </tr>
 246   </table>
 247 </div>
 248
 249 <!-- _______________________________________________________________________ -->
 250 <div class="doc_subsection"><a name="actions"></a>Actions</div>
 251 <div class="doc_text">
 252   <p>An action, with regard to <tt>llvmc</tt> is a basic operation that it takes
 253   in order to fulfill the user's request. Each phase of compilation will invoke
 254   zero or more actions in order to accomplish that phase.</p>
 255   <p>Actions come in two forms:</p>
 256   <ul>
 257     <li>Invokable Executables</li>
 258     <li>Functions in a shared library</li>
 259   </ul>
 260 </div>
 261
 262 <!-- *********************************************************************** -->
 263 <div class="doc_section"><a name="configuration">Configuration</a></div>
 264 <!-- *********************************************************************** -->
 265 <div class="doc_text">
 266   <p>This section of the document describes the configuration files used by
 267   <tt>llvmc</tt>.  Configuration information is relatively static for a
 268   given release of LLVM and a compiler tool. However, the details may
 269   change from release to release of either.  Users are encouraged to simply use
 270   the various options of the <tt>llvmc</tt> command and ignore the configuration
 271   of the tool. These configuration files are for compiler writers and LLVM
 272   developers. Those wishing to simply use <tt>llvmc</tt> don't need to understand
 273   this section but it may be instructive on how the tool works.</p>
 274 </div>
 275
 276 <!-- _______________________________________________________________________ -->
 277 <div class="doc_subsection"><a name="overview"></a>Overview</div>
 278 <div class="doc_text">
 279 <p><tt>llvmc</tt> is highly configurable both on the command line and in
 280 configuration files. The options it understands are generic, consistent and
 281 simple by design.  Furthermore, the <tt>llvmc</tt> options apply to the
 282 compilation of any LLVM enabled programming language. To be enabled as a
 283 supported source language compiler, a compiler writer must provide a
 284 configuration file that tells <tt>llvmc</tt> how to invoke the compiler
 285 and what its capabilities are. The purpose of the configuration files then
 286 is to allow compiler writers to specify to <tt>llvmc</tt> how the compiler
 287 should be invoked. Users may but are not advised to alter the compiler's
 288 <tt>llvmc</tt> configuration.</p>
 289
 290 <p>Because <tt>llvmc</tt> just invokes other programs, it must deal with the
 291 available command line options for those programs regardless of whether they
 292 were written for LLVM or not. Furthermore, not all compiler tools will
 293 have the same capabilities. Some compiler tools will simply generate LLVM assembly
 294 code, others will be able to generate fully optimized byte code. In general,
 295 <tt>llvmc</tt> doesn't make any assumptions about the capabilities or command
 296 line options of a sub-tool. It simply uses the details found in the
 297 configuration files and leaves it to the compiler writer to specify the
 298 configuration correctly.</p>
 299
 300 <p>This approach means that new compiler tools can be up and working very
 301 quickly. As a first cut, a tool can simply compile its source to raw
 302 (unoptimized) bytecode or LLVM assembly and <tt>llvmc</tt> can be configured
 303 to pick up the slack (translate LLVM assembly to bytecode, optimize the
 304 bytecode, generate native assembly, link, etc.).   In fact, the compiler tools
 305 need not use any LLVM libraries, and it could be written in any language
 306 (instead of C++).  The configuration data will allow the full range of
 307 optimization, assembly, and linking capabilities that LLVM provides to be added
 308 to these kinds of tools.  Enabling the rapid development of front-ends is one
 309 of the primary goals of <tt>llvmc</tt>.</p>
 310
 311 <p>As a compiler tool matures, it may utilize the LLVM libraries and tools
 312 to more efficiently produce optimized bytecode directly in a single compilation
 313 and optimization program. In these cases, multiple tools would not be needed
 314 and the configuration data for the compiler would change.</p>
 315
 316 <p>Configuring <tt>llvmc</tt> to the needs and capabilities of a source language
 317 compiler is relatively straight-forward.  A compiler writer must provide a
 318 definition of what to do for each of the five compilation phases for each of
 319 the optimization levels. The specification consists simply of prototypical
 320 command lines into which <tt>llvmc</tt> can substitute command line
 321 arguments and file names. Note that any given phase can be completely blank if
 322 the source language's compiler combines multiple phases into a single program.
 323 For example, quite often pre-processing, translation, and optimization are
 324 combined into a single program. The specification for such a compiler would have
 325 blank entries for pre-processing and translation but a full command line for
 326 optimization.</p>
 327 </div>
 328
 329 <!-- _______________________________________________________________________ -->
 330 <div class="doc_subsection"><a name="filetypes">Configuration Files</a></div>
 331 <div class="doc_subsubsection"><a name="filecontents">File Contents</a></div>
 332 <div class="doc_text">
 333   <p>Each configuration file provides the details for a single source language
 334   that is to be compiled.  This configuration information tells <tt>llvmc</tt>
 335   how to invoke the language's pre-processor, translator, optimizer, assembler
 336   and linker. Note that a given source language needn't provide all these tools
 337   as many of them exist in llvm currently.</p>
 338 </div>
 339 <div class="doc_subsubsection"><a name="dirsearch">Directory Search</a></div>
 340 <div class="doc_text">
 341   <p><tt>llvmc</tt> always looks for files of a specific name. It uses the
 342   first file with the name its looking for by searching directories in the
 343   following order:<br/>
 344   <ol>
 345     <li>Any directory specified by the <tt>-config-dir</tt> option will be
 346     checked first.</li>
 347     <li>If the environment variable LLVM_CONFIG_DIR is set, and it contains
 348     the name of a valid directory, that directory will be searched next.</li>
 349     <li>If the user's home directory (typically <tt>/home/user</tt> contains
 350     a sub-directory named <tt>.llvm</tt> and that directory contains a
 351     sub-directory named <tt>etc</tt> then that directory will be tried
 352     next.</li>
 353     <li>If the LLVM installation directory (typically <tt>/usr/local/llvm</tt>
 354     contains a sub-directory named <tt>etc</tt> then that directory will be
 355     tried last.</li>
 356     <li>A standard "system" directory will be searched next. This is typically
 357     <tt>/etc/llvm</tt> on UNIX&trade; and <tt>C:\WINNT</tt> on Microsoft
 358     Windows&trade;.</li>
 359     <li>If the configuration file sought still can't be found, <tt>llvmc</tt>
 360     will print an error message and exit.</li>
 361   </ol>
 362   <p>The first file found in this search will be used. Other files with the
 363   same name will be ignored even if they exist in one of the subsequent search
 364   locations.</p>
 365 </div>
 366
 367 <div class="doc_subsubsection"><a name="filenames">File Names</a></div>
 368 <div class="doc_text">
 369   <p>In the directories searched, each configuration file is given a specific
 370   name to foster faster lookup (so llvmc doesn't have to do directory searches).
 371   The name of a given language specific configuration file is simply the same
 372   as the suffix used to identify files containing source in that language.
 373   For example, a configuration file for C++ source might be named
 374   <tt>cpp</tt>, <tt>C</tt>, or <tt>cxx</tt>. For languages that support multiple
 375   file suffixes, multiple (probably identical) files (or symbolic links) will
 376   need to be provided.</p>
 377 </div>
 378
 379 <div class="doc_subsubsection"><a name="whatgetsread">What Gets Read</a></div>
 380 <div class="doc_text">
 381   <p>Which configuration files are read depends on the command line options and
 382   the suffixes of the file names provided on <tt>llvmc</tt>'s command line. Note
 383   that the <tt>-x LANGUAGE</tt> option alters the language that <tt>llvmc</tt>
 384   uses for the subsequent files on the command line.  Only the configuration
 385   files actually needed to complete <tt>llvmc</tt>'s task are read. Other
 386   language specific files will be ignored.</p>
 387 </div>
 388
 389 <!-- _______________________________________________________________________ -->
 390 <div class="doc_subsection"><a name="syntax"></a>Syntax</div>
 391 <div class="doc_text">
 392   <p>The syntax of the configuration files is very simple and somewhat
 393   compatible with Java's property files. Here are the syntax rules:</p>
 394   <ul>
 395     <li>The file encoding is ASCII.</li>
 396     <li>The file is line oriented. There should be one configuration definition
 397     per line. Lines are terminated by the newline (0x0A) and/or carriage return
 398     characters (0x0D)</li>
 399     <li>A backslash (<tt>\</tt>) before a newline causes the newline to be
 400     ignored. This is useful for line continuation of long definitions. A
 401     backslash anywhere else is recognized as a backslash.</li>
 402     <li>A configuration item consists of a name, an <tt>=</tt> and a value.</li>
 403     <li>A name consists of a sequence of identifiers separated by period.</li>
 404     <li>An identifier consists of specific keywords made up of only lower case
 405     and upper case letters (e.g. <tt>lang.name</tt>).</li>
 406     <li>Values come in four flavors: booleans, integers, commands and
 407     strings.</li>
 408     <li>Valid "false" boolean values are <tt>false False FALSE no No NO
 409       off Off</tt> and <tt>OFF</tt>.</li>
 410     <li>Valid "true" boolean values are <tt>true True TRUE yes Yes YES
 411       on On</tt> and <tt>ON</tt>.</li>
 412     <li>Integers are simply sequences of digits.</li>
 413     <li>Commands start with a program name and are followed by a sequence of
 414     words that are passed to that program as command line arguments. Program
 415     arguments that begin and end with the <tt>%</tt> sign will have their value
 416     substituted. Program names beginning with <tt>/</tt> are considered to be
 417     absolute. Otherwise the <tt>PATH</tt> will be applied to find the program to
 418     execute.</li>
 419     <li>Strings are composed of multiple sequences of characters from the
 420     character class <tt>[-A-Za-z0-9_:%+/\\|,]</tt> separated by white
 421     space.</li>
 422     <li>White space on a line is folded. Multiple blanks or tabs will be
 423     reduced to a single blank.</li>
 424     <li>White space before the configuration item's name is ignored.</li>
 425     <li>White space on either side of the <tt>=</tt> is ignored.</li>
 426     <li>White space in a string value is used to separate the individual
 427     components of the string value but otherwise ignored.</li>
 428     <li>Comments are introduced by the <tt>#</tt> character. Everything after a
 429     <tt>#</tt> and before the end of line is ignored.</li>
 430   </ul>
 431 </div>
 432
 433 <!-- _______________________________________________________________________ -->
 434 <div class="doc_subsection"><a name="items">Configuration Items</a></div>
 435 <div class="doc_text">
 436   <p>The table below provides definitions of the allowed configuration items
 437   that may appear in a configuration file. Every item has a default value and
 438   does not need to appear in the configuration file. Missing items will have the
 439   default value. Each identifier may appear as all lower case, first letter
 440   capitalized or all upper case.</p>
 441   <table>
 442     <tbody>
 443       <tr>
 444         <th>Name</th>
 445         <th>Value Type</th>
 446         <th>Description</th>
 447         <th>Default</th>
 448       </tr>
 449       <tr><td colspan="4"><h4>LLVMC ITEMS</h4></td></tr>
 450       <tr>
 451         <td><b>version</b></td>
 452         <td>string</td>
 453         <td class="td_left">Provides the version string for the contents of this
 454           configuration file. What is accepted as a legal configuration file
 455           will change over time and this item tells <tt>llvmc</tt> which version
 456           should be expected.</td>
 457         <td><i>b</i></td>
 458       </tr>
 459       <tr><td colspan="4"><h4>LANG ITEMS</h4></td></tr>
 460       <tr>
 461         <td><b>lang.name</b></td>
 462         <td>string</td>
 463         <td class="td_left">Provides the common name for a language definition.
 464           For example "C++", "Pascal", "FORTRAN", etc.</td>
 465         <td><i>blank</i></td>
 466       </tr>
 467       <tr>
 468         <td><b>lang.opt1</b></td>
 469         <td>string</td>
 470         <td class="td_left">Specifies the parameters to give the optimizer when
 471           <tt>-O1</tt> is specified on the <tt>llvmc</tt> command line.</td>
 472         <td><tt>-simplifycfg -instcombine -mem2reg</tt></td>
 473       </tr>
 474       <tr>
 475         <td><b>lang.opt2</b></td>
 476         <td>string</td>
 477         <td class="td_left">Specifies the parameters to give the optimizer when
 478           <tt>-O2</tt> is specified on the <tt>llvmc</tt> command line.</td>
 479         <td><i>TBD</i></td>
 480       </tr>
 481       <tr>
 482         <td><b>lang.opt3</b></td>
 483         <td>string</td>
 484         <td class="td_left">Specifies the parameters to give the optimizer when
 485           <tt>-O3</tt> is specified on the <tt>llvmc</tt> command line.</td>
 486         <td><i>TBD</i></td>
 487       </tr>
 488       <tr>
 489         <td><b>lang.opt4</b></td>
 490         <td>string</td>
 491         <td class="td_left">Specifies the parameters to give the optimizer when
 492           <tt>-O4</tt> is specified on the <tt>llvmc</tt> command line.</td>
 493         <td><i>TBD</i></td>
 494       </tr>
 495       <tr>
 496         <td><b>lang.opt5</b></td>
 497         <td>string</td>
 498         <td class="td_left">Specifies the parameters to give the optimizer when
 499           <tt>-O5</tt> is specified on the <tt>llvmc</tt> command line.</td>
 500         <td><i>TBD</i></td>
 501       </tr>
 502       <tr><td colspan="4"><h4>PREPROCESSOR ITEMS</h4></td></tr>
 503       <tr>
 504         <td><b>preprocessor.command</b></td>
 505         <td>command</td>
 506         <td class="td_left">This provides the command prototype that will be used
 507           to run the preprocessor.  This is generally only used with the
 508           <tt>-E</tt> option.</td>
 509         <td>&lt;blank&gt;</td>
 510       </tr>
 511       <tr>
 512         <td><b>preprocessor.required</b></td>
 513         <td>boolean</td>
 514         <td class="td_left">This item specifies whether the pre-processing phase
 515           is required by the language. If the value is true, then the
 516           <tt>preprocessor.command</tt> value must not be blank. With this option,
 517           <tt>llvmc</tt> will always run the preprocessor as it assumes that the
 518           translation and optimization phases don't know how to pre-process their
 519           input.</td>
 520         <td>false</td>
 521       </tr>
 522       <tr><td colspan="4"><h4>TRANSLATOR ITEMS</h4></td></tr>
 523       <tr>
 524         <td><b>translator.command</b></td>
 525         <td>command</td>
 526         <td class="td_left">This provides the command prototype that will be used
 527           to run the translator. Valid substitutions are <tt>%in%</tt> for the
 528           input file and <tt>%out%</tt> for the output file.</td>
 529         <td>&lt;blank&gt;</td>
 530       </tr>
 531       <tr>
 532         <td><b>translator.output</b></td>
 533         <td><tt>bytecode</tt> or <tt>assembly</tt></td>
 534         <td class="td_left">This item specifies the kind of output the language's
 535           translator generates.</td>
 536         <td><tt>bytecode</tt></td>
 537       </tr>
 538       <tr>
 539         <td><b>translator.preprocesses</b></td>
 540         <td>boolean</td>
 541         <td class="td_left">Indicates that the translator also preprocesses. If
 542           this is true, then <tt>llvmc</tt> will skip the pre-processing phase
 543           whenever the final phase is not pre-processing.</td>
 544         <td><tt>false</tt></td>
 545       </tr>
 546       <tr><td colspan="4"><h4>OPTIMIZER ITEMS</h4></td></tr>
 547       <tr>
 548         <td><b>optimizer.command</b></td>
 549         <td>command</td>
 550         <td class="td_left">This provides the command prototype that will be used
 551           to run the optimizer. Valid substitutions are <tt>%in%</tt> for the
 552           input file and <tt>%out%</tt> for the output file.</td>
 553         <td>&lt;blank&gt;</td>
 554       </tr>
 555       <tr>
 556         <td><b>optimizer.output</b></td>
 557         <td><tt>bytecode</tt> or <tt>assembly</tt></td>
 558         <td class="td_left">This item specifies the kind of output the language's
 559           optimizer generates. Valid values are "assembly" and "bytecode"<td>
 560         <td><tt>bytecode</tt></td>
 561       </tr>
 562       <tr>
 563         <td><b>optimizer.preprocesses</b></td>
 564         <td>boolean</td>
 565         <td class="td_left">Indicates that the optimizer also preprocesses. If
 566           this is true, then <tt>llvmc</tt> will skip the pre-processing phase
 567           whenever the final phase is optimization or later.</td>
 568         <td><tt>false</tt></td>
 569       </tr>
 570       <tr>
 571         <td><b>optimizer.translates</b></td>
 572         <td>boolean</td>
 573         <td class="td_left">Indicates that the optimizer also translates. If
 574           this is true, then <tt>llvmc</tt> will skip the translation phase
 575           whenever the final phase is optimization or later.</td>
 576         <td><tt>false</tt></td>
 577       </tr>
 578       <tr><td colspan="4"><h4>ASSEMBLER ITEMS</h4></td></tr>
 579       <tr>
 580         <td><b>assembler.command</b></td>
 581         <td>command</td>
 582         <td class="td_left">This provides the command prototype that will be used
 583           to run the assembler. Valid substitutions are <tt>%in%</tt> for the
 584           input file and <tt>%out%</tt> for the output file.</td>
 585         <td>&lt;blank&gt;</td>
 586       </tr>
 587     </tbody>
 588   </table>
 589 </div>
 590
 591 <!-- _______________________________________________________________________ -->
 592 <div class="doc_subsection"><a name="substitutions">Substitutions</a></div>
 593 <div class="doc_text">
 594   <p>On any configruation item that ends in <tt>command</tt>, you must
 595   specify substitution tokens.  Substitution tokens begin and end with a percent
 596   sign (<tt>%</tt>) and are replaced by the corresponding text. Any substitution
 597   token may be given on any <tt>command</tt> line but some are more useful than
 598   others. In particular each command <em>should</em> have both an <tt>%in%</tt>
 599   and an <tt>%out%</tt> substittution. The table below provides definitions of
 600   each of the allowed substitution tokens.</p>
 601   <table>
 602     <tbody>
 603       <tr>
 604         <th>Substitution Token</th>
 605         <th>Replacement Description</th>
 606       </tr>
 607       <tr>
 608         <td><tt>%args%</tt></td>
 609         <td class="td_left">Replaced with all the tool-specific arguments given
 610           to <tt>llvmc</tt> via the <tt>-T</tt> set of options. This just allows
 611           you to place these arguments in the correct place on the command line.
 612           If the <tt>%args%</tt> option does not appear on your command line,
 613           then you are explicitly disallowing the <tt>-T</tt> option for your
 614           tool.
 615         </td>
 616       <tr>
 617         <td><tt>%force%</tt></td>
 618         <td class="td_left">Replaced with the <tt>-f</tt> option if it was
 619           specified on the <tt>llvmc</tt> command line. This is intended to tell
 620           the compiler tool to force the overwrite of output files.
 621         </td>
 622       </tr>
 623       <tr>
 624         <td><tt>%in%</tt></td>
 625         <td class="td_left">Replaced with the full path of the input file. You
 626           needn't worry about the cascading of file names. <tt>llvmc</tt> will
 627           create temporary files and ensure that the output of one phase is the
 628           input to the next phase.</td>
 629       </tr>
 630       <tr>
 631         <td><tt>%opt%</tt></td>
 632         <td class="td_left">Replaced with the optimization options for the
 633           tool. If the tool understands the <tt>-O</tt> options then that will
 634           be passed. Otherwise, the <tt>lang.optN</tt> series of configuration
 635           items will specify which arguments are to be given.</td>
 636       </tr>
 637       <tr>
 638         <td><tt>%out%</tt></td>
 639         <td class="td_left">Replaced with the full path of the output file.
 640           Note that this is not necessarily the output file specified with the
 641           <tt>-o</tt> option on <tt>llvmc</tt>'s command line. It might be a
 642           temporary file that will be passed to a subsequent phase's input.
 643         </td>
 644       </tr>
 645       <tr>
 646         <td><tt>%stats%</tt></td>
 647         <td class="td_left">If your command accepts the <tt>-stats</tt> option,
 648           use this substitution token. If the user requested <tt>-stats</tt>
 649           from the <tt>llvmc</tt> command line then this token will be replaced
 650           with <tt>-stats</tt>, otherwise it will be ignored.
 651         </td>
 652       </tr>
 653       <tr>
 654         <td><tt>%target%</tt></td>
 655         <td class="td_left">Replaced with the name of the target "machine" for
 656           which code should be generated. The value used here is taken from the
 657           <tt>llvmc</tt> option <tt>-march</tt>.
 658         </td>
 659       </tr>
 660       <tr>
 661         <td><tt>%time%</tt></td>
 662         <td class="td_left">If your command accepts the <tt>-time-passes</tt>
 663           option, use this substitution token. If the user requested
 664           <tt>-time-passes</tt> from the <tt>llvmc</tt> command line then this
 665           token will be replaced with <tt>-time-passes</tt>, otherwise it will
 666           be ignored.
 667         </td>
 668       </tr>
 669     </tbody>
 670   </table>
 671 </div>
 672
 673 <!-- _______________________________________________________________________ -->
 674 <div class="doc_subsection"><a name="sample">Sample Config File</a></div>
 675 <div class="doc_text">
 676   <p>Since an example is always instructive, here's how the Stacker language
 677   configuration file looks.</p>
 678   <pre><tt>
 679 # Stacker Configuration File For llvmc
 680
 681 ##########################################################
 682 # Language definitions
 683 ##########################################################
 684   lang.name=Stacker
 685   lang.opt1=-simplifycfg -instcombine -mem2reg
 686   lang.opt2=-simplifycfg -instcombine -mem2reg -load-vn \
 687     -gcse -dse -scalarrepl -sccp
 688   lang.opt3=-simplifycfg -instcombine -mem2reg -load-vn \
 689     -gcse -dse -scalarrepl -sccp -branch-combine -adce \
 690     -globaldce -inline -licm
 691   lang.opt4=-simplifycfg -instcombine -mem2reg -load-vn \
 692     -gcse -dse -scalarrepl -sccp -ipconstprop \
 693     -branch-combine -adce -globaldce -inline -licm
 694   lang.opt5=-simplifycfg -instcombine -mem2reg --load-vn \
 695     -gcse -dse scalarrepl -sccp -ipconstprop \
 696     -branch-combine -adce -globaldce -inline -licm \
 697     -block-placement
 698
 699 ##########################################################
 700 # Pre-processor definitions
 701 ##########################################################
 702
 703   # Stacker doesn't have a preprocessor but the following
 704   # allows the -E option to be supported
 705   preprocessor.command=cp %in% %out%
 706   preprocessor.required=false
 707
 708 ##########################################################
 709 # Translator definitions
 710 ##########################################################
 711
 712   # To compile stacker source, we just run the stacker
 713   # compiler with a default stack size of 2048 entries.
 714   translator.command=stkrc -s 2048 %in% -o %out% %time% \
 715     %stats% %force% %args%
 716
 717   # stkrc doesn't preprocess but we set this to true so
 718   # that we don't run the cp command by default.
 719   translator.preprocesses=true
 720
 721   # The translator is required to run.
 722   translator.required=true
 723
 724   # stkrc doesn't handle the -On options
 725   translator.output=bytecode
 726
 727 ##########################################################
 728 # Optimizer definitions
 729 ##########################################################
 730
 731   # For optimization, we use the LLVM "opt" program
 732   optimizer.command=opt %in% -o %out% %opt% %time% %stats% \
 733     %force% %args%
 734
 735   optimizer.required = true
 736
 737   # opt doesn't translate
 738   optimizer.translates = no
 739
 740   # opt doesn't preprocess
 741   optimizer.preprocesses=no
 742
 743   # opt produces bytecode
 744   optimizer.output = bc
 745
 746 ##########################################################
 747 # Assembler definitions
 748 ##########################################################
 749   assembler.command=llc %in% -o %out% %target% %time% %stats%
 750 </tt></pre>
 751
 752
 753 <!-- *********************************************************************** -->
 754 <div class="doc_section"><a name="glossary">Glossary</a></div>
 755 <!-- *********************************************************************** -->
 756 <div class="doc_text">
 757   <p>This document uses precise terms in reference to the various artifacts and
 758   concepts related to compilation. The terms used throughout this document are
 759   defined below.</p>
 760   <dl>
 761     <dt><a name="def_assembly"><b>assembly</b></a></dt>
 762     <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode or
 763     LLVM assembly code is assembled to a native code format (either target
 764     specific aseembly language or the platform's native object file format).
 765     </dd>
 766
 767     <dt><a name="def_compiler"><b>compiler</b></a></dt>
 768     <dd>Refers to any program that can be invoked by <tt>llvmc</tt> to accomplish
 769     the work of one or more compilation <a href="#def_phase">phases</a>.</dd>
 770
 771     <dt><a name="def_driver"><b>driver</b></a></dt>
 772     <dd>Refers to <tt>llvmc</tt> itself.</dd>
 773
 774     <dt><a name="def_linking"><b>linking</b></a></dt>
 775     <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode files
 776     and (optionally) native system libraries are combined to form a complete
 777     executable program.</dd>
 778
 779     <dt><a name="def_optimization"><b>optimization</b></a></dt>
 780     <dd>A compilation <a href="#def_phase">phase</a> in which LLVM bytecode is
 781     optimized.</dd>
 782
 783     <dt><a name="def_phase"><b>phase</b></a></dt>
 784     <dd>Refers to any one of the five compilation phases that that
 785     <tt>llvmc</tt> supports. The five phases are:
 786     <a href="#def_preprocessing">preprocessing</a>,
 787     <a href="#def_translation">translation</a>,
 788     <a href="#def_optimization">optimization</a>,
 789     <a href="#def_assembly">assembly</a>,
 790     <a href="#def_linking">linking</a>.</dd>
 791
 792     <dt><a name="def_sourcelanguage"><b>source language</b></a></dt>
 793     <dd>Any common programming language (e.g. C, C++, Java, Stacker, ML,
 794     FORTRAN).  These languages are distinguished from any of the lower level
 795     languages (such as LLVM or native assembly), by the fact that a
 796     <a href="#def_translation">translation</a> <a href="#def_phase">phase</a>
 797     is required before LLVM can be applied.</dd>
 798
 799     <dt><a name="def_tool"><b>tool</b></a></dt>
 800     <dd>Refers to any program in the LLVM tool set.</dd>
 801
 802     <dt><a name="def_translation"><b>translation</b></a></dt>
 803     <dd>A compilation <a href="#def_phase">phase</a> in which
 804     <a href="#def_sourcelanguage">source language</a> code is translated into
 805     either LLVM assembly language or LLVM bytecode.</dd>
 806   </dl>
 807 </div>
 808 <!-- *********************************************************************** -->
 809 <hr>
 810 <address> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 811  src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a><a
 812  href="http://validator.w3.org/check/referer"><img
 813  src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a><a
 814  href="mailto:rspencer@x10sys.com">Reid Spencer</a><br>
 815 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
 816 Last modified: $Date$
 817 </address>
 818 <!-- vim: sw=2
 819 -->
 820 </body>
 821 </html>