From 858bfdcf8421695fea84aaa3f8a4fed630bb363d Mon Sep 17 00:00:00 2001 From: Tanya Lattner Date: Mon, 20 Nov 2006 06:07:46 +0000 Subject: [PATCH] Merging from mainline llvm-svn: 31872 --- llvm/docs/CFEBuildInstrs.html | 493 ++++++++++++++++++++-------------- llvm/docs/GettingStarted.html | 32 +-- 2 files changed, 300 insertions(+), 225 deletions(-) diff --git a/llvm/docs/CFEBuildInstrs.html b/llvm/docs/CFEBuildInstrs.html index 4242206c5a34..85d1ebd90ff6 100644 --- a/llvm/docs/CFEBuildInstrs.html +++ b/llvm/docs/CFEBuildInstrs.html @@ -36,22 +36,24 @@
-

This document is intended to explain the process of building the -LLVM C/C++ front-end from its source code. You have to do this, for example, if -you are porting LLVM to a new architecture or operating system, if you are -working from Top-Of-Tree CVS/SVN, or if there is no precompiled snapshot -available.

-

NOTE: This is currently a somewhat fragile, error-prone -process, and you should only try to do it if:

+

This document is intended to explain the process of building the LLVM C/C++ +front-end from its source code. You have to do this, for example, if you are +porting LLVM to a new architecture or operating system, if you are working from +Top-Of-Tree CVS/SVN, or if there is no precompiled snapshot available.

+ +

NOTE: This is currently a somewhat fragile, error-prone process, and +you should only try to do it if:

    -
  1. you really, really, really can't use the binaries we distribute
    2. +
  2. you really, really, really can't use the + binaries we distribute
  3. you are an elite GCC hacker.
  4. you want to use the latest bits from CVS.

We welcome patches to help make this process simpler.

+
@@ -61,38 +63,48 @@ process, and you should only try to do it if:

+

If you are building LLVM and the GCC front-end under Cygwin, please note that the LLVM and GCC makefiles do not correctly handle spaces in paths. To deal -with this issue, make sure that your LLVM and GCC source and build trees are -located in a top-level directory (like /cygdrive/c/llvm and +with this issue, make sure that your LLVM and GCC source and build trees are +located in a top-level directory (like /cygdrive/c/llvm and /cygdrive/c/llvm-cfrontend), not in a directory that contains a space -(which includes your "home directory", because it lives under the "Documents -and Settings" directory). We welcome patches to fix this issue. -

+(which includes your "home directory", because it lives under the "Documents and +Settings" directory). We welcome patches to fix this issue.

+

It has been found that the GCC 3.3.3 compiler provided with recent Cygwin versions is incapable of compiling the LLVM GCC front-end correctly. If your -Cygwin -installation includes GCC 3.3.3, we strongly recommend that you download -GCC 3.4.3, build it separately, and use it for compiling the LLVM GCC front-end. - This has been -shown to work correctly.

+Cygwin installation includes GCC 3.3.3, we strongly recommend that you +download GCC 3.4.3, build it separately, and use it for compiling the LLVM GCC +front-end. This has been shown to work correctly.

+

Some versions of Cygwin utilize an experimental version of GNU binutils that will cause the GNU ld linker to fail an assertion when linking components of the libstdc++. It is recommended that you replace the entire binutils package with version 2.15 such that "ld --version" responds with

+ +
GNU ld version 2.15
-not with:
+
+ +

not with:

+ +
GNU ld version 2.15.91 20040725
+
+
Building under AIX
+
+

If you are building LLVM and the GCC front-end under AIX, do NOT use GNU Binutils. They are not stable under AIX and may produce incorrect and/or -invalid code. Instead, use the system assembler and linker. -

+invalid code. Instead, use the system assembler and linker.

+
@@ -104,33 +116,37 @@ invalid code. Instead, use the system assembler and linker.

This section describes how to aquire and build llvm-gcc4, which is based on -the GCC 4.0.1 front-end. This front-end supports C, C++, Objective-C, and +the GCC 4.0.1 front-end. This front-end supports C, C++, Objective-C, and Objective-C++. Note that the instructions for building this front-end are -completely different than those for building llvm-gcc3. -

+completely different than those for building llvm-gcc3.

    -
  1. -

    Retrieve the appropriate llvm-gcc4-x.y.source.tar.gz archive from the llvm -web site.

    -

    It is also possible to download the sources of the llvm-gcc4 front end from -a read-only mirror using subversion. To check out the code the first time use: -

    +

  2. Retrieve the appropriate llvm-gcc4-x.y.source.tar.gz archive from the + llvm web site.

    -svn co svn://anonsvn.opensource.apple.com/svn/llvm/trunk -dst-directory +

    It is also possible to download the sources of the llvm-gcc4 front end + from a read-only mirror using subversion. To check out the code the + first time use:

    -

    After that, the code can be be updated in the destination directory using; -

    +
    +
    +svn co svn://anonsvn.opensource.apple.com/svn/llvm/trunk dst-directory
+
    +
    -svn update +

    After that, the code can be be updated in the destination directory + using:

    -

    The mirror is brought up to date every evening.

    -
    3. +
    +
    svn update
    +
    -
  3. Follow the directions in the top-level README.LLVM file for up-to-date - instructions on how to build llvm-gcc4.
    4. +

    The mirror is brought up to date every evening.

    + +
  4. Follow the directions in the top-level README.LLVM file for + up-to-date instructions on how to build llvm-gcc4.
+
@@ -140,192 +156,251 @@ a read-only mirror using subversion. To check out the code the first time use:
+
    -
  1. Aquire llvm-gcc3 from LLVM CVS or -from a release tarball.
    2. +
  2. Aquire llvm-gcc3 from LLVM CVS + or from a release tarball.
    3. -

  3. Configure and build the LLVM libraries and tools. There are two ways to -do this: either with objdir == srcdir or -objdir != srcdir. It is recommended -that srcdir be the same as objdir for your LLVM tree (but note -that you should always use srcdir != objdir for llvm-gcc):

    -
      -
    • With objdir != srcdir:
      - % cd objdir
- % srcdir/configure --prefix=/some/path/you/can/install/to [options...]
- % gmake tools-only
-
      • -
    • With objdir == srcdir:
      - % cd llvm
- % ./configure --prefix=/some/path/you/can/install/to [options...]
- % gmake tools-only
-
      • -
    -

    This will build all of the LLVM tools and libraries. The --prefix -option defaults to /usr/local (per configure standards) but unless you are a -system administrator, you probably won't be able to install LLVM there because -of permissions. Specify a path into which LLVM can be installed (e.g. ---prefix=/home/user/llvm).

    -
    4. +

  4. Configure and build the LLVM libraries and tools. There are two ways to + do this: either with objdir == srcdir or + objdir != srcdir. It is recommended that + srcdir be the same as objdir for your + LLVM tree (but note that you should always use srcdir != + objdir for llvm-gcc):

    -

  5. Add the directory containing the tools to your PATH.

    +
      +

    • With objdir != srcdir:

      + +
      - % set path = ( `cd llvm/Debug/bin && pwd` $path )
-
      • - -

    • Unpack the C/C++ front-end source into cfrontend/src, either by - untar'ing a cfrontend.source.tar.gz file or checking out CVS into this - directory.

      • - -

    • Make "build" and "install" directories as siblings of the "src" tree:

      -
      - % pwd
- /usr/local/example/cfrontend/src
- % cd ..
- % mkdir build install
- % set CFEINSTALL = `pwd`/install
-
      • - - -

    • Configure, build, and install the GCC front-end:

      - -

      -Linux/x86:
      -Linux/IA-64:
      -MacOS X/PowerPC (requires dlcompat library):
      -AIX/PowerPC: -

      - -
      - % cd build
- % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
-   --disable-shared --enable-languages=c,c++ --program-prefix=llvm-
- % gmake all; gmake install
+% cd objdir
+% srcdir/configure --prefix=/some/path/you/can/install/to [options...]
+% gmake tools-only
      +
+ +

  • With objdir == srcdir:

    -

    Cygwin/x86:

    - +
    - % cd build
- % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
-   --disable-shared --enable-languages=c,c++ --disable-c-mbchar \
-   --program-prefix=llvm-
- % gmake all; gmake install
+% cd llvm
+% ./configure --prefix=/some/path/you/can/install/to [options...]
+% gmake tools-only
    +
    +
    • + -

    Solaris/SPARC:

    - -

    -The GCC front-end can be configured for either SPARC V8 (32 bit) or SPARC V9 (64 -bit). This changes, among other things, the sizes of integer types and the -macros defined for conditional compilation. -

    - -

    -The SPARC V8 ABI support is more robust than the V9 ABI support and can generate -SPARC V9 code. It is highly recommended that you use the V8 ABI with LLVM, as -shown below. Also, -note that Solaris has trouble with various wide (multibyte) character -functions from C as referenced from C++, so we typically configure with ---disable-c-mbchar (cf. Bug 206). -

    +

    This will build all of the LLVM tools and libraries. The + --prefix option defaults to /usr/local (per configure + standards) but unless you are a system administrator, you probably + won't be able to install LLVM there because of permissions. Specify a + path into which LLVM can be installed + (e.g. --prefix=/home/user/llvm).

    +

  • Add the directory containing the tools to your PATH.

    +
    +csh: 
    - % cd build
- % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
-   --disable-shared --enable-languages=c,c++ --host=sparc-sun-solaris2.8 \
-   --disable-c-mbchar --program-prefix=llvm-
- % gmake all; gmake install
+  % set path = ( `cd llvm/Debug/bin && pwd` $path )
    - -

    Common Problem: You may get error messages regarding the fact - that LLVM does not support inline assembly. Here are two common - fixes:

    - -
      -

    • Fix 1: If you have system header files that include - inline assembly, you may have to modify them to remove the inline - assembly and install the modified versions in - $CFEINSTALL/lib/gcc/target-triplet/3.4-llvm/include.

      • - -
    • Fix 2: If you are building the C++ front-end on a CPU we - haven't tried yet, you will probably have to edit the appropriate - version of atomicity.h under - src/libstdc++-v3/config/cpu/name-of-cpu/atomicity.h - and apply a patch so that it does not use inline assembly.
      • -
    - -

    Porting to a new architecture: If you are porting the front-end - to a new architecture or compiling in a configuration that we have - not tried previously, there are probably several changes you will have to make - to the GCC target to get it to work correctly. These include:

    - -

      -
    • Often targets include special assembler or linker flags which - gccas/gccld does not understand. In general, these can - just be removed.
      • -
    • LLVM currently does not support any floating point values other than - 32-bit and 64-bit IEEE floating point. The primary effect of this is - that you may have to map "long double" onto "double".
      • -
    • The profiling hooks in GCC do not apply at all to the LLVM front-end. - These may need to be disabled.
      • -
    • No inline assembly for position independent code. At the LLVM level, - everything is position independent.
      • -
    • We handle .init and .fini differently.
      • -
    • You may have to disable multilib support in your target. Using multilib - support causes the GCC compiler driver to add a lot of "-L" - options to the link line, which do not relate to LLVM and confuse - gccld. To disable multilibs, delete any - MULTILIB_OPTIONS lines from your target files.
      • -
    • Did we mention that we don't support inline assembly? You'll probably - have to add some fixinclude hacks to disable it in the system - headers.
      • -
    -
    • - -

  • Put $CFEINSTALL/bin into your PATH environment -variable.

    - -
    • - -

  • Go back into the LLVM source tree proper. Rerun configure, using -the same options as the last time. This will cause the configuration to now find -the newly built llvm-gcc and llvm-g++ executables.

    • - -

  • Rebuild your CVS tree. This shouldn't cause the whole thing to be - rebuilt, but it should build the runtime libraries. After the tree is - built, install the runtime libraries into your GCC front-end build tree. - These are the commands you need:

    +sh: 
    - % gmake
- % gmake -C runtime install-bytecode
-
    • - -

  • Optionally, build a symbol table for the newly installed runtime -libraries. Although this step is optional, you are strongly encouraged to -do this as the symbol tables will make a significant difference in your -link times. Use the llvm-ranlib tool to do this, as follows:

    -
    - % cd $CFEINSTALL/lib
- % llvm-ranlib libiberty.a
- % llvm-ranlib libstdc++.a
- % llvm-ranlib libsupc++.a
- % cd $CFEINSTALL/lib/gcc/target-triplet/3.4-llvm
- % llvm-ranlib libgcc.a
- % llvm-ranlib libgcov.a
+  % export PATH=`cd llvm/Debug/bin && pwd`:$PATH
    + +
    • -

  • Test the newly-installed C frontend by one or more of the -following means:

    -
    • +

  • Unpack the C/C++ front-end source, either by + untar'ing/unzipping a tar.gz file or checking out CVS into this + directory.

    • +

  • Make "build" and "install" directories as siblings of the "src" + tree:

    + +
    +csh: +
    +  % pwd
+  /usr/local/example/llvm-gcc3.4/src
+  % cd ..
+  % mkdir build install
+  % set CFEINSTALL = `pwd`/install
+
    +sh: +
    +  % pwd
+  /usr/local/example/llvm-gcc3.4/src
+  % cd ..
+  % mkdir build install
+  % export CFEINSTALL=`pwd`/install
+
    +
    +
    • + +

  • Configure, build, and install the GCC front-end:

    + +

    + Linux/x86:
    + Linux/IA-64:
    + MacOS X/PowerPC (requires dlcompat library):
    + AIX/PowerPC: +

    + +
    +
    +% cd build
+% ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
+  --disable-shared --enable-languages=c,c++ --program-prefix=llvm-
+% gmake all; gmake install
+
    +
    + +

    Cygwin/x86:

    + +
    +
    +% cd build
+% ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
+  --disable-shared --enable-languages=c,c++ --disable-c-mbchar \
+  --program-prefix=llvm-
+% gmake all; gmake install
+
    +
    + +

    Solaris/SPARC:

    + +

    The GCC front-end can be configured for either SPARC V8 (32 bit) or + SPARC V9 (64 bit). This changes, among other things, the sizes of + integer types and the macros defined for conditional compilation.

    + +

    The SPARC V8 ABI support is more robust than the V9 ABI support and can + generate SPARC V9 code. It is highly recommended that you use the V8 + ABI with LLVM, as shown below. Also, note that Solaris has trouble + with various wide (multibyte) character functions from C as referenced + from C++, so we typically configure with --disable-c-mbchar (cf. Bug 206).

    + +
    +
    +% cd build
+% ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
+  --disable-shared --enable-languages=c,c++ --host=sparc-sun-solaris2.8 \
+  --disable-c-mbchar --program-prefix=llvm-
+% gmake all; gmake install
+
    +
    + +

    Common Problem: You may get error messages regarding the fact + that LLVM does not support inline assembly. Here are two common + fixes:

    + + + +

    Porting to a new architecture: If you are porting the front-end + to a new architecture or compiling in a configuration that we have not + tried previously, there are probably several changes you will have to + make to the GCC target to get it to work correctly. These include:

    + +
    • + +

  • Put $CFEINSTALL/bin into your PATH environment + variable.

    + +
    +csh: +
    +  % setenv PATH $CFEINSTALL/bin:$PATH
+
    +sh: +
    +  % export PATH=$CFEINSTALL/bin:$PATH
+
    +
    +
    • + +

  • Go back into the LLVM source tree proper. Rerun configure, using the + same options as the last time. This will cause the configuration to now + find the newly built llvm-gcc and llvm-g++ executables.

    • + +

  • Rebuild your CVS tree. This shouldn't cause the whole thing to be + rebuilt, but it should build the runtime libraries. After the tree is + built, install the runtime libraries into your GCC front-end build tree. + These are the commands you need:

    + +
    +
    +% gmake
+% gmake -C runtime install-bytecode
+
    +
    +
    • + +

  • Optionally, build a symbol table for the newly installed runtime + libraries. Although this step is optional, you are strongly encouraged to + do this as the symbol tables will make a significant difference in your + link times. Use the llvm-ranlib tool to do this, as follows:

    + +
    +
    +% cd $CFEINSTALL/lib
+% llvm-ranlib libiberty.a
+% llvm-ranlib libstdc++.a
+% llvm-ranlib libsupc++.a
+% cd $CFEINSTALL/lib/gcc/target-triplet/3.4-llvm
+% llvm-ranlib libgcc.a
+% llvm-ranlib libgcov.a
+
    +
    +
    • + +

  • Test the newly-installed C frontend by one or more of the following + means:

    + +
    • + diff --git a/llvm/docs/GettingStarted.html b/llvm/docs/GettingStarted.html index c627731a0625..518572c1b53f 100644 --- a/llvm/docs/GettingStarted.html +++ b/llvm/docs/GettingStarted.html @@ -119,11 +119,11 @@ and performance.
  • Install the GCC front end if you intend to compile C or C++:
    1. cd where-you-want-the-C-front-end-to-live
      2. -
    2. gunzip --stdout cfrontend.platform.tar.gz | tar -xvf - +
    3. gunzip --stdout llvm-gcc.platform.tar.gz | tar -xvf -
      4. -
    4. cd cfrontend/platform
      +
    5. cd llvm-gcc3.4/platform (llvm-gcc3.4 only)
      ./fixheaders
      6. -
    6. Add the cfrontend's "bin" directory to your PATH variable.
      7. +
    7. Add llvm-gcc's "bin" directory to your PATH variable.
  • Get the LLVM Source Code @@ -592,7 +592,7 @@ All these paths are absolute:

    This is where the LLVM GCC Front End is installed.

    For the pre-built GCC front end binaries, the LLVMGCCDIR is - cfrontend/platform/llvm-gcc. + llvm-gcc/platform/llvm-gcc. @@ -643,21 +643,19 @@ compressed with the gzip program.

    llvm-test-x.y.tar.gz
    Source release for the LLVM test suite.
    -
    cfrontend-x.y.source.tar.gz
    -
    Source release of the GCC front end.
    - -
    cfrontend-x.y.i686-redhat-linux-gnu.tar.gz
    -
    Binary release of the GCC front end for Linux/x86.
    +
    llvm-gcc3.4-x.y.source.tar.gz
    +
    Source release of the LLVM GCC 3.4 front end.
    + +
    llvm-gcc3.4-x.y-platform.tar.gz
    +
    Binary release of the LLVM GCC 3.4 for a specific platform.
    llvm-gcc4-x.y.source.tar.gz
    Source release of the llvm-gcc4 front end. See README.LLVM in the root directory for build instructions.
    -
    llvm-gcc4-x.y.powerpc-apple-darwin8.6.0.tar.gz
    -
    Binary release of the llvm-gcc4 front end for MacOS X/PowerPC.
    +
    llvm-gcc4-x.y-platform.tar.gz
    +
    Binary release of the llvm-gcc4 front end for a specific platform.
    -
    llvm-gcc4-x.y.i686-apple-darwin8.6.1.tar.gz
    -
    Binary release of the llvm-gcc4 front end for MacOS X/X86.

    It is also possible to download the sources of the llvm-gcc4 front end from a @@ -694,6 +692,8 @@ revision), you can specify a label. The following releases have the following labels:

      +
    • Release 1.9: RELEASE_19
      • +
    • Release 1.8: RELEASE_18
    • Release 1.7: RELEASE_17
    • Release 1.6: RELEASE_16
    • Release 1.5: RELEASE_15
      • @@ -741,13 +741,13 @@ location must be specified when the LLVM suite is configured.

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

      Next, you will need to fix your system header files:

      +

      Next, you will need to fix your system header files (llvm-gcc3.4 only):

      -

      cd cfrontend/platform
      +

      cd llvm-gcc3.4/platform
      ./fixheaders

      The binary versions of the GCC front end may not suit all of your needs. For