-
-
-
- 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.
-
-
-
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 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.
-
-
-
-
- LLVM is known to work on the following platforms:
-
-
Linux on x86 (Pentium and above)
-
-
Approximately 760 MB of Free Disk Space
-
-
Source code: 30 MB
-
Object code: 670 MB
-
GCC front end: 60 MB
-
-
-
-
-
-
Solaris on SparcV9 (Ultrasparc)
-
-
Approximately 1.24 GB of Free Disk Space
-
-
Source code: 30 MB
-
Object code: 1000 MB
-
GCC front end: 210 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).
-
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).
-
-
-
LLVMGCCDIR
-
- This is the where the LLVM GCC Front End is installed.
-
- For the pre-built GCC front end binaries, the LLVMGCCDIR is
- cfrontend/platform/llvm-gcc.
-
- 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.
-
-
-
alias llvmgcc LLVMGCCDIR/bin/gcc
-
alias llvmg++ LLVMGCCDIR/bin/g++
-
- This alias allows you to use the LLVM C and C++ front ends without putting
- them in your PATH or typing in their complete pathnames.
-
- 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:
-
-
llvm.tar.gz
-
This is the source code to the LLVM suite.
-
-
-
cfrontend.sparc.tar.gz
-
This is the binary release of the GCC front end for Solaris/Sparc.
-
-
-
cfrontend.x86.tar.gz
-
This is the binary release of the GCC front end for Linux/x86.
-
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.
-
-
- Note that the GCC front end is not included in the CVS repository. You
- should have downloaded the binary distribution for your platform.
-
- 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:
+
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.
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 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.
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).
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.
-
- cd cfrontend/sparc
+
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).
+
+
+
LLVMGCCDIR
+
+ This is the where the LLVM GCC Front End is installed.
+
+ For the pre-built GCC front end binaries, the LLVMGCCDIR is
+ cfrontend/platform/llvm-gcc.
+
+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.
+
+
+
alias llvmgcc LLVMGCCDIR/bin/gcc
+
alias llvmg++ LLVMGCCDIR/bin/g++
+
+ This alias allows you to use the LLVM C and C++ front ends without putting
+ them in your PATH or typing in their complete pathnames.
+
+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:
+
+
llvm.tar.gz
+
This is the source code to the LLVM suite.
+
+
+
cfrontend.sparc.tar.gz
+
This is the binary release of the GCC front end for Solaris/Sparc.
+
+
+
cfrontend.x86.tar.gz
+
This is the binary release of the GCC front end for Linux/x86.
+
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.
+
+
Note that the GCC front end is not included in the CVS repository. You
+should have downloaded the binary distribution for your platform.
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.platform.tar.gz | tar -xvf
+ -
+
+
+
If you are on a Sparc/Solaris machine, you will need to fix the header
+files:
+
+
cd cfrontend/sparc
+ ./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 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:
+
+
+
--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 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).
+
+
--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.
+
+
--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.
+
+
+
To configure LLVM, follow these steps:
+
+
+
Change directory into the object root directory:
- ./fixheaders
-
-
+ cd OBJ_ROOT
- 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.
-
+
Run the configure script located in the LLVM source tree:
+
+ SRC_ROOT/configure
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.
+
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 GCC front end
+install, 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.
-
- The following environment variables are used by the configure
- script to configure the build system:
-
- 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.
-
-
-
+
Once you have configured LLVM, you can build it. There are three types of
+builds:
-
- The following options can be used to set or enable LLVM specific options:
-
-
-
-
--with-llvmgccdir=LLVMGCCDIR
+
+
Debug Builds
- Path to the location where the LLVM C front end binaries and
- associated libraries will be installed.
-
-
--enable-optimized
+ 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.
+
+
+
Release (Optimized) Builds
- 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).
-
-
--enable-jit
+ 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.
+
+
+
Profile Builds
- 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.
-
-
--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.
-
-
-
- To configure LLVM, follow these steps:
-
-
Change directory into the object root directory:
-
- cd OBJ_ROOT
-
-
-
Run the configure script located in the LLVM source tree:
-
- SRC_ROOT/configure
-
-
-
-
- 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 GCC front end
- install, 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.
-
-
- 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.
-
-
-
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.
-
-
-
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:
-
- 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.
-
-
-
- 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
- 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/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/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. Additionally, it can convert
- LLVM bytecode to C, which is enabled with the -c option.
-
-
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.
-
-
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.
First, create a simple C file, name it 'hello.c':
+ 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:
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.
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
+ 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/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/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. Additionally, it can convert
+ LLVM bytecode to C, which is enabled with the -c option.
+
+
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.
+
+
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
+
or
- % lli hello.bc
+
% lli hello.bc
-
Use the llvm-dis utility to take a look at the LLVM assembly
- code:
+
Use the llvm-dis utility to take a look at the LLVM assembly
+ code:
- % llvm-dis < hello.bc | less
+
% llvm-dis < hello.bc | less
-
Compile the program to native Sparc assembly using the code
- generator (assuming you are currently on a Sparc system):
+
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
+
% llc hello.bc -o hello.s
-
Assemble the native sparc assemble file into a program:
+
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.
+
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:
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: