Program layout
- CVS directories
-
- Depend, Debug, &
- Release directories
- llvm/include
- llvm/lib
- llvm/test
@@ -54,7 +55,111 @@
-
The next section of this guide is meant to get
+ Welcome to LLVM! In order to get started, you first need to know some
+ basic information.
+
+
+ First, LLVM comes in two pieces. The first piece is the LLVM suite. This
+ contains all of the tools, libraries, and header files needed to use the
+ low level virtual machine. It also contains a test suite that can be used
+ to test the LLVM tools and the GCC front end.
+
+ The second piece is the GCC front end. This component provides a version
+ of GCC that compiles C code into LLVM bytecode. Currently, the C front end
+ is a modified version of GCC 3.4 (we track the GCC 3.4 development).
+ Once compiled into LLVM bytecode, a program can be manipulated with the
+ LLVM tools.
+
+
+
+
+
+ Before you begin to use the LLVM system, review the requirements given
+ below. This may save you some trouble by knowing ahead of time what
+ hardware and software you will need.
+
+
+
+
+ LLVM is known to work on the following platforms:
+
+ - Linux on x86
+
+ - Approximately 700 MB of Free Disk Space
+
+ - Source code: 30 MB
+
- Object code: 670 MB
+
+
+ - Solaris on SparcV9 (Ultrasparc)
+
+ - Approximately 1.03 GB of Free Disk Space
+
+ - Source code: 30 MB
+
- Object code: 1000 MB
+
+
+
+
+ LLVM may compile on other platforms. The LLVM utilities should work
+ on other platforms, so it should be possible to generate and produce LLVM
+ bytecode on unsupported platforms (although bytecode generated on one
+ platform may not work on another platform). However, the code generators
+ and Just In Time Compilers (JIT's) only generate SparcV9 or x86 machine
+ code.
+
+
+
+
+
+ Compiling LLVM requires that you have several different software packages
+ installed:
+
+
+ - GCC
+
-
+ The GNU Compiler Collection must be installed with C and C++ language
+ support. GCC 3.2.x works, and GCC 3.x is generally supported.
+
+
+ Note that we currently do not support any other C++ compiler.
+
+
+ - GNU Make
+
-
+ The LLVM build system relies upon GNU Make extensions. Therefore, you
+ will need GNU Make (sometimes known as gmake) to build LLVM.
+
+
+
- Flex and Bison
+
-
+ The LLVM source code is built using flex and bison. You will not be
+ able to configure and compile LLVM without them.
+
+
+
- GNU M4
+
-
+ If you are installing Bison on your machine for the first time, you
+ will need GNU M4 (version 1.4 or higher).
+
+
+
+ There are some additional tools that you may want to have when working with
+ LLVM:
+
+
+
+ - GNU Autoconf
+
- GNU M4
+
+ If you want to make changes to the configure scripts, you will need
+ GNU autoconf (2.53 or higher), and consequently, GNU M4 (version 1.4
+ or higher).
+
+
+
+
+ The next section of this guide is meant to get
you up and running with LLVM and to give you some basic information about
the LLVM environment. The first subsection gives
a short summary for those who are already familiar with the system and
@@ -72,107 +177,42 @@
-
-
-
-
-
-
-
- LLVM is known to work on the following platforms:
-
- - Linux on x86
-
- - Approximately 700 MB of Free Disk Space
-
- - Source code: 30 MB
-
- Object code: 670 MB
-
-
- - Solaris on Sparc
-
- - Approximately 1.03 GB of Free Disk Space
-
- - Source code: 30 MB
-
- Object code: 1000 MB
-
-
-
-
- LLVM may compile on other platforms. While the LLVM utilities should work,
- they will only generate Sparc or x86 machine code.
-
-
-
-
-
- Compiling LLVM requires that you have several different software packages
- installed:
-
-
- - GCC
-
- 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.
-
-
-
- Note that we currently do not support any other C++ compiler.
-
-
- - GNU Make
-
- The LLVM build system relies upon GNU Make extensions. Therefore, you
- will need GNU Make (sometimes known as gmake) to build LLVM.
-
-
- - Flex and Bison
-
- The LLVM source code is built using flex and bison. You will not be
- able to configure and compile LLVM without them.
-
-
-
-
- There are some additional tools that you may want to have when working with
- LLVM:
-
-
-
- - GNU Autoconf and GNU M4
-
- 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.
-
-
-
Here's the short story for getting up and running quickly with LLVM:
- - Find the path to the CVS repository containing LLVM (we'll call this CVSROOTDIR).
-
- cd where-you-want-llvm-to-live
-
- cvs -d CVSROOTDIR checkout llvm
-
- cd llvm
-
- Run configure to configure the Makefiles and header files.
- Useful options include:
-
- - --with-objroot=directory
-
- Specifiy where object files should be placed during the build.
+ - Build the LLVM suite
+
+ - Find the path to the CVS repository containing LLVM (we'll call this CVSROOTDIR).
+
- cd where-you-want-llvm-to-live
+
- cvs -d CVSROOTDIR checkout llvm
+
- cd llvm
+
- Run configure to configure the Makefiles and header files.
+ Useful options include:
+
+ - --with-objroot=directory
+
+ Specify where object files should be placed during the build.
- - --with-llvmgccdir=directory
-
- Specifiy where the LLVM C frontend has been installed.
-
- - Set your LLVM_LIB_SEARCH_PATH environment variable.
-
- gmake -k |& tee gnumake.out
- # this is csh or tcsh syntax
+
- --with-llvmgccdir=directory
+
+ Specify where the LLVM C frontend is going to be installed.
+
+ - Set your LLVM_LIB_SEARCH_PATH environment variable.
+
- gmake -k |& tee gnumake.out
+ # this is csh or tcsh syntax
+
+
+
- Build the LLVM C Front End
+
+ - Create a directory for the object files to live.
+
- cd object file directory
+
- Run Pathname-to-where-the-source-code-lives/configure --prefix=LLVMGCCDIR to configure GCC.
+
- make bootstrap
+
- make install
+
See Setting up your environment on tips to
@@ -191,18 +231,94 @@
of this document below. 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:
-
+
+ - CVSROOTDIR
+
-
+ This is the path for the CVS repository containing the LLVM source
+ code. Ask the person responsible for your local LLVM installation to
+ give you this path.
+
+
+
- OBJ_ROOT
+
-
+ This is the top level directory for where the LLVM suite object files
+ will be placed during the build.
+
+
+
- LLVMGCCDIR
+
-
+ This is the pathname to the location where the LLVM C Front End will
+ be installed. Note that the C front end does not need to be installed
+ during the LLVM suite build; you will just need to know where it will
+ go for configuring the build system and running the test suite later.
+
+
+
- GCCSRC
+
-
+ This is the pathname of the directory where the LLVM C front end source
+ code can be found.
+
+
+
- GCCOBJ
+
-
+ This is the pathname of the directory where the LLVM C front end object
+ code will be placed during the build. It can be safely removed once
+ the build is complete.
+
+
+
+
+
+
+
+ In order to compile and use LLVM, you will need to set some environment
+ variables. There are also some shell aliases which you may find useful.
+ You can set these on the command line, or better yet, set them in your
+ .cshrc or .profile.
+
+
+ - LLVM_LIB_SEARCH_PATH=LLVMGCCDIR/llvm-gcc/bytecode-libs
+
-
+ This environment variable helps the LLVM C front end find bytecode
+ libraries that it will need for compilation.
+
+
+
- PATH=${PATH}:OBJ_ROOT/llvm/tools/Debug
+
-
+ Adding this directory to the end of your path will allow the
+ compilation of the C front end to find the LLVM tools. The LLVM tools
+ are needed for the C front end compile.
+
+
+
- CC=Pathname to your GCC compiler
+
-
+ The GCC compiler that you want to use must be the first C compiler in
+ your PATH. Otherwise, set this variable so that
+ configure will use the GCC compiler that you want to use.
+
+
+
- CXX=Pathname to your GCC C++ compiler
+
-
+ The GCC compiler that you want to use must be the first C++ compiler in
+ your PATH. Otherwise, set this variable so that
+ configure will use the GCC compiler that you want to use.
+
+
+
- CVSROOT=CVSROOT
+
-
+ This environment variable tells CVS where to find the CVS repository.
+
+
+
- alias llvmgcc LLVMGCCDIR/bin/llvm-gcc
+
-
+ This alias allows you to use the LLVM C front end without putting it in
+ your PATH or typing in its complete pathname.
+
- Before checking out the source code, you will need to know the path to
- the CVS repository containing the LLVM source code (we'll call this
- CVSROOTDIR below). Ask the person responsible for your local LLVM
- installation to give you this path.
-
To get a fresh copy of the entire source code, all you
need to do is check it out from CVS as follows:
@@ -214,13 +330,19 @@
directory and fully populate it with the LLVM source code, Makefiles,
test directories, and local copies of documentation files.
+
+ Note that the C front end is not included in the CVS repository. You
+ should have either downloaded the source, or better yet, downloaded the
+ binary distribution for your platform.
+
+
-
+
- Once checked out from the CVS repository, options and pathnames specific
- to an installation of LLVM can be set via the configure script.
- This script sets variables in llvm/Makefile.config and
+
Once checked out from the CVS repository, the LLVM suite source code
+ must be configured via the configure script. This script sets
+ variables in llvm/Makefile.config and
llvm/include/Config/config.h.
@@ -229,102 +351,250 @@
- - CXX = Pathname of the C++ compiler to use.
-
- CC = Pathname of the C compiler to use.
+
- CXX = Pathname of the C++ compiler to use.
+
- CC = Pathname of the C compiler to use.
The following options can be used to set or enable LLVM specific options:
-
- - --with-objroot=LLVM_OBJ_ROOT =
+
+ - --with-objroot=OBJ_ROOT
+
-
Path to the directory where
object files, libraries, and executables should be placed.
+ If this is set to ., then the object files will be placed
+ within the source code tree. If left unspecified, the default value is
+ ..
(See the Section on
The location for LLVM object files
for more information.)
-
- --with-llvmgccdir=LLVMGCCDIR =
- Path to the location of the LLVM front-end
- binaries and associated libraries.
-
- --enable-optimized =
+
+
- --with-llvmgccdir=LLVMGCCDIR
+
-
+ Path to the location where the LLVM C front end binaries and
+ associated libraries will be installed.
+
+
- --enable-optimized
+
-
Enables optimized compilation (debugging symbols are removed and GCC
- optimization flags are enabled).
-
- --enable-jit =
+ optimization flags are enabled). The default is to use an unoptimized
+ build (also known as a debug build).
+
+
- --enable-jit
+
-
Compile the Just In Time (JIT) functionality. This is not available
- on all platforms.
-
+ on all platforms. The default is dependent on platform, so it is best
+ to explicitly enable it if you want it.
+
In addition to running configure, you must set the
LLVM_LIB_SEARCH_PATH environment variable in your startup scripts.
This environment variable is used to locate "system" libraries like
"-lc" and "-lm" 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 set LLVM_LIB_SEARCH_PATH to
+ install, or LLVMGCCDIR/llvm-gcc/bytecode-libs. For example, one might
+ set LLVM_LIB_SEARCH_PATH to
/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs for the X86
version of the C front-end on our research machines.
+
+
+
+
+ Once you have configured LLVM, you can build it. There are three types of
+ builds:
+
+
+ - Debug Builds
+
-
+ These builds are the default. They compile the tools and libraries
+ with debugging information.
+
+
+
- Release (Optimized) Builds
+
-
+ These builds are enabled with the --enable-optimized option to
+ configure. They compile the tools and libraries with GCC
+ optimizer flags on and strip debugging information from the libraries
+ and executables it generates.
+
+
+
- Profile Builds
+
-
+ These builds are for use with profiling. They compile profiling
+ information into the code for use with programs like gprof.
+ Profile builds must be started by setting variables on the
+ make command line.
+
+
+ Once you have LLVM configured, you can build it by entering the top level
+ llvm directory and issuing the following command:
+
+ make
+
+
+ If you have multiple processors in your machine, you may wish to use some
+ of the parallel build options provided by GNU Make. For example, you could
+ use the command:
+
+
+
+ make -j2
+
+
+ There are several other targets which are useful when working with the LLVM
+ source code:
+
+
+ - make clean
+
-
+ Removes all files generated by the build. This includes object files,
+ generated C/C++ files, libraries, and executables.
+
+
+
- make distclean
+
-
+ Removes everything that make clean does, but also removes
+ files generated by configure. It attempts to return the
+ source tree to the original state in which it was shipped.
+
+
+
+ It is also possible to override default values from configure by
+ declaring variables on the command line. The following are some examples:
+
+
+ - make ENABLE_OPTIMIZED=1
+
-
+ Perform a Release (Optimized) build.
+
+
+
- make ENABLE_PROFILING=1
+
-
+ Perform a Profiling build.
+
+
+
- make VERBOSE=1
+
-
+ Print what make is doing on standard output.
+
+
+
+ Every directory in the LLVM source tree includes a Makefile to
+ build it and any subdirectories that it contains. Entering any directory
+ inside the LLVM source tree and typing make should rebuild
+ anything in or below that directory that is out of date.
+
+
+
+
+
+
+
+ This step is optional if you have the C front end binary distrubtion for
+ your platform.
+
+
+
+ Now that you have the LLVM Suite built, you can build the C front end. For
+ those of you that have built GCC before, the process is very similar.
+
+ Be forewarned, though: the build system for the C front end is not as
+ polished as the rest of the LLVM code, so there will be many warnings and
+ errors that you will need to ignore for now:
+
+
+ - Ensure that OBJ_ROOT/llvm/tools/Debug is at the
+ end of your PATH environment variable.
+
+
- cd GCCOBJ
+
+
- Configure the source code:
+
+ - On Linux/x86, use
+
+ - GCCSRC/configure --prefix=LLVMGCCDIR
+ --enable-languages=c
+
+
+ - On Solaris/Sparc, use
+
+ - GCCSRC/configure --prefix=LLVMGCCDIR
+ --enable-languages=c --target=sparcv9-sun-solaris2
+
+
+
+ - make bootstrap
+
+
- The build will eventually fail. Don't worry; chances are good that
+ everything that needed to build is built.
+
+
- make install
+
+
+ At this point, you should have a working copy of the LLVM C front end
+ installed in LLVMGCCDIR.
+
- The LLVM make system sends most output files generated during the build
- into the directory defined by the variable OBJ_ROOT in
- llvm/Makefile.config. This can be either just your normal LLVM
+
The LLVM build system sends most output files generated during the build
+ into the directory defined by the variable OBJ_ROOT in
+ llvm/Makefile.config, which is set by the --with-objroot
+ option in configure. This can be either just your normal LLVM
source tree or some other directory writable by you. You may wish to put
object files on a different filesystem either to keep them from being backed
up or to speed up local builds.
-
If you wish to place output files into a separate directory, use the
- --with-objroot=directory option of configure to
- set the top level directory of where the object files will go. Otherwise,
- leave this option unspecified, and configure will place files
- within the LLVM source tree.
+
+ If OBJ_ROOT is specified, then the build system will create a
+ directory tree underneath it that resembles the source code's pathname
+ relative to your home directory.
+
-
-
-
+
+ For example, suppose that OBJ_ROOT is set to /tmp and the
+ LLVM suite source code is located in /usr/home/joe/src/llvm, where
+ /usr/home/joe is the home directory of a user named Joe. Then,
+ the object files will be placed in /tmp/src/llvm.
+
- NOTE: This step is optional but will set up your environment so you
- can use the compiled LLVM tools with as little hassle as
- possible.)
+
+ The LLVM build will place files underneath OBJ_ROOT in directories
+ named after the build type:
+
- Add the following lines to your .cshrc (or the corresponding
- lines to your .profile if you use a bourne shell derivative).
-
-
- # Make the C front end easy to use...
- alias llvmgcc LLVMGCCDIR/bin/llvm-gcc
-
- # Make the LLVM tools easy to use...
- setenv PATH OBJ_ROOT/llvm/tools/Debug:${PATH}
-
- The llvmgcc alias is useful because the C compiler is not
- included in the CVS tree you just checked out.
-
- The other LLVM tools are part of the LLVM
- source base and built when compiling LLVM. They will be built into the
- OBJ_ROOT/tools/Debug directory.
-
-
-
-
-
- Every directory in the LLVM source tree includes a Makefile to
- build it and any subdirectories that it contains. These makefiles require
- that you use GNU Make (sometimes called gmake) instead of
- make to
- build them, but can
- otherwise be used freely. To build the entire LLVM system, just enter the
- top level llvm directory and type gmake. A few minutes
- later you will hopefully have a freshly compiled toolchain waiting for you
- in OBJ_ROOT/llvm/tools/Debug. If you want to look at the
- libraries that
- were compiled, look in OBJ_ROOT/llvm/lib/Debug.
-
- If you get an error about a /localhome directory, follow the
- instructions in the section about Setting Up Your
- Environment.
+
+ - Debug Builds
+
-
+
+ - Tools
+
- OBJ_ROOT/llvm/tools/Debug
+
- Libraries
+
- OBJ_ROOT/llvm/lib/Debug
+
+
+
- Release Builds
+
-
+
+ - Tools
+
- OBJ_ROOT/llvm/tools/Release
+
- Libraries
+
- OBJ_ROOT/llvm/lib/Release
+
+
+
- Profile Builds
+
-
+
+ - Tools
+
- OBJ_ROOT/llvm/tools/Profile
+
- Libraries
+
- OBJ_ROOT/llvm/lib/Profile
+
+
@@ -332,7 +602,7 @@
- One useful source of infomation about the LLVM sourcebase is the LLVM One useful source of information about the LLVM source base is the LLVM doxygen documentation, available at http://llvm.cs.uiuc.edu/doxygen/. The
following is a brief introduction to code layout:
@@ -346,25 +616,6 @@
for the most part these can just be ignored.
-
-
-
-
- If you are building with the "OBJ_ROOT=." option enabled in the
- Makefile.config file (i.e. you did not specify
- --with-objroot when you ran configure), most source
- directories will contain two
- directories, Depend and Debug. The Depend
- directory contains automatically generated dependance files which are used
- during compilation to make sure that source files get rebuilt if a header
- file they use is modified. The Debug directory holds the object
- files, library files, and executables that are used for building a debug
- enabled build. The Release directory is created to hold the same
- files when the ENABLE_OPTIMIZED=1 flag is passed to gmake,
- causing an optimized build to be performed.
-
-
@@ -379,7 +630,7 @@
Reoptimizer, Target, Transforms, etc...