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 9 2008" 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 Executing the test suite
 279 ========================
 280
 281 Testing is performed when the *check* target is built. For instance, if you are
 282 using makefiles, execute this command while on the top level of your build
 283 directory:
 284
 285 .. code-block:: console
 286
 287   $ make check
 288
 289 On Visual Studio, you may run tests to build the project "check".
 290
 291 Cross compiling
 292 ===============
 293
 294 See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for
 295 generic instructions on how to cross-compile with CMake. It goes into detailed
 296 explanations and may seem daunting, but it is not. On the wiki page there are
 297 several examples including toolchain files. Go directly to `this section
 298 <http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_
 299 for a quick solution.
 300
 301 Also see the `LLVM-specific variables`_ section for variables used when
 302 cross-compiling.
 303
 304 Embedding LLVM in your project
 305 ==============================
 306
 307 The most difficult part of adding LLVM to the build of a project is to determine
 308 the set of LLVM libraries corresponding to the set of required LLVM
 309 features. What follows is an example of how to obtain this information:
 310
 311 .. code-block:: cmake
 312
 313   # A convenience variable:
 314   set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
 315
 316   # A bit of a sanity check:
 317   if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
 318   message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
 319   endif()
 320
 321   # We incorporate the CMake features provided by LLVM:
 322   set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
 323   include(LLVMConfig)
 324
 325   # Now set the header and library paths:
 326   include_directories( ${LLVM_INCLUDE_DIRS} )
 327   link_directories( ${LLVM_LIBRARY_DIRS} )
 328   add_definitions( ${LLVM_DEFINITIONS} )
 329
 330   # Let's suppose we want to build a JIT compiler with support for
 331   # binary code (no interpreter):
 332   llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
 333
 334   # Finally, we link the LLVM libraries to our executable:
 335   target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
 336
 337 This assumes that LLVM_ROOT points to an install of LLVM. The procedure works
 338 too for uninstalled builds although we need to take care to add an
 339 `include_directories` for the location of the headers on the LLVM source
 340 directory (if we are building out-of-source.)
 341
 342 Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is
 343 an equivalent variant of snippet shown above:
 344
 345 .. code-block:: cmake
 346
 347   find_package(LLVM)
 348
 349   if( NOT LLVM_FOUND )
 350     message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
 351   endif()
 352
 353   include_directories( ${LLVM_INCLUDE_DIRS} )
 354   link_directories( ${LLVM_LIBRARY_DIRS} )
 355
 356   llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
 357
 358   target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
 359
 360 .. _cmake-out-of-source-pass:
 361
 362 Developing LLVM pass out of source
 363 ----------------------------------
 364
 365 It is possible to develop LLVM passes against installed LLVM.  An example of
 366 project layout provided below:
 367
 368 .. code-block:: none
 369
 370   <project dir>/
 371       |
 372       CMakeLists.txt
 373       <pass name>/
 374           |
 375           CMakeLists.txt
 376           Pass.cpp
 377           ...
 378
 379 Contents of ``<project dir>/CMakeLists.txt``:
 380
 381 .. code-block:: cmake
 382
 383   find_package(LLVM)
 384
 385   # Define add_llvm_* macro's.
 386   include(AddLLVM)
 387
 388   add_definitions(${LLVM_DEFINITIONS})
 389   include_directories(${LLVM_INCLUDE_DIRS})
 390   link_directories(${LLVM_LIBRARY_DIRS})
 391
 392   add_subdirectory(<pass name>)
 393
 394 Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
 395
 396 .. code-block:: cmake
 397
 398   add_llvm_loadable_module(LLVMPassname
 399     Pass.cpp
 400     )
 401
 402 When you are done developing your pass, you may wish to integrate it
 403 into LLVM source tree. You can achieve it in two easy steps:
 404
 405 #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
 406
 407 #. Adding ``add_subdirectory(<pass name>)`` line into
 408    ``<LLVM root>/lib/Transform/CMakeLists.txt``.
 409
 410 Compiler/Platform specific topics
 411 =================================
 412
 413 Notes for specific compilers and/or platforms.
 414
 415 Microsoft Visual C++
 416 --------------------
 417
 418 **LLVM_COMPILER_JOBS**:STRING
 419   Specifies the maximum number of parallell compiler jobs to use per project
 420   when building with msbuild or Visual Studio. Only supported for Visual Studio
 421   2008 and Visual Studio 2010 CMake generators. 0 means use all
 422   processors. Default is 0.