docs/CMake.rst

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