From d9aa95d53410ad3c333e5ceb1d08a012f42716d6 Mon Sep 17 00:00:00 2001 From: Bill Wendling Date: Fri, 6 Jul 2012 05:51:50 +0000 Subject: Sphinxify the CMake document. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@159806 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CMake.html | 584 ---------------------------------------------------- docs/CMake.rst | 423 +++++++++++++++++++++++++++++++++++++ docs/userguides.rst | 3 +- 3 files changed, 425 insertions(+), 585 deletions(-) delete mode 100644 docs/CMake.html create mode 100644 docs/CMake.rst diff --git a/docs/CMake.html b/docs/CMake.html deleted file mode 100644 index e4ac6a401b..0000000000 --- a/docs/CMake.html +++ /dev/null @@ -1,584 +0,0 @@ - - - - - Building LLVM with CMake - - - -

- Building LLVM with CMake -

- - - -
-

Written by Oscar Fuentes

-
- - -

-Introduction -

- - -
- -

CMake is a cross-platform - build-generator tool. CMake does not build the project, it generates - the files needed by your build tool (GNU make, Visual Studio, etc) for - building LLVM.

- -

If you are really anxious about getting a functional LLVM build, - go to the Quick start section. If you - are a CMake novice, start on Basic CMake - usage and then go back to the Quick - start once you know what you are - doing. The Options and variables section - is a reference for customizing your build. If you already have - experience with CMake, this is the recommended starting point. -

- - -

-Quick start -

- - -
- -

We use here the command-line, non-interactive CMake interface

- -
    - -

  1. Download - and install CMake. Version 2.8 is the minimum required.

    - -

  2. Open a shell. Your development tools must be reachable from this - shell through the PATH environment variable.

    - -

  3. Create a directory for containing the build. It is not - supported to build LLVM on the source directory. cd to this - directory:

    -
    -

    mkdir mybuilddir

    -

    cd mybuilddir

    -
    - -

  4. Execute this command on the shell - replacing path/to/llvm/source/root with the path to the - root of your LLVM source tree:

    -
    -

    cmake path/to/llvm/source/root

    -
    - -

    CMake will detect your development environment, perform a - series of test and generate the files required for building - LLVM. CMake will use default values for all build - parameters. See the Options and variables - section for fine-tuning your build

    - -

    This can fail if CMake can't detect your toolset, or if it - thinks that the environment is not sane enough. On this case - make sure that the toolset that you intend to use is the only - one reachable from the shell and that the shell itself is the - correct one for you development environment. CMake will refuse - to build MinGW makefiles if you have a POSIX shell reachable - through the PATH environment variable, for instance. You can - force CMake to use a given build tool, see - the Usage section.

    - -
- -
- - -

- Basic CMake usage -

- - -
- -

This section explains basic aspects of CMake, mostly for - explaining those options which you may need on your day-to-day - usage.

- -

CMake comes with extensive documentation in the form of html - files and on the cmake executable itself. Execute cmake - --help for further help options.

- -

CMake requires to know for which build tool it shall generate - files (GNU make, Visual Studio, Xcode, etc). If not specified on - the command line, it tries to guess it based on you - environment. Once identified the build tool, CMake uses the - corresponding Generator for creating files for your build - tool. You can explicitly specify the generator with the command - line option -G "Name of the generator". For knowing the - available generators on your platform, execute

- -
-

cmake --help

-
- -

This will list the generator's names at the end of the help - text. Generator's names are case-sensitive. Example:

- -
-

cmake -G "Visual Studio 9 2008" 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 for building with NMake. By default, - CMake chooses the more specific generator supported by your - development environment. If you want an alternative generator, - you must tell this to CMake with the -G option.

- -

TODO: explain variables and cache. Move explanation here from - #options section.

- -
- - -

- Options and variables -

- - -
- -

Variables customize how the build will be generated. Options are - boolean variables, with possible values ON/OFF. Options and - variables are defined on the CMake command line like this:

- -
-

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:

- -
-

cmake -UVARIABLE path/to/llvm/source

-
- -

Variables are stored on the CMake cache. This is a file - named CMakeCache.txt on the root of the build - directory. Do not hand-edit it.

- -

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:

- -
-

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 brief explanation and LLVM-specific notes. For full - documentation, check the CMake docs or execute cmake - --help-variable VARIABLE_NAME.

- -
-
CMAKE_BUILD_TYPE:STRING
- -
Sets the build type for make based generators. Possible - values are Release, Debug, RelWithDebInfo and MinSizeRel. On - systems like Visual Studio the user sets the build type with the IDE - settings.
- -
CMAKE_INSTALL_PREFIX:PATH
-
Path where LLVM will be installed if "make install" is invoked - or the "INSTALL" target is built.
- -
LLVM_LIBDIR_SUFFIX:STRING
-
Extra suffix to append to the directory where libraries are to - be installed. On a 64-bit architecture, one could use - -DLLVM_LIBDIR_SUFFIX=64 to install libraries to /usr/lib64.
- -
CMAKE_C_FLAGS:STRING
-
Extra flags to use when compiling C source files.
- -
CMAKE_CXX_FLAGS:STRING
-
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 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".
- -
LLVM_BUILD_TOOLS:BOOL
-
Build LLVM tools. Defaults to ON. Targets for building each tool - are generated in any case. You can build an tool separately by - invoking its target. For example, you can build llvm-as - with a makefile-based system executing make llvm-as on the - root of your build directory.
- -
LLVM_INCLUDE_TOOLS:BOOL
-
Generate build targets for the LLVM tools. Defaults to - ON. You can use that option for disabling the generation of build - targets for the LLVM tools.
- -
LLVM_BUILD_EXAMPLES:BOOL
-
Build LLVM examples. Defaults to OFF. Targets for building each - example are generated in any case. See documentation - for LLVM_BUILD_TOOLS above for more details.
- -
LLVM_INCLUDE_EXAMPLES:BOOL
-
Generate build targets for the LLVM examples. Defaults to - ON. You can use that option for disabling the generation of build - targets for the LLVM examples.
- -
LLVM_BUILD_TESTS:BOOL
-
Build LLVM unit tests. Defaults to OFF. Targets for building - each unit test are generated in any case. You can build a specific - unit test with the target UnitTestNameTests (where at this - time UnitTestName can be ADT, Analysis, ExecutionEngine, - JIT, Support, Transform, VMCore; see the subdirectories - of unittests for an updated list.) It is possible to build - all unit tests with the target UnitTests.
- -
LLVM_INCLUDE_TESTS:BOOL
-
Generate build targets for the LLVM unit tests. Defaults to - ON. You can use that option for disabling the generation of build - targets for the LLVM unit tests.
- -
LLVM_APPEND_VC_REV:BOOL
-
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_ASSERTIONS:BOOL
-
Enables code assertions. Defaults to OFF if and only if - CMAKE_BUILD_TYPE is Release.
- -
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_WARNINGS:BOOL
-
Enable all compiler warnings. Defaults to ON.
- -
LLVM_ENABLE_PEDANTIC:BOOL
-
Enable pedantic mode. This disable compiler specific extensions, is - possible. Defaults to ON.
- -
LLVM_ENABLE_WERROR:BOOL
-
Stop and fail build, if a compiler warning is - triggered. Defaults to OFF.
- -
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_TARGET_ARCH:STRING
-
LLVM target to use for native code generation. This is required - for JIT generation. It defaults to "host", meaning that it shall - pick the architecture of the machine where LLVM is being built. If - you are cross-compiling, set it to the target architecture - name.
- -
LLVM_TABLEGEN:STRING
-
Full path to a native TableGen executable (usually - named tblgen). This is intended for cross-compiling: if the - user sets this variable, no native TableGen will be created.
- -
LLVM_LIT_ARGS:STRING
-
Arguments given to lit. - make check and make clang-test are affected. - By default, "-sv --no-progress-bar" - on Visual C++ and Xcode, - "-sv" on others.
- -
LLVM_LIT_TOOLS_DIR:PATH
-
The path to GnuWin32 tools for tests. Valid on Windows host. - Defaults to "", then Lit seeks tools according to %PATH%. - Lit can find tools(eg. grep, sort, &c) on LLVM_LIT_TOOLS_DIR at first, - without specifying GnuWin32 to %PATH%.
- -
LLVM_ENABLE_FFI:BOOL
-
Indicates whether LLVM Interpreter will be linked with Foreign - Function Interface library. If the library or its headers are - installed on a custom location, you can set the variables - FFI_INCLUDE_DIR and FFI_LIBRARY_DIR. 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.
- -
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_INTEL_JITEVENTS_DIR:PATH
-
Path to installation of Intel(R) VTune(TM) Amplifier XE 2011, - used to locate the jitprofiling library. Default = - %VTUNE_AMPLIFIER_XE_2011_DIR% (Windows) - | /opt/intel/vtune_amplifier_xe_2011 (Linux)
- -
- -
- -
- - -

- Executing the test suite -

- - -
- -

Testing is performed when the check target is built. For - instance, if you are using makefiles, execute this command while on - the top level of your build directory:

- -
-

make check

-
- -

On Visual Studio, you may run tests to build the project "check".

- -
- - -

- Cross compiling -

- - -
- -

See this - wiki page for generic instructions on how to cross-compile - with CMake. It goes into detailed explanations and may seem - daunting, but it is not. On the wiki page there are several - examples including toolchain files. Go directly to - this - section for a quick solution.

- -

Also see the LLVM-specific variables - section for variables used when 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:

- -
- 
-    # A convenience variable:
-    set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
-    # 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.)

- -

Alternativaly, you can utilize CMake's find_package - functionality. Here is an equivalent variant of snippet shown above:

- -
- 
-    find_package(LLVM)
-
-    if( NOT LLVM_FOUND )
-      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} )
-
-    llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
-
-    target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
-
-
- - -

- Developing LLVM pass out of source -

- -
- -

It is possible to develop LLVM passes against installed LLVM. - An example of project layout provided below:

- -
- 
-      <project dir>/
-          |
-          CMakeLists.txt
-          <pass name>/
-              |
-              CMakeLists.txt
-              Pass.cpp
-              ...
-
-
- -

Contents of <project dir>/CMakeLists.txt:

- -
- 
-    find_package(LLVM)
-
-    # Define add_llvm_* macro's.
-    include(AddLLVM)
-
-    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:

- -
- 
-    add_llvm_loadable_module(LLVMPassname
-      Pass.cpp
-      )
-
-
- -

When you are done developing your pass, you may wish to integrate it - into LLVM source tree. You can achieve it in two easy steps:
- 1. Copying <pass name> folder into <LLVM root>/lib/Transform directory.
- 2. Adding "add_subdirectory(<pass name>)" line into <LLVM root>/lib/Transform/CMakeLists.txt

-
- - -
- - -

- Compiler/Platform specific topics -

- - -
- -

Notes for specific compilers and/or platforms.

- -

- 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.
-
- -
- -
- - - -
-
- Valid CSS - Valid HTML 4.01 - - Oscar Fuentes
- LLVM Compiler Infrastructure
- Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $ -
- - - diff --git a/docs/CMake.rst b/docs/CMake.rst new file mode 100644 index 0000000000..7e161620d6 --- /dev/null +++ b/docs/CMake.rst @@ -0,0 +1,423 @@ +.. _cmake: + +======================== +Building LLVM with CMake +======================== + +.. contents:: + :local: + +Introduction +============ + +`CMake `_ is a cross-platform build-generator tool. CMake +does not build the project, it generates the files needed by your build tool +(GNU make, Visual Studio, etc) for building LLVM. + +If you are really anxious about getting a functional LLVM build, go to the +`Quick start`_ section. If you are a CMake novice, start on `Basic CMake usage`_ +and then go back to the `Quick start`_ once you know what you are doing. The +`Options and variables`_ section is a reference for customizing your build. If +you already have experience with CMake, this is the recommended starting point. + +.. _Quick start: + +Quick start +=========== + +We use here the command-line, non-interactive CMake interface. + +#. `Download `_ and install + CMake. Version 2.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 + + $ 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 + + $ cmake path/to/llvm/source/root + + CMake will detect your development environment, perform a series of test and + generate the files required for building LLVM. CMake will use default values + for all build parameters. See the `Options and variables`_ section for + fine-tuning your build + + This can fail if CMake can't detect your toolset, or if it thinks that the + environment is not sane enough. On this case make sure that the toolset that + you intend to use is the only one reachable from the shell and that the shell + itself is the correct one for you development environment. CMake will refuse + to build MinGW makefiles if you have a POSIX shell reachable through the PATH + environment variable, for instance. You can force CMake to use a given build + tool, see the `Usage`_ section. + +.. _Basic CMake usage: +.. _Usage: + +Basic CMake usage +================= + +This section explains basic aspects of CMake, mostly for explaining those +options which you may need on your day-to-day usage. + +CMake comes with extensive documentation in the form of html files and on the +cmake executable itself. Execute ``cmake --help`` for further help options. + +CMake requires to know for which build tool it shall generate files (GNU make, +Visual Studio, Xcode, etc). If not specified on the command line, it tries to +guess it based on you environment. Once identified the build tool, CMake uses +the corresponding *Generator* for creating files for your build tool. You can +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 + + $ 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 + + $ cmake -G "Visual Studio 9 2008" 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 +for building with NMake. By default, CMake chooses the more specific generator +supported by your development environment. If you want an alternative generator, +you must tell this to CMake with the ``-G`` option. + +.. todo:: + + Explain variables and cache. Move explanation here from #options section. + +.. _Options and variables: + +Options and variables +===================== + +Variables customize how the build will be generated. Options are boolean +variables, with possible values ON/OFF. Options and variables are defined on the +CMake command line like this: + +.. code-block:: bash + + $ 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 + + $ cmake -UVARIABLE path/to/llvm/source + +Variables are stored on the CMake cache. This is a file named ``CMakeCache.txt`` +on the root of the build directory. Do not hand-edit it. + +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 + + $ 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 +brief explanation and LLVM-specific notes. For full documentation, check the +CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. + +**CMAKE_BUILD_TYPE**:STRING + Sets the build type for ``make`` based generators. Possible values are + Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio + the user sets the build type with the IDE settings. + +**CMAKE_INSTALL_PREFIX**:PATH + Path where LLVM will be installed if "make install" is invoked or the + "INSTALL" target is built. + +**LLVM_LIBDIR_SUFFIX**:STRING + Extra suffix to append to the directory where libraries are to be + installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` + to install libraries to ``/usr/lib64``. + +**CMAKE_C_FLAGS**:STRING + Extra flags to use when compiling C source files. + +**CMAKE_CXX_FLAGS**:STRING + 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 + other OSes. + +.. _LLVM-specific variables: + +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"``. + +**LLVM_BUILD_TOOLS**:BOOL + Build LLVM tools. Defaults to ON. Targets for building each tool are generated + in any case. You can build an tool separately by invoking its target. For + example, you can build *llvm-as* with a makefile-based system executing *make + llvm-as* on the root of your build directory. + +**LLVM_INCLUDE_TOOLS**:BOOL + Generate build targets for the LLVM tools. Defaults to ON. You can use that + option for disabling the generation of build targets for the LLVM tools. + +**LLVM_BUILD_EXAMPLES**:BOOL + Build LLVM examples. Defaults to OFF. Targets for building each example are + generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more + details. + +**LLVM_INCLUDE_EXAMPLES**:BOOL + Generate build targets for the LLVM examples. Defaults to ON. You can use that + option for disabling the generation of build targets for the LLVM examples. + +**LLVM_BUILD_TESTS**:BOOL + Build LLVM unit tests. Defaults to OFF. Targets for building each unit test + are generated in any case. You can build a specific unit test with the target + *UnitTestNameTests* (where at this time *UnitTestName* can be ADT, Analysis, + ExecutionEngine, JIT, Support, Transform, VMCore; see the subdirectories of + *unittests* for an updated list.) It is possible to build all unit tests with + the target *UnitTests*. + +**LLVM_INCLUDE_TESTS**:BOOL + Generate build targets for the LLVM unit tests. Defaults to ON. You can use + that option for disabling the generation of build targets for the LLVM unit + tests. + +**LLVM_APPEND_VC_REV**:BOOL + 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_ASSERTIONS**:BOOL + Enables code assertions. Defaults to OFF if and only if ``CMAKE_BUILD_TYPE`` + is *Release*. + +**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_WARNINGS**:BOOL + Enable all compiler warnings. Defaults to ON. + +**LLVM_ENABLE_PEDANTIC**:BOOL + Enable pedantic mode. This disable compiler specific extensions, is + possible. Defaults to ON. + +**LLVM_ENABLE_WERROR**:BOOL + Stop and fail build, if a compiler warning is triggered. Defaults to OFF. + +**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_TARGET_ARCH**:STRING + LLVM target to use for native code generation. This is required for JIT + generation. It defaults to "host", meaning that it shall pick the architecture + of the machine where LLVM is being built. If you are cross-compiling, set it + to the target architecture name. + +**LLVM_TABLEGEN**:STRING + Full path to a native TableGen executable (usually named ``tblgen``). This is + intended for cross-compiling: if the user sets this variable, no native + TableGen will be created. + +**LLVM_LIT_ARGS**:STRING + Arguments given to lit. ``make check`` and ``make clang-test`` are affected. + By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on + others. + +**LLVM_LIT_TOOLS_DIR**:PATH + The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to "", + then Lit seeks tools according to %PATH%. Lit can find tools(eg. grep, sort, + &c) on LLVM_LIT_TOOLS_DIR at first, without specifying GnuWin32 to %PATH%. + +**LLVM_ENABLE_FFI**:BOOL + Indicates whether LLVM Interpreter will be linked with Foreign Function + Interface library. If the library or its headers are installed on a custom + location, you can set the variables FFI_INCLUDE_DIR and + FFI_LIBRARY_DIR. 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. + +**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_INTEL_JITEVENTS_DIR**:PATH + Path to installation of Intel(R) VTune(TM) Amplifier XE 2011, used to locate + the ``jitprofiling`` library. Default = ``%VTUNE_AMPLIFIER_XE_2011_DIR%`` + (Windows) | ``/opt/intel/vtune_amplifier_xe_2011`` (Linux) + +Executing the test suite +======================== + +Testing is performed when the *check* target is built. For instance, if you are +using makefiles, execute this command while on the top level of your build +directory: + +.. code-block:: bash + + $ make check + +On Visual Studio, you may run tests to build the project "check". + +Cross compiling +=============== + +See `this wiki page `_ for +generic instructions on how to cross-compile with CMake. It goes into detailed +explanations and may seem daunting, but it is not. On the wiki page there are +several examples including toolchain files. Go directly to `this section +`_ +for a quick solution. + +Also see the `LLVM-specific variables`_ section for variables used when +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: + +.. code-block:: cmake + + # A convenience variable: + set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.") + + # 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.) + +Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is +an equivalent variant of snippet shown above: + +.. code-block:: cmake + + find_package(LLVM) + + if( NOT LLVM_FOUND ) + 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} ) + + llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native) + + target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES}) + +Developing LLVM pass out of source +---------------------------------- + +It is possible to develop LLVM passes against installed LLVM. An example of +project layout provided below: + +.. code-block:: bash + + / + | + CMakeLists.txt + / + | + CMakeLists.txt + Pass.cpp + ... + +Contents of ``/CMakeLists.txt``: + +.. code-block:: cmake + + find_package(LLVM) + + # Define add_llvm_* macro's. + include(AddLLVM) + + add_definitions(${LLVM_DEFINITIONS}) + include_directories(${LLVM_INCLUDE_DIRS}) + link_directories(${LLVM_LIBRARY_DIRS}) + + add_subdirectory() + +Contents of ``//CMakeLists.txt``: + +.. code-block:: cmake + + add_llvm_loadable_module(LLVMPassname + Pass.cpp + ) + +When you are done developing your pass, you may wish to integrate it +into LLVM source tree. You can achieve it in two easy steps: + +#. Copying ```` folder into ``/lib/Transform`` directory. + +#. Adding ``add_subdirectory()`` line into + ``/lib/Transform/CMakeLists.txt``. + +Compiler/Platform specific topics +================================= + +Notes for specific compilers and/or platforms. + +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. diff --git a/docs/userguides.rst b/docs/userguides.rst index 1b44c48fe9..57f77f84b5 100644 --- a/docs/userguides.rst +++ b/docs/userguides.rst @@ -6,6 +6,7 @@ User Guides .. toctree:: :hidden: + CMake CommandGuide/index DeveloperPolicy GettingStartedVS @@ -19,7 +20,7 @@ User Guides Everything from unpacking and compilation of the distribution to execution of some tools. -* `LLVM CMake guide `_ +* :ref:`cmake` An addendum to the main Getting Started guide for those using the `CMake build system `_. -- cgit v1.2.3