| <!--#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>≥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>≥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>≥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>≥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=<path></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=<mode_name></em>. This gives a name to your |
| configuration. You can replace <tt><mode_name></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>.<mode_name>_options</tt>. To repeat the options specified the |
| first time, simply issue the command <tt>scons mode=<mode_name></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" --> |