[llvm-branch-commits] [llvm-branch] r214079 - Merging r214077:

Dan Liew dan at su-root.co.uk
Mon Jul 28 06:39:33 PDT 2014

Author: delcypher
Date: Mon Jul 28 08:39:33 2014
New Revision: 214079

URL: http://llvm.org/viewvc/llvm-project?rev=214079&view=rev
Merging r214077:
r214077 | delcypher | 2014-07-28 14:36:37 +0100 (Mon, 28 Jul 2014) | 2 lines

Document the new LLVM CMake interface for building against LLVM
libraries. With many contributions from Brad King.


Modified: llvm/branches/release_35/docs/CMake.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/branches/release_35/docs/CMake.rst?rev=214079&r1=214078&r2=214079&view=diff
--- llvm/branches/release_35/docs/CMake.rst (original)
+++ llvm/branches/release_35/docs/CMake.rst Mon Jul 28 08:39:33 2014
@@ -392,66 +392,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.
-.. code-block:: cmake
+Here is a simple example of CMakeLists.txt file that imports the LLVM libraries
+and uses them to build a simple application ``simple-tool``.
-  # A convenience variable:
-  set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
+.. code-block:: cmake
-  # 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()
-  # We incorporate the CMake features provided by LLVM:
-  set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
-  include(LLVMConfig)
-  # Now set the header and library paths:
-  include_directories( ${LLVM_INCLUDE_DIRS} )
-  link_directories( ${LLVM_LIBRARY_DIRS} )
-  add_definitions( ${LLVM_DEFINITIONS} )
-  # 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)
-  # Finally, we link the LLVM libraries to our executable:
-  target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
-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.)
+  cmake_minimum_required(VERSION 2.8.8)
+  project(SimpleProject)
-Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is
-an equivalent variant of snippet shown above:
+  find_package(LLVM REQUIRED CONFIG)
-.. code-block:: cmake
+  message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
-  find_package(LLVM)
+  # Set your project compile flags.
+  # E.g. if using the C++ header files
+  # you will need to enable C++11 support
+  # for your compiler.
-    message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
-  endif()
-  include_directories( ${LLVM_INCLUDE_DIRS} )
-  link_directories( ${LLVM_LIBRARY_DIRS} )
+  include_directories(${LLVM_INCLUDE_DIRS})
+  add_definitions(${LLVM_DEFINITIONS})
-  llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
+  # Now build our tools
+  add_excutable(simple-tool tool.cpp)
-  target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+  # Find the libraries that correspond to the LLVM components
+  # that we wish to use
+  llvm_map_components_to_libnames(llvm_libs support core irreader)
+  # Link against LLVM libraries
+  target_link_libraries(simple-tool ${llvm_libs})
+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``).
+This file is available in two different locations.
+* ``<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
+  The path to the LLVM CMake directory (i.e. the directory containing
+  LLVMConfig.cmake).
+  A list of preprocessor defines that should be used when building against LLVM.
+  This is set to ON if LLVM was built with assertions, otherwise OFF.
+  This is set to ON if LLVM was built with exception handling (EH) enabled,
+  otherwise OFF.
+  This is set to ON if LLVM was built with run time type information (RTTI),
+  otherwise OFF.
+  A list of include paths to directories containing LLVM header files.
+  The LLVM version. This string can be used with CMake conditionals. E.g. ``if
+  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
@@ -468,14 +514,10 @@ Contents of ``<project dir>/CMakeLists.t
 .. code-block:: cmake
-  find_package(LLVM)
-  # Define add_llvm_* macro's.
-  include(AddLLVM)
+  find_package(LLVM REQUIRED CONFIG)
-  link_directories(${LLVM_LIBRARY_DIRS})
   add_subdirectory(<pass name>)
@@ -483,6 +525,25 @@ Contents of ``<project dir>/<pass name>/
 .. 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
+  include(AddLLVM)
+And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to
+.. code-block:: cmake

More information about the llvm-branch-commits mailing list