From rspencer at reidspencer.com Mon Jun 12 01:28:17 2006
From: rspencer at reidspencer.com (rspencer at reidspencer.com)
Date: Mon, 12 Jun 2006 02:28:17 -0400
Subject: [hlvm-commits] r234 - docs
Message-ID: <200606120628.k5C6SHlr012027@sneezy.swagora.com>
Author: reid
Date: 2006-06-12 02:28:16 -0400 (Mon, 12 Jun 2006)
New Revision: 234
Log:
Describe how to use scons for building HLVM.
Modified:
docs/GettingStarted.html
Modified: docs/GettingStarted.html
===================================================================
--- docs/GettingStarted.html 2006-06-11 19:02:45 UTC (rev 233)
+++ docs/GettingStarted.html 2006-06-12 06:28:16 UTC (rev 234)
@@ -18,6 +18,7 @@
Building Other Packages
+ Building HLVM With SCons
@@ -99,24 +100,19 @@
-
-
-HLVM is dependent on a number of other software packages. These
-packages will be required before you can build HLVM. Fortunately, the configure
-script will tell you which packages you lack. The table below shows the software
-that HLVM depends on. You must obtain and build these packages yourself
-if they are not already present on your system.
-
-
-
Before you begin to use the HLVM system, review the requirements given below.
-This may save you some trouble by knowing ahead of time what hardware and
-software you will need.
-
+
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.
+
The table below shows the software that HLVM depends on. You must
+ obtain and build these packages yourself if they are not already present on
+ your system. HLVM won't compile or run without them.
@@ -139,27 +135,39 @@
| llvm |
1.8cvs2 |
- optimization, code generation, bytecode, JIT |
+ 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 HLVM. |
- | llvm-gcc |
+ llvm-gcc4 |
4 |
- C and C++ compilation to llvm bytecode |
+ 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. |
| apr |
1.2.7 |
- runtime environment, OS abstraction, threading, loading, etc. |
+ 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. |
| apr-util |
1.2.7 |
- additional runtime utilities |
+ Apache Portable Runtime Utilities. Additional runtime utilities. |
| libxml2 |
2.6.24 |
- XML parsing and validation toolkit |
+ XML parsing and validation toolkit. |
| gperf |
@@ -175,14 +183,19 @@
| subversion |
≥1.1 |
- Suversion access to HLVM source |
+ Suversion access to HLVM source repository. |
| scons |
0.96.92 |
- Software Construction system used for HLVM's build |
+ Software Construction system used for HLVM's build system. |
+ | python |
+ 2.3 |
+ Python programming language, required by scons |
+
+
| dejagnu |
1.4.2 |
Automated test suite1 |
@@ -288,5 +301,99 @@
are a few things you need to do correctly.
+
+
+
+
+
HLVM uses the SCons tool for software construction. While make
+ and the various auto* tools were originally used, the full
+ programming language support (Python) of SCons was attractive because of the
+ platform support and the need to do intricate things to build HLVM. If you
+ are not familiar with SCons, we recommend you take a quick peek at the
+ SCons User
+ Manual. While an in depth knowledge is not needed to build HLVM, having
+ some understanding of scons will definitely help.
+
The details on using scons for HLVM can be found in the
+ Developer's Guide, but here's a precis to
+ help you get started:
+
+ - You can still use make as the Makefile in the top
+ level has the customary targets that will invoke the corresponding
+ scons command.
+ - 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 build 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.
+ - 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.
+ - There are numerous configuration options available. You should use the
+ scons -Q --help option to get a description of all of them.
+ - Configuration options are saved in cache files so you don't have to keep
+ repeating them on each invocation of scons
+ - The important options to use are:
+
+ - -Q. Normally scons is quite verbose about all the
+ configuration checks it is doing. This option just tells scons to be quiet
+ about such things.
+ - --prefx=/path/to/install/dir. This option tells the build
+ system where HLVM should be installed. The default is /usr/local.
+
+ - confpath=<path>. 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 /proj/install or
+ /more/install. 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 confpath paths over the
+ regular places that it looks.
+ - mode=<mode_name>. This gives a name to your
+ configuration. You can replace <mode_name> 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
+ .<mode_name>_options. To repeat the options specified the
+ first time, simply issue the command scons mode=<mode_name>
+ and all your configuration options will be read from the cache file.
+ - debug=0|1. 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.
+ - assertions=0|1. 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.
+ - inline=0|1. 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 gdb, it is often
+ handy to turn this off. You pay a performance penalty but it is also much
+ easier to debug the code.
+ - optimize. 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.
+ - with_*. There are a variety of options that are prefixed with
+ with_, for example with_llvm or with_apr. Thise
+ options allow you to tell scons where a specific package is located on
+ your system. See the scons -Q --help output for a full list of
+ these options.
+
+ - The default target will simply build all the libraries and tools.
+ - There are additional pseudo-targets (aliases in SCons lingo) that
+ you can build:
+
+ - check. This will run the Deja-Gnu test suite located in the
+ test 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.
+ - install. This alias will install the HLVM header files,
+ libraries, tools and documentation to the install directory (which was
+ specified with the --prefix= configuration option).
+ - docs. 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.
+
+
+