X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCMake.rst;h=b6dd83850ff27442ca12b87ae6e5772aa5138435;hb=ff676299858e85366830be7c201961c63ba915a9;hp=988e12b73502887fb5dda1e8e68fa02c824ec0e9;hpb=913982386604ffdf70efa903b57588b505a8b269;p=oota-llvm.git diff --git a/docs/CMake.rst b/docs/CMake.rst index 988e12b7350..b6dd83850ff 100644 --- a/docs/CMake.rst +++ b/docs/CMake.rst @@ -26,7 +26,7 @@ Quick start We use here the command-line, non-interactive CMake interface. #. `Download `_ 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. @@ -59,6 +59,36 @@ We use here the command-line, non-interactive CMake interface. 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: @@ -215,23 +245,40 @@ LLVM-specific variables 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. @@ -280,8 +327,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``, ``Undefined``, ``Thread``, + and ``Address;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 @@ -302,8 +355,8 @@ LLVM-specific variables otherwise this has no effect. **LLVM_DOXYGEN_QCH_FILENAME**:STRING - The filename of the Qt Compressed Help file that will be genrated when - ``-DLLVM_ENABLE_DOXYGEN=ON`` and + 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 @@ -316,7 +369,7 @@ LLVM-specific variables 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 @@ -355,6 +408,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 +441,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) - # 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. + +* ``/share/llvm/cmake/LLVMConfig.cmake`` where + ```` is the install prefix of an installed version of LLVM. + On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``. + +* ``/share/llvm/cmake/LLVMConfig.cmake`` where + ```` 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 - find_package(LLVM) +``LLVM_CMAKE_DIR`` + The path to the LLVM CMake directory (i.e. the directory containing + 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_DEFINITIONS`` + A list of preprocessor defines that should be used when building against LLVM. - include_directories( ${LLVM_INCLUDE_DIRS} ) - link_directories( ${LLVM_LIBRARY_DIRS} ) +``LLVM_ENABLE_ASSERTIONS`` + This is set to ON if LLVM was built with assertions, otherwise OFF. - llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native) +``LLVM_ENABLE_EH`` + This is set to ON if LLVM was built with exception handling (EH) enabled, + otherwise OFF. - target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES}) +``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 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,19 +563,34 @@ Contents of ``/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() Contents of ``//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 ``/CMakeLists.txt`` (after +``find_package(LLVM ...)``) + +.. code-block:: cmake + + list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}") + include(AddLLVM) + +And then changing ``//CMakeLists.txt`` to + .. code-block:: cmake add_llvm_loadable_module(LLVMPassname @@ -487,7 +605,7 @@ into LLVM source tree. You can achieve it in two easy steps: #. Adding ``add_subdirectory()`` line into ``/lib/Transform/CMakeLists.txt``. -Compiler/Platform specific topics +Compiler/Platform-specific topics ================================= Notes for specific compilers and/or platforms.