docs/CMake.rst

   1 .. _building-with-cmake:
   2
   3 ========================
   4 Building LLVM with CMake
   5 ========================
   6
   7 .. contents::
   8    :local:
   9
  10 Introduction
  11 ============
  12
  13 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
  14 does not build the project, it generates the files needed by your build tool
  15 (GNU make, Visual Studio, etc) for building LLVM.
  16
  17 If you are really anxious about getting a functional LLVM build, go to the
  18 `Quick start`_ section. If you are a CMake novice, start on `Basic CMake usage`_
  19 and then go back to the `Quick start`_ once you know what you are doing. The
  20 `Options and variables`_ section is a reference for customizing your build. If
  21 you already have experience with CMake, this is the recommended starting point.
  22
  23 .. _Quick start:
  24
  25 Quick start
  26 ===========
  27
  28 We use here the command-line, non-interactive CMake interface.
  29
  30 #. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
  31    CMake. Version 2.8 is the minimum required.
  32
  33 #. Open a shell. Your development tools must be reachable from this shell
  34    through the PATH environment variable.
  35
  36 #. Create a directory for containing the build. It is not supported to build
  37    LLVM on the source directory. cd to this directory:
  38
  39    .. code-block:: bash
  40
  41      $ mkdir mybuilddir
  42      $ cd mybuilddir
  43
  44 #. Execute this command on the shell replacing `path/to/llvm/source/root` with
  45    the path to the root of your LLVM source tree:
  46
  47    .. code-block:: bash
  48
  49      $ cmake path/to/llvm/source/root
  50
  51    CMake will detect your development environment, perform a series of test and
  52    generate the files required for building LLVM. CMake will use default values
  53    for all build parameters. See the `Options and variables`_ section for
  54    fine-tuning your build
  55
  56    This can fail if CMake can't detect your toolset, or if it thinks that the
  57    environment is not sane enough. On this case make sure that the toolset that
  58    you intend to use is the only one reachable from the shell and that the shell
  59    itself is the correct one for you development environment. CMake will refuse
  60    to build MinGW makefiles if you have a POSIX shell reachable through the PATH
  61    environment variable, for instance. You can force CMake to use a given build
  62    tool, see the `Usage`_ section.
  63
  64 .. _Basic CMake usage:
  65 .. _Usage:
  66
  67 Basic CMake usage
  68 =================
  69
  70 This section explains basic aspects of CMake, mostly for explaining those
  71 options which you may need on your day-to-day usage.
  72
  73 CMake comes with extensive documentation in the form of html files and on the
  74 cmake executable itself. Execute ``cmake --help`` for further help options.
  75
  76 CMake requires to know for which build tool it shall generate files (GNU make,
  77 Visual Studio, Xcode, etc). If not specified on the command line, it tries to
  78 guess it based on you environment. Once identified the build tool, CMake uses
  79 the corresponding *Generator* for creating files for your build tool. You can
  80 explicitly specify the generator with the command line option ``-G "Name of the
  81 generator"``. For knowing the available generators on your platform, execute
  82
  83 .. code-block:: bash
  84
  85   $ cmake --help
  86
  87 This will list the generator's names at the end of the help text. Generator's
  88 names are case-sensitive. Example:
  89
  90 .. code-block:: bash
  91
  92   $ cmake -G "Visual Studio 9 2008" path/to/llvm/source/root
  93
  94 For a given development platform there can be more than one adequate
  95 generator. If you use Visual Studio "NMake Makefiles" is a generator you can use
  96 for building with NMake. By default, CMake chooses the more specific generator
  97 supported by your development environment. If you want an alternative generator,
  98 you must tell this to CMake with the ``-G`` option.
  99
 100 .. todo::
 101
 102   Explain variables and cache. Move explanation here from #options section.
 103
 104 .. _Options and variables:
 105
 106 Options and variables
 107 =====================
 108
 109 Variables customize how the build will be generated. Options are boolean
 110 variables, with possible values ON/OFF. Options and variables are defined on the
 111 CMake command line like this:
 112
 113 .. code-block:: bash
 114
 115   $ cmake -DVARIABLE=value path/to/llvm/source
 116
 117 You can set a variable after the initial CMake invocation for changing its
 118 value. You can also undefine a variable:
 119
 120 .. code-block:: bash
 121
 122   $ cmake -UVARIABLE path/to/llvm/source
 123
 124 Variables are stored on the CMake cache. This is a file named ``CMakeCache.txt``
 125 on the root of the build directory. Do not hand-edit it.
 126
 127 Variables are listed here appending its type after a colon. It is correct to
 128 write the variable and the type on the CMake command line:
 129
 130 .. code-block:: bash
 131
 132   $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
 133
 134 Frequently-used CMake variables
 135 -------------------------------
 136
 137 Here are listed some of the CMake variables that are used often, along with a
 138 brief explanation and LLVM-specific notes. For full documentation, check the
 139 CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
 140
 141 **CMAKE_BUILD_TYPE**:STRING
 142   Sets the build type for ``make`` based generators. Possible values are
 143   Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
 144   the user sets the build type with the IDE settings.
 145
 146 **CMAKE_INSTALL_PREFIX**:PATH
 147   Path where LLVM will be installed if "make install" is invoked or the
 148   "INSTALL" target is built.
 149
 150 **LLVM_LIBDIR_SUFFIX**:STRING
 151   Extra suffix to append to the directory where libraries are to be
 152   installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
 153   to install libraries to ``/usr/lib64``.
 154
 155 **CMAKE_C_FLAGS**:STRING
 156   Extra flags to use when compiling C source files.
 157
 158 **CMAKE_CXX_FLAGS**:STRING
 159   Extra flags to use when compiling C++ source files.
 160
 161 **BUILD_SHARED_LIBS**:BOOL
 162   Flag indicating is shared libraries will be built. Its default value is
 163   OFF. Shared libraries are not supported on Windows and not recommended in the
 164   other OSes.
 165
 166 .. _LLVM-specific variables:
 167
 168 LLVM-specific variables
 169 -----------------------
 170
 171 **LLVM_TARGETS_TO_BUILD**:STRING
 172   Semicolon-separated list of targets to build, or *all* for building all
 173   targets. Case-sensitive. For Visual C++ defaults to *X86*. On the other cases
 174   defaults to *all*. Example: ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
 175
 176 **LLVM_BUILD_TOOLS**:BOOL
 177   Build LLVM tools. Defaults to ON. Targets for building each tool are generated
 178   in any case. You can build an tool separately by invoking its target. For
 179   example, you can build *llvm-as* with a makefile-based system executing *make
 180   llvm-as* on the root of your build directory.
 181
 182 **LLVM_INCLUDE_TOOLS**:BOOL
 183   Generate build targets for the LLVM tools. Defaults to ON. You can use that
 184   option for disabling the generation of build targets for the LLVM tools.
 185
 186 **LLVM_BUILD_EXAMPLES**:BOOL
 187   Build LLVM examples. Defaults to OFF. Targets for building each example are
 188   generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
 189   details.
 190
 191 **LLVM_INCLUDE_EXAMPLES**:BOOL
 192   Generate build targets for the LLVM examples. Defaults to ON. You can use that
 193   option for disabling the generation of build targets for the LLVM examples.
 194
 195 **LLVM_BUILD_TESTS**:BOOL
 196   Build LLVM unit tests. Defaults to OFF. Targets for building each unit test
 197   are generated in any case. You can build a specific unit test with the target
 198   *UnitTestNameTests* (where at this time *UnitTestName* can be ADT, Analysis,
 199   ExecutionEngine, JIT, Support, Transform, VMCore; see the subdirectories of
 200   *unittests* for an updated list.) It is possible to build all unit tests with
 201   the target *UnitTests*.
 202
 203 **LLVM_INCLUDE_TESTS**:BOOL
 204   Generate build targets for the LLVM unit tests. Defaults to ON. You can use
 205   that option for disabling the generation of build targets for the LLVM unit
 206   tests.
 207
 208 **LLVM_APPEND_VC_REV**:BOOL
 209   Append version control revision info (svn revision number or git revision id)
 210   to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work
 211   cmake must be invoked before the build. Defaults to OFF.
 212
 213 **LLVM_ENABLE_THREADS**:BOOL
 214   Build with threads support, if available. Defaults to ON.
 215
 216 **LLVM_ENABLE_ASSERTIONS**:BOOL
 217   Enables code assertions. Defaults to OFF if and only if ``CMAKE_BUILD_TYPE``
 218   is *Release*.
 219
 220 **LLVM_ENABLE_PIC**:BOOL
 221   Add the ``-fPIC`` flag for the compiler command-line, if the compiler supports
 222   this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
 223
 224 **LLVM_ENABLE_WARNINGS**:BOOL
 225   Enable all compiler warnings. Defaults to ON.
 226
 227 **LLVM_ENABLE_PEDANTIC**:BOOL
 228   Enable pedantic mode. This disable compiler specific extensions, is
 229   possible. Defaults to ON.
 230
 231 **LLVM_ENABLE_WERROR**:BOOL
 232   Stop and fail build, if a compiler warning is triggered. Defaults to OFF.
 233
 234 **LLVM_BUILD_32_BITS**:BOOL
 235   Build 32-bits executables and libraries on 64-bits systems. This option is
 236   available only on some 64-bits unix systems. Defaults to OFF.
 237
 238 **LLVM_TARGET_ARCH**:STRING
 239   LLVM target to use for native code generation. This is required for JIT
 240   generation. It defaults to "host", meaning that it shall pick the architecture
 241   of the machine where LLVM is being built. If you are cross-compiling, set it
 242   to the target architecture name.
 243
 244 **LLVM_TABLEGEN**:STRING
 245   Full path to a native TableGen executable (usually named ``tblgen``). This is
 246   intended for cross-compiling: if the user sets this variable, no native
 247   TableGen will be created.
 248
 249 **LLVM_LIT_ARGS**:STRING
 250   Arguments given to lit.  ``make check`` and ``make clang-test`` are affected.
 251   By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
 252   others.
 253
 254 **LLVM_LIT_TOOLS_DIR**:PATH
 255   The path to GnuWin32 tools for tests. Valid on Windows host.  Defaults to "",
 256   then Lit seeks tools according to %PATH%.  Lit can find tools(eg. grep, sort,
 257   &c) on LLVM_LIT_TOOLS_DIR at first, without specifying GnuWin32 to %PATH%.
 258
 259 **LLVM_ENABLE_FFI**:BOOL
 260   Indicates whether LLVM Interpreter will be linked with Foreign Function
 261   Interface library. If the library or its headers are installed on a custom
 262   location, you can set the variables FFI_INCLUDE_DIR and
 263   FFI_LIBRARY_DIR. Defaults to OFF.
 264
 265 **LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
 266   Path to ``{Clang,lld,Polly}``\'s source directory. Defaults to
 267   ``tools/{clang,lld,polly}``. ``{Clang,lld,Polly}`` will not be built when it
 268   is empty or it does not point valid path.
 269
 270 **LLVM_USE_OPROFILE**:BOOL
 271   Enable building OProfile JIT support. Defaults to OFF
 272
 273 **LLVM_USE_INTEL_JITEVENTS**:BOOL
 274   Enable building support for Intel JIT Events API. Defaults to OFF
 275
 276 **LLVM_INTEL_JITEVENTS_DIR**:PATH
 277   Path to installation of Intel(R) VTune(TM) Amplifier XE 2011, used to locate
 278   the ``jitprofiling`` library. Default = ``%VTUNE_AMPLIFIER_XE_2011_DIR%``
 279   (Windows) | ``/opt/intel/vtune_amplifier_xe_2011`` (Linux)
 280
 281 Executing the test suite
 282 ========================
 283
 284 Testing is performed when the *check* target is built. For instance, if you are
 285 using makefiles, execute this command while on the top level of your build
 286 directory:
 287
 288 .. code-block:: bash
 289
 290   $ make check
 291
 292 On Visual Studio, you may run tests to build the project "check".
 293
 294 Cross compiling
 295 ===============
 296
 297 See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for
 298 generic instructions on how to cross-compile with CMake. It goes into detailed
 299 explanations and may seem daunting, but it is not. On the wiki page there are
 300 several examples including toolchain files. Go directly to `this section
 301 <http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_
 302 for a quick solution.
 303
 304 Also see the `LLVM-specific variables`_ section for variables used when
 305 cross-compiling.
 306
 307 Embedding LLVM in your project
 308 ==============================
 309
 310 The most difficult part of adding LLVM to the build of a project is to determine
 311 the set of LLVM libraries corresponding to the set of required LLVM
 312 features. What follows is an example of how to obtain this information:
 313
 314 .. code-block:: cmake
 315
 316   # A convenience variable:
 317   set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
 318
 319   # A bit of a sanity check:
 320   if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
 321   message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
 322   endif()
 323
 324   # We incorporate the CMake features provided by LLVM:
 325   set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
 326   include(LLVMConfig)
 327
 328   # Now set the header and library paths:
 329   include_directories( ${LLVM_INCLUDE_DIRS} )
 330   link_directories( ${LLVM_LIBRARY_DIRS} )
 331   add_definitions( ${LLVM_DEFINITIONS} )
 332
 333   # Let's suppose we want to build a JIT compiler with support for
 334   # binary code (no interpreter):
 335   llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
 336
 337   # Finally, we link the LLVM libraries to our executable:
 338   target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
 339
 340 This assumes that LLVM_ROOT points to an install of LLVM. The procedure works
 341 too for uninstalled builds although we need to take care to add an
 342 `include_directories` for the location of the headers on the LLVM source
 343 directory (if we are building out-of-source.)
 344
 345 Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is
 346 an equivalent variant of snippet shown above:
 347
 348 .. code-block:: cmake
 349
 350   find_package(LLVM)
 351
 352   if( NOT LLVM_FOUND )
 353     message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
 354   endif()
 355
 356   include_directories( ${LLVM_INCLUDE_DIRS} )
 357   link_directories( ${LLVM_LIBRARY_DIRS} )
 358
 359   llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
 360
 361   target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
 362
 363 Developing LLVM pass out of source
 364 ----------------------------------
 365
 366 It is possible to develop LLVM passes against installed LLVM.  An example of
 367 project layout provided below:
 368
 369 .. code-block:: bash
 370
 371   <project dir>/
 372       |
 373       CMakeLists.txt
 374       <pass name>/
 375           |
 376           CMakeLists.txt
 377           Pass.cpp
 378           ...
 379
 380 Contents of ``<project dir>/CMakeLists.txt``:
 381
 382 .. code-block:: cmake
 383
 384   find_package(LLVM)
 385
 386   # Define add_llvm_* macro's.
 387   include(AddLLVM)
 388
 389   add_definitions(${LLVM_DEFINITIONS})
 390   include_directories(${LLVM_INCLUDE_DIRS})
 391   link_directories(${LLVM_LIBRARY_DIRS})
 392
 393   add_subdirectory(<pass name>)
 394
 395 Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
 396
 397 .. code-block:: cmake
 398
 399   add_llvm_loadable_module(LLVMPassname
 400     Pass.cpp
 401     )
 402
 403 When you are done developing your pass, you may wish to integrate it
 404 into LLVM source tree. You can achieve it in two easy steps:
 405
 406 #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
 407
 408 #. Adding ``add_subdirectory(<pass name>)`` line into
 409    ``<LLVM root>/lib/Transform/CMakeLists.txt``.
 410
 411 Compiler/Platform specific topics
 412 =================================
 413
 414 Notes for specific compilers and/or platforms.
 415
 416 Microsoft Visual C++
 417 --------------------
 418
 419 **LLVM_COMPILER_JOBS**:STRING
 420   Specifies the maximum number of parallell compiler jobs to use per project
 421   when building with msbuild or Visual Studio. Only supported for Visual Studio
 422   2008 and Visual Studio 2010 CMake generators. 0 means use all
 423   processors. Default is 0.