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