Merged in autoconf branch. This provides configuration via the autoconf

system.


git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@7014 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 160 insertions, 37 deletions

diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html
index 711b04c..70b56c9 100644
--- a/docs/GettingStarted.html
+++ b/docs/GettingStarted.html
@@ -19,6 +19,11 @@
       <li><a href="#overview">Overview</a>
       <li><a href="#starting">Getting started with LLVM</a>
         <ol>
+          <li><a href="#requirements">Requirements</a>
+          <ol>
+              <li><a href="#hardware">Hardware</a>
+              <li><a href="#software">Software</a>
+          </ol>
           <li><a href="#quickstart">Getting started quickly (a summary)</a>
           <li><a href="#checkout">Checkout LLVM from CVS</a>
           <li><a href="#terminology">Terminology and Notation</tt></a>
@@ -66,6 +71,82 @@
     </center>
     <!--=====================================================================-->
 
+    <!--=====================================================================-->
+    <h3><a name="requirements"><b>Requirements</b></a></h3>
+    <!--=====================================================================-->
+
+    <!--=====================================================================-->
+    <h4><a name="hardware"><b>Hardware</b></a></h4>
+    <!--=====================================================================-->
+    LLVM is known to work on the following platforms:
+    <ul>
+        <li> Linux on x86
+        <ul>
+            <li> Approximately 700 MB of Free Disk Space
+            <ul>
+                <li>Source code: 30 MB
+                <li>Object code: 670 MB
+            </ul>
+        </ul>
+        <li> Solaris on Sparc
+        <ul>
+            <li> Approximately 1.03 GB of Free Disk Space
+            <ul>
+                <li>Source code: 30 MB
+                <li>Object code: 1000 MB
+            </ul>
+        </ul>
+    </ul>
+
+    LLVM may compile on other platforms.  While the LLVM utilities should work,
+    they will only generate Sparc or x86 machine code.
+
+    <!--=====================================================================-->
+    <h4><a name="software"><b>Software</b></a></h4>
+    <!--=====================================================================-->
+    <p>
+    Compiling LLVM requires that you have several different software packages
+    installed:
+
+    <ul>
+        <li> GCC
+        <p>
+        The GNU Compiler Collection must be installed with C and C++ language
+        support.  GCC 3.x is supported, although some effort has been made to
+        support GCC 2.96.
+        </p>
+
+        <p>
+        Note that we currently do not support any other C++ compiler.
+        </p>
+
+        <li> GNU Make
+        <p>
+        The LLVM build system relies upon GNU Make extensions.  Therefore, you
+        will need GNU Make (sometimes known as gmake) to build LLVM.
+        </p>
+
+        <li> Flex and Bison
+        <p>
+        The LLVM source code is built using flex and bison.  You will not be
+        able to configure and compile LLVM without them.
+        </p>
+    </ul>
+
+    <p>
+    There are some additional tools that you may want to have when working with
+    LLVM:
+    </p>
+
+    <ul>
+        <li> GNU Autoconf and GNU M4
+        <p>
+        If you want to make changes to the autoconf scripts which configure LLVM
+        for compilation, you will need GNU autoconf, and consequently, GNU M4.
+        LLVM was built with autoconf 2.53, so that release and any later
+        release should work.
+        </p>
+    </ul>
 
     <!--=====================================================================-->
     <h3><a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a></h3>
@@ -77,9 +158,17 @@
     <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
     <li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt>
     <li><tt>cd llvm</tt>
-    <li>Edit <tt>Makefile.config</tt> to set local paths.  This includes
-        setting the install location of the C frontend and the various paths
-        to the C and C++ compilers used to build LLVM itself.
+    <li>Run <tt>configure</tt> to configure the Makefiles and header files.
+    Useful options include:
+        <ul>
+            <li><tt>--with-objroot=<i>directory</i></tt>
+            <br>
+            Specifiy where object files should be placed during the build.
+
+            <li><tt>--with-llvmgccdir=<i>directory</i></tt>
+            <br>
+            Specifiy where the LLVM C frontend has been installed.
+        </ul>
     <li>Set your LLVM_LIB_SEARCH_PATH environment variable.
     <li><tt>gmake -k |& tee gnumake.out
 	    &nbsp;&nbsp;&nbsp;# this is csh or tcsh syntax</tt>
@@ -97,8 +186,8 @@
 
     <p>Throughout this manual, the following names are used to denote paths
     specific to the local system and working environment.  <i>These are not
-    environment variables you need to set, but just strings used in the rest
-    of this document below.</i>.  In any of the examples below, simply replace
+    environment variables you need to set but just strings used in the rest
+    of this document below</i>.  In any of the examples below, simply replace
     each of these names with the appropriate pathname on your local system.
     All these paths are absolute:</p>
     <ul>
@@ -109,7 +198,7 @@
     <!------------------------------------------------------------------------->
 
     <p>Before checking out the source code, you will need to know the path to
-    the CVS repository containing LLVM source code (we'll call this
+    the CVS repository containing the LLVM source code (we'll call this
     <i>CVSROOTDIR</i> below).  Ask the person responsible for your local LLVM
     installation to give you this path.
 
@@ -128,30 +217,52 @@
     <h3><a name="config">Local Configuration Options</a></h3>
     <!------------------------------------------------------------------------->
 
-    <p>The file <tt>llvm/Makefile.config</tt>
-    defines the following path variables
-    which are specific to a particular installation of LLVM.
-    These need to be modified only once after checking out a copy
-    of LLVM (if the default values do not already match your system):
+    <p>Once checked out from the CVS repository, options and pathnames specific
+    to an installation of LLVM can be set via the <tt>configure</tt> script.
+    This script sets variables in <tt>llvm/Makefile.config</tt> and
+    <tt>llvm/include/Config/config.h</tt>.
+
+    <p>
+    The following environment variables are used by <tt>configure</tt> to
+    configure Makefile.config:
+    </p>
+
+    <ul>
+    <p><li><i>CXX</i> = Pathname of the C++ compiler to use.
+    <p><li><i>CC</i> = Pathname of the C compiler to use.
+    </ul>
+
+    The following options can be used to set or enable LLVM specific options:
 
     <ul>
-    <p><li><i>CXX</i> = Path to C++ compiler to use.
-    <p><li><i>OBJ_ROOT</i> = Path to the llvm directory where
-				 object files should be placed.
-				 (See the Section on <a href=#objfiles>
-				 The location for LLVM object files</a>
-				 for more information.)
-    <p><li><i>LLVMGCCDIR</i>   = Path to the location of the LLVM front-end
-				 binaries and associated libraries.
-    <p><li><i>PURIFY</i>       = Path to the purify program.
+    <p><li><i>--with-objroot=LLVM_OBJ_ROOT</i> =
+        Path to the directory where
+		object files, libraries, and executables should be placed.
+		(See the Section on <a href=#objfiles>
+		The location for LLVM object files</a>
+		for more information.)
+    <p><li><i>--with-llvmgccdir=LLVMGCCDIR</i>   =
+        Path to the location of the LLVM front-end
+		binaries and associated libraries.
+    <p><li><i>--enable-optimized</i>       =
+        Enables optimized compilation (debugging symbols are removed and GCC
+        optimization flags are enabled).
+    <p><li><i>--enable-profiling</i>       =
+        Enables profiling compilation (compiler flags needed to add profiling
+        data are enabled).
+    <p><li><i>--enable-verbose</i>       =
+        Enables verbose messages during the compile.
+    <p><li><i>--enable-jit</i>       =
+        Compile the Just In Time (JIT) functionality.  This is not available
+        on all platforms.
     </ul>
 
-    In addition to settings in this file, you must set a
+    In addition to running <tt>configure</tt>, you must set the
     <tt>LLVM_LIB_SEARCH_PATH</tt> environment variable in your startup scripts.
     This environment variable is used to locate "system" libraries like
     "<tt>-lc</tt>" and "<tt>-lm</tt>" when linking.  This variable should be set
     to the absolute path for the bytecode-libs subdirectory of the C front-end
-    install.  For example, one might use
+    install.  For example, one might set <tt>LLVM_LIB_SEARCH_PATH</tt> to
     <tt>/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs</tt> for the X86
     version of the C front-end on our research machines.<p>
 
@@ -166,9 +277,11 @@
     object files on a different filesystem either to keep them from being backed
     up or to speed up local builds.
 
-    <p>If you do not wish to use a different location for object files (i.e.
-    you are building into the source tree directly), just set this variable to
-    ".".<p>
+    <p>If you wish to place output files into a separate directory, use the
+    <tt>--with-objroot=<i>directory</i></tt> option of <tt>configure</tt> to
+    set the top level directory of where the object files will go.  Otherwise,
+    leave this option unspecified, and <tt>configure</tt> will place files
+    within the LLVM source tree.
 
     <!------------------------------------------------------------------------->
     <h3><a name="environment">Setting up your environment</a></h3>
@@ -190,7 +303,7 @@
     </pre>
     The <tt>llvmgcc</tt> alias is useful because the C compiler is not
     included in the CVS tree you just checked out.
-    
+
     <p>The other <a href="#tools">LLVM tools</a> are part of the LLVM
     source base and built when compiling LLVM.  They will be built into the
     <tt><i>OBJ_ROOT</i>/tools/Debug</tt> directory.</p>
@@ -201,14 +314,15 @@
 
     <p>Every directory in the LLVM source tree includes a <tt>Makefile</tt> to
     build it and any subdirectories that it contains.  These makefiles require
-    that you use GNU Make (aka <tt>gmake</tt>) instead of <tt>make</tt> to
+    that you use GNU Make (sometimes called <tt>gmake</tt>) instead of
+    <tt>make</tt> to
     build them, but can
     otherwise be used freely.  To build the entire LLVM system, just enter the
     top level <tt>llvm</tt> directory and type <tt>gmake</tt>.  A few minutes
     later you will hopefully have a freshly compiled toolchain waiting for you
     in <tt><i>OBJ_ROOT</i>/llvm/tools/Debug</tt>.  If you want to look at the
-    libraries that were compiled, look in
-    <tt><i>OBJ_ROOT</i>/llvm/lib/Debug</tt>.</p>
+    libraries that
+    were compiled, look in <tt><i>OBJ_ROOT</i>/llvm/lib/Debug</tt>.</p>
 
     If you get an error about a <tt>/localhome</tt> directory, follow the
     instructions in the section about <a href="#environment">Setting Up Your
@@ -242,7 +356,9 @@
     <!------------------------------------------------------------------------->
 
     If you are building with the "<tt>OBJ_ROOT=.</tt>" option enabled in the
-    <tt>Makefile.config</tt> file, most source directories will contain two
+    <tt>Makefile.config</tt> file (i.e. you did not specify
+    <tt>--with-objroot</tt> when you ran <tt>configure</tt>), most source
+    directories will contain two
     directories, <tt>Depend</tt> and <tt>Debug</tt>. The <tt>Depend</tt>
     directory contains automatically generated dependance files which are used
     during compilation to make sure that source files get rebuilt if a header
@@ -250,7 +366,7 @@
     files, library files, and executables that are used for building a debug
     enabled build.  The <tt>Release</tt> directory is created to hold the same
     files when the <tt>ENABLE_OPTIMIZED=1</tt> flag is passed to <tt>gmake</tt>,
-    causing an optimized built to be performed.<p>
+    causing an optimized build to be performed.<p>
 
 
     <!------------------------------------------------------------------------->
@@ -258,7 +374,7 @@
     <!------------------------------------------------------------------------->
 
     This directory contains public header files exported from the LLVM
-    library. The two main subdirectories of this directory are:<p>
+    library. The three main subdirectories of this directory are:<p>
 
     <ol>
        <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
@@ -268,16 +384,23 @@
 
        <li><tt>llvm/include/Support</tt> - This directory contains generic
        support libraries that are independant of LLVM, but are used by LLVM.
-       For example, header files for some C++ STL utilities and a Command Line
-       option processing library are located here.
+       For example, some C++ STL utilities and a Command Line option processing
+       library.
+
+       <li><tt>llvm/include/Config</tt> - This directory contains header files
+       configured by the <tt>configure</tt> script.  They wrap "standard" UNIX
+       and C header files.  Source code can include these header files which
+       automatically take care of the conditional #includes that the configure
+       script generates.
     </ol>
 
     <!------------------------------------------------------------------------->
     <h3><a name="lib"><tt>llvm/lib</tt></a></h3>
     <!------------------------------------------------------------------------->
 
-    This directory contains most source files of LLVM system. In LLVM, almost
-    all code exists in libraries, making it very easy to share code among the
+    This directory contains most of the source files of the LLVM system. In
+    LLVM almost all
+    code exists in libraries, making it very easy to share code among the
     different <a href="#tools">tools</a>.<p>
 
      <dl compact>
@@ -365,7 +488,7 @@
         <dt><tt><b>gccas</b></tt><dd> This tool is invoked by the
         <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler.  This
         tool actually assembles LLVM assembly to LLVM bytecode,
-	performs a variety of optimizations,
+	    performs a variety of optimizations,
         and outputs LLVM bytecode.  Thus when you invoke <tt>llvmgcc -c x.c -o
         x.o</tt>, you are causing <tt>gccas</tt> to be run, which writes the
         <tt>x.o</tt> file (which is an LLVM bytecode file that can be