diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index f4083f34817..711b04cdc4c 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -1,468 +1,480 @@ - - Getting Started with LLVM System - - - -
-

Getting Started with the LLVM System
-By: Guochun Shi, Chris Lattner and Vikram Adve

-
- - -

Contents

- - - - - -
-

Overview

-
- - -

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 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. -

-
-

Getting Started

-
- - - -

Getting Started Quickly (A Summary)

- - Here's the short story for getting up and running quickly with LLVM: - -
    -
  1. Find the path to the CVS repository containing LLVM (we'll call -this CVSROOTDIR).
    2. -
  2. cd where-you-want-llvm-to-live
    3. -
  3. cvs -d CVSROOTDIR checkout llvm
    4. -
  4. cd llvm
    5. -
  5. Edit Makefile.config to set local paths. This includes - setting the install location of the C frontend and the various paths - to the C and C++ compilers used to build LLVM itself.
    6. -
  6. Set your LLVM_LIB_SEARCH_PATH environment variable.
    7. -
  7. gmake -k |& tee gnumake.out    # this is -csh or tcsh syntax
    8. -
- -

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. -

-

Terminology and Notation

- - -

Through 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. + +

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. + + +

Terminology and Notation

+ + +

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:

- - - - -

Checkout LLVM from CVS

- - -

Before checking out the source code, you will need to know the path to - the CVS repository containing LLVM source code (we'll call this CVSROOTDIR -below). Ask the person responsible for your local LLVM installation -to give you this path.

-

To 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.

- - -

Local Configuration Options

- - -

The file llvm/Makefile.config defines the following path -variables which are specific to a particular installation of LLVM. - These should need to be modified only once after checking out a copy - of LLVM (if the default values do not already match your system): -

- - In addition to settings in this file, you must set a LLVM_LIB_SEARCH_PATH -environment variable in your startup scripts. This environment variable -is used to locate "system" libraries like "-lc" and "-lm" -when linking. This variable should be set to the absolute path for the -bytecode-libs subdirectory of the C front-end install. For example, - /home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs is used -for the X86 version of the C front-end on our research machines. -

-

-

The location for LLVM object files

- - -

The LLVM make system sends most output files generated during the build - into the directory defined by the variable OBJ_ROOT in llvm/Makefile.config. - This can be either just your normal LLVM source tree or some other directory -writable by you. You may wish to put object files on a different filesystem -either to keep them from being backed up or to speed up local builds. -

-

If you do not wish to use a different location for object files (i.e. -building into the source tree directly), just set this variable to ".".

-

-

-

Setting up your environment

- - NOTE: This step is optional but will set up your environment so you - can use the compiled LLVM tools with as little hassle as possible.) - -

Add the following lines to your .cshrc (or the corresponding - lines to your .profile if you use a bourne shell derivative). -

-
       # Make the C front end easy to use...
       alias llvmgcc LLVMGCCDIR/bin/llvm-gcc
+    
+
+    
+    
Checkout LLVM from CVS

+    
+
+    
Before checking out the source code, you will need to know the path to
+    the CVS repository containing LLVM source code (we'll call this
+    CVSROOTDIR below).  Ask the person responsible for your local LLVM
+    installation to give you this path.
+
+    
To 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.

+
+    
+    
Local Configuration Options

+    
+
+    
The file llvm/Makefile.config
+    defines the following path variables
+    which are specific to a particular installation of LLVM.
+    These need to be modified only once after checking out a copy
+    of LLVM (if the default values do not already match your system):
+
+    

+
+    In addition to settings in this file, you must set a
+    LLVM_LIB_SEARCH_PATH environment variable in your startup scripts.
+    This environment variable is used to locate "system" libraries like
+    "-lc" and "-lm" when linking.  This variable should be set
+    to the absolute path for the bytecode-libs subdirectory of the C front-end
+    install.  For example, one might use
+    /home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs for the X86
+    version of the C front-end on our research machines.

+
+    
+    
The location for LLVM object files

+    
+
+    
The LLVM make system sends most output files generated during the build
+    into the directory defined by the variable OBJ_ROOT in
+    llvm/Makefile.config.  This can be either just your normal LLVM
+    source tree or some other directory writable by you.  You may wish to put
+    object files on a different filesystem either to keep them from being backed
+    up or to speed up local builds.
+
+    
If you do not wish to use a different location for object files (i.e.
+    you are building into the source tree directly), just set this variable to
+    ".".

+
+    
+    
Setting up your environment

+    
+
+    NOTE: This step is optional but will set up your environment so you
+    can use the compiled LLVM tools with as little hassle as
+     possible.)
+
+    
Add the following lines to your .cshrc (or the corresponding
+    lines to your .profile if you use a bourne shell derivative).
+
+    
+       # Make the C front end easy to use...
+       alias llvmgcc LLVMGCCDIR/bin/llvm-gcc
 
        # Make the LLVM tools easy to use...
-       setenv PATH OBJ_ROOT/llvm/tools/Debug:${PATH}
    

-     The llvmgcc alias is useful because the C compiler is not 
-   included in the CVS tree you just checked out.          
-
The other LLVM tools are part of the LLVM     source
-base and are built when compiling LLVM.  They will be built into the    
-OBJ_ROOT/tools/Debug directory.

-       
+       setenv PATH OBJ_ROOT/llvm/tools/Debug:${PATH}
+
+ The llvmgcc alias is useful because the C compiler is not + included in the CVS tree you just checked out. -

Compiling the source code

- - -

Every directory in the LLVM source tree includes a Makefile to - build it and any subdirectories that it contains. These makefiles require - GNU Make (gmake) instead of make to build them, but -can otherwise be used freely. To build the entire LLVM system, just -enter the top level llvm directory and type gmake. - A few minutes later you will hopefully have a freshly compiled toolchain -waiting for you in OBJ_ROOT/llvm/tools/Debug. - If you want to look at the libraries that were compiled, look in OBJ_ROOT/llvm/lib/Debug.

- If you get an error about the /localhome directory, chances -are good that something has been misconfigured.  Follow the instructions -in the section about Setting Up Your Environment. - - -
-

Program Layout

-
- - -

One useful source of infomation about the LLVM sourcebase is the LLVM -doxygen documentation, available at -http://llvm.cs.uiuc.edu/doxygen/. -The following is a brief introduction to code layout:

- - -

CVS directories

- - Every directory checked out of CVS will contain a CVS directory; - for the most part, these can just be ignored. - -

Depend, Debug, & Release +

The other LLVM tools are part of the LLVM + source base and built when compiling LLVM. They will be built into the + OBJ_ROOT/tools/Debug directory.

+ + +

Compiling the source code

+ + +

Every directory in the LLVM source tree includes a Makefile to + build it and any subdirectories that it contains. These makefiles require + that you use GNU Make (aka gmake) instead of make to + build them, but can + otherwise be used freely. To build the entire LLVM system, just enter the + top level llvm directory and type gmake. A few minutes + later you will hopefully have a freshly compiled toolchain waiting for you + in OBJ_ROOT/llvm/tools/Debug. If you want to look at the + libraries that were compiled, look in + OBJ_ROOT/llvm/lib/Debug.

+ + If you get an error about a /localhome directory, follow the + instructions in the section about Setting Up Your + Environment. + + + + +
+

Program Layout

+
+ + +

One useful source of infomation about the LLVM sourcebase is the LLVM doxygen documentation, available at http://llvm.cs.uiuc.edu/doxygen/. The + following is a brief introduction to code layout:

+ + + +

CVS directories

+ + + Every directory checked out of CVS will contain a CVS directory; + for the most part these can just be ignored. + + + +

Depend, Debug, & Release directories

- - If you are building with the "OBJ_ROOT=." option enabled in -the Makefile.config file, most source directories will contain -two directories, Depend and Debug. The Depend - directory contains automatically generated dependance files which are -used during compilation to make sure that source files get rebuilt if -a header file they use is modified. The Debug directory holds -the object files, library files, and executables that are used for building -a debug enabled build. The Release directory is created to -hold the same files when the ENABLE_OPTIMIZED=1 flag is passed -to gmake, causing an optimized built to be performed. -

-

-

llvm/include

- - This directory contains public header files exported from the LLVM - library. The two main subdirectories of this directory are: -

-
    -
  1. 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... -
    2. -
  2. llvm/include/Support - This directory contains generic - support libraries that are independant of LLVM, but are used by LLVM. - For example, some C++ STL utilities and a Command Line option processing - library.
    3. -
- - -

llvm/lib

- - This directory contains most source files of 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/.
-
- - -

llvm/test

- - -

This directory contains regression tests and source code that is used -to test the LLVM infrastructure...

- - -

llvm/tools

- - -

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 intepreter, - lli is also has debugger and tracing modes (entered by -specifying -debug or -trace on the command line, -respectively). -

-
-
llc
-
llc is the LLVM backend compiler, which translates -LLVM bytecode to a SPARC 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. -

+ + + If you are building with the "OBJ_ROOT=." option enabled in the + Makefile.config file, most source directories will contain two + directories, Depend and Debug. The Depend + directory contains automatically generated dependance files which are used + during compilation to make sure that source files get rebuilt if a header + file they use is modified. The Debug directory holds the object + files, library files, and executables that are used for building a debug + enabled build. The Release directory is created to hold the same + files when the ENABLE_OPTIMIZED=1 flag is passed to gmake, + causing an optimized built to be performed.

+ + + +

llvm/include

+ + + This directory contains public header files exported from the LLVM + library. The two main subdirectories of this directory are:

+

    -
    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 "wierd" 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. -

    -
    +
  1. 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... + +
  2. llvm/include/Support - This directory contains generic + support libraries that are independant of LLVM, but are used by LLVM. + For example, header files for some C++ STL utilities and a Command Line + option processing library are located here.
-
-
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. -

-
-
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. -

-
-
- - -

An example using the LLVM tool chain

- - -
    -
  1. First, create a simple C file, name it 'hello.c': - - 
       #include <stdio.h>
       int main() {
         printf("hello world\n");
         return 0;
       }
    -
    2. -
  2. Next, compile the C file into a LLVM bytecode file: -

    % llvmgcc hello.c -o hello

    -

    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.

    -

    -
    3. -
  3. Run the program. To make sure the program ran, execute one of the - following commands: -

    % ./hello

    -

    or

    -

    % lli hello.bc

    -

    -
    4. -
  4. Use the dis utility to take a look at the LLVM assembly - code: -

    % dis < hello.bc | less

    -

    -
    5. -
  5. Compile the program to native Sparc assembly using the code generator: -

    % llc hello.bc -o hello.s

    -

    -
    6. -
  6. Assemble the native sparc assemble file into a program: -

    % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc

    -

    -
    7. -
  7. Execute the native sparc program: -

    % ./hello.sparc

    -

    -
    8. -     -
- - -

Links

- - -

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:

+ + +

llvm/lib

+ + + This directory contains most source files of 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/. +
+ + +

llvm/test

+ + +

This directory contains regression tests and source code that is used to + test the LLVM infrastructure...

+ + +

llvm/tools

+ + +

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 intepreter, lli is also has debugger and tracing + modes (entered by specifying -debug or -trace on the + command line, respectively).

+ +

llc
llc is the LLVM backend compiler, + which translates LLVM bytecode to a SPARC 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 "wierd" + 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.

+ + +

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.

+ +

+ + +

An example using the LLVM tool chain

+ + +
    +
  1. First, create a simple C file, name it 'hello.c': + 
    +   #include <stdio.h>
+   int main() {
+     printf("hello world\n");
+     return 0;
+   }
+
    + +
  2. Next, compile the C file into a LLVM bytecode file:

    + + % llvmgcc hello.c -o hello

    + + 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.

    + +

  3. Run the program. To make sure the program ran, execute one of the + following commands:

    -

     - -
    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
    - + % ./hello

    + + or

    + + % lli hello.bc

    + +

  4. Use the dis utility to take a look at the LLVM assembly + code:

    + + % dis < hello.bc | less

    + +

  5. Compile the program to native Sparc assembly using the code + generator:

    + + % llc hello.bc -o hello.s

    + +

  6. Assemble the native sparc assemble file into a program:

    + + % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc

    + +

  7. Execute the native sparc program:

    + + % ./hello.sparc

    + +

+ + + +

Links

+ + +

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 + +