From dd9dab3fd7a017816a7693da2b8ba1d1ebdc2ac1 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Fri, 6 Sep 2002 16:26:13 +0000 Subject: [PATCH] Commit Vikram's changes for 426 class llvm-svn: 3593 --- llvm/docs/GettingStarted.html | 227 ++++++++++++++++++++++------------ 1 file changed, 151 insertions(+), 76 deletions(-) diff --git a/llvm/docs/GettingStarted.html b/llvm/docs/GettingStarted.html index c0ea286d98c4..9c16d65f91cb 100644 --- a/llvm/docs/GettingStarted.html +++ b/llvm/docs/GettingStarted.html @@ -5,17 +5,27 @@ -

Getting Started with the LLVM System
By: Guochun Shi and Chris Lattner

+

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

+ + +

Contents

+ - -

Getting Started with LLVM

+
+

Overview

+
-

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.

- +

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

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

Checkout LLVM from CVS

+

Terminology and Notation

-

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.

- +

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:

+ -

Access to /shared

+

Checkout LLVM from CVS

- By default, LLVM is configured to send all compiled files into the - /shared/[yourloginname]/ directory. The idea is that this - directory is local to the machine you're working on, so the huge libraries - and .o files you will be compiling will not have to be sent over - NFS. If you are in a situation where this setup is correct, you don't have - to do anything. If you don't have a /shared directory, you will - have to make a couple of modifications to your setup.

- - The first modification is that you need to enable the "BUILD_ROOT = - . line in the top level Makefile.common. This will instruct - LLVM to build into the current directory tree instead of - /shared.

+

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.

-

Set up your environment

+

Local Configuration Options

- -

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

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

+ + +

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, + 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 frontend easy to use...
-       alias llvmgcc /home/vadve/lattner/cvs/gcc_install/bin/gcc
+       # Make the C front end easy to use...
+       alias llvmgcc LLVMGCCDIR/bin/gcc
 
        # Make the LLVM tools easy to use...
-       setenv PATH /shared/[yourloginname]/llvm/tools/Debug:${PATH}
+       setenv PATH LLVM_OBJ_DIR/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. If you do not - have access to /shared, use this line instead:

- - 
-       setenv PATH ~/llvm/tools/Debug:${PATH}
-
- - Adding these two lines to your path will make it much easier to use the LLVM - tools.

- + The llvmgcc alias is useful because the C compiler is not + included in the CVS tree you just checked out. + +

The other LLVM 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

+

Compiling the source code

Every directory in the LLVM source tree includes a Makefile to build it, @@ -121,17 +196,16 @@ in llvm/tools/Debug. If you want to look at the libraries that were compiled, look in llvm/lib/Debug.

-

By default, the LLVM build process sends all temporary (.o, - .so, .a) files into a /shared/[your login - name]/... directory, which is supposed to be on a disk local to the - current machine. If you get an error talking about a /shared - directory, follow the instructions in the section about - /shared.

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

Program Layout

+
+

Program Layout

+

One useful source of infomation about the LLVM sourcebase is the LLVM

    -
    gccas
    This took is invoked by the +
    gccas
    This tool is invoked by the llvmgcc frontend as the "assembler" part of the compiler. This - tool actually assembles its input, performs a variety of optimizations, + 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 @@ -380,9 +455,9 @@
    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.

    + additions...), please send an email to + Nicholas Hildenbrandt or + Chris Lattner.