From 7fe7f817e9e16c4773f5a4e3ba4c6144674d218e Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Wed, 24 Jul 2002 19:51:14 +0000 Subject: [PATCH] Major changes, expansions, clarifications and corrections. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@3046 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/GettingStarted.html | 453 ++++++++++++++++++++++++++++----------- 1 file changed, 329 insertions(+), 124 deletions(-) diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index 465c006d76a..c3c34d3bcbd 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -1,146 +1,351 @@ - Specification for LLVM system code + Getting Started with LLVM System -

Specification for LLVM system

-

Index

+

Getting Started with the LLVM System

-

Checkout LLVM from CVS

-

-

-
cvs root directory:
/home/vadve/vadve/Research/DynOpt/CVSRepository
-
project name:
llvm -
- - For those who are not familar with cvs, there are two steps you should do:
-
    -
  1. - set CVSROOT. Add the following line into the .cshrc file in your home directory if you are using tcsh or csh:
    - setenv CVSROOT /home/vadve/vadve/Research/DynOpt/CVSRepository -
    2. -
  2. - check out. Go to the directory you want to store LLVM, type
    - cvs checkout llvm -
    3. -
- - note: the c front-end implementation is not in cvs. If you want to use it, you can use excutable in Chris Lattner's directory
-
/home/vadve/lattner/cvs/gcc_install/bin/gcc
- a brief usage of this gcc and other tools are introduced later. To read it now, click here. - -

Compile and Run

- There is a makefile in each directory. You can simple type gmake in the ~/llvm directory to compile all the files or you can type gmake in the certain directory to compile all files and subdirectories in that directory.
- You might want to add the the following directory into your path:
-
llvm/tools/Debug
- so you can run tools in any directory. If you are using csh or tcsh, add
-
setenv PATH llvm/tools/Debug:${PATH}
- at the end of the file .cshrc in your home directory. - - -

Program Layout

- Many useful infomation can be obtained from the LLVM doxygen tree available at http://llvm.cs.uiuc.edu/doxygen/
- The following is a brief introduction to code layout: - -

Depend and Debug directories

- Most directories contain these two directories. The depend directory contains dependance files which will be used during complilation. The debug directory contains object files, library files or executables after compilation. -

llvm/include

- This directory contains common head files supporting the LLVM library. Specific head files which are only used by certain directory are place in that directory instead of here. -

llvm/lib

- This directory contains most important files of LLVM system.
-
- -
llvm/lib/transforms/
This directory contains files and directories for transforming one representation to another representation. -
llvm/lib/Target/
This directory contains files and directories for target machine. The files under llvm/lib/Target describe the common property for any target machine. The directory llvm/lib/Target/Sparc describe the sparc machine specification.
- -
llvm/lib/Analysis/
This directory contains files and directories for doing all kinds of data and control analysis. -
llvm/lib/AsmParser/
This directory contains files and directories for parsing the llvm assemly files. -
llvm/lib/ByteCode/
This directory contains files and directories for reading and write LLVM bytecode. -
llvm/lib/CWrite/
This directory contains files and directories for writing c files as output. -
llvm/lib/CodeGen/
This directory contains files and directories for instruction selection, instruction scheduling and register allocation. -
llvm/lib/Reoptimizer
This directory contains files and directories for all kinds of optimizations, e.g. dead code elimination, Loop Invariant Code Motion, etc. - -
llvm/lib/Support/
This directory contains some files and directories supporting the library, e.g. commandline processor and statistic reporter. -
llvm/lib/VMCore/
This directory contains files and directories for implementing the virtual machine instruction set. -
-

llvm/test

- This directory contains llvm assembly and other files to test the llvm library. - -

llvm/tools

-

The tools directory contains many tools. You can always get help by typing command_name --help . The following is a brief introduction to each tool. -

-
analyze
??? -
as
llvm .ll -> .bc assembler -
The assembler transfroms the human readable assembly to llvm bytecode. -
dis
llvm .bc -> .ll disassembler -
The disassembler transfroms the llvm bytecode to human readable assembly. -
extract
??? -
gccas
llvm .ll -> .bc assembler -
The assembler transfroms the human readable assembly to llvm bytecode. -
gccld
many llvm bytecode -> llvm bytecode + optimizations -
gccld links many llvm bytecode files into one bytecode file and does some optimization. -
link
many llvm bytecode -> llvm bytecode -
link takes many llvm bytecode files and link them into one llvm bytecode file. -
llc
llvm bytecode -> SPARC assembly -
llc takes a llvm bytecode file and output a SPARC assembly file. -
lli
llvm interpreter -
lli reads a llvm bytecode file and execute it. -
opt
llvm .bc -> .bc modular optimizer -
opt reads llvm bytecode and do certain optimization, then output llvm bytecode . -
- -

tutorial for using tools

-
    -
  • create a simple c file:
    - 
    -	      hello.c 
 
-	           int main() {
-	           printf("hello world\n");
-	           return 0;
-	           }
-
    -
    • -
  • compile the c file into a llvm bytecode file
    - % alias llvmgcc /home/vadve/lattner/cvs/gcc_install/bin/gcc
    - % llvmgcc hello.c
    - there will be two output files: a.out and a.out.bc. The file a.out is a shell script and a.out.bc is the llvm bytecode. You can run a.out to excute or directly call the interpreter:
    - % lli a.out.bc
    -
  • dissembler and assembler
    - read llvm bytecode and output human readable llvm assembly
    - %dis a.out.bc -o hello.ll
    - read human readable llvm assembly code and output llvm bytecode
    - %as hello.ll -o hello.bc -
    • -
  • compile to sparc assembly
    - %llc hello.bc -o hello.s -
    • -
-

Links

- -
- If you have any question, please send an email to Lattner Chris Arthur or Guochun Shi.

+ + + +

Getting Started with LLVM

+ + +

This guide is meant to get you up and running with LLVM as quickly as + possible. Once you get the basic system running you can choose an area to + dive into and learn more about. If you get stuck or something is missing + from this document, please email Chris.

+ + + +

Checkout LLVM from CVS

+ + +

First step is to get the actual source code. To do this, all you need to + do is check it out from CVS. From your home directory, just enter:

+ +

cvs -d /home/vadve/vadve/Research/DynOpt/CVSRepository checkout llvm

+ +

This will create an 'llvm' directory in your home directory and fully + populate it with the source code for LLVM.

+ + + +

Set up your environment

+ + +

Now that you have the source code available, you should set up your + environment to be able to use the LLVM tools (once compiled) with as little + hassle as possible. To do this, we recommend that you add the following + lines to your .cshrc (or the corresponding lines to your + .profile if you use a bourne shell derivative): + + 

+       # Make the C frontend easy to use...
+       alias llvmgcc /home/vadve/lattner/cvs/gcc_install/bin/gcc
+
+       # Make the LLVM tools easy to use...
+       setenv PATH ~/llvm/tools/Debug:${PATH}
+
+ +

The C compiler is not included in the CVS tree you just checked out, so + we just point to the cannonical location, and access it with the + llvmgcc command. The rest of the LLVM tools + will be built into the llvm/tools/Debug directory inside of the sourcebase. + Adding them to your path will make it much easier to use them.

+ + + + +

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.

+ + + +

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

+ + + Most source directories 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/CWrite/
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 Propogation, 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 took is invoked by the + llvmgcc frontend as the "assembler" part of the compiler. This + tool actually assembles its input, 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:

    + + % ./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 or Guochun Shi.

+ -Last modified: Wed Jul 17 17:55:16 CDT 2002 +Last modified: Wed Jul 24 14:43:12 CDT 2002