diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index 8dadc17f209..f4083f34817 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -1,477 +1,468 @@ - - 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 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: + + 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. All these paths are absolute:

- - - -

Checkout LLVM from CVS

- - -

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

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 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 LLVM_OBJ_DIR in - llvm/Makefile.config. This can be either just your normal LLVM - source tree or some other directory writable by you. You may wish to put - object files on a different filesystem either to keep them from being backed - up or to speed up local builds. - -

If you do not wish to use a different location for object files (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 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
 
        # Make the LLVM tools easy to use...
-       setenv PATH LLVM_OBJ_DIR/llvm/tools/Debug:${PATH}
-    

-    The llvmgcc alias is useful because the C compiler is not
-    included in the CVS tree you just checked out.
+       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.

+ -

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

- - -

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 gmake, instead of make to build them, but can - otherwise be used freely. To build the entire LLVM system, just enter the - top level llvm directory and type gmake. A few minutes - later you will hopefully have a freshly compiled toolchain waiting for you - in llvm/tools/Debug. If you want to look at the libraries that - were compiled, look in llvm/lib/Debug.

- - If you get an error talking 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 +

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 directories

- - - If you are building with the "BUILD_ROOT=." option enabled in the - Makefile.common 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. 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. -
- - -

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

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

    - +

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

      +
    - - - -

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

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