X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCMake.rst;h=47cb2f3f04fdc8aa84194c4b45999f88bee38a31;hb=16a6d38e010c3d903497e967b583c5bb7b9196a2;hp=8459081fb8b3118b6f736850e317807e51f1ce7b;hpb=ee03c949b85036b68c261dcc27dca064ee7e525d;p=oota-llvm.git diff --git a/docs/CMake.rst b/docs/CMake.rst index 8459081fb8b..47cb2f3f04f 100644 --- a/docs/CMake.rst +++ b/docs/CMake.rst @@ -87,7 +87,7 @@ names are case-sensitive. Example: .. 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 @@ -132,7 +132,7 @@ write the variable and the type on the CMake command line: 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``. @@ -157,8 +157,8 @@ 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: @@ -211,19 +211,30 @@ LLVM-specific variables **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*. +**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 @@ -263,7 +274,7 @@ LLVM-specific variables **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 @@ -275,6 +286,93 @@ LLVM-specific variables 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 genrated 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 ======================== @@ -304,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) - # 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_excutable(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 + +``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. + +``LLVM_ENABLE_ASSERTIONS`` + This is set to ON if LLVM was built with assertions, otherwise OFF. - find_package(LLVM) +``LLVM_ENABLE_EH`` + This is set to ON if LLVM was built with exception handling (EH) enabled, + 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_RTTI`` + This is set to ON if LLVM was built with run time type information (RTTI), + otherwise OFF. - include_directories( ${LLVM_INCLUDE_DIRS} ) - link_directories( ${LLVM_LIBRARY_DIRS} ) +``LLVM_INCLUDE_DIRS`` + A list of include paths to directories containing LLVM header files. - llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native) +``LLVM_PACKAGE_VERSION`` + The LLVM version. This string can be used with CMake conditionals. E.g. ``if + (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``. - target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES}) +``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 @@ -380,19 +524,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 @@ -407,7 +566,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. @@ -417,6 +576,5 @@ Microsoft Visual C++ **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.