ReleaseNotes: C API policy; by Eric Christopher

[oota-llvm.git] / docs / GettingStarted.rst

diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst
index 7e223b928d5741574ef064a7bcb8c01bb72c98b2..6aba500367939e24953ec8eff08ef26574d50f37 100644 (file)
--- a/docs/GettingStarted.rst
+++ b/docs/GettingStarted.rst
@@ -1,5 +1,5 @@
 ====================================
 ====================================

-Getting Started with the LLVM System  
+Getting Started with the LLVM System

 ====================================
 
 .. contents::
 ====================================
 
 .. contents::


@@ -49,34 +49,52 @@ Here's the short story for getting up and running quickly with LLVM:
    * ``cd llvm/tools``
    * ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang``
 
    * ``cd llvm/tools``
    * ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang``
 

-#. Checkout Compiler-RT:
+#. Checkout Compiler-RT (required to build the sanitizers):

 
    * ``cd where-you-want-llvm-to-live``
    * ``cd llvm/projects``
    * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk 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``
 

+#. Checkout Libomp (required for OpenMP support):
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``cd llvm/projects``
+   * ``svn co http://llvm.org/svn/llvm-project/openmp/trunk openmp``
+
+#. Checkout libcxx and libcxxabi **[Optional]**:
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``cd llvm/projects``
+   * ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
+   * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi``
+

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

-#. Configure and build LLVM and Clang (Recommended process using CMake):
+#. Configure and build LLVM and Clang:
+
+   The usual build uses `CMake <CMake.html>`_. If you would rather use
+   autotools, see `Building LLVM with autotools <BuildingLLVMWithAutotools.html>`_.
+   Although the build is known to work with CMake >= 2.8.8, we recommend CMake
+   >= v3.2, especially if you're generating Ninja build files.

 
    * ``cd where you want to build llvm``
    * ``mkdir build``
    * ``cd build``
    * ``cmake -G <generator> [options] <path to llvm sources>``
 
    * ``cd where you want to build llvm``
    * ``mkdir build``
    * ``cd build``
    * ``cmake -G <generator> [options] <path to llvm sources>``

-     
+

      Some common generators are:
 
      * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
      * ``Ninja`` --- for generating `Ninja <http://martine.github.io/ninja/>`
      Some common generators are:
 
      * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
      * ``Ninja`` --- for generating `Ninja <http://martine.github.io/ninja/>`

-        build files.
+        build files. Most llvm developers use Ninja.

      * ``Visual Studio`` --- for generating Visual Studio projects and
         solutions.
      * ``Xcode`` --- for generating Xcode projects.
      * ``Visual Studio`` --- for generating Visual Studio projects and
         solutions.
      * ``Xcode`` --- for generating Xcode projects.

-     
+

      Some Common options:
 
      * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
      Some Common options:
 
      * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full


@@ -89,36 +107,20 @@ Here's the short story for getting up and running quickly with LLVM:
      * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
        (default is Yes for Debug builds, No for all other build types).
 
      * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
        (default is Yes for Debug builds, No for all other build types).
 

-   * For more information see `CMake <CMake.html>`_
-
-#. Configure and build LLVM and Clang (Alternate process using configure):
-
-   * ``cd where-you-want-to-build-llvm``
-   * ``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 want the LLVM tools and libraries to be installed (default
-       ``/usr/local``).
+   * Run your build tool of choice!

 
 

-     * ``--enable-optimized`` --- Compile with optimizations enabled (default
-       is NO).
+     * The default target (i.e. ``make``) will build all of LLVM

 
 

-     * ``--enable-assertions`` --- Compile with assertion checks enabled
-       (default is YES).
+     * The ``check-all`` target (i.e. ``make check-all``) will run the
+       regression tests to ensure everything is in working order.

 
 

-   * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run
-     simultaneously.  This builds both LLVM and Clang for Debug+Asserts mode.
-     The ``--enable-optimized`` configure option is used to specify a Release
-     build.
+     * CMake will generate build targets for each tool and library, and most
+       LLVM sub-projects generate their own ``check-<project>`` target.

 
 

-   * ``make check-all`` --- This run the regression tests to ensure everything
-     is in working order.
+   * For more information see `CMake <CMake.html>`_

 
    * If you get an "internal compiler error (ICE)" or test failures, see
 
    * If you get an "internal compiler error (ICE)" or test failures, see

-     `below`.
+     `below`_.

 
 Consult the `Getting Started with LLVM`_ section for detailed information on
 configuring and compiling LLVM.  See `Setting Up Your Environment`_ for tips
 
 Consult the `Getting Started with LLVM`_ section for detailed information on
 configuring and compiling LLVM.  See `Setting Up Your Environment`_ for tips


@@ -138,20 +140,20 @@ Hardware
 LLVM is known to work on the following host platforms:
 
 ================== ===================== =============
 LLVM is known to work on the following host platforms:
 
 ================== ===================== =============

-OS                 Arch                  Compilers               
+OS                 Arch                  Compilers

 ================== ===================== =============
 ================== ===================== =============

-Linux              x86\ :sup:`1`         GCC, Clang              
-Linux              amd64                 GCC, Clang              
-Linux              ARM\ :sup:`4`         GCC, Clang              
-Linux              PowerPC               GCC, Clang              
-Solaris            V9 (Ultrasparc)       GCC                     
-FreeBSD            x86\ :sup:`1`         GCC, Clang              
-FreeBSD            amd64                 GCC, Clang              
-MacOS X\ :sup:`2`  PowerPC               GCC                     
-MacOS X            x86                   GCC, Clang              
-Cygwin/Win32       x86\ :sup:`1, 3`      GCC                     
-Windows            x86\ :sup:`1`         Visual Studio           
-Windows x64        x86-64                Visual Studio           
+Linux              x86\ :sup:`1`         GCC, Clang
+Linux              amd64                 GCC, Clang
+Linux              ARM\ :sup:`4`         GCC, Clang
+Linux              PowerPC               GCC, Clang
+Solaris            V9 (Ultrasparc)       GCC
+FreeBSD            x86\ :sup:`1`         GCC, Clang
+FreeBSD            amd64                 GCC, Clang
+MacOS X\ :sup:`2`  PowerPC               GCC
+MacOS X            x86                   GCC, Clang
+Cygwin/Win32       x86\ :sup:`1, 3`      GCC
+Windows            x86\ :sup:`1`         Visual Studio
+Windows x64        x86-64                Visual Studio

 ================== ===================== =============
 
 .. note::
 ================== ===================== =============
 
 .. note::


@@ -220,14 +222,14 @@ Unix utilities. Specifically:
 * **chmod** --- change permissions on a file
 * **cat** --- output concatenation utility
 * **cp** --- copy files
 * **chmod** --- change permissions on a file
 * **cat** --- output concatenation utility
 * **cp** --- copy files

-* **date** --- print the current date/time 
+* **date** --- print the current date/time

 * **echo** --- print to standard output
 * **egrep** --- extended regular expression search utility
 * **find** --- find files/dirs in a file system
 * **grep** --- regular expression search utility
 * **gzip** --- gzip command for distribution generation
 * **gunzip** --- gunzip command for distribution checking
 * **echo** --- print to standard output
 * **egrep** --- extended regular expression search utility
 * **find** --- find files/dirs in a file system
 * **grep** --- regular expression search utility
 * **gzip** --- gzip command for distribution generation
 * **gunzip** --- gunzip command for distribution checking

-* **install** --- install directories/files 
+* **install** --- install directories/files

 * **mkdir** --- create a directory
 * **mv** --- move (rename) files
 * **ranlib** --- symbol table builder for archive libraries
 * **mkdir** --- create a directory
 * **mv** --- move (rename) files
 * **ranlib** --- symbol table builder for archive libraries


@@ -339,7 +341,11 @@ Easy steps for installing GCC 4.8.2:
 
 .. code-block:: console
 
 
 .. code-block:: console
 

-  % wget ftp://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2.sig
+  % wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
+  % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-4.8.2.tar.bz2.sig`
+  % if [ $signature_invalid ]; then echo "Invalid signature" ; exit 1 ; fi

   % tar -xvjf gcc-4.8.2.tar.bz2
   % cd gcc-4.8.2
   % ./contrib/download_prerequisites
   % tar -xvjf gcc-4.8.2.tar.bz2
   % cd gcc-4.8.2
   % ./contrib/download_prerequisites


@@ -530,13 +536,28 @@ If you want to check out clang too, run:
   % cd llvm/tools
   % git clone http://llvm.org/git/clang.git
 
   % cd llvm/tools
   % git clone http://llvm.org/git/clang.git
 

-If you want to check out compiler-rt too, run:
+If you want to check out compiler-rt (required to build the sanitizers), run:

 
 .. code-block:: console
 
   % cd llvm/projects
   % git clone http://llvm.org/git/compiler-rt.git
 
 
 .. code-block:: console
 
   % cd llvm/projects
   % git clone http://llvm.org/git/compiler-rt.git
 

+If you want to check out libomp (required for OpenMP support), run:
+
+.. code-block:: console
+
+  % cd llvm/projects
+  % git clone http://llvm.org/git/openmp.git
+
+If you want to check out libcxx and libcxxabi (optional), run:
+
+.. code-block:: console
+
+  % cd llvm/projects
+  % git clone http://llvm.org/git/libcxx.git
+  % git clone http://llvm.org/git/libcxxabi.git
+

 If you want to check out the Test Suite Source Code (optional), run:
 
 .. code-block:: console
 If you want to check out the Test Suite Source Code (optional), run:
 
 .. code-block:: console


@@ -628,7 +649,7 @@ To set up clone from which you can submit code using ``git-svn``, run:
   % git config svn-remote.svn.fetch :refs/remotes/origin/master
   % git svn rebase -l
 
   % git config svn-remote.svn.fetch :refs/remotes/origin/master
   % git svn rebase -l
 

-Likewise for compiler-rt and test-suite.
+Likewise for compiler-rt, libomp and test-suite.

 
 To update this clone without generating git-svn tags that conflict with the
 upstream Git repo, run:
 
 To update this clone without generating git-svn tags that conflict with the
 upstream Git repo, run:


@@ -642,7 +663,7 @@ upstream Git repo, run:
      git checkout master &&
      git svn rebase -l)
 
      git checkout master &&
      git svn rebase -l)
 

-Likewise for compiler-rt and test-suite.
+Likewise for compiler-rt, libomp and test-suite.

 
 This leaves your working directories on their master branches, so you'll need to
 ``checkout`` each working branch individually and ``rebase`` it on top of its
 
 This leaves your working directories on their master branches, so you'll need to
 ``checkout`` each working branch individually and ``rebase`` it on top of its


@@ -723,9 +744,9 @@ used by people developing LLVM.
 |                         | the configure script. The default list is defined  |
 |                         | as ``LLVM_ALL_TARGETS``, and can be set to include |
 |                         | out-of-tree targets. The default value includes:   |
 |                         | the configure script. The default list is defined  |
 |                         | as ``LLVM_ALL_TARGETS``, and can be set to include |
 |                         | out-of-tree targets. The default value includes:   |

-|                         | ``AArch64, ARM, CppBackend, Hexagon,               |
-|                         | Mips, MSP430, NVPTX, PowerPC, R600, Sparc,         |
-|                         | SystemZ, X86, XCore``.                             |
+|                         | ``AArch64, AMDGPU, ARM, BPF, CppBackend, Hexagon,  |
+|                         | Mips, MSP430, NVPTX, PowerPC, Sparc, SystemZ       |
+|                         | X86, XCore``.                                      |

 +-------------------------+----------------------------------------------------+
 | LLVM_ENABLE_DOXYGEN     | Build doxygen-based documentation from the source  |
 |                         | code This is disabled by default because it is     |
 +-------------------------+----------------------------------------------------+
 | LLVM_ENABLE_DOXYGEN     | Build doxygen-based documentation from the source  |
 |                         | code This is disabled by default because it is     |


@@ -847,7 +868,7 @@ with the latest Xcode:
 
 .. code-block:: console
 
 
 .. code-block:: console
 

-  % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES=“armv7;armv7s;arm64"
+  % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES="armv7;armv7s;arm64"

     -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake
     -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off
     -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]
     -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake
     -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off
     -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]


@@ -890,7 +911,7 @@ Underneath that directory there is another directory with a name ending in
 For example:
 
   .. code-block:: console
 For example:
 
   .. code-block:: console

-  
+

     % cd llvm_build_dir
     % find lib/Support/ -name APFloat*
     lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o
     % cd llvm_build_dir
     % find lib/Support/ -name APFloat*
     lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o


@@ -999,7 +1020,7 @@ different `tools`_.
   code generation.  For example, the ``llvm/lib/Target/X86`` directory holds the
   X86 machine description while ``llvm/lib/Target/ARM`` implements the ARM
   backend.
   code generation.  For example, the ``llvm/lib/Target/X86`` directory holds the
   X86 machine description while ``llvm/lib/Target/ARM`` implements the ARM
   backend.

-    
+

 ``llvm/lib/CodeGen/``
 
   This directory contains the major parts of the code generator: Instruction
 ``llvm/lib/CodeGen/``
 
   This directory contains the major parts of the code generator: Instruction


@@ -1084,7 +1105,7 @@ the `Command Guide <CommandGuide/index.html>`_.
 
   The archiver produces an archive containing the given LLVM bitcode files,
   optionally with an index for faster lookup.
 
   The archiver produces an archive containing the given LLVM bitcode files,
   optionally with an index for faster lookup.

-  
+

 ``llvm-as``
 
   The assembler transforms the human readable LLVM assembly to LLVM bitcode.
 ``llvm-as``
 
   The assembler transforms the human readable LLVM assembly to LLVM bitcode.


@@ -1097,7 +1118,7 @@ the `Command Guide <CommandGuide/index.html>`_.
 
   ``llvm-link``, not surprisingly, links multiple LLVM modules into a single
   program.
 
   ``llvm-link``, not surprisingly, links multiple LLVM modules into a single
   program.

-  
+

 ``lli``
 
   ``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode
 ``lli``
 
   ``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode


@@ -1228,7 +1249,7 @@ Example with clang
    .. code-block:: console
 
       % ./hello
    .. code-block:: console
 
       % ./hello

- 
+

    and
 
    .. code-block:: console
    and
 
    .. code-block:: console