+ 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 and C++ code into LLVM bytecode. Currently, the + GCC 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 from the LLVM suite. + + +
+ +
-
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 - want to get started as quickly as possible. + Unpacking the distribution requires the following tools: +
+ Note that we currently do not support any other C++ compiler. +
+ ++ +
+ +
+ There are some additional tools that you may want to have when working with + LLVM: +
+ ++ 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). +
+ ++ In order to run the tests in the LLVM test suite, you will need QMTest and + a version of the Python interpreter that works with QMTest. +
The remainder 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 next section gives a short summary for those + who are already familiar with the system and want to get started as quickly + as possible. A complete guide to installation is + provided in the subsequent section.
The later sections of this guide describe the general layout of the the LLVM source-tree, a general layout of the the LLVM source-tree, a simple example using the LLVM tool chain, and links to find more information about LLVM or to get help via e-mail.
+ +
+ +
+ +
+ +
+ +
+
See Setting up your environment on tips to +
See Setting Up Your Environment on tips to simplify working with the LLVM front-end and compiled tools. See the - other sub-sections below for other useful details in working with LLVM, + next section for other useful details in working with LLVM, or go straight to Program Layout to learn about the layout of the source code tree. + +
Through this manual, the following names are used to denote paths +
Throughout this manual, the following names are used to denote paths specific to the local system and working environment. These are not - environment variables you need to set, but just strings used in the rest - of this document below.. 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. 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:
-+ +
+ +
+ +
+ For the pre-built GCC front end binaries, the LLVMGCCDIR is + cfrontend/platform/llvm-gcc. +
Before checking out the source code, you will need to know the path to - CVS repository containing LLVM source code (we'll call this - CVSROOTDIR below). Ask the person responsible for your local LLVM - installation to give you this path. +
+ 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. -
To get a fresh copy of the entire source code, all you - need to do is check it out from CVS as follows: +
+ +
+ If you have the LLVM distribution, you will need to unpack it before you + can begin to compile it. LLVM is distributed as a set of three files. Each + file is a TAR archive that is compressed with the gzip program. +
+ +The three files are as follows: +
+ +
+ +
If you have access to our CVS repository, you can get a fresh copy of + the entire source code. All you need to do is check it out from CVS as + follows:
+ Note that the GCC front end is not included in the CVS repository. You + should have downloaded the binary distribution for your platform. +
+ -The file llvm/Makefile.config - defines the following path variables, - which are specific to a particular installation of LLVM. - These should need to be modified only once after checking out a copy - of LLVM (if the default values do not already match your system): +
+ Before configuring and compiling the LLVM suite, you need to extract the + LLVM GCC front end from the binary distribution. It is used for building the + bytecode libraries later used by the GCC front end for linking programs, and + its location must be specified when the LLVM suite is configured. +
-+ To install the GCC front end, do the following: +
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. It also populates OBJ_ROOT with + the Makefiles needed to build LLVM. + +
+ The following environment variables are used by the configure + script to configure the build system: +
+ +| Variable | ++ Purpose + | +
|---|---|
| CC | ++ Tells configure which C compiler to use. By default, + configure will look for the first GCC C compiler in + PATH. Use this variable to override + configure's default behavior. + | +
| CXX | ++ Tells configure which C++ compiler to use. By default, + configure will look for the first GCC C++ compiler in + PATH. Use this variable to override + configure's default behavior. + | +
+ The following options can be used to set or enable LLVM specific options: +
+ ++
+
+
+ To configure LLVM, follow these steps: +
+ +
+
+ version of the GCC front end on our research machines.
-
The LLVM make system sends most output files generated during the build - into the directory defined by the variable LLVM_OBJ_DIR in - llvm/Makefile.config. 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. + Once you have configured LLVM, you can build it. There are three types of + builds: -
If you do not wish to use a different location for object files (building - into the source tree directly), just set this variable to ".".
+
+ +
+ +
+ gmake + +
+ 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: +
+ ++ gmake -j2 + +
+ There are several special targets which are useful when working with the LLVM + source code: + +
+ +
+ +
- 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.) +
Add the following lines to your .cshrc (or the corresponding - lines to your .profile if you use a bourne shell derivative). + It is also possible to override default values from configure by + declaring variables on the command line. The following are some examples: -
- # Make the C front end easy to use... - alias llvmgcc LLVMGCCDIR/bin/llvm-gcc +
+ +
+ +
+
The other LLVM tools are part of the LLVM - source base, and built when compiling LLVM. They will be built into the - LLVM_OBJ_DIR/tools/Debug directory.
+ Every directory in the LLVM object tree includes a Makefile to + build it and any subdirectories that it contains. Entering any directory + inside the LLVM object tree and typing gmake should rebuild + anything in or below that directory that is out of date. -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 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 llvm/tools/Debug. If you want to look at the libraries that - were compiled, look in llvm/lib/Debug.
++ The LLVM build system is capable of sharing a single LLVM source tree among + several LLVM builds. Hence, it is possible to build LLVM for several + different platforms or configurations using the same source tree. +
+ This is accomplished in the typical autoconf manner: +
+ cd OBJ_ROOT - If you get an error talking about a /localhome directory, follow - the instructions in the section about Setting Up Your - Environment. +
+ SRC_ROOT/configure +
+ The LLVM build will place files underneath OBJ_ROOT in directories + named after the build type: +
++ +
+ +
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:
- + href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/. + The following is a brief introduction to code layout: +- -
+ library. The three main subdirectories of this directory are:
@@ -298,8 +752,7 @@
+ This directory contains libraries which are compiled into LLVM bytecode and + used when linking programs with the GCC front end. Most of these libraries + are skeleton versions of real libraries; for example, libc is a stripped down + version of glibc. +
+ ++ Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end + to compile. +
+This directory contains regression tests and source code that is used to - test the LLVM infrastructure...
+ test the LLVM infrastructure. ++ +
+ +
+ +
-
+
+
+
+ to a simple interpreter, lli also has a tracing mode (entered by + specifying -trace on the command line). Finally, for + architectures that support it (currently only x86 and Sparc), by default, + lli will function as a Just-In-Time compiler (if the + functionality was compiled in), and will execute the code much + faster than the interpreter.
+ which translates LLVM bytecode to a SPARC or x86 assembly file.
-
+ performs a variety of optimizations, and outputs LLVM bytecode. Thus + when you invoke llvmgcc -c x.c -o x.o, you are causing + gccas to be run, which writes the x.o file (which is + an LLVM bytecode file that can be disassembled or manipulated just like + any other bytecode file). The command line interface to gccas + is designed to be as close as possible to the system + `as' utility so that the gcc frontend itself did not have to be + modified to interface to a "weird" assembler.
@@ -386,16 +876,81 @@ command is a good way to get a list of the program transformations available in LLVM.
- -
+
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ - + -
-
- % dis < hello.bc | less
+ % llvm-dis < hello.bc | less
+ generator (assuming you are currently on a Sparc system):
% llc hello.bc -o hello.s
@@ -449,7 +1004,76 @@ -
+ +
+ Another possibility is that we hardcoded a path in our Makefiles. If + you see this, please email the LLVM bug mailing list with the name of + the offending Makefile and a description of what is wrong with it. + +
+ +
+ PATH=
+ This is still somewhat inconvenient, but it allows + configure to do its work without having to adjust your + PATH permanently. +
+ The best thing to try is to remove the old files and re-build. In most + cases, this takes care of the problem. To do this, just type make + clean and then make in the directory that fails to build. +
+ +
This document is just an introduction to how to use LLVM to do @@ -460,19 +1084,19 @@