From 0b459204afc597e424d6c2fe78782669ca73bdc9 Mon Sep 17 00:00:00 2001 From: John Criswell Date: Tue, 8 Jul 2003 20:35:59 +0000 Subject: [PATCH] Corrected the Table of Contents. Corrected capitalization of subheadings. Created a new subsection for compiling the C front end and moved all references to it there. Updated the disk space requirements to reflect the need for the binary C front end and the optional C front end source. Added information on unpacking the distribution to the summary section. Moved autoconf environment variables to the autoconf section. Changed make to gmake. Removed some of the precise directions for unpacking the archives. Fixed some formatting inconsistencies (headings that were not centered). git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@7132 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/GettingStarted.html | 393 ++++++++++++++++++++++++--------------- 1 file changed, 239 insertions(+), 154 deletions(-) diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index a33b4b14efe..0aaecb145cc 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -27,25 +27,27 @@
  • Getting started with LLVM
      -
    1. Getting started quickly (a summary) +
    2. Getting Started Quickly (A Summary)
    3. Terminology and Notation -
    4. Setting up your environment +
    5. Setting Up Your Environment
    6. Unpacking the LLVM Archives
    7. Checkout LLVM from CVS -
    8. Local LLVM Configuration +
    9. Install the C Front End +
    10. Local LLVM Configuration
    11. Compiling the LLVM Suite Source Code -
    12. Compiling the LLVM C Front End -
    13. The location for object files +
    14. The Location of LLVM Object Files
  • Program layout
      -
    1. CVS directories +
    2. CVS directories
    3. llvm/include
    4. llvm/lib
    5. llvm/test
    6. llvm/tools
    -
  • An example using the LLVM tool chain +
  • Compiling the LLVM C Front End +
  • An Example Using the LLVM Tool Chain +
  • Common Problems
  • Links @@ -63,13 +65,13 @@ First, LLVM comes in two pieces. The first piece is the LLVM suite. This contains all of the tools, libraries, and header files needed to use the low level virtual machine. It also contains a test suite that can be used - to test the LLVM tools and the GCC front end. + to test the LLVM tools and the C front end.

    - The second piece is the GCC front end. This component provides a version + The second piece is the C front end. This component provides a version of GCC that compiles C code into LLVM bytecode. Currently, the C front end is a modified version of GCC 3.4 (we track the GCC 3.4 development). Once compiled into LLVM bytecode, a program can be manipulated with the - LLVM tools. + LLVM tools from the LLVM suite.

    Requirements

    @@ -86,27 +88,63 @@ +

    + If you want to compile your own version of the C front end, you will need + additional disk space: +

    + + + +

    LLVM may compile on other platforms. The LLVM utilities should work on other platforms, so it should be possible to generate and produce LLVM bytecode on unsupported platforms (although bytecode generated on one platform may not work on another platform). However, the code generators and Just-In-Time (JIT) compilers only generate SparcV9 or x86 machine code. +

    Software

    @@ -184,7 +222,7 @@
    -

    Getting Started

    +

    Getting Started with LLVM

    @@ -194,43 +232,75 @@ Here's the short story for getting up and running quickly with LLVM:
      -
    1. Build the LLVM suite +
    2. Install the C front end:
        -
      1. Find the path to the CVS repository containing LLVM (we'll call this CVSROOTDIR). -
      2. cd where-you-want-llvm-to-live -
      3. cvs -d CVSROOTDIR checkout llvm -
      4. cd llvm -
      5. Run configure to configure the Makefiles and header files. - Useful options include: -
          -
        • --with-objroot=directory -
          - Specify where object files should be placed during the build. +
        • cd where-you-want-the-C-front-end-to-live +
        • gunzip --stdout cfrontend.platform.tar.gz | tar -xvf + - +
      -
    3. --with-llvmgccdir=directory -
      - Specify where the LLVM C frontend is going to be installed. - -
    4. Set your LLVM_LIB_SEARCH_PATH environment variable. -
    5. gmake -k |& tee gnumake.out +

      + +

    6. Get the Source Code +
        +
      • With the distributed files: +
          +
        1. cd where-you-want-llvm-to-live +
        2. gunzip --stdout llvm.tar.gz | tar -xvf - +
        3. gunzip --stdout cfrontend.platform.tar.gz | tar -xvf - +
        4. cd llvm +
        + +

        + +

      • With anonymous CVS access: +
          +
        1. Find the path to the CVS repository containing LLVM (we'll call this CVSROOTDIR). +
        2. cd where-you-want-llvm-to-live +
        3. cvs -d CVSROOTDIR checkout llvm +
        4. cd llvm +
        +
      + + +

      + +

    7. Configure the LLVM Build Environment +
        +
      1. Run configure to configure the Makefiles and header + files for the default platform. + Useful options include: +
          +
        • --with-objroot=directory +
          + Specify where object files should be placed during the build. + +
        • --with-llvmgccdir=directory +
          + Specify where the LLVM C frontend is going to be installed. +
        +
      + +

      + +

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

      -

    9. Build the LLVM C Front End (optional) -
        -
      1. Create a directory for the object files to live. -
      2. cd object file directory -
      3. Run Pathname-to-where-the-source-code-lives/configure --prefix=LLVMGCCDIR to configure GCC. -
      4. make bootstrap -
      5. make install -
      +
    -

    See Setting up your environment on tips to +

    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. + layout of the source code tree. For information on building the C front + end yourself, see Compiling the LLVM C Front End for + information.

    Terminology and Notation

    @@ -280,7 +350,7 @@ -

    Setting up your environment

    +

    Setting Up Your Environment

    @@ -296,32 +366,6 @@ libraries that it will need for compilation.

    -

    PATH=${PATH}:OBJ_ROOT/llvm/tools/Debug -
    - Adding this directory to the end of your path will allow the - compilation of the C front end to find the LLVM tools. The LLVM tools - are needed for the C front end compile. -

    - -

    CC=Pathname to your GCC compiler -
    - The GCC compiler that you want to use must be the first C compiler in - your PATH. Otherwise, set this variable so that - configure will use the GCC compiler that you want to use. -

    - -

    CXX=Pathname to your GCC C++ compiler -
    - The GCC compiler that you want to use must be the first C++ compiler in - your PATH. Otherwise, set this variable so that - configure will use the GCC compiler that you want to use. -

    - -

    CVSROOT=CVSROOT -
    - This environment variable tells CVS where to find the CVS repository. -

    -

    alias llvmgcc LLVMGCCDIR/bin/llvm-gcc
    This alias allows you to use the LLVM C front end without putting it in @@ -338,7 +382,7 @@ file is a TAR archive that is compressed with the gzip program.

    -

    The four files are the following: +

    The four files are as follows:

    llvm.tar.gz
    This is the source code to the LLVM suite. @@ -357,19 +401,6 @@

    -

    - To unpack the files, take each one, unzip it, and then untar it. A fast - way to do that is with the following: -

    - - gunzip --stdout name of file | tar -xvf - - -

    - For example, to extract the LLVM source code, use the following command: -

    - - gunzip --stdout llvm.tar.gz | tar -xvf - -

    Checkout LLVM from CVS

    @@ -392,6 +423,25 @@ binary distribution for your platform.

    + +

    Install the C Front End

    + + +

    + Before configuring and compiling the LLVM suite, it is best to extract the + LLVM C front end. While not used in building, the C front end is used by + the LLVM test suite, and its location must be given to the + configure script before the LLVM suite can be built. +

    + +

    + To install the C front end, do the following: +

      +
    1. cd where-you-want-the-front-end-to-live +
    2. gunzip --stdout cfrontend.platform.tar.gz | tar -xvf + - +
    +

    Local LLVM Configuration

    @@ -402,16 +452,42 @@ llvm/include/Config/config.h.

    - The following environment variables are used by configure to - configure Makefile.config: + The following environment variables are used by the configure + script to configure the build system:

    -
      -

    • CXX = Pathname of the C++ compiler to use. -

    • CC = Pathname of the C compiler to use. -
    + + + + + + + + + + + + + + +
    Variable + Purpose +
    CC + Tells configure which C compiler to use. By default, + configure will look for the first GCC 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 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: +

    --with-objroot=OBJ_ROOT @@ -422,7 +498,7 @@ within the source code tree. If left unspecified, the default value is .. (See the Section on - The location for LLVM object files + The Location of LLVM Object Files for more information.)

    --with-llvmgccdir=LLVMGCCDIR @@ -480,13 +556,13 @@ 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 setting variables on the - make command line. + gmake command line.
    Once you have LLVM configured, you can build it by entering the top level llvm directory and issuing the following command:

    - make + gmake

    If you have multiple processors in your machine, you may wish to use some @@ -495,22 +571,22 @@

    - make -j2 + gmake -j2

    There are several other targets which are useful when working with the LLVM source code:

    -
    make clean +
    gmake clean
    Removes all files generated by the build. This includes object files, generated C/C++ files, libraries, and executables.

    -

    make distclean +
    gmake distclean
    - Removes everything that make clean does, but also removes + 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.

    @@ -520,79 +596,29 @@ declaring variables on the command line. The following are some examples:

    -
    make ENABLE_OPTIMIZED=1 +
    gmake ENABLE_OPTIMIZED=1
    Perform a Release (Optimized) build.

    -

    make ENABLE_PROFILING=1 +
    gmake ENABLE_PROFILING=1
    Perform a Profiling build.

    -

    make VERBOSE=1 +
    gmake VERBOSE=1
    - Print what make is doing on standard output. + Print what gmake is doing on standard output.

    Every directory in the LLVM source tree includes a Makefile to build it and any subdirectories that it contains. Entering any directory - inside the LLVM source tree and typing make should rebuild + inside the LLVM source tree and typing gmake should rebuild anything in or below that directory that is out of date. -

    Compiling the LLVM C Front End

    - - - -

    - This step is optional if you have the C front end binary distrubtion for - your platform. -

    -     - - Now that you have the LLVM Suite built, you can build the C front end. For - those of you that have built GCC before, the process is very similar. -

    - Be forewarned, though: the build system for the C front end is not as - polished as the rest of the LLVM code, so there will be many warnings and - errors that you will need to ignore for now: - -

      -
    1. Ensure that OBJ_ROOT/llvm/tools/Debug is at the - end of your PATH environment variable. - -
    2. cd GCCOBJ - -
    3. Configure the source code: -
        -
      • On Linux/x86, use -
          -
        • GCCSRC/configure --prefix=LLVMGCCDIR - --enable-languages=c -
        - -
      • On Solaris/Sparc, use -
          -
        • GCCSRC/configure --prefix=LLVMGCCDIR - --enable-languages=c --target=sparcv9-sun-solaris2 -
        -
      - -
    4. make - -
    5. The build will eventually fail. Don't worry; chances are good that - everything that needed to build is built. - -
    6. make -k install -
    - - At this point, you should have a working copy of the LLVM C front end - installed in LLVMGCCDIR. - - -

    The location for LLVM object files

    +

    The Location of LLVM Object Files

    The LLVM build system sends most output files generated during the build @@ -825,9 +851,66 @@ what an analysis does.

    - + -

    An example using the LLVM tool chain

    +

    Compiling the LLVM C Front End

    + + +

    + + This step is optional if you have the C front end binary distrubtion for + your platform. + +

    + + Now that you have the LLVM suite built, you can build the C front end. For + those of you that have built GCC before, the process is very similar. +

    + Be forewarned, though: the build system for the C front end is not as + polished as the rest of the LLVM code, so there will be many warnings and + errors that you will need to ignore for now: + +

      +
    1. Ensure that OBJ_ROOT/llvm/tools/Debug is at the + end of your PATH environment variable. The front end + build needs to know where to find the LLVM tools, but you want to + ensure that these tools are not found before the system assembler and + linker that you normally use for compilation. + +
    2. cd GCCOBJ + +
    3. Configure the source code: +
        +
      • On Linux/x86, use +
          +
        • GCCSRC/configure --prefix=LLVMGCCDIR + --enable-languages=c +
        + +
      • On Solaris/Sparc, use +
          +
        • GCCSRC/configure --prefix=LLVMGCCDIR + --enable-languages=c --target=sparcv9-sun-solaris2 +
        +
      + +
    4. gmake + +
    5. The build will eventually fail. Don't worry; chances are good that + everything that needed to build is built. + +
    6. gmake -k install +
    + +

    + Once this is done, you should have a built front end compiler in + LLVMGCCDIR. +

    + + +

    +
    An Example Using the LLVM Tool Chain
    +

      @@ -881,7 +964,9 @@ -

      Common Problems

      +

      +
      Common Problems
      +

      Below are common problems and their remedies: @@ -933,7 +1018,7 @@ -

      Links

      +

      Links

      This document is just an introduction to how to use LLVM to do