From 1fc08f5e9ef733ef1ce6f363fecedc2260e78974 Mon Sep 17 00:00:00 2001 From: dim Date: Sat, 14 Apr 2012 13:54:10 +0000 Subject: Vendor import of llvm trunk r154661: http://llvm.org/svn/llvm-project/llvm/trunk@r154661 --- docs/GettingStarted.html | 311 +++++++++++++++-------------------------------- 1 file changed, 99 insertions(+), 212 deletions(-) (limited to 'docs/GettingStarted.html') diff --git a/docs/GettingStarted.html b/docs/GettingStarted.html index e198e02..52baf90 100644 --- a/docs/GettingStarted.html +++ b/docs/GettingStarted.html @@ -29,7 +29,6 @@
  • Unpacking the LLVM Archives
  • Checkout LLVM from Subversion
  • LLVM GIT mirror
    • -
  • Install the GCC Front End
  • Local LLVM Configuration
  • Compiling the LLVM Suite Source Code
  • Cross-Compiling LLVM
    • @@ -52,7 +51,7 @@
  • An Example Using the LLVM Tool Chain
      -
    1. Example with llvm-gcc4
      2. +
    2. Example with Clang
  • Common Problems
  • Links @@ -82,16 +81,15 @@ basic information.

    First, LLVM comes in three 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 contains an -assembler, disassembler, bitcode analyzer and bitcode optimizer. It -also contains basic regression tests that can be used to test the LLVM -tools and the GCC front end.

    - -

    The second piece is the GCC front end. This component provides a version of -GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front -end uses the GCC parser to convert code to LLVM. Once -compiled into LLVM bitcode, a program can be manipulated with the LLVM tools -from the LLVM suite.

    +needed to use LLVM. It contains an assembler, disassembler, bitcode +analyzer and bitcode optimizer. It also contains basic regression tests that +can be used to test the LLVM tools and the Clang front end.

    + +

    The second piece is the Clang front end. +This component compiles C, C++, Objective C, and Objective C++ code into LLVM +bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the +LLVM tools from the LLVM suite. +

    There is a third, optional piece called Test Suite. It is a suite of programs @@ -109,83 +107,98 @@ and performance.

    +

    The LLVM Getting Started documentation may be out of date. So, the Clang +Getting Started page might +also be a good place to start.

    +

    Here's the short story for getting up and running quickly with LLVM:

    1. Read the documentation.
    2. Read the documentation.
    3. Remember that you were warned twice about reading the documentation.
      4. -
    4. Install the llvm-gcc-4.2 front end if you intend to compile C or C++ - (see Install the GCC Front End for details): -
        -
      1. cd where-you-want-the-C-front-end-to-live
        2. -
      2. gunzip --stdout llvm-gcc-4.2-version-platform.tar.gz | tar -xvf -
        3. -
      3. install-binutils-binary-from-MinGW (Windows only)
        4. -
      4. Note: If the binary extension is ".bz" use bunzip2 instead of gunzip.
        5. -
      5. Note: On Windows, use 7-Zip or a similar archiving tool.
        6. -
      6. Add llvm-gcc's "bin" directory to your PATH environment variable.
        7. -
      5. -
    5. Get the LLVM Source Code +
    6. Checkout LLVM:
        -
      • With the distributed files (or use SVN): -
          -
        1. cd where-you-want-llvm-to-live -
        2. gunzip --stdout llvm-version.tar.gz | tar -xvf - -
        • - -
      7. +
    7. cd where-you-want-llvm-to-live +
    8. svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
      9. + + -
    9. [Optional] Get the Test Suite Source Code +
    10. Checkout Clang:
        -
      • With the distributed files (or use SVN): -
          -
        1. cd where-you-want-llvm-to-live -
        2. cd llvm/projects -
        3. gunzip --stdout llvm-test-version.tar.gz | tar -xvf - -
        4. mv llvm-test-version test-suite -
        • +
      • cd where-you-want-llvm-to-live +
      • cd llvm/tools +
      • svn co http://llvm.org/svn/llvm-project/cfe/trunk clang
        • +
      +
      11. - +
    11. Checkout Compiler-RT: +
        +
      • cd where-you-want-llvm-to-live +
      • cd llvm/projects +
      • svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk + compiler-rt
        • +
      +
      12. +
    12. Get the Test Suite Source Code [Optional] +
        +
      • cd where-you-want-llvm-to-live +
      • cd llvm/projects +
      • svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
        • +
      +
      13. -
    13. Configure the LLVM Build Environment -
        +
      1. Configure and build LLVM and Clang: +
        • cd where-you-want-to-build-llvm
          • -
        • /path/to/llvm/configure [options]
          - Some common options: +
        • mkdir build (for building without polluting the source dir)
          • +
        • cd build
          • +
        • ../llvm/configure [options] +
          Some common options:
            -
          • --prefix=directory -

            Specify for directory the full pathname of where you +

          • --prefix=directory - + Specify for directory the full pathname of where you want the LLVM tools and libraries to be installed (default - /usr/local).

            • -
          • --with-llvmgccdir=directory -

            Optionally, specify for directory the full pathname of the - C/C++ front end installation to use with this LLVM configuration. If - not specified, the PATH will be searched. This is only needed if you - want to run test-suite or do some special kinds of LLVM builds.

            • -
          • --enable-spec2000=directory -

            Enable the SPEC2000 benchmarks for testing. The SPEC2000 - benchmarks should be available in - directory.

            • + /usr/local).
          -
      14. -
    14. Build the LLVM Suite: -
        -
      1. gmake -k |& tee gnumake.out -    # this is csh or tcsh syntax
        2. -
      2. If you get an "internal compiler error (ICE)" or test failures, see - below.
        3. -
      +
        +
      • --enable-optimized - + Compile with optimizations enabled (default is NO).
        • +
      + +
        +
      • --enable-assertions - + Compile with assertion checks enabled (default is YES).
        • +
      +
      15. +
    15. make [-j] - The -j specifies the number of jobs (commands) to + run simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. + The --enabled-optimized configure option is used to specify a Release build.
      16. +
    16. make check-all - + This run the regression tests to ensure everything is in working order.
      17. +
    17. make update - + This command is used to update all the svn repositories at once, rather then + having to cd into the individual repositories and running + svn update.
      18. +
    18. It is also possible to use CMake instead of the makefiles. With CMake + it is also possible to generate project files for several IDEs: Eclipse + CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.
      19. +
    19. If you get an "internal compiler error (ICE)" or test failures, see + below.
      20. + + +

    Consult the Getting Started with LLVM section for detailed information on configuring and compiling LLVM. See Setting Up Your Environment for tips that simplify -working with the GCC front end and LLVM tools. Go to Program +working with the Clang front end and LLVM tools. Go to Program Layout to learn about the layout of the source code tree.

    @@ -283,7 +296,7 @@ software you will need.

    Windows x861 - Visual Studio 2005 SP1 or higher4,5 + Visual Studio 2008 or higher4,5 AIX3,4 PowerPC @@ -361,10 +374,6 @@ able to assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation should work as well, although the generated native code may not work on your platform.

    -

    The GCC front end is not very portable at the moment. If you want to get it -to work on another platform, you can download a copy of the source and try to compile it on your platform.

    - @@ -430,7 +439,7 @@ href="GCCFEBuildInstrs.html">try to compile it on your platform.

    perl ≥5.6.0 - Nightly tester, utilities + Utilities @@ -441,13 +450,13 @@ href="GCCFEBuildInstrs.html">try to compile it on your platform.

    GNU Autoconf - 2.61 + 2.60 Configuration script builder4 GNU Automake - 1.10 + 1.9.6 aclocal macro generator4 @@ -471,8 +480,8 @@ href="GCCFEBuildInstrs.html">try to compile it on your platform.

  • Only needed if you want to run the automated test suite in the llvm/test directory.
  • If you want to make changes to the configure scripts, - you will need GNU autoconf (2.61), and consequently, GNU M4 (version 1.4 - or higher). You will also need automake (1.10). We only use aclocal + you will need GNU autoconf (2.60), and consequently, GNU M4 (version 1.4 + or higher). You will also need automake (1.9.6). We only use aclocal from that package.
    • @@ -516,9 +525,8 @@ href="GCCFEBuildInstrs.html">try to compile it on your platform.

    LLVM is very demanding of the host C++ compiler, and as such tends to expose bugs in the compiler. In particular, several versions of GCC crash when trying -to compile LLVM. We routinely use GCC 3.3.3, 3.4.0, and Apple 4.0.1 -successfully with them (however, see important notes below). Other versions -of GCC will probably work as well. GCC versions listed +to compile LLVM. We routinely use GCC 4.2 (and higher) or Clang. +Other versions of GCC will probably work as well. GCC versions listed here are known to not work. If you are using one of these versions, please try to upgrade your GCC to something more recent. If you run into a problem with a version of GCC not listed here, please let @@ -538,8 +546,7 @@ href="http://gcc.gnu.org/PR13392">serious bug which causes it to crash in the "convert_from_eh_region_ranges_1" GCC function.

    Cygwin GCC 3.3.3: The version of GCC 3.3.3 commonly shipped with - Cygwin does not work. Please upgrade - to a newer version if possible.

    + Cygwin does not work.

    SuSE GCC 3.3.3: The version of GCC 3.3.3 shipped with SuSE 9.1 (and possibly others) does not compile LLVM correctly (it appears that exception handling is broken in some cases). Please download the FSF 3.3.3 or upgrade @@ -651,12 +658,6 @@ All these paths are absolute:

    can be the same as SRC_ROOT).

    -
    LLVMGCCDIR -
    - This is where the LLVM GCC Front End is installed. -

    - For the pre-built GCC front end binaries, the LLVMGCCDIR is - llvm-gcc/platform/llvm-gcc. @@ -747,7 +748,6 @@ revision), you can checkout it from the 'tags' directory (instead of subdirectories of the 'tags' directory:

    llvm/lib/CodeGen/
    This directory contains the major parts of the code generator: Instruction @@ -1530,7 +1435,7 @@ different tools.

    This directory contains libraries which are compiled into LLVM bitcode and -used when linking programs with the GCC front end. Most of these libraries are +used when linking programs with the Clang front end. Most of these libraries are skeleton versions of real libraries; for example, libc is a stripped down version of glibc.

    @@ -1692,12 +1597,6 @@ are code generators for parts of LLVM infrastructure.

    directory, switch to directory llvm/tools/llc and build it, causing a re-linking of LLC.

    -
    NewNightlyTest.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 @@ -1722,20 +1621,11 @@ are code generators for parts of LLVM infrastructure.

    -

    This section gives an example of using LLVM. llvm-gcc3 is now obsolete, -so we only include instructions for llvm-gcc4. -

    - -

    Note: The gcc4 frontend's invocation is considerably different -from the previous gcc3 frontend. In particular, the gcc4 frontend does not -create bitcode by default: gcc4 produces native code. As the example below illustrates, -the '--emit-llvm' flag is needed to produce LLVM bitcode output. For makefiles and -configure scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode -output.

    +

    This section gives an example of using LLVM with the Clang front end.

    - Example with llvm-gcc4 + Example with clang

    @@ -1755,24 +1645,21 @@ int main() {

  • Next, compile the C file into a native executable:

    - 
    % llvm-gcc hello.c -o hello
    + 
    % clang hello.c -o hello
    -

    Note that llvm-gcc works just like GCC by default. The standard -S and +

    Note that clang works just like GCC by default. The standard -S and -c arguments work as usual (producing a native .s or .o file, respectively).

  • Next, compile the C file into a LLVM bitcode file:

    - 
    % llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc
    + 
    % clang -O3 -emit-llvm hello.c -c -o hello.bc

    • The -emit-llvm option can be used with the -S or -c options to emit an LLVM ".ll" or ".bc" file (respectively) for the code. This allows you to use the standard LLVM tools on - the bitcode file.

    - -

    Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments. -

    + the bitcode file.

  • Run the program in both forms. To run the program, use:

    @@ -1811,7 +1698,7 @@ int main() { 
    % ./hello.native
    -

    Note that using llvm-gcc to compile directly to native code (i.e. when +

    Note that using clang to compile directly to native code (i.e. when the -emit-llvm option is not present) does steps 6/7/8 for you.

    • @@ -1870,7 +1757,7 @@ out:

    Chris Lattner
    Reid Spencer
    The LLVM Compiler Infrastructure
    - Last modified: $Date: 2011-10-17 08:31:32 +0200 (Mon, 17 Oct 2011) $ + Last modified: $Date: 2012-03-27 13:25:16 +0200 (Tue, 27 Mar 2012) $ -- cgit v1.1