<!--#set var="title" value="Getting Started with HLVM" -->
<!--#include virtual="/incl/header.incl" -->
<h1>Getting Started with HLVM</h1>
<ol>
  <li><a href="#quickstart">Quick Start (For The Impatient)</a></li>
  <li><a href="#overview">Overview</a></li>
  <li><a href="#requirements">Requirements</a>
    <ol>
      <li><a href="#hardware">Hardware</a></li>
      <li><a href="#software">Software</a></li>
    </ol>
  </li>
  <li><a href="#other_packages">Building Other Packages</a>
    <ol>
      <li><a href="#SSIA">Single Separate Install Area</a></li>
      <li><a href="#apr">apr</a></li>
      <li><a href="#apr-util">apr-util</a></li>
      <li><a href="#llvm">llvm</a></li>
      <li><a href="#llvm-gcc4">llvm-gcc4</a></li>
      <li><a href="#gperf">gperf</a></li>
      <li><a href="#deja-gnu">deja-gnu/</a></li>
    </ol>
  </li>
  <li><a href="#building">Building HLVM With SCons</a>
    <ol>
      <li><a href="#quick">Quick Start</a></li>
      <li><a href="#about_scons">About SCons And HLVM</a></li>
      <li><a href="#scons_options">SCons Options Supported</a></li>
      <li><a href="#targets">Build Targets</a></li>
    </ol>
  </li>
  <li><a href="#make">Building HLVM With Make</a>
    <ol>
      <li><a href="#make_targets">Targets Supported</a></li>
      <li><a href="#tipsntricks">Tips And Tricks</a></li>
    </ol>
  </li>
</ol>

<div class="author">
  <p>Author: <a href="mailto:rspencer@reidspencer.com">Reid Spencer</a>.</p>
</div>

<h2><a name="quickstart"><b>Quick Start (For The Impatient)</b></a></h2>
<div class="text">
<p>Here's the quick start for getting up and running quickly with HLVM. Note
that this is for experts and the impatient only.</p>
<ol>
  <li>Read the documentation.</li>
  <li>Read the documentation.</li>
  <li>Remember that you were warned twice about reading the documentation.</li>
  <li>Obtain, build, and install the dependent packages. You need llvm, 
  llvm-gcc4, apr, apr-util, libxml2, scons, gperf, gcc, dejagnu, python, tcl,
  and expect.</li>
  <li>Obtain the HLVM Source Code
  (<a href="http://llvm.org/svn/llvm-project/hlvm/trunk">http://llvm.org/svn/llvm-project/hlvm/trunk</a>).</li>
  <li>Build hlvm with: <tt>scons -Q mode=debug confpath=/paths/to/pkgs</tt></li>
  <li>The configuration utility might ask you where your 3rd party software is
  located. Please enter the paths appropriately.</li>
  <li>Run the test suite with: <tt>scons -Q check</tt></li>
  <li>Install hlvm with: <tt>scons -Q mode=debug install 
    prefix=/path/to/put/hlvm</tt></li>
</ol>
</div>

<h2><a name="overview"><b>Overview</b></a></h2>
<div class="text">
<p>Welcome to HLVM! This document shows you how to get started with the High
Level Virtual Machine. Before you do that, lets get some questions answered up
front to make sure you actually want to get started with HLVM.</p>
<dl>
  <dt>What is HLVM?</dt>
  <dd>HLVM is a toolkit for building virtual machines for dynamic languages. Its
  not something everyone is going to want to mess with. Generally, it is highly
  technical and doesn't really do much for an end user. On the other hand, if
  you're developing your own dynamic programming language, HLVM is <em>just</em>
  the ticket.</dd>
  <dt>Who uses HLVM?</dt>
  <dd>Generally, programming language researchers and software tool vendors 
  use HLVM.</dd>
  <dt>What does HLVM do?</dt>
  <dd>HLVM doesn't really <em>do</em> anything. While it provides a few
  executables, these are ancillary in nature. Most of HLVM's capabilities are
  provided through a set of code libraries that can be incorporated into other
  programs. HLVM does provide a virtual machine executable but without a program
  to run (one that has been compiled by HLVM based tools), the virtual machine
  won't do anything. So, if you're an end user of software, HLVM probably isn't
  for you. If you're a developer, however, we think you'll find HLVM quite
  spiffy.</dd>
  <dt>How hard is HLVM to build?</dt>
  <dd>Although we've tried to make building HLVM dead simple, it is a
  complicated system and you must understand some of those complexities to get
  it right. One of its major complexities is that it incorporates many other
  packages that are not distributed with HLVM. You must build and install those
  packages yourself.</dd>
</dl>
<p>Okay, if you're still interested in HLVM, then we have a few more
introductory things to cover:</p>
<ol>
  <li>HLVM provides a suite of libraries and a few tools. These are statically
  linked (archive files and object files) so that you can incorporate the
  appropriate pieces into your project. This was done purposefully since we
  don't believe that creating a monolithic shared library (DLL) is particularly
  useful. This architecture gives you the freedom to construct your own
  libraries by picking the appropriate things from the palette that HLVM offers.
  </li>
  <li>Although HLVM provides several tools, these are ancillary in nature. They
  are provided to help either with testing HLVM or to help you use HLVM. The
  <tt>hlvm</tt> program (the actual virtual machine) is a reference
  implementation. You may choose to implement it differently (with the help of
  HLVM's runtime libraries, of course).</li>
</ol>
</div>

<h2><a name="requirements"><b>Requirements</b></a></h2>
<div class="text">
  <p>Before you attempt to build HLVM, you need to understand its requirements.
  HLVM is non-trivial and depends on a number of other software packages. These
  packages will be required before you can build HLVM. Taking
  a moment to familiarize yourself with HLVM's requirements may save you some 
  time in the long run.</p>
  <p>The table below shows the software that HLVM depends on. You <b>must</b> 
  obtain and build these packages yourself if they are not already present on 
  your system. HLVM won't compile or run without them.</p>

  <h3><a name="hardware">Hardware</a></h3>
  <p>HLVM supports whatever hardware LLVM supports. For details, please see
  <a href="http://llvm.org/docs/GettingStarted.html#hardware">LLVM's documentation</a></p>

  <h3><a name="software">Software</a></h3>
  <p>Compiling HLVM requires that you have several software packages installed. 
  The table below lists those required packages. The Package column is the usual
  name for the software package that HLVM depends on. The Version column 
  provides "known to work" versions of the package. The Notes column describes 
  how HLVM uses the package and provides other details.</p>
  <table>
    <tr><th>Package</th><th>Version</th><th>Notes</th></tr>
    <tr>
      <td><a href="http://gcc.gnu.org">gcc</a></td>
      <td>&ge;3.4.6 (4.1 recommended)</td>
      <td>C/C++ compiler for compiling HLVM.</td>
    </tr>
    <tr>
      <td><a href="http://llvm.org/">llvm</a>
        <a href="#sf1"><sup>1</sup></a></td>
      <td>1.8cvs</td>
      <td>Low Level Virtual Machine. This compler infrastructure provides the
        low level code generation and optimization, linking, bytecode, JIT,
        and other facilities HLVM needs.  LLVM is HLVM's sister project. 
        It handles all the low level details for</td>
    </tr>
    <tr>
      <td><a href="http://llvm.org/">llvm-gcc4</a>
        <a href="#sf1"><sup>1</sup></a></td>
      <td>4</td>
    <td>LLVM C/C++ Frontend, Version 4. This is a full GCC (Gnu Compiler 
      Collection) compiler but with extensions for generating code via LLVM 
      instead of GCC's normal RTL-based backend. This tool can compile C, C++,
      Objective-C and Objective-C++ languages into either native binary or
      LLVM bytecode. In either case, it utilizes LLVM's suite of passes for code
      optimization.</td>
    </tr>
    <tr>
      <td><a href="http://apr.apache.org/">apr</a></td>
      <td>1.2.7</td>
      <td>Apache Portable Runtime. APR is used as the portability layer to
        abstract away differences between the various operating systems that
        HLVM runs on. This simplifies the HLVM Runtime library implementation
        and also endows it with some robustness. It handles various OS 
        abstraction such as file I/O, threading, locking, loading, etc.</td>
    </tr>
    <tr>
      <td><a href="http://apr.apache.org/">apr-util</a></td>
      <td>1.2.7</td>
      <td>Apache Portable Runtime Utilities. Additional runtime utilities for
      DBM database access, code set conversion (iconv) and miscellaneous other
      utilities.</td>
    </tr>
    <tr>
      <td><a href="http://xmlsoft.org/downloads.html">libxml2</a></td>
      <td>2.6.24</td>
      <td>XML parsing and validation toolkit. This is used for reading and
        writing XML forms of the Abstract Syntax Tree. </td>
    </tr>
    <tr>
      <td><a href="http://www.gnu.org/software/gperf/">gperf</a></td>
      <td>2.7.2 (3.0.1 won't work)</td>
      <td>GNU Perfect Hash Function Generator. This is used for recognizing 
        element and attribute names in XML documents.</td>
    </tr>
    <tr>
      <td><a href="http://subversion.tigris.org/">subversion</a></td>
      <td>&ge;1.1</td>
      <td>Subversion source Subversion access to HLVM source repository.</td>
    </tr>
    <tr>
      <td><a href="http://scons.org/download.php">scons</a></td>
      <td>0.96.92</td>
      <td>Software Construction system used for HLVM's build system.</td>
    </tr>
    <tr>
      <td><a href="http://python.org/">python</a></td>
      <td>2.3</td>
      <td>Python programming language, required by scons</td>
    </tr>
    <tr>
      <td><a href="http://savannah.gnu.org/projects/dejagnu">dejagnu</a></td>
      <td>1.4.2</td>
      <td>Test suite automation package. You only need this if you want to
        run the automated test suite.</td>
    </tr>
    <tr>
      <td><a href="http://expect.nist.gov/">expect</a></td>
      <td>5.38.0</td>
      <td>Test scripting language. DejaGnu is based on this. You only need
        this if you want to run the automated test suite.</td>
    </tr>
    <tr>
      <td><a href="http://www.tcl.tk/software/tcltk/">tcl</a></td>
      <td>8.3, 8.4</td>
      <td>Test Control Language. Expect is based on this. You only need this if
      you want to run the automated test suite.</td>
    </tr>
    <tr>
      <td><a href="http://www.stack.nl/~dimitri/doxygen/">doxygen</a></td>
      <td>&ge;1.4.4<a href="#sf3"><sup>3</sup></a></td>
      <td>C/C++ automated documentation generator for building the XHTML
        documentation from the comments in the HLVM header files. You only need
      this if you intend to build the documentation.</td>
    </tr>
    <tr>
      <td><a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a></td>
      <td>&ge;2.6.24<a href="#sf3"><sup>3</sup></a></td>
      <td>XSLT Processor (comes with libxml2). This is used to transform the
        Relax NG schema for the HLVM Abstract Syntax Tree (AST) into 
        documentation that describes the AST. You only need this if you intend
        to build the documentation.</td>
    </tr>
  </table>

  <p><b>Notes:</b></p>
  <div class="notes">
  <ol>
    <li><a name="sf1"></a>Certain LLVM tools are being modified to accommodate 
    HLVM as it progresses. Until this situation stabilizes you will be required
      to have a very fresh (recent) version of LLVM from the CVS sources.  At 
      some point in the future, an LLVM release will contain all the features 
      that HLVM needs and this notice will be removed. Until then, you should 
      obtain and build LLVM from CVS and keep it up to date regularly.</li>
  </ol>
  </div>
  
  <p>Additionally, your compilation host is expected to have the usual Unix 
  utilities, specifically:</p>
  <ul>
    <li><b>ar</b> - archive library builder</li>
    <li><b>gzip*</b> - gzip command for distribution generation</li>
    <li><b>gunzip*</b> - gunzip command for distribution checking</li>
    <li><b>ranlib</b> - symbol table builder for archive libraries</li>
    <li><b>tar</b> - tape archive for distribution generation</li>
  </ul>
</div>

<!-- *********************************************************************** -->
<h2><a name="other_packages">Building Other Packages</a></h2>
<!-- *********************************************************************** -->
<div class="text">
  <h3><a name="SSIA">Single Separate Install Area</a></h3>
  <p>It is suggested that you keep a separate installation area for building the
  things upon which HLVM depends. This is the location in your file system where
  you will install the built packages. It is the parameter to the 
  <tt>--prefix</tt> options to the configure programs of those packages. By 
  using a separate install area, you ensure that the HLVM version of required 
  packages doesn't interfere with any of your system installed packages.</p>
  <h3><a name="libxml2">libxml2</a></h3>
  <ul>
    <li>If your system doesn't already have a modern version of libxml2, you can
    generally build this quite painlessly as it doesn't depend on much
    else.</li>
    <li>You need a modern version of this package, in the 2.6 series, in order
    to successfully build HLVM. HLVM uses the Relax/NG validator that was added
    and improved in the 2.6 series of releases. Reid used 2.6.24 to develop HLVM
    and you are advised to use that version or a later one.</li>
    <li>See the <tt>README</tt> file in the libxml2 root directory.</li>
    <li>Build with:<pre>
    ./configure --prefix=/where/to/install 
    make 
    make install</pre></li>
    <li>Use <tt>./configure --help</tt> to get a full list of libxml2's
    configuration options; it has many. Not everything libxml2 provides is
    needed. We need the parser, the textwriter and the relaxng validator.</li>
  </ul>
  <h3><a name="apr">apr</a></h3>
  <ul>
    <li>This package builds quite easily as well and doesn't depend on 
    anything other than your operating system.</li>
    <li>You need version 1.2.7 or later.</li>
    <li>See the <tt>README.dev</tt> for build instructions.</li>
    <li>Build with:<pre>
    ./buildconf    #generates the configure script
    ./configure --prefix=/where/to/install --enable-threads --enable-other-child
    make
    make install</pre></li>
    <li>Optionally use the <tt>--enable-debug</tt> configure flag for making
    debugging easier (and your HLVM programs run slower).</li>
  </ul>
  <h3><a name="apr-util">apr-util</a></h3>
  <ul>
    <li>This package builds quite easily and doesn't depend on much.</li>
    <li>Build with:<pre>
    ./buildconf    #generates the configure script
    ./configure --prefix=/where/to/install --with-apr=/path/to/apr
    make
    make install</pre></li>
    <li>apr-util provides ldap, dbm, and iconv services all of which HLVM will
    eventually use. apr-util's <tt>configure</tt> script will generally be able
    to figure out what your system has and use it. However, if it can't you
    might want to use the various <tt>--with-*</tt> options to tell apr-util
    where your packages are located.</li>
  </ul>
  <h3><a name="llvm">llvm</a></h3>
  <ul>
    <li>You <em>must</em> use the latest CVS version of LLVM. LLVM is HLVM's 
    sister project and the two are intricately connected. Consequently, patches
    are made to LLVM in order to satisfy HLVM's requirements. At some point,
    this restriction will be lifted as a released version of LLVM will contain
    all of HLVM's requirements. However, while in development you should
    checkout the latest version of LLVM and keep it up to date.</li>
    <li>Build with:<pre>
    cd /path/to/llvm/
    mkdir ../build
    cd ../build
    ../llvm/configure --prefix=/install/dir --with-llvmgccdir=/path/to/llvmgcc
    make ENABLE_OPTIMIZED=1 tools-only
    make tools-only
    make install</pre></li>
    <li><em>Note:</em> that you are actually building two copies of LLVM here. 
    The first one is built with ENABLE_OPTIMIZED=1. This is for llvm-gcc4 to 
    use and is optimized for quick compiles. The llvm-gcc4 configuration will 
    know how to find the build targets of this optimized release version. The 
    second build is a debug build for linking with HLVM. This ensures that you 
    can debug into LLVM, should you need to.</li>
    <li><em>Note:</em> that we only build the <tt>tools-only</tt> target. This
    saves us from building the llvm-gcc3 runtime libraries and examples that we
    won't use. It also gets around a chicken-and-egg problem where the LLVM
    runtime libraries depend on llvm-gcc3 but llvm-gcc3 depends on the LLVM
    tools being built. Use of llvm-gcc4 completely gets around this problem and
    so it is only necessary to build the LLVM tools and not the runtime library.
    </li>
  </ul>
  <h3><a name="llvm-gcc4">llvm-gcc4</a></h3>
  <ul>
    <li>You <em>must</em> use version 4 of llvm-gcc, not version 3. Version 4 is
    much better integrated with LLVM, supports more languages, builds native
    object files by default, and otherwise looks and acts more like a full gcc
    compiler than did llvm-gcc3.</li>
    <li>Obtain llvm-gcc4 source from 
    <a href="http://nondot.org/sabre/2006-06-01-llvm-gcc-4.tar.gz">
      http://nondot.org/sabre/2006-06-01-llvm-gcc-4.tar.gz</a></li>
    <li>Alternatively, you can obtain a binary version of llvm-gcc4 for
    x86 Linux (Fedora Core 3) from
    <a href="http://llvm.org/2006-06-01-llvm-gcc4-linux-x86-binary.tar.gz">
      http://llvm.org/2006-06-01-llvm-gcc4-linux-x86-binary.tar.gz</a></li>
    <li>You <em>must</em> install llvm-gcc4 into an installation area that
    is not used by any other software, particularly gcc. This is required
    because you might clobber your compiler's runtime libraries and tools
    otherwise. Just pick an installation directory where no other software is
    installed.</li>
    <li>See the <tt>README.LLVM</tt> in the top of the llvm-gcc4 source tree
    if you're inclined to build llvm-gcc4 on your own. It isn't hard but there
    are a few things you need to do correctly.</li>
    <li>Basic build steps:<pre>
    mkdir llvm-gcc
    cd llvm-gcc
    tar zxf llvm-gcc4-x.y.source.tar.gz
    mkdir obj
    mkdir install
    cd obj
    ../llvm-gcc4-x.y.source/configure --prefix=`pwd`/../install/ \
      -enable-llvm=$LLVMOBJDIR --enable-languages=c,c++,objc,obj-c++
    make
    make install</pre></li>
    <li><em>Note:</em> that the -enable-llvm option should specify the root of
    the build directory in which LLVM was built. If you built LLVM according to
    the instructions above, this directory will contain directories named
    <tt>Release</tt> and <tt>Debug</tt>. llvm-gcc4 will look for its tools in
    the <tt>Release</tt> directory.</li>
    <li><em>Note:</em> that the --enable-languages option shown above provides
    the complete list of languages that could be built with llvm-gcc4. However,
    HLVM only needs C and C++ so you can shorten the build for llvm-gcc4 a
    little by dropping <tt>,objc,obj-c++</tt> from this option.</li>
  </ul>
  <h3><a name="gperf">gperf</a></h3>
  <ul>
    <li>Pretty simple tool to build.</li>
    <li>You need version 2.7.2. HLVM hasn't been tried with any other
    version.</li>
    <li>Build with:<pre>
    ./configure --prefix=/install/path
    make
    make install</pre></li>
  </ul>
  <h3><a name="deja-gnu">deja-gnu/</a></h3>
  <ul>
    <li>Simple tool to build</li>
    <li>You need version 1.4.4 or later</li>
    <li>Build with:<pre>
    ./configure --prefix=/install/path
    make
    make install</pre></li>
  </ul>
</div>

<h2><a name="building">Building HLVM With SCons</a></h2>
<div class="text">
  <h3><a name="quick">Quick Start</a></h3>
  <p>If you took our advice and built all dependent packages (except llvm-gcc4)
  into a separate install area, then you can build HLVM quickly by using this
  command:</p><pre>
  scons -Q mode=debug confpath=/path/to/llvm-gcc4/install:/path/to/install</pre>
  <p>The <tt>confpath</tt> option indicates to the HLVM build system some 
  additional places to search for software. The first path should be the 
  location in which the llmv-gcc4 software was installed. The second path should
  be the <a href="#SSIA">Single Separate Install Area</a> where you installed 
  all the other packages such as llvm, apr, apr-util, etc.</p>

  <h3><a name="about_scons">About SCons And HLVM</a></h3>
  <p>HLVM uses the SCons tool for software construction. While <tt>make</tt> 
  and the various <tt>auto*</tt> tools were originally used, the full
  programming language support of SCons (Python) was attractive because of the
  platform support and the need to do intricate things to build HLVM. HLVM's
  use of SCons departs a bit from the norm because SCons doesn't provide
  everything that HLVM needs.  If you
  are not familiar with SCons, we recommend you take a quick peek at the
  <a href="http://www.scons.org/doc/0.96.92/HTML/scons-user.html">SCons User 
    Manual</a>. While an in depth knowledge is not needed to build HLVM, having
  some understanding of scons will definitely help.</p>
  <p>The details on using scons for HLVM can be found in the 
  <a href="DevelopersGuide.html">Developer's Guide</a>, but here's a precis to
  help you get started:</p>
  <ul>
    <li>You can still use <tt>make</tt> as the <tt>Makefile</tt> in the top
    level has the customary targets that will invoke the corresponding
    <tt>scons</tt> command.</li>
    <li>HLVM uses a number of customizations to the facilities provided in order
    to keep the SConstruct and SConscript files minimized. These facilities are
    provided in a Python module named <tt>build</tt> at the root directory. This
    departure was necessary in order to hide the implementation details of many
    of the build rules and configuration details that HLVM requires.</li>
    <li>An important thing to know is that configuration is done on every build.
    However, if the dependencies haven't changed, the result is cached and this
    runs quite quickly. This is a huge help to the project because it
    automatically detects environment changes and reconfigures HLVM accordingly
    which saves time and also catches problems very early.</li>
    <li>There are numerous configuration options available. You should use the
    <tt>scons -Q --help</tt> option to get a description of all of them.</li>
    <li>Configuration options are saved in cache files so you don't have to keep
    repeating them on each invocation of <tt>scons</tt></li>
  </ul>
  <h3><a name="scons_options">SCons Options Supported</a></h3>
  <p>The important options that may be given on the scons command line are:</p>
  <ul>
    <li><em>-Q</em>. Normally scons is quite verbose about all the
    configuration checks it is doing. This option just tells scons to be quiet
    about such things.</li>
    <li><em>--prefx=/path/to/install/dir</em>. This option tells the build
    system where HLVM should be installed. The default is <tt>/usr/local</tt>.
    </li>
    <li><em>confpath=&lt;path&gt;</em>. This option provides a colon (:)
    separated list of paths to search when configuring HLVM. This is handy if
    you normally install your software in an unusual place. For example, some
    of our developers install software to <tt>/proj/install</tt> or 
    <tt>/more/install</tt>. By using this option, the configuration code will
    search the paths for the packages and tools that it is looking for.
    Furthermore, it will give priority to the <tt>confpath</tt> paths over the
    regular places that it looks.</li>
    <li><em>mode=&lt;mode_name&gt;</em>. This gives a name to your
    configuration. You can replace <tt>&lt;mode_name&gt;</tt> with any name
    you like.  For example you might think of your configuration as
    "debug" or "optimized". When you name a configuration this way, your
    configuration parameters will be saved in a file named
    <tt>.&lt;mode_name&gt;_options</tt>. To repeat the options specified the
    first time, simply issue the command <tt>scons mode=&lt;mode_name&gt;</tt>
    and all your configuration options will be read from the cache file.</li>
    <li><em>debug=0|1</em>. This turns debug mode on and off. Debug mode
    causes the compiler to emit debug symbols and turns on the HLVM_DEBUG
    pre-processor symbol so that debug code can be included.</li>
    <li><em>assertions=0|1</em>. This turns assertions on or off. This is
    separate from debug because we might want to have a release or optimized
    version that includes assertions but not debug code.</li>
    <li><em>inline=0|1</em>. This controls whether the compiler should emit
    inline functions as real functions or attempt to inline them. When
    building a version you intend to debug with <tt>gdb</tt>, it is often
    handy to turn this off. You pay a performance penalty but it is also much
    easier to debug the code.</li>
    <li><em>optimize</em>. This option tells the compiler to optimize the
    generated code. This may make it difficult to debug the resulting program.
    However, it will also make the program run much faster.</li>
    <li><em>with_*</em>. There are a variety of options that are prefixed with
    <tt>with_</tt>, for example <tt>with_llvm</tt> or <tt>with_apr</tt>. Thise
    options allow you to tell scons where a specific package is located on
    your system. See the <tt>scons -Q --help</tt> output for a full list of
    these options.</li>
  </ul>
  <h3><a name="targets">Build Targets</a></h3>
  <p>The default build target will simply build all the libraries and tools. 
  There are additional pseudo-targets (<i>aliases</i> in SCons lingo) that you 
  can build:</p>
  <ul>
    <li><em>check</em>. This will run the Deja-Gnu test suite located in the
    <tt>test</tt> directory. If you're making changes to HLVM, it is handy to
    run this frequently to ensure that you haven't caused any regressions.
    Patches that do not pass this test suite will not be accepted.</li>
    <li><em>install</em>. This alias will install the HLVM header files,
    libraries, tools and documentation to the install directory (which was
    specified with the <tt>--prefix=</tt> configuration option).</li>
    <li><em>docs</em>. By default, documentation is not built because it is
    time consuming and not necessary for each build. When this alias is used,
    the doxygen and XSLT generated documentation will be built.</li>
  </ul>
</div>

<!-- *********************************************************************** -->
<div class="section"><a name="make">Building HLVM With Make</a></div>
<!-- *********************************************************************** -->
<div class="text">
  <p>If you don't want to learn how to use SCons, HLVM provides a 
  <tt>Makefile</tt> that will invoke it for you. All the usual targets are 
  provided.  To use this facility, simply do a local edit of the Makefile
  and adjust the three variables:</p>
  <dl>
    <dt>MYMODE</dt>
    <dd>Indicates the name of the build mode you want to build by default. This
    can be any string, but it will be more useful if it is one of these:
    <ul>
      <li><em>Debug</em> - specifies a debug build with assertions turned on and
      inline functions turned off. Initialize this build mode with 
      <tt>make Debug</tt>.</li>
      <li><em>Optimized</em> - specifies an optimized build with debug turned
      off, inline turned on, and assertions turned on.  Initialize this build
      mode with <tt>make Optimized</tt>.</li>
      <li><em>Release</em> - specifies an optimized build with assertions turned
      off and symbols stripped. Initialize this build with 
      <tt>make Release</tt>.</li>
      <li><em>Profile</em> - specifies an optimized profiling build with 
      assertions turned off, inline turned on and with profiling options
      suitable for profiling the tools with gmon. Initialize this build with 
      <tt>make Profile</tt>.</li>
    </ul></dd>
    <dt>MYPATH</dt>
    <dd>This provides a path for the 3rd party software that HLVM depends on.
    You should change this path to match your local environment. If you don't
    get this right then the first time you run scons, it will ask you to
    manually enter paths for things like the APR library and LLVM.</dd>
    <dt>MYPREFIX</dt>
    <dd>This provides the directory into which HLVM will be installed. If it is
    not specifed, the default will be /usr/local.</dd>
  </dl>
  <p>Once you've made these adjustments you can use the various targets in the
  Makefile to build HLVM. Note that these targets just convert the target into
  the appropriate invocation of the <tt>scons</tt> command.</p>
  <h3><a name="make_targets">Targets Supported</a></h3>
  <p>You can use the following targets to build HLVM in various ways:</p>
  <dl>
    <dt>all</dt>
    <dd>Builds HLVM in the default mode, as specified by <em>MYMODE</em>.
    Typically this is a Debug build.</dd>
    <dt>debug Debug</dt>
    <dd>This builds HLVM in a mode named "Debug" and sets the various options
    appropriately for a debug build. You should use this target the first time 
    you want a Debug build.</dd>
    <dt>optimized Optimized</dt>
    <dd>This builds HLVM in a mode named "Optimized" and sets the various 
    options appropriately for an optimized build. You should use this target 
    the first time you want an Optimized build.</dd>
    <dt>release Release</dt>
    <dd>This builds HLVM in a mode named "Release" and sets the various options
    appropriately for a release build. You should use this target the first
    time you want a Release build.</dd>
    <dt>profile Profile</dt>
    <dd>This builds HLVM in a mode named "Profile" and sets the various options
    appropriately for an profiled build. You should use this target the first
    time you want an Profile build.</dd>
    <dt>check</dt>
    <dd>This doesn't build HLVM but instead invokes the test suite via dejagnu.
    Use this to make sure that your local modifications haven't caused any
    regressions.</dd>
    <dt>clean</dt>
    <dd>This removes all the build targets that were previously built. The next
    time you build the <tt>all</tt> target, everything will be rebuilt.</dd>
    <dt>doc</dt>
    <dd>This builds the documentation for HLVM. It will run doxygen and xsltproc
    to build the generated portion of the documentation.</dd>
    <dt>hlvm</dt>
    <dd>This provides a partial build of HLVM. It descends into the 
    <tt>hlvm</tt> directory and builds only the libraries located there.</dd>
    <dt>install</dt>
    <dd>This will installed HLVM libraries, headers and executable tools into 
    the directory named by the <em>MYPREFIX</em> variable.</dd>
    <dt>tools</dt>
    <dd>This provides a partial build of HLVM. It skips building the libraries 
    in the <tt>hlvm</tt> directory and instead descends into the <tt>tools</tt>
    and builds the executable tools there.</dd>
  </dl>
  <h3><a name="tipsntricks">Tips And Tricks</a></h3>
  <ul>
    <li><em>Override MYMODE</em>. On the <tt>make</tt> command line you can
    override the value of <tt>MYMODE</tt> makefile variable. This allows you to
    use any of the usual targets with a different build mode. For example,
    suppose your <tt>Makefile</tt> specifies a value of "Debug" for
    <tt>MYMODE</tt>. This situation indicates that the "Debug" configuration
    will be used for all regular builds. However, if you want to install the
    Release version, say, you could issue this command:<pre>
    make install MYMODE=Release</pre></li>
  </ul>
</div>
<!--#include virtual="/incl/footer.incl" -->