Update aosp/master LLVM for rebase to r222494.

Change-Id: Ic787f5e0124df789bd26f3f24680f45e678eef2d

1 files changed, 126 insertions, 47 deletions

diff --git a/docs/CMake.rst b/docs/CMake.rst
index bfc9cb9..653fa16 100644
--- a/docs/CMake.rst
+++ b/docs/CMake.rst
@@ -218,10 +218,18 @@ LLVM-specific variables
   Enables code assertions. Defaults to OFF if and only if ``CMAKE_BUILD_TYPE``
   is *Release*.
 
+**LLVM_ENABLE_EH**:BOOL
+  Build LLVM with exception handling support. This is necessary if you wish to
+  link against LLVM libraries and make use of C++ exceptions in your own code
+  that need to propagate through LLVM code. Defaults to OFF.
+
 **LLVM_ENABLE_PIC**:BOOL
   Add the ``-fPIC`` flag for the compiler command-line, if the compiler supports
   this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
 
+**LLVM_ENABLE_RTTI**:BOOL
+  Build LLVM with run time type information. Defaults to OFF.
+
 **LLVM_ENABLE_WARNINGS**:BOOL
   Enable all compiler warnings. Defaults to ON.
 
@@ -280,8 +288,14 @@ LLVM-specific variables
 
 **LLVM_USE_SANITIZER**:STRING
   Define the sanitizer used to build LLVM binaries and tests. Possible values
-  are ``Address``, ``Memory`` and ``MemoryWithOrigins``. Defaults to empty
-  string.
+  are ``Address``, ``Memory``, ``MemoryWithOrigins`` and ``Undefined``.
+  Defaults to empty string.
+
+**LLVM_PARALLEL_COMPILE_JOBS**:STRING
+  Define the maximum number of concurrent compilation jobs.
+
+**LLVM_PARALLEL_LINK_JOBS**:STRING
+  Define the maximum number of concurrent link jobs.
 
 **LLVM_BUILD_DOCS**:BOOL
   Enables all enabled documentation targets (i.e. Doxgyen and Sphinx targets) to
@@ -355,6 +369,10 @@ LLVM-specific variables
   is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
   to ON.
 
+**SPHINX_WARNINGS_AS_ERRORS**:BOOL
+  If enabled then sphinx documentation warnings will be treated as
+  errors. Defaults to ON.
+
 Executing the test suite
 ========================
 
@@ -384,66 +402,112 @@ cross-compiling.
 Embedding LLVM in your project
 ==============================
 
-The most difficult part of adding LLVM to the build of a project is to determine
-the set of LLVM libraries corresponding to the set of required LLVM
-features. What follows is an example of how to obtain this information:
+From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems export
+LLVM libraries as importable CMake targets. This means that clients of LLVM can
+now reliably use CMake to develop their own LLVM based projects against an
+installed version of LLVM regardless of how it was built.
+
+Here is a simple example of CMakeLists.txt file that imports the LLVM libraries
+and uses them to build a simple application ``simple-tool``.
 
 .. code-block:: cmake
 
-  # A convenience variable:
-  set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
+  cmake_minimum_required(VERSION 2.8.8)
+  project(SimpleProject)
+
+  find_package(LLVM REQUIRED CONFIG)
+
+  message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+  message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
 
-  # A bit of a sanity check:
-  if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
-  message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
-  endif()
+  # Set your project compile flags.
+  # E.g. if using the C++ header files
+  # you will need to enable C++11 support
+  # for your compiler.
 
-  # We incorporate the CMake features provided by LLVM:
-  set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
-  include(LLVMConfig)
+  include_directories(${LLVM_INCLUDE_DIRS})
+  add_definitions(${LLVM_DEFINITIONS})
 
-  # Now set the header and library paths:
-  include_directories( ${LLVM_INCLUDE_DIRS} )
-  link_directories( ${LLVM_LIBRARY_DIRS} )
-  add_definitions( ${LLVM_DEFINITIONS} )
+  # Now build our tools
+  add_excutable(simple-tool tool.cpp)
 
-  # Let's suppose we want to build a JIT compiler with support for
-  # binary code (no interpreter):
-  llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
+  # Find the libraries that correspond to the LLVM components
+  # that we wish to use
+  llvm_map_components_to_libnames(llvm_libs support core irreader)
 
-  # Finally, we link the LLVM libraries to our executable:
-  target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+  # Link against LLVM libraries
+  target_link_libraries(simple-tool ${llvm_libs})
 
-This assumes that LLVM_ROOT points to an install of LLVM. The procedure works
-too for uninstalled builds although we need to take care to add an
-`include_directories` for the location of the headers on the LLVM source
-directory (if we are building out-of-source.)
+The ``find_package(...)`` directive when used in CONFIG mode (as in the above
+example) will look for the ``LLVMConfig.cmake`` file in various locations (see
+cmake manual for details).  It creates a ``LLVM_DIR`` cache entry to save the
+directory where ``LLVMConfig.cmake`` is found or allows the user to specify the
+directory (e.g. by passing ``-DLLVM_DIR=/usr/share/llvm/cmake`` to
+the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
 
-Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is
-an equivalent variant of snippet shown above:
+This file is available in two different locations.
 
-.. code-block:: cmake
+* ``<INSTALL_PREFIX>/share/llvm/cmake/LLVMConfig.cmake`` where
+  ``<INSTALL_PREFIX>`` is the install prefix of an installed version of LLVM.
+  On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``.
+
+* ``<LLVM_BUILD_ROOT>/share/llvm/cmake/LLVMConfig.cmake`` where
+  ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note this only
+  available when building LLVM with CMake**
+
+If LLVM is installed in your operating system's normal installation prefix (e.g.
+on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
+automatically find LLVM if it is installed correctly. If LLVM is not installed
+or you wish to build directly against the LLVM build tree you can use
+``LLVM_DIR`` as previously mentioned.
+
+The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
+include
+
+``LLVM_CMAKE_DIR``
+  The path to the LLVM CMake directory (i.e. the directory containing
+  LLVMConfig.cmake).
+
+``LLVM_DEFINITIONS``
+  A list of preprocessor defines that should be used when building against LLVM.
 
-  find_package(LLVM)
+``LLVM_ENABLE_ASSERTIONS``
+  This is set to ON if LLVM was built with assertions, otherwise OFF.
 
-  if( NOT LLVM_FOUND )
-    message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
-  endif()
+``LLVM_ENABLE_EH``
+  This is set to ON if LLVM was built with exception handling (EH) enabled,
+  otherwise OFF.
 
-  include_directories( ${LLVM_INCLUDE_DIRS} )
-  link_directories( ${LLVM_LIBRARY_DIRS} )
+``LLVM_ENABLE_RTTI``
+  This is set to ON if LLVM was built with run time type information (RTTI),
+  otherwise OFF.
 
-  llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
+``LLVM_INCLUDE_DIRS``
+  A list of include paths to directories containing LLVM header files.
 
-  target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+``LLVM_PACKAGE_VERSION``
+  The LLVM version. This string can be used with CMake conditionals. E.g. ``if
+  (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
+
+``LLVM_TOOLS_BINARY_DIR``
+  The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
+
+Notice that in the above example we link ``simple-tool`` against several LLVM
+libraries. The list of libraries is determined by using the
+``llvm_map_components_to_libnames()`` CMake function. For a list of available
+components look at the output of running ``llvm-config --components``.
+
+Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
+used instead of ``llvm_map_components_to_libnames()``. This is now deprecated
+and will be removed in a future version of LLVM.
 
 .. _cmake-out-of-source-pass:
 
-Developing LLVM pass out of source
-----------------------------------
+Developing LLVM passes out of source
+------------------------------------
 
-It is possible to develop LLVM passes against installed LLVM.  An example of
-project layout provided below:
+It is possible to develop LLVM passes out of LLVM's source tree (i.e. against an
+installed or built LLVM). An example of a project layout is provided below.
 
 .. code-block:: none
 
@@ -460,14 +524,10 @@ Contents of ``<project dir>/CMakeLists.txt``:
 
 .. code-block:: cmake
 
-  find_package(LLVM)
-
-  # Define add_llvm_* macro's.
-  include(AddLLVM)
+  find_package(LLVM REQUIRED CONFIG)
 
   add_definitions(${LLVM_DEFINITIONS})
   include_directories(${LLVM_INCLUDE_DIRS})
-  link_directories(${LLVM_LIBRARY_DIRS})
 
   add_subdirectory(<pass name>)
 
@@ -475,6 +535,25 @@ Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
 
 .. code-block:: cmake
 
+  add_library(LLVMPassname MODULE Pass.cpp)
+
+Note if you intend for this pass to be merged into the LLVM source tree at some
+point in the future it might make more sense to use LLVM's internal
+add_llvm_loadable_module function instead by...
+
+
+Adding the following to ``<project dir>/CMakeLists.txt`` (after
+``find_package(LLVM ...)``)
+
+.. code-block:: cmake
+
+  list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
+  include(AddLLVM)
+
+And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to
+
+.. code-block:: cmake
+
   add_llvm_loadable_module(LLVMPassname
     Pass.cpp
     )