X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FGettingStarted.html;h=ea273a395579a54971445f40e35e48f00e3a2e27;hb=abb1b588c2eb08ab9dd306b50001805bdce89553;hp=f4083f34817ac6a6eeca1d903ac76fcfa7fd1f9d;hpb=8df90e0c8dc293d1265783a5f6f237708f578b03;p=oota-llvm.git diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index f4083f34817..ea273a39557 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -1,468 +1,1102 @@ - - Getting Started with LLVM System - - - -
-

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

-
- - -

Contents

- - - + +

+ +

  • Configure the LLVM Build Environment +
      +
    1. 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 +
      +
    1. Set your LLVM_LIB_SEARCH_PATH environment variable. +
    2. gmake -k |& tee gnumake.out +    # this is csh or tcsh syntax +
    + +

    + -

    • -
  • Program layout + +

    See Setting Up Your Environment on tips to + simplify working with the LLVM front-end and compiled tools. See the + next section for other useful details in working with LLVM, + or go straight to Program Layout to learn about the + layout of the source code tree. + + +

    +

    Getting Started with LLVM

    +
    +
    + + + +

    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:

    +
    +
    CVSROOTDIR +
    + This is the path for the CVS repository containing the LLVM source + code. Ask the person responsible for your local LLVM installation to + give you this path. +

    + +

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

    + + +

    Setting Up Your Environment

    + + +

    + 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/llvm-gcc/bytecode-libs +
    + This environment variable helps the LLVM GCC front end find bytecode + libraries that it will need for compilation. +

    + +

    alias llvmgcc LLVMGCCDIR/llvm-gcc/bin/gcc +
    alias llvmg++ LLVMGCCDIR/llvm-gcc/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. +
    + + +

    Unpacking the LLVM Archives

    + + +

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

    Checkout LLVM from CVS

    + + +

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

    + + +

    Install the GCC Front End

    + + +

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

      -
    1. CVS directories
      2. -
    2. Depend, Debug, & - Release directories
      3. -
    3. llvm/include
      4. -
    4. llvm/lib
      5. -
    5. llvm/test
      6. -
    6. llvm/tools
      7. +
    7. cd where-you-want-the-front-end-to-live +
    8. gunzip --stdout cfrontend.platform.tar.gz | tar -xvf + -
    -
    • -
  • An example using the LLVM tool chain -
    • -
  • Links
    • - - - -
    -

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

    Local LLVM Configuration

    + + +

    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:

    -
    -

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

    -

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

    + +

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

      +
    1. Change directory into the object root directory: +
      + cd OBJ_ROOT +

      + +

    2. Run the configure script located in the LLVM source tree: +
      + SRC_ROOT/configure +

      +

    -

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

    -

    + + 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/llvm-gcc/bytecode-libs. For example, one might + set LLVM_LIB_SEARCH_PATH to + /home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs for the X86 + version of the GCC front end on our research machines.

    + + +

    Compiling the LLVM Suite Source Code

    + + + 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 Location of LLVM Object Files

    + + +

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

    + +

    + The LLVM build will place files underneath OBJ_ROOT in directories + named after the build type:

    -

    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.

    - - -

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

    + +

    +
    Debug Builds +
    +
    +
    Tools +
    OBJ_ROOT/tools/Debug +
    Libraries +
    OBJ_ROOT/lib/Debug +
    +

    + +

    Release Builds +
    +
    +
    Tools +
    OBJ_ROOT/tools/Release +
    Libraries +
    OBJ_ROOT/lib/Release +
    +

    + +

    Profile Builds +
    +
    +
    Tools +
    OBJ_ROOT/tools/Profile +
    Libraries +
    OBJ_ROOT/lib/Profile +
    +
    + + +
    +

    Program Layout

    +
    +
    + + +

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

    -

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

    + + +

    CVS directories

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

    llvm/include

    + + + This directory contains public header files exported from the LLVM + library. The three 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, + Target, Transforms, etc... + +
    2. 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. + +
    3. 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.
    -
    -
    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 of the source files of the LLVM system. In + LLVM, almost all + code exists in libraries, making it very easy to share code among the + different tools.

    + +

    +
    llvm/lib/VMCore/
    This directory holds the core LLVM + source files that implement core classes like Instruction and BasicBlock. + +
    llvm/lib/AsmParser/
    This directory holds the source code + for the LLVM assembly language parser library. + +
    llvm/lib/ByteCode/
    This directory holds code for reading + and write LLVM bytecode. + +
    llvm/lib/CWriter/
    This directory implements the LLVM to C + converter. + +
    llvm/lib/Analysis/
    This directory contains a variety of + different program analyses, such as Dominator Information, Call Graphs, + Induction Variables, Interval Identification, Natural Loop Identification, + etc... + +
    llvm/lib/Transforms/
    This directory contains the source + code for the LLVM to LLVM program transformations, such as Aggressive Dead + Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop + Invarient Code Motion, Dead Global Elimination, 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/. +
    + + +

    llvm/runtime

    + + +

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

    + + +

    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.

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

    + +

    + + +

    llvm/utils

    + + + This directory contains utilities for working with LLVM sourcecode, 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 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.

    + +

    + + +

    +
    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 llvm-dis utility to take a look at the LLVM assembly + code:

      + + % llvm-dis < hello.bc | less

      + +

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

      + +

    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

      + +

    + + + +

    +
    Common Problems
    +

    +
    + + + Below are common problems and their remedies: + +
    +
    When I run configure, it finds the wrong C compiler. +
    + The configure script attempts to locate first gcc and + then cc, unless it finds compiler paths set in CC and + CXX for the C and C++ compiler, respectively. + + If configure finds the wrong compiler, either adjust your + PATH environment variable or set CC and CXX + explicitly. +

    + +

    I compile the code, and I get some error about /localhome. +
    + There are several possible causes for this. The first is that you + didn't set a pathname properly when using configure, and it + defaulted to a pathname that we use on our research machines. +

    + Another possibility is that we hardcoded a path in our Makefiles. If + you see this, please email the LLVM bug mailing list with the name of + the offending Makefile and a description of what is wrong with it. + +

    The configure script finds the right C compiler, but it + uses the LLVM linker from a previous build. What do I do? +
    + The configure script uses the PATH to find + executables, so if it's grabbing the wrong linker/assembler/etc, there + are two ways to fix it: +
      +
    1. Adjust your PATH environment variable so that the + correct program appears first in the PATH. This may work, + but may not be convenient when you want them first in your + path for other work. +

      + +

    2. Run configure with an alternative PATH that + is correct. In a Borne compatible shell, the syntax would be: +

      + PATH= ./configure ... +

      + This is still somewhat inconvenient, but it allows + configure to do its work without having to adjust your + PATH permanently. +

    + +
    I've upgraded to a new version of LLVM, and I get strange build + errors. +
    + Sometimes changes to the LLVM source code alters how the build system + works. Changes in libtool, autoconf, or header file dependencies are + especially prone to this sort of problem. +

    + The best thing to try is to remove the old files and re-build. In most + cases, this takes care of the problem. To do this, just type make + clean and then make in the directory that fails to build. +

    + +

    + + +

    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: Mon Aug 11 13:52:22 CDT 2003 + +