diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index 3aab1932ffb..3eae0d10bb6 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -1,1049 +1,1097 @@ - + -
-- 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. - - -
- -
- -
- -
- -
- -
- - - -
- 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. - - -
- -
- 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. -
- - -- - Compiling LLVM requires that you have several software packages installed: - -
- There are some additional tools that you may want to have when working with - LLVM: -
- -- If you want to make changes to the configure scripts, you will need - GNU autoconf (2.57 or higher), and consequently, GNU M4 (version 1.4 - or higher). -
- -- These are needed to use the LLVM test suite. -
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:
-- -
- -
- 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. - -
- -
- If you have the LLVM distribution, you will need to unpack it before you - can begin to compile it. LLVM is distributed as a set of three files. Each - file is a TAR archive that is compressed with the gzip program. -
- -The three files are as follows: -
- -
- -
If you have access to our CVS repository, you can get a fresh copy of - the entire source code. All you need to do is check it out from CVS as - follows: -
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: +
By: + Guochun Shi, + Chris Lattner, + John Criswell, + Misha Brukman, and + Vikram Adve.
+ + + +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:
+ +Specify where the LLVM GCC frontend is installed.
Enable the SPEC2000 benchmarks for testing. The SPEC2000 + benchmarks should be available in + directory.
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:
+ +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.
+ +Compiling LLVM requires that you have several software packages +installed:
+ +There are some additional tools that you may want to have when working with +LLVM:
+ +If you want to make changes to the configure scripts, you will need GNU + autoconf (2.57 or higher), and consequently, GNU M4 (version 1.4 or + higher).
These are needed to use the LLVM test suite.
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:
+ +
-
- cd cfrontend/sparc
+
+
+
+ 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. + +
+ +
+If you have the LLVM distribution, you will need to unpack it before you +can begin to compile it. LLVM is distributed as a set of three files. Each +file is a TAR archive that is compressed with the gzip program. +
+ +The three files are as follows: +
+ +
+ +
If you have access to our CVS repository, you can get a fresh copy of +the entire source code. All you need to do is check it out from CVS as +follows:
+ +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:
+ +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.
+ +In cases like these, you may want to try building the GCC front end from source. This is +not for the faint of heart, so be forewarned.
+ +Once checked out from the CVS repository, the LLVM suite source code must be +configured via the configure script. This script sets variables in +llvm/Makefile.config and llvm/include/Config/config.h. It +also populates OBJ_ROOT with the Makefiles needed to build LLVM.
+ +The following environment variables are used by the configure +script to configure the build system:
+ +Variable | +Purpose | +
---|---|
CC | +Tells configure which C compiler to use. By default, + configure will look for the first GCC C compiler in + PATH. Use this variable to override + configure's default behavior. | +
CXX | +Tells configure which C++ compiler to use. By default, + configure will look for the first GCC C++ compiler in + PATH. Use this variable to override + configure's default behavior. | +
The following options can be used to set or enable LLVM specific options:
+ ++
+
+
To configure LLVM, follow these steps:
+ +- 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. -
+- In cases like these, you may want to try - building the GCC front end from source. - This is not for the faint of heart, so be forewarned. -
- -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: -
+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. - | -
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: -
- --
+ +
-
+ +
-
- To configure LLVM, follow these steps: -
- -
-
- - -
- -
- -
- 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: - -
- -
- -
- -
- -
- -
-
- The LLVM build system is capable of sharing a single LLVM source tree among - several LLVM builds. Hence, it is possible to build LLVM for several - different platforms or configurations using the same source tree. -
- This is accomplished in the typical autoconf manner: -
- cd OBJ_ROOT - -
- 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 libraries which are compiled into LLVM bytecode and - used when linking programs with the GCC front end. Most of these libraries - are skeleton versions of real libraries; for example, libc is a stripped down - version of glibc. -
- -- Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end - to compile. -
- - -This directory contains regression tests and source code that is used to - test the LLVM infrastructure. -
- - -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.
- -- -
- -
- -
- -
- -
- -
- -
- -
- -
- -
-
- -
- -
- -
- -
- -
- -
- -
- -
- -
- - - - -
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:
+ ++ +
+ +
+
It is also possible to override default values from configure by +declaring variables on the command line. The following are some examples:
+ ++ +
+ +
+
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:
+ +Every directory checked out of CVS will contain a CVS directory; for +the most part these can just be ignored.
+ +This directory contains public header files exported from the LLVM +library. The three main subdirectories of this directory are:
+ +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.
+ +This directory contains libraries which are compiled into LLVM bytecode and +used when linking programs with the GCC front end. Most of these libraries are +skeleton versions of real libraries; for example, libc is a stripped down +version of glibc.
+ +Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front +end to compile.
+ +This directory contains regression tests and source code that is used to test +the LLVM infrastructure.
+ +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.
+ ++ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+
+ +
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.
+ ++ +
+ +
+ +
+ +
+ +
+ +
+ +
+ +
+ + + + + + +
+ + +#include <stdio.h> int main() { printf("hello world\n"); return 0; } -+
+
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:
- % ./hello+
% ./hello
- or+
or
- % lli hello.bc+
% lli hello.bc
+
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):
- % llc hello.bc -o hello.s+
% llc hello.bc -o hello.s
-+
Assemble the native sparc assemble file into a program:
- % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc+
% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc
-+
Execute the native sparc program:
- % ./hello.sparc+
% ./hello.sparc
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:
- - -Last modified: Thu Nov 6 14:50:33 CST 2003 - - + + +