From ce760f6f544c23e372933ae96910536e48a7a350 Mon Sep 17 00:00:00 2001 From: John Criswell Date: Thu, 3 Jul 2003 16:01:38 +0000 Subject: [PATCH] Performed a major update for the pre-release. Attempted to better structure and order the document. Added more information about autoconf, the build system, and how to build LLVM. Added directions on how to build the C front end. Added a section on common problems and their solutions. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@7096 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/GettingStarted.html | 610 +++++++++++++++++++++++++++++---------- 1 file changed, 457 insertions(+), 153 deletions(-) diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index 4814036148d..778c569215a 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -18,26 +18,27 @@ -
  • Solaris on Sparc +
  • Solaris on SparcV9 (Ultrasparc) - LLVM may compile on other platforms. While the LLVM utilities should work, - they will only generate Sparc or x86 machine code. + 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 Compilers (JIT's) only generate SparcV9 or x86 machine + code.

    Software

    @@ -109,30 +115,33 @@ Compiling LLVM requires that you have several different software packages installed: - +

    + +

    GNU M4 +
    + If you are installing Bison on your machine for the first time, you + will need GNU M4 (version 1.4 or higher). +

    There are some additional tools that you may want to have when working with @@ -140,39 +149,70 @@

      -
    • GNU Autoconf and GNU M4 +
    • GNU Autoconf +
    • GNU M4

      - If you want to make changes to the autoconf scripts which configure LLVM - for compilation, you will need GNU autoconf, and consequently, GNU M4. - LLVM was built with autoconf 2.53, so that release and any later - release should work. + If you want to make changes to the configure scripts, you will need + GNU autoconf (2.53 or higher), and consequently, GNU M4 (version 1.4 + or higher).

    + +

    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:
      -
    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 -
        - Specifiy where object files should be placed during the build. +
      • Build the LLVM suite +
          +
        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. -
          • --with-llvmgccdir=directory -
            - Specifiy where the LLVM C frontend has been installed. -
          -
        6. Set your LLVM_LIB_SEARCH_PATH environment variable. -
        7. gmake -k |& tee gnumake.out -    # this is csh or tcsh syntax +
        8. --with-llvmgccdir=directory +
          + Specify where the LLVM C frontend is going to be installed. +
      +
    6. Set your LLVM_LIB_SEARCH_PATH environment variable. +
    7. gmake -k |& tee gnumake.out +    # this is csh or tcsh syntax +
    +

    +

  • Build the LLVM C Front End +
      +
    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 @@ -191,17 +231,93 @@ 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. +

    + +

    OBJ_ROOT +
    + This is the top level directory for where the LLVM suite object files + will be placed during the build. +

    + +

    LLVMGCCDIR +
    + This is the pathname to the location where the LLVM C Front End will + be installed. Note that the C front end does not need to be installed + during the LLVM suite build; you will just need to know where it will + go for configuring the build system and running the test suite later. +

    + +

    GCCSRC +
    + This is the pathname of the directory where the LLVM C front end source + code can be found. +

    + +

    GCCOBJ +
    + This is the pathname of the directory where the LLVM C front end object + code will be placed during the build. It can be safely removed once + the build is complete. +
    -

    Checkout LLVM from CVS

    +

    Setting up your environment

    -

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

    + 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 C front end find bytecode + 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 + your PATH or typing in its complete pathname. +
    + + +

    Checkout LLVM from CVS

    +

    To get a fresh copy of the entire source code, all you need to do is check it out from CVS as follows: @@ -214,13 +330,19 @@ directory and fully populate it with the LLVM source code, Makefiles, test directories, and local copies of documentation files.

    +

    + Note that the C front end is not included in the CVS repository. You + should have either downloaded the source, or better yet, downloaded the + binary distribution for your platform. +

    + -

    Local Configuration Options

    +

    Local LLVM Configuration

    -

    Once checked out from the CVS repository, options and pathnames specific - to an installation of LLVM can be set via the configure script. - This script sets variables in llvm/Makefile.config and +

    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.

    @@ -229,102 +351,250 @@

      -

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

    • CC = Pathname of the C compiler to use. +

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

    • CC = Pathname of the C compiler to use.
    The following options can be used to set or enable LLVM specific options: -
      -

    • --with-objroot=LLVM_OBJ_ROOT = +
      +
      --with-objroot=OBJ_ROOT +
      Path to the directory where object files, libraries, and executables should be placed. + If this is set to ., then the object files will be placed + within the source code tree. If left unspecified, the default value is + .. (See the Section on The location for LLVM object files for more information.) -

    • --with-llvmgccdir=LLVMGCCDIR = - Path to the location of the LLVM front-end - binaries and associated libraries. -

    • --enable-optimized = +

      +

      --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 (debugging symbols are removed and GCC - optimization flags are enabled). -

    • --enable-jit = + 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. -
    + on all platforms. The default is dependent on platform, so it is best + to explicitly enable it if you want it. + 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 C front-end - install. For example, one might set LLVM_LIB_SEARCH_PATH to + 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 C front-end on our research machines.

    -

    The location for LLVM object files

    +

    Compiling the LLVM Suite Source Code

    -

    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. + Once you have configured LLVM, you can build it. There are three types of + builds: + +

    +
    Debug Builds +
    + These builds are the default. They compile the tools and libraries + with debugging information. +

    -

    If you wish to place output files into a separate directory, use the - --with-objroot=directory option of configure to - set the top level directory of where the object files will go. Otherwise, - leave this option unspecified, and configure will place files - within the LLVM source tree. +

    Release (Optimized) Builds +
    + These builds are enabled with the --enable-optimized option to + configure. They compile the tools and libraries with GCC + optimizer flags on 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 setting variables on the + make command line. +
    + + Once you have LLVM configured, you can build it by entering the top level + llvm directory and issuing the following command: +

    + make + +

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

    + +

    + make -j2 + +

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

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

    + +

    make distclean +
    + Removes everything that make 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. +

    +

    + + It is also possible to override default values from configure by + declaring variables on the command line. The following are some examples: + +
    +
    make ENABLE_OPTIMIZED=1 +
    + Perform a Release (Optimized) build. +

    + +

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

    + +

    make VERBOSE=1 +
    + Print what make 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 + anything in or below that directory that is out of date. -

    Setting up your environment

    +

    Building the LLVM C Front End

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

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

    Add the following lines to your .cshrc (or the corresponding - lines to your .profile if you use a bourne shell derivative). +

      +
    1. Ensure that OBJ_ROOT/llvm/tools/Debug is at the + end of your PATH environment variable. - 
      -       # Make the C front end easy to use...
-       alias llvmgcc LLVMGCCDIR/bin/llvm-gcc
+        
    2. cd GCCOBJ
 
-       # Make the LLVM tools easy to use...
-       setenv PATH OBJ_ROOT/llvm/tools/Debug:${PATH}
-
      3. - The llvmgcc alias is useful because the C compiler is not - included in the CVS tree you just checked out. +
    3. Configure the source code: +
        +
      • On Linux/x86, use +
          +
        • GCCSRC/configure --prefix=LLVMGCCDIR + --enable-languages=c +
        -

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

        +
      • On Solaris/Sparc, use +
          +
        • GCCSRC/configure --prefix=LLVMGCCDIR + --enable-languages=c --target=sparcv9-sun-solaris2 +
        +
      + +
    4. make bootstrap + +
    5. The build will eventually fail. Don't worry; chances are good that + everything that needed to build is built. + +
    6. make install +
    + + At this point, you should have a working copy of the LLVM C front end + installed in LLVMGCCDIR. -

    Compiling the source code

    +

    The location for LLVM object files

    -

    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 GNU Make (sometimes called 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.

    +

    The LLVM build system sends most output files generated during the build + into the directory defined by the variable OBJ_ROOT in + llvm/Makefile.config, which is set by the --with-objroot + option in configure. 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 get an error about a /localhome directory, follow the - instructions in the section about Setting Up Your - Environment. +

    + If OBJ_ROOT is specified, then the build system will create a + directory tree underneath it that resembles the source code's pathname + relative to your home directory. +

    +

    + For example, suppose that OBJ_ROOT is set to /tmp and the + LLVM suite source code is located in /usr/home/joe/src/llvm, where + /usr/home/joe is the home directory of a user named Joe. Then, + the object files will be placed in /tmp/src/llvm. +

    +

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

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

    + +

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

    + +

    Profile Builds +
    +
    +
    Tools +
    OBJ_ROOT/llvm/tools/Profile +
    Libraries +
    OBJ_ROOT/llvm/lib/Profile +
    +
    @@ -332,7 +602,7 @@
    -

    One useful source of infomation about the LLVM sourcebase is the LLVM 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:

    @@ -346,25 +616,6 @@ 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 (i.e. you did not specify - --with-objroot when you ran configure), 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 build to be performed.

    - -

    llvm/include

    @@ -379,7 +630,7 @@ Reoptimizer, Target, Transforms, etc...
  • llvm/include/Support - This directory contains generic - support libraries that are independant of LLVM, but are used by LLVM. + 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. @@ -466,7 +717,7 @@
    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 + to a simple interpreter, lli is also has debugger and tracing modes (entered by specifying -debug or -trace on the command line, respectively).

    @@ -491,7 +742,7 @@ 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" + frontend itself did not have to be modified to interface to a "weird" assembler.

    gccld
    gccld links together several LLVM @@ -570,6 +821,58 @@ + +

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

    +
    +

    Links

    @@ -583,6 +886,7 @@
    -- 2.34.1