-.. _building-with-cmake:
-
========================
Building LLVM with CMake
========================
We use here the command-line, non-interactive CMake interface.
#. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
- CMake. Version 2.8 is the minimum required.
+ CMake. Version 2.8.8 is the minimum required.
#. Open a shell. Your development tools must be reachable from this shell
through the PATH environment variable.
#. Create a directory for containing the build. It is not supported to build
LLVM on the source directory. cd to this directory:
- .. code-block:: bash
+ .. code-block:: console
$ mkdir mybuilddir
$ cd mybuilddir
#. Execute this command on the shell replacing `path/to/llvm/source/root` with
the path to the root of your LLVM source tree:
- .. code-block:: bash
+ .. code-block:: console
$ cmake path/to/llvm/source/root
environment variable, for instance. You can force CMake to use a given build
tool, see the `Usage`_ section.
+#. After CMake has finished running, proceed to use IDE project files or start
+ the build from the build directory:
+
+ .. code-block:: console
+
+ $ cmake --build .
+
+ The ``--build`` option tells ``cmake`` to invoke the underlying build
+ tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc).
+
+ The underlying build tool can be invoked directly either of course, but
+ the ``--build`` option is portable.
+
+#. After LLVM has finished building, install it from the build directory:
+
+ .. code-block:: console
+
+ $ cmake --build . --target install
+
+ The ``--target`` option with ``install`` parameter in addition to
+ the ``--build`` option tells ``cmake`` to build the ``install`` target.
+
+ It is possible to set a different install prefix at installation time
+ by invoking the ``cmake_install.cmake`` script generated in the
+ build directory:
+
+ .. code-block:: console
+
+ $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
+
.. _Basic CMake usage:
.. _Usage:
explicitly specify the generator with the command line option ``-G "Name of the
generator"``. For knowing the available generators on your platform, execute
-.. code-block:: bash
+.. code-block:: console
$ cmake --help
This will list the generator's names at the end of the help text. Generator's
names are case-sensitive. Example:
-.. code-block:: bash
+.. code-block:: console
- $ cmake -G "Visual Studio 9 2008" path/to/llvm/source/root
+ $ cmake -G "Visual Studio 11" path/to/llvm/source/root
For a given development platform there can be more than one adequate
generator. If you use Visual Studio "NMake Makefiles" is a generator you can use
variables, with possible values ON/OFF. Options and variables are defined on the
CMake command line like this:
-.. code-block:: bash
+.. code-block:: console
$ cmake -DVARIABLE=value path/to/llvm/source
You can set a variable after the initial CMake invocation for changing its
value. You can also undefine a variable:
-.. code-block:: bash
+.. code-block:: console
$ cmake -UVARIABLE path/to/llvm/source
Variables are listed here appending its type after a colon. It is correct to
write the variable and the type on the CMake command line:
-.. code-block:: bash
+.. code-block:: console
$ cmake -DVARIABLE:TYPE=value path/to/llvm/source
Frequently-used CMake variables
-------------------------------
-Here are listed some of the CMake variables that are used often, along with a
+Here are some of the CMake variables that are used often, along with a
brief explanation and LLVM-specific notes. For full documentation, check the
CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
Extra flags to use when compiling C++ source files.
**BUILD_SHARED_LIBS**:BOOL
- Flag indicating is shared libraries will be built. Its default value is
- OFF. Shared libraries are not supported on Windows and not recommended in the
+ Flag indicating if shared libraries will be built. Its default value is
+ OFF. Shared libraries are not supported on Windows and not recommended on the
other OSes.
.. _LLVM-specific variables:
**LLVM_TARGETS_TO_BUILD**:STRING
Semicolon-separated list of targets to build, or *all* for building all
- targets. Case-sensitive. For Visual C++ defaults to *X86*. On the other cases
- defaults to *all*. Example: ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
+ targets. Case-sensitive. Defaults to *all*. Example:
+ ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
**LLVM_BUILD_TOOLS**:BOOL
Build LLVM tools. Defaults to ON. Targets for building each tool are generated
tests.
**LLVM_APPEND_VC_REV**:BOOL
- Append version control revision info (svn revision number or git revision id)
+ Append version control revision info (svn revision number or Git revision id)
to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work
cmake must be invoked before the build. Defaults to OFF.
**LLVM_ENABLE_THREADS**:BOOL
Build with threads support, if available. Defaults to ON.
+**LLVM_ENABLE_CXX1Y**:BOOL
+ Build in C++1y mode, if available. Defaults to OFF.
+
**LLVM_ENABLE_ASSERTIONS**:BOOL
- Enables code assertions. Defaults to OFF if and only if ``CMAKE_BUILD_TYPE``
- is *Release*.
+ Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
+ is *Debug*.
+
+**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.
**LLVM_ENABLE_PEDANTIC**:BOOL
- Enable pedantic mode. This disable compiler specific extensions, is
+ Enable pedantic mode. This disables compiler specific extensions, if
possible. Defaults to ON.
**LLVM_ENABLE_WERROR**:BOOL
Stop and fail build, if a compiler warning is triggered. Defaults to OFF.
+**LLVM_ABI_BREAKING_CHECKS**:STRING
+ Used to decide if LLVM should be built with ABI breaking checks or
+ not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
+ `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
+ assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
+ (off) irrespective of whether normal (`NDEBUG` based) assertions are
+ enabled or not. A version of LLVM built with ABI breaking checks
+ is not ABI compatible with a version built without it.
+
**LLVM_BUILD_32_BITS**:BOOL
Build 32-bits executables and libraries on 64-bits systems. This option is
available only on some 64-bits unix systems. Defaults to OFF.
**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
Path to ``{Clang,lld,Polly}``\'s source directory. Defaults to
``tools/{clang,lld,polly}``. ``{Clang,lld,Polly}`` will not be built when it
- is empty or it does not point valid path.
+ is empty or it does not point to a valid path.
**LLVM_USE_OPROFILE**:BOOL
Enable building OProfile JIT support. Defaults to OFF
**LLVM_USE_INTEL_JITEVENTS**:BOOL
Enable building support for Intel JIT Events API. Defaults to OFF
+**LLVM_ENABLE_ZLIB**:BOOL
+ Build with zlib to support compression/uncompression in LLVM tools.
+ Defaults to ON.
+
+**LLVM_USE_SANITIZER**:STRING
+ Define the sanitizer used to build LLVM binaries and tests. Possible values
+ 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
+ be built as part of the normal build. If the ``install`` target is run then
+ this also enables all built documentation targets to be installed. Defaults to
+ OFF.
+
+**LLVM_ENABLE_DOXYGEN**:BOOL
+ Enables the generation of browsable HTML documentation using doxygen.
+ Defaults to OFF.
+
+**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
+ Enables the generation of a Qt Compressed Help file. Defaults to OFF.
+ This affects the make target ``doxygen-llvm``. When enabled, apart from
+ the normal HTML output generated by doxygen, this will produce a QCH file
+ named ``org.llvm.qch``. You can then load this file into Qt Creator.
+ This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
+ otherwise this has no effect.
+
+**LLVM_DOXYGEN_QCH_FILENAME**:STRING
+ The filename of the Qt Compressed Help file that will be generated when
+ ``-DLLVM_ENABLE_DOXYGEN=ON`` and
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
+ ``org.llvm.qch``.
+ This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise this has no effect.
+
+**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
+ Namespace under which the intermediate Qt Help Project file lives. See `Qt
+ Help Project`_
+ for more information. Defaults to "org.llvm". This option is only useful in
+ combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
+ this has no effect.
+
+**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
+ See `Qt Help Project`_ for
+ more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
+ is a combination of the package name and version string. This filter can then
+ be used in Qt Creator to select only documentation from LLVM when browsing
+ through all the help files that you might have loaded. This option is only
+ useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise this has no effect.
+
+.. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
+
+**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
+ The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
+ ``find_program()`` can find. This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise this has no
+ effect.
+
+**LLVM_ENABLE_SPHINX**:BOOL
+ If enabled CMake will search for the ``sphinx-build`` executable and will make
+ the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
+ Defaults to OFF.
+
+**SPHINX_EXECUTABLE**:STRING
+ The path to the ``sphinx-build`` executable detected by CMake.
+
+**SPHINX_OUTPUT_HTML**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for
+ building the documentation as html are added (but not built by default unless
+ ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the
+ source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
+ and ``docs-lld-html``). Defaults to ON.
+
+**SPHINX_OUTPUT_MAN**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
+ the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
+ 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
========================
using makefiles, execute this command while on the top level of your build
directory:
-.. code-block:: bash
+.. code-block:: console
$ make check
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)
- # 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()
+ find_package(LLVM REQUIRED CONFIG)
- # We incorporate the CMake features provided by LLVM:
- set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
- include(LLVMConfig)
+ message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+ message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
- # Now set the header and library paths:
- include_directories( ${LLVM_INCLUDE_DIRS} )
- link_directories( ${LLVM_LIBRARY_DIRS} )
- add_definitions( ${LLVM_DEFINITIONS} )
+ # Set your project compile flags.
+ # E.g. if using the C++ header files
+ # you will need to enable C++11 support
+ # for your compiler.
- # 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)
+ include_directories(${LLVM_INCLUDE_DIRS})
+ add_definitions(${LLVM_DEFINITIONS})
- # Finally, we link the LLVM libraries to our executable:
- target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+ # Now build our tools
+ add_executable(simple-tool tool.cpp)
-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.)
+ # Find the libraries that correspond to the LLVM components
+ # that we wish to use
+ llvm_map_components_to_libnames(llvm_libs support core irreader)
-Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is
-an equivalent variant of snippet shown above:
+ # Link against LLVM libraries
+ target_link_libraries(simple-tool ${llvm_libs})
-.. code-block:: cmake
+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.
- find_package(LLVM)
+* ``<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``.
- 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_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**
- include_directories( ${LLVM_INCLUDE_DIRS} )
- link_directories( ${LLVM_LIBRARY_DIRS} )
+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.
- llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
+The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
+include
- target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+``LLVM_CMAKE_DIR``
+ The path to the LLVM CMake directory (i.e. the directory containing
+ LLVMConfig.cmake).
-Developing LLVM pass out of source
-----------------------------------
+``LLVM_DEFINITIONS``
+ A list of preprocessor defines that should be used when building against LLVM.
-It is possible to develop LLVM passes against installed LLVM. An example of
-project layout provided below:
+``LLVM_ENABLE_ASSERTIONS``
+ This is set to ON if LLVM was built with assertions, otherwise OFF.
-.. code-block:: bash
+``LLVM_ENABLE_EH``
+ This is set to ON if LLVM was built with exception handling (EH) enabled,
+ otherwise OFF.
+
+``LLVM_ENABLE_RTTI``
+ This is set to ON if LLVM was built with run time type information (RTTI),
+ otherwise OFF.
+
+``LLVM_INCLUDE_DIRS``
+ A list of include paths to directories containing LLVM header files.
+
+``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 passes out of source
+------------------------------------
+
+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
<project dir>/
|
.. 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>)
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
#. Adding ``add_subdirectory(<pass name>)`` line into
``<LLVM root>/lib/Transform/CMakeLists.txt``.
-Compiler/Platform specific topics
+Compiler/Platform-specific topics
=================================
Notes for specific compilers and/or platforms.
**LLVM_COMPILER_JOBS**:STRING
Specifies the maximum number of parallell compiler jobs to use per project
- when building with msbuild or Visual Studio. Only supported for Visual Studio
- 2008 and Visual Studio 2010 CMake generators. 0 means use all
- processors. Default is 0.
+ when building with msbuild or Visual Studio. Only supported for the Visual
+ Studio 2010 CMake generator. 0 means use all processors. Default is 0.