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 contains an assembler, disassembler, bytecode
+analyzer, and bytecode optimizer. 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.
Here's the short story for getting up and running quickly with LLVM:
+
+
+
Install the GCC front end:
+
+
cd where-you-want-the-C-front-end-to-live
+
gunzip --stdout cfrontend.platform.tar.gz | tar -xvf -
+
Sparc and MacOS X Only:
+ cd cfrontend/platform
+ ./fixheaders
+
+
+
Get the Source Code
+
+
With the distributed files:
+
+
cd where-you-want-llvm-to-live
+
gunzip --stdout llvm-version.tar.gz | tar -xvf -
+
cd llvm
+
-
- 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 C front end.
-
- The second piece is the C 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 from the LLVM suite.
-
-
-
-
-
- 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.
-
-
-
Hit the return key when prompted for the password.
+
cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm
+ co llvm
+
cd llvm
+
+
+
+
Configure the LLVM Build Environment
+
+
Change directory to where you want to store the LLVM object
+ files and run configure to configure the Makefiles and
+ header files for the default platform. Useful options include:
+
+
--with-llvmgccdir=directory
+
Specify the full pathname of where the LLVM GCC frontend is
+ installed.
+
--enable-spec2000=directory
+
Enable the SPEC2000 benchmarks for testing. The SPEC2000
+ benchmarks should be available in
+ directory.
+
+
+
+
Build the LLVM Suite:
+
+
Set your LLVM_LIB_SEARCH_PATH environment variable.
+
gmake -k |& tee gnumake.out
+ # this is csh or tcsh syntax
+
+
+
+
+
Consult the Getting Started with LLVM section for
+detailed information on configuring and compiling LLVM. See Setting Up Your Environment for tips that simplify
+working with the GCC front end and LLVM tools. Go to Program
+Layout to learn about the layout of the source code tree.
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.
- If you want to compile your own version of the C front end, you will need
- additional disk space:
-
-
+
Source code: 45 MB
+
Object code: 956 MB
+
GCC front end: 40 MB
+
+
+
+
+
Solaris on SparcV9 (Ultrasparc)
+
+
Approximately 1.75 GB of Free Disk Space
+
+
Source code: 45 MB
+
Object code: 1705 MB
+
GCC front end: 50 MB
+
+
+
+
+
FreeBSD on x86 (Pentium and above)
+
+
Approximately 935 MB of Free Disk Space
-
Linux on x86
-
-
Approximately 249 MB of Free Disk Space
-
-
Source code: 146 MB
-
Object code: 82 MB
-
Installed binaries: 21 MB
-
-
-
-
-
-
Solaris on Sparc
-
-
Approximately 264 MB of Free Disk Space
-
-
Source code: 146 MB
-
Object code: 93 MB
-
Installed binaries: 25 MB
-
-
-
+
Source code: 45 MB
+
Object code: 850 MB
+
GCC front end: 40 MB
+
+
+
+
+
MacOS X on PowerPC
+
+
No native code generation
+
Approximately 1.25 GB of Free Disk Space
+
+
Source code: 45 MB
+
Object code: 1160 MB
+
GCC front end: 40 MB
+
+
+
+
+
+
+
The LLVM suite may compile on other platforms, but it is not
+guaranteed to do so. If compilation is successful, the LLVM utilities should be
+able to assemble, disassemble, analyze, and optimize LLVM bytecode. Code
+generation should work as well, although the generated native code may not work
+on your platform.
+
+
The GCC front end is not very portable at the moment. If you want to get it
+to work on another platform, you can download a copy of the source and try to
+compile it on your platform.
If you want to make changes to the configure scripts, you will need GNU
+ autoconf (2.57 or higher), and consequently, GNU M4 (version 1.4 or
+ higher). You will also need automake. Any old version of
+ automake from 1.4p5 on should work; we only use aclocal from that
+ package.
+ These are needed to use the LLVM test suite. Please note that newer
+ versions of QMTest may not work with the LLVM test suite. QMTest 2.0.3
+ can be retrieved from the QMTest CVS repository using the following
+ commands:
+
cvs -d :pserver:anoncvs@cvs.codesourcery.com:/home/qm/Repository co -r release-2-0-3 qm
+
+
+
+
+
+
+
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.
+A complete guide to installation is provided in the
+next section.
+
+
The later sections of this guide describe the 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.
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
+each of these names with the appropriate pathname on your local system.
+All these paths are absolute:
+
+
+
SRC_ROOT
+
+ This is the top level directory of the LLVM source tree.
+
+
OBJ_ROOT
+
+ This is the top level directory of the LLVM object tree (i.e. the
+ tree where object files and compiled programs will be placed. It
+ can be the same as SRC_ROOT).
- 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 (JIT) compilers only generate SparcV9 or x86 machine code.
-
- 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
- want to get started as quickly as possible.
-
-
The later sections of this guide describe the 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.
-
-
-
-
-
- Here's the short story for getting up and running quickly with LLVM:
-
-
Install the C front end:
-
-
cd where-you-want-the-C-front-end-to-live
-
gunzip --stdout cfrontend.platform.tar.gz | tar -xvf
- -
-
-
-
-
-
Get the Source Code
-
-
With the distributed files:
-
-
cd where-you-want-llvm-to-live
-
gunzip --stdout llvm.tar.gz | tar -xvf -
-
gunzip --stdout cfrontend.platform.tar.gz | tar -xvf -
-
cd llvm
-
-
-
-
-
With anonymous CVS access:
-
-
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
-
-
-
-
-
-
-
Configure the LLVM Build Environment
-
-
Run configure to configure the Makefiles and header
- files for the default platform.
- Useful options include:
-
-
--with-objroot=directory
-
- Specify where object files should be placed during the build.
-
-
--with-llvmgccdir=directory
-
- Specify where the LLVM C frontend is going to be installed.
-
-
-
-
-
-
Build the LLVM Suite
-
-
Set your LLVM_LIB_SEARCH_PATH environment variable.
-
gmake -k |& tee gnumake.out
- # this is csh or tcsh syntax
-
-
-
-
-
-
-
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,
- or go straight to Program Layout to learn about the
- layout of the source code tree. For information on building the C front
- end yourself, see Compiling the LLVM C Front End for
- information.
+
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
- 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.
-
- For the pre-built C front end binaries, the LLVMGCCDIR is
- cfrontend/platform/llvm-gcc.
-
-
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/bytecode-libs
+
+ This environment variable helps the LLVM GCC front end find bytecode
+ libraries that it will need for compilation.
- 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.
-
-
+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 two files: the LLVM
+suite and the LLVM GCC front end compiled for your platform. Each
+file is a TAR archive that is compressed with the gzip program.
+
+
+
The files are as follows:
+
+
llvm-1.2.tar.gz
+
This is the source code to the LLVM suite.
- 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 four files. Each
- file is a TAR archive that is compressed with the gzip program.
-
-
-
The four files are as follows:
-
-
llvm.tar.gz
-
This is the source code to the LLVM suite.
-
-
-
cfrontend.sparc.tar.gz
-
This is the binary release of the C front end for Solaris/Sparc.
-
-
-
cfrontend.x86.tar.gz
-
This is the binary release of the C front end for Linux/x86.
-
-
-
cfrontend-src.tar.gz
-
This is the source code release of the C front end.
-
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:
-
-
cd where-you-want-llvm-to-live
-
cvs -d CVSROOTDIR checkout llvm
-
-
-
This will create an 'llvm' directory in the current
- directory and fully populate it with the LLVM source code, Makefiles,
- test directories, and local copies of documentation files.
+
cfrontend-1.2.sparc-sun-solaris2.8.tar.gz
+
This is the binary release of the GCC front end for Solaris/Sparc.
- 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.
-
This is the binary release of the GCC front end for Linux/x86.
- Before configuring and compiling the LLVM suite, it is best to extract the
- LLVM C front end. While not used in building, the C front end is used by
- the LLVM test suite, and its location must be given to the
- configure script before the LLVM suite can be built.
-
+
cfrontend-1.2.i386-unknown-freebsd5.1.tar.gz
+
This is the binary release of the GCC front end for FreeBSD/x86.
- To install the C front end, do the following:
-
-
cd where-you-want-the-front-end-to-live
-
gunzip --stdout cfrontend.platform.tar.gz | tar -xvf
- -
-
This is the binary release of the GCC front end for MacOS X/PPC.
+
-
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.
+
-
- 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 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 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:
-
+
-
-
--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 of LLVM Object Files
- for more information.)
-
-
--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). 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. 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, 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
- gmake command line.
-
-
- Once you have LLVM configured, you can build it by entering the top level
- llvm directory and issuing the following command:
-
- gmake
+
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:
Hit the return key when prompted for the password.
+
cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
+ llvm
+
+
+
This will create an 'llvm' directory in the current
+directory and fully populate it with the LLVM source code, Makefiles,
+test directories, and local copies of documentation files.
+
+
If you want to get a specific release (as opposed to the most recent
+revision), you can specify a label. The following releases have the following
+label:
+
+
+
+ Release 1.2: RELEASE_12
+
+
+
+ Release 1.1: RELEASE_11
+
+
+
+ Release 1.0: RELEASE_1
+
+
+
+
+If you would like to get the GCC front end source code, you can also get it
+from the CVS repository:
+
+
cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
+ llvm-gcc
+
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:
+
+
+
cd where-you-want-the-front-end-to-live
+
gunzip --stdout cfrontend-version.platform.tar.gz | tar -xvf
+ -
+
+
+
If you are using Solaris/Sparc or MacOS X/PPC, you will need to fix the
+header files:
+
+
cd cfrontend/platform
+ ./fixheaders
+
+
The binary versions of the GCC front end may not suit all of your needs. For
+example, the binary distribution may include an old version of a system header
+file, not "fix" a header file that needs to be fixed for GCC, or it may be
+linked with libraries not available on your system.
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 begin building
+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:
+
+
+
--with-llvmgccdir=LLVMGCCDIR
+
+ Path to the location where the LLVM GCC front end binaries and
+ associated libraries were installed. This must be specified as an
+ absolute pathname.
- 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:
-
-
+
--enable-optimized
+
+ Enables optimized compilation by default (debugging symbols are removed
+ and GCC optimization flags are enabled). The default is to use an
+ unoptimized build (also known as a debug build).
- gmake -j2
-
+
--enable-jit
+
+ Compile the Just In Time (JIT) compiler functionality. This is not
+ available
+ on all platforms. The default is dependent on platform, so it is best
+ to explicitly enable it if you want it.
- There are several other targets which are useful when working with the LLVM
- source code:
-
-
-
gmake clean
-
- Removes all files generated by the build. This includes object files,
- generated C/C++ files, libraries, and executables.
-
-
-
gmake distclean
-
- Removes everything that gmake 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:
-
-
-
gmake ENABLE_OPTIMIZED=1
-
- Perform a Release (Optimized) build.
-
-
-
gmake ENABLE_PROFILING=1
-
- Perform a Profiling build.
-
-
-
gmake VERBOSE=1
-
- Print what gmake 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 gmake should rebuild
- anything in or below that directory that is out of date.
-
-
-
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.
-
+
--enable-spec2000
+
--enable-spec2000=<directory>
+
+ Enable the use of SPEC2000 when testing LLVM. This is disabled by default
+ (unless configure finds SPEC2000 installed). By specifying
+ directory, you can tell configure where to find the SPEC2000
+ benchmarks. If directory is left unspecified, configure
+ uses the default value
+ /home/vadve/shared/benchmarks/speccpu2000/benchspec.
- 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.
-
-
+
--enable-spec95
+
--enable-spec95=<directory>
+
+ Enable the use of SPEC95 when testing LLVM. It is similar to the
+ --enable-spec2000 option.
+
+
--enable-povray
+
--enable-povray=<directory>
+
+ Enable the use of Povray as an external test. Versions of Povray written
+ in C should work. This option is similar to the --enable-spec2000
+ option.
+
+
+
To configure LLVM, follow these steps:
+
+
+
Change directory into the object root directory:
+
+ cd OBJ_ROOT
- 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.
-
+
Run the configure script located in the LLVM source tree:
+
+ SRC_ROOT/configure
- The LLVM build will place files underneath OBJ_ROOT in directories
- named after the build type:
-
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:
-
-
- This directory contains public header files exported from the LLVM
- library. The three main subdirectories of this directory are:
+
-
-
llvm/include/llvm - This directory contains all of the LLVM
- specific header files. This directory also has subdirectories for
- different portions of LLVM: Analysis, CodeGen,
- Reoptimizer, Target, Transforms, etc...
-
-
llvm/include/Support - This directory contains generic
- support libraries that are independent of LLVM, but are used by LLVM.
- For example, some C++ STL utilities and a Command Line option processing
- library.
-
-
llvm/include/Config - This directory contains header files
- configured by the configure 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.
-
-
-
- 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 tools.
-
-
-
llvm/lib/VMCore/
This directory holds the core LLVM
- source files that implement core classes like Instruction and BasicBlock.
-
-
llvm/lib/AsmParser/
This directory holds the source code
- for the LLVM assembly language parser library.
-
-
llvm/lib/ByteCode/
This directory holds code for reading
- and write LLVM bytecode.
-
-
llvm/lib/CWriter/
This directory implements the LLVM to C
- converter.
-
-
llvm/lib/Analysis/
This directory contains a variety of
- different program analyses, such as Dominator Information, Call Graphs,
- Induction Variables, Interval Identification, Natural Loop Identification,
- etc...
-
-
llvm/lib/Transforms/
This directory contains the source
- code for the LLVM to LLVM program transformations, such as Aggressive Dead
- Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop
- Invarient Code Motion, Dead Global Elimination, Pool Allocation, and many
- others...
-
-
llvm/lib/Target/
This directory contains files that
- describe various target architectures for code generation. For example,
- the llvm/lib/Target/Sparc directory holds the Sparc machine
- description.
-
-
llvm/lib/CodeGen/
This directory contains the major parts
- of the code generator: Instruction Selector, Instruction Scheduling, and
- Register Allocation.
-
-
llvm/lib/Reoptimizer/
This directory holds code related
- to the runtime reoptimizer framework that is currently under development.
-
-
llvm/lib/Support/
This directory contains the source code
- that corresponds to the header files located in
- llvm/include/Support/.
-
The tools directory contains the executables built out of the
- libraries above, which form the main part of the user interface. You can
- always get help for a tool by typing tool_name --help. The
- following is a brief introduction to the most important tools.
-
-
-
as
The assembler transforms the human readable
- LLVM assembly to LLVM bytecode.
-
-
dis
The disassembler transforms the LLVM bytecode
- to human readable LLVM assembly. Additionally it can convert LLVM
- bytecode to C, which is enabled with the -c option.
-
-
lli
lli is the LLVM interpreter, which
- can directly execute LLVM bytecode (although very slowly...). In addition
- to a simple interpreter, lli is also has debugger and tracing
- modes (entered by specifying -debug or -trace on the
- command line, respectively). 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.
-
-
llc
llc is the LLVM backend compiler,
- which translates LLVM bytecode to a SPARC or x86 assembly file.
-
-
llvmgcc
llvmgcc is a GCC based C frontend
- that has been retargeted to emit LLVM code as the machine code output. It
- works just like any other GCC compiler, taking the typical -c, -S, -E,
- -o options that are typically used. The source code for the
- llvmgcc tool is currently not included in the LLVM cvs tree
- because it is quite large and not very interesting.
-
-
-
gccas
This tool is invoked by the
- llvmgcc frontend as the "assembler" part of the compiler. This
- tool actually assembles LLVM assembly to LLVM bytecode,
- 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.
-
-
gccld
gccld links together several LLVM
- bytecode files into one bytecode file and does some optimization. It is
- the linker invoked by the gcc frontend when multiple .o files need to be
- linked together. Like gccas the command line interface of
- gccld is designed to match the system linker, to aid
- interfacing with the GCC frontend.
-
-
-
opt
opt reads LLVM bytecode, applies a
- series of LLVM to LLVM transformations (which are specified on the command
- line), and then outputs the resultant bytecode. The 'opt --help'
- command is a good way to get a list of the program transformations
- available in LLVM.
+
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 of the bytecode-libs subdirectory of the GCC front
+end, or LLVMGCCDIR/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 GCC front end on our research machines.
-
-
analyze
analyze is used to run a specific
- analysis on an input LLVM bytecode file and print out the results. It is
- primarily useful for debugging analyses, or familiarizing yourself with
- what an analysis does.
Once you have configured LLVM, you can build it. There are three types of
+builds:
+
+
+
Debug Builds
+
+ These builds are the default when one types gmake (unless the
+ --enable-optimized option was used during configuration). The
+ build system will compile the tools and libraries with debugging
+ information.
-
- 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. The front end
- build needs to know where to find the LLVM tools, but you want to
- ensure that these tools are not found before the system assembler and
- linker that you normally use for compilation.
+
Release (Optimized) Builds
+
+ These builds are enabled with the --enable-optimized option to
+ configure or by specifying ENABLE_OPTIMIZED=1 on the
+ gmake command line. For these builds, the build system will
+ compile the tools and libraries with GCC optimizations enabled and strip
+ debugging information from the libraries and executables it generates.
+
-
cd GCCOBJ
+
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 specifying ENABLE_PROFILING=1
+ on the gmake command line.
+
+
+
Once you have LLVM configured, you can build it by entering the
+OBJ_ROOT directory and issuing the following command:
+
+
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:
+
+
+
gmake clean
+
+ Removes all files generated by the build. This includes object files,
+ generated C/C++ files, libraries, and executables.
+
+
+
gmake distclean
+
+ Removes everything that gmake 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.
+
+
+
gmake install
+
+ Installs LLVM files into the proper location. For the most part,
+ this does nothing, but it does install bytecode libraries into the
+ GCC front end's bytecode library directory. If you need to update
+ your bytecode libraries, this is the target to use once you've built
+ them.
+
+
+
+
It is also possible to override default values from configure by
+declaring variables on the command line. The following are some examples:
+
+
+
gmake ENABLE_OPTIMIZED=1
+
+ Perform a Release (Optimized) build.
+
+
+
gmake ENABLE_PROFILING=1
+
+ Perform a Profiling build.
+
+
+
gmake VERBOSE=1
+
+ Print what gmake is doing on standard output.
+
+
+
+
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.
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:
+
+
+
Change directory to where the LLVM object files should live:
+
+
cd OBJ_ROOT
+
+
Run the configure script found in the LLVM source
+ directory:
+
+
SRC_ROOT/configure
+
+
+
The LLVM build will place files underneath OBJ_ROOT in directories
+named after the build type:
+If you're running on a linux system that supports the "binfmt_misc"
+module, and you have root access on the system, you can set your system up to
+execute LLVM bytecode files directly. To do this, use commands like this (the
+first command may not be required if you are already using the module):
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:
This directory contains public header files exported from the LLVM
+library. The three main subdirectories of this directory are:
+
+
+
llvm/include/llvm - This directory contains all of the LLVM
+ specific header files. This directory also has subdirectories for
+ different portions of LLVM: Analysis, CodeGen,
+ Target, Transforms, etc...
+
+
llvm/include/Support - This directory contains generic
+ support libraries that are independent of LLVM, but are used by LLVM.
+ For example, some C++ STL utilities and a Command Line option processing
+ library store their header files here.
llvm/include/Config - This directory contains header files
+ configured by the configure 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.
The build will eventually fail. Don't worry; chances are good that
- everything that needed to build is built.
+
-
gmake -k install
-
+
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 tools.
-
- Once this is done, you should have a built front end compiler in
- LLVMGCCDIR.
-
+
+
llvm/lib/VMCore/
This directory holds the core LLVM
+ source files that implement core classes like Instruction and BasicBlock.
-
-
This directory holds the source code
+ for the LLVM assembly language parser library.
-
-
First, create a simple C file, name it 'hello.c':
+
llvm/lib/ByteCode/
This directory holds code for reading
+ and write LLVM bytecode.
+
+
llvm/lib/CWriter/
This directory implements the LLVM to C
+ converter.
+
+
llvm/lib/Analysis/
This directory contains a variety of
+ different program analyses, such as Dominator Information, Call Graphs,
+ Induction Variables, Interval Identification, Natural Loop Identification,
+ etc...
+
+
llvm/lib/Transforms/
This directory contains the source
+ code for the LLVM to LLVM program transformations, such as Aggressive Dead
+ Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop
+ Invariant Code Motion, Dead Global Elimination, and many others...
+
+
llvm/lib/Target/
This directory contains files that
+ describe various target architectures for code generation. For example,
+ the llvm/lib/Target/SparcV9 directory holds the Sparc machine
+ description.
+
+
llvm/lib/CodeGen/
This directory contains the major parts
+ of the code generator: Instruction Selector, Instruction Scheduling, and
+ Register Allocation.
+
+
llvm/lib/Support/
This directory contains the source code
+ that corresponds to the header files located in
+ llvm/include/Support/.
+
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.
The tools directory contains the executables built out of the
+libraries above, which form the main part of the user interface. You can
+always get help for a tool by typing tool_name --help. The
+following is a brief introduction to the most important tools:
+
+
+
analyze
analyze is used to run a specific
+ analysis on an input LLVM bytecode file and print out the results. It is
+ primarily useful for debugging analyses, or familiarizing yourself with
+ what an analysis does.
+
+
bugpoint
bugpoint is used to debug
+ optimization passes or code generation backends by narrowing down the
+ given test case to the minimum number of passes and/or instructions that
+ still cause a problem, whether it is a crash or miscompilation. See HowToSubmitABug.html for more information
+ on using bugpoint.
+
+
llvm-ar
The archiver produces an archive containing
+ the given LLVM bytecode files, optionally with an index for faster
+ lookup.
+
+
llvm-as
The assembler transforms the human readable
+ LLVM assembly to LLVM bytecode.
+
+
llvm-dis
The disassembler transforms the LLVM
+ bytecode to human readable LLVM assembly.
+
+
llvm-link
llvm-link, not surprisingly,
+ links multiple LLVM modules into a single program.
+
+
lli
lli is the LLVM interpreter, which
+ can directly execute LLVM bytecode (although very slowly...). In addition
+ 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.
+
+
llc
llc is the LLVM backend compiler, which
+ translates LLVM bytecode to a SPARC or x86 assembly file, or to C code (with
+ the -march=c option).
+
+
llvmgcc
llvmgcc is a GCC-based C frontend
+ that has been retargeted to emit LLVM code as the machine code output. It
+ works just like any other GCC compiler, taking the typical -c, -S, -E,
+ -o options that are typically used. The source code for the
+ llvmgcc tool is currently not included in the LLVM CVS tree
+ because it is quite large and not very interesting.
+
+
+
+
gccas
This tool is invoked by the
+ llvmgcc frontend as the "assembler" part of the compiler. This
+ tool actually assembles LLVM assembly to LLVM bytecode,
+ 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.
+
+
gccld
gccld links together several LLVM
+ bytecode files into one bytecode file and does some optimization. It is
+ the linker invoked by the GCC frontend when multiple .o files need to be
+ linked together. Like gccas, the command line interface of
+ gccld is designed to match the system linker, to aid
+ interfacing with the GCC frontend.
+
+
+
opt
opt reads LLVM bytecode, applies a
+ series of LLVM to LLVM transformations (which are specified on the command
+ line), and then outputs the resultant bytecode. The 'opt --help'
+ command is a good way to get a list of the program transformations
+ available in LLVM.
+
+
This directory contains utilities for working with LLVM source code, and some
+of the utilities are actually required as part of the build process because they
+are code generators for parts of LLVM infrastructure.
+
+
+
Burg/
Burg is an instruction selector
+ generator -- it builds trees on which it then performs pattern-matching to
+ select instructions according to the patterns the user has specified. Burg
+ is currently used in the Sparc V9 backend.
+
+
codegen-diff
codegen-diff is a script
+ that finds differences between code that LLC generates and code that LLI
+ generates. This is a useful tool if you are debugging one of them,
+ assuming that the other generates correct output. For the full user
+ manual, run `perldoc codegen-diff'.
+
+
cvsupdate
cvsupdate is a script that will
+ update your CVS tree, but produce a much cleaner and more organized output
+ than simply running `cvs -z3 up -dP' will. For example, it will group
+ together all the new and updated files and modified files in separate
+ sections, so you can see at a glance what has changed. If you are at the
+ top of your LLVM CVS tree, running utils/cvsupdate is the
+ preferred way of updating the tree.
+
+
emacs/
The emacs directory contains
+ syntax-highlighting files which will work with Emacs and XEmacs editors,
+ providing syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the README file in that directory.
+
+
getsrcs.sh
The getsrcs.sh script finds
+ and outputs all non-generated source files, which is useful if one wishes
+ to do a lot of development across directories and does not want to
+ individually find each file. One way to use it is to run, for example:
+ xemacs `utils/getsources.sh` from the top of your LLVM source
+ tree.
+
+
makellvm
The makellvm script compiles all
+ files in the current directory and then compiles and links the tool that
+ is the first argument. For example, assuming you are in the directory
+ llvm/lib/Target/Sparc, if makellvm is in your path,
+ simply running makellvm llc will make a build of the current
+ directory, switch to directory llvm/tools/llc and build it,
+ causing a re-linking of LLC.
+
+
NightlyTest.pl and
+ NightlyTestTemplate.html
These files are used in a
+ cron script to generate nightly status reports of the functionality of
+ tools, and the results can be seen by following the appropriate link on
+ the LLVM homepage.
+
+
TableGen/
The TableGen directory contains
+ the tool used to generate register descriptions, instruction set
+ descriptions, and even assemblers from common TableGen description
+ files.
+
+
vim/
The vim directory contains
+ syntax-highlighting files which will work with the VIM editor, providing
+ syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the README file in that directory.
Next, compile the C file into a LLVM bytecode file:
+
Next, compile the C file into a LLVM bytecode file:
+
% llvmgcc hello.c -o hello
- % llvmgcc hello.c -o hello
-
- This will create two result files: hello and
+
This will create two result files: hello and
hello.bc. The hello.bc is the LLVM bytecode that
corresponds the the compiled program and the library facilities that it
required. hello is a simple shell script that runs the bytecode
- file with lli, making the result directly executable.
+ file with lli, making the result directly executable.
-
Run the program. To make sure the program ran, execute one of the
- following commands:
+
Run the program. To make sure the program ran, execute one of the
+ following commands:
- % ./hello
+
% ./hello
- or
-
- % lli hello.bc
-
-
Use the dis utility to take a look at the LLVM assembly
- code:
-
- % dis < hello.bc | less
-
-
Compile the program to native Sparc assembly using the code
- generator (assuming you are currently on a Sparc system):
-
- % llc hello.bc -o hello.s
-
-
Assemble the native sparc assemble file into a program:
-
-
- Below are common problems and their remedies:
-
-
-
When I run configure, it finds the wrong C compiler.
-
- The configure script attempts to locate first gcc and
- then cc, unless it finds compiler paths set in CC and
- CXX for the C and C++ compiler, respectively.
-
- If configure finds the wrong compiler, either adjust your
- PATH environment variable or set CC and CXX
- explicitly.
-
-
-
I compile the code, and I get some error about /localhome.
-
- There are several possible causes for this. The first is that you
- didn't set a pathname properly when using configure, and it
- defaulted to a pathname that we use on our research machines.
-
- 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.
-
-
The configure script finds the right C compiler, but it
- uses the LLVM linker from a previous build. What do I do?
-
- The configure script uses the PATH to find
- executables, so if it's grabbing the wrong linker/assembler/etc, there
- are two ways to fix it:
-
-
Adjust your PATH environment variable so that the
- correct program appears first in the PATH. This may work,
- but may not be convenient when you want them first in your
- path for other work.
-
-
-
Run configure with an alternative PATH that
- is correct. In a Borne compatible shell, the syntax would be:
-
- PATH= ./configure ...
-
- This is still somewhat inconvenient, but it allows
- configure to do its work without having to adjust your
- PATH permanently.
-
This document is just an introduction to how to use LLVM to do
- some simple things... there are many more interesting and complicated things
- that you can do that aren't documented here (but we'll gladly accept a patch
- if you want to write something up!). For more information about LLVM, check
- out:
-
-
-
- If you have any questions or run into any snags (or you have any
- additions...), please send an email to
- Chris Lattner.
-
-
-
-Last modified: Tue Jun 3 22:06:43 CDT 2003
-
-
+
% lli hello.bc
+
+
Use the llvm-dis utility to take a look at the LLVM assembly
+ code:
+
+
% llvm-dis < hello.bc | less
+
+
Compile the program to native Sparc assembly using the code
+ generator (assuming you are currently on a Sparc system):
+
+
% llc hello.bc -o hello.s
+
+
Assemble the native sparc assemble file into a program:
If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the Frequently
+Asked Questions page.
This document is just an introduction to how to use LLVM to do
+some simple things... there are many more interesting and complicated things
+that you can do that aren't documented here (but we'll gladly accept a patch
+if you want to write something up!). For more information about LLVM, check
+out: