Google Git
Sign in
llvm / llvm-archive / 089ca8750d7cd1f1ec96968922bf4bcfe223bb3a / . / hlvm / docs / GettingStarted.html
blob: d5cce82b8fffad4c919d930ecde4c218b34468ff [file] [log] [blame]
<!--#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" -->