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 with `Basic CMake usage`_
  17 and then go back to the `Quick start`_ section 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.8 is the minimum required, but if you're using the Ninja
  30    backend, CMake v3.2 or newer is required to `get interactive output
  31    <http://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20141117/244797.html>`_
  32    when running :doc:`Lit <CommandGuide/lit>`.
  33
  34 #. Open a shell. Your development tools must be reachable from this shell
  35    through the PATH environment variable.
  36
  37 #. Create a build directory. Building LLVM in the source
  38    directory is not supported. cd to this directory:
  39
  40    .. code-block:: console
  41
  42      $ mkdir mybuilddir
  43      $ cd mybuilddir
  44
  45 #. Execute this command in the shell replacing `path/to/llvm/source/root` with
  46    the path to the root of your LLVM source tree:
  47
  48    .. code-block:: console
  49
  50      $ cmake path/to/llvm/source/root
  51
  52    CMake will detect your development environment, perform a series of tests, and
  53    generate the files required for building LLVM. CMake will use default values
  54    for all build parameters. See the `Options and variables`_ section for
  55    a list of build parameters that you can modify.
  56
  57    This can fail if CMake can't detect your toolset, or if it thinks that the
  58    environment is not sane enough. In this case, make sure that the toolset that
  59    you intend to use is the only one reachable from the shell, and that the shell
  60    itself is the correct one for your development environment. CMake will refuse
  61    to build MinGW makefiles if you have a POSIX shell reachable through the PATH
  62    environment variable, for instance. You can force CMake to use a given build
  63    tool; for instructions, see the `Usage`_ section, below.
  64
  65 #. After CMake has finished running, proceed to use IDE project files, or start
  66    the build from the build directory:
  67
  68    .. code-block:: console
  69
  70      $ cmake --build .
  71
  72    The ``--build`` option tells ``cmake`` to invoke the underlying build
  73    tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc.)
  74
  75    The underlying build tool can be invoked directly, of course, but
  76    the ``--build`` option is portable.
  77
  78 #. After LLVM has finished building, install it from the build directory:
  79
  80    .. code-block:: console
  81
  82      $ cmake --build . --target install
  83
  84    The ``--target`` option with ``install`` parameter in addition to
  85    the ``--build`` option tells ``cmake`` to build the ``install`` target.
  86
  87    It is possible to set a different install prefix at installation time
  88    by invoking the ``cmake_install.cmake`` script generated in the
  89    build directory:
  90
  91    .. code-block:: console
  92
  93      $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
  94
  95 .. _Basic CMake usage:
  96 .. _Usage:
  97
  98 Basic CMake usage
  99 =================
 100
 101 This section explains basic aspects of CMake
 102 which you may need in your day-to-day usage.
 103
 104 CMake comes with extensive documentation, in the form of html files, and as
 105 online help accessible via the ``cmake`` executable itself. Execute ``cmake
 106 --help`` for further help options.
 107
 108 CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,
 109 or Xcode). If not specified on the command line, CMake tries to guess which
 110 build tool to use, based on your environment. Once it has identified your
 111 build tool, CMake uses the corresponding *Generator* to create files for your
 112 build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can
 113 explicitly specify the generator with the command line option ``-G "Name of the
 114 generator"``. To see a list of the available generators on your system, execute
 115
 116 .. code-block:: console
 117
 118   $ cmake --help
 119
 120 This will list the generator names at the end of the help text.
 121
 122 Generators' names are case-sensitive, and may contain spaces. For this reason,
 123 you should enter them exactly as they are listed in the ``cmake --help``
 124 output, in quotes. For example, to generate project files specifically for
 125 Visual Studio 12, you can execute:
 126
 127 .. code-block:: console
 128
 129   $ cmake -G "Visual Studio 12" path/to/llvm/source/root
 130
 131 For a given development platform there can be more than one adequate
 132 generator. If you use Visual Studio, "NMake Makefiles" is a generator you can use
 133 for building with NMake. By default, CMake chooses the most specific generator
 134 supported by your development environment. If you want an alternative generator,
 135 you must tell this to CMake with the ``-G`` option.
 136
 137 .. todo::
 138
 139   Explain variables and cache. Move explanation here from #options section.
 140
 141 .. _Options and variables:
 142
 143 Options and variables
 144 =====================
 145
 146 Variables customize how the build will be generated. Options are boolean
 147 variables, with possible values ON/OFF. Options and variables are defined on the
 148 CMake command line like this:
 149
 150 .. code-block:: console
 151
 152   $ cmake -DVARIABLE=value path/to/llvm/source
 153
 154 You can set a variable after the initial CMake invocation to change its
 155 value. You can also undefine a variable:
 156
 157 .. code-block:: console
 158
 159   $ cmake -UVARIABLE path/to/llvm/source
 160
 161 Variables are stored in the CMake cache. This is a file named ``CMakeCache.txt``
 162 stored at the root of your build directory that is generated by ``cmake``.
 163 Editing it yourself is not recommended.
 164
 165 Variables are listed in the CMake cache and later in this document with
 166 the variable name and type separated by a colon. You can also specify the
 167 variable and type on the CMake command line:
 168
 169 .. code-block:: console
 170
 171   $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
 172
 173 Frequently-used CMake variables
 174 -------------------------------
 175
 176 Here are some of the CMake variables that are used often, along with a
 177 brief explanation and LLVM-specific notes. For full documentation, consult the
 178 CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
 179
 180 **CMAKE_BUILD_TYPE**:STRING
 181   Sets the build type for ``make``-based generators. Possible values are
 182   Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE such as
 183   Visual Studio, you should use the IDE settings to set the build type.
 184
 185 **CMAKE_INSTALL_PREFIX**:PATH
 186   Path where LLVM will be installed if "make install" is invoked or the
 187   "install" target is built.
 188
 189 **LLVM_LIBDIR_SUFFIX**:STRING
 190   Extra suffix to append to the directory where libraries are to be
 191   installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
 192   to install libraries to ``/usr/lib64``.
 193
 194 **CMAKE_C_FLAGS**:STRING
 195   Extra flags to use when compiling C source files.
 196
 197 **CMAKE_CXX_FLAGS**:STRING
 198   Extra flags to use when compiling C++ source files.
 199
 200 **BUILD_SHARED_LIBS**:BOOL
 201   Flag indicating if shared libraries will be built. Its default value is
 202   OFF. This option is only recommended for use by LLVM developers.
 203   On Windows, shared libraries may be used when building with MinGW, including
 204   mingw-w64, but not when building with the Microsoft toolchain.
 205
 206 .. _LLVM-specific variables:
 207
 208 LLVM-specific variables
 209 -----------------------
 210
 211 **LLVM_TARGETS_TO_BUILD**:STRING
 212   Semicolon-separated list of targets to build, or *all* for building all
 213   targets. Case-sensitive. Defaults to *all*. Example:
 214   ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
 215
 216 **LLVM_BUILD_TOOLS**:BOOL
 217   Build LLVM tools. Defaults to ON. Targets for building each tool are generated
 218   in any case. You can build a tool separately by invoking its target. For
 219   example, you can build *llvm-as* with a Makefile-based system by executing *make
 220   llvm-as* at the root of your build directory.
 221
 222 **LLVM_INCLUDE_TOOLS**:BOOL
 223   Generate build targets for the LLVM tools. Defaults to ON. You can use this
 224   option to disable the generation of build targets for the LLVM tools.
 225
 226 **LLVM_BUILD_EXAMPLES**:BOOL
 227   Build LLVM examples. Defaults to OFF. Targets for building each example are
 228   generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
 229   details.
 230
 231 **LLVM_INCLUDE_EXAMPLES**:BOOL
 232   Generate build targets for the LLVM examples. Defaults to ON. You can use this
 233   option to disable the generation of build targets for the LLVM examples.
 234
 235 **LLVM_BUILD_TESTS**:BOOL
 236   Build LLVM unit tests. Defaults to OFF. Targets for building each unit test
 237   are generated in any case. You can build a specific unit test using the
 238   targets defined under *unittests*, such as ADTTests, IRTests, SupportTests,
 239   etc. (Search for ``add_llvm_unittest`` in the subdirectories of *unittests*
 240   for a complete list of unit tests.) It is possible to build all unit tests
 241   with the target *UnitTests*.
 242
 243 **LLVM_INCLUDE_TESTS**:BOOL
 244   Generate build targets for the LLVM unit tests. Defaults to ON. You can use
 245   this option to disable the generation of build targets for the LLVM unit
 246   tests.
 247
 248 **LLVM_APPEND_VC_REV**:BOOL
 249   Append version control revision info (svn revision number or Git revision id)
 250   to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work
 251   cmake must be invoked before the build. Defaults to OFF.
 252
 253 **LLVM_ENABLE_THREADS**:BOOL
 254   Build with threads support, if available. Defaults to ON.
 255
 256 **LLVM_ENABLE_CXX1Y**:BOOL
 257   Build in C++1y mode, if available. Defaults to OFF.
 258
 259 **LLVM_ENABLE_ASSERTIONS**:BOOL
 260   Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
 261   is *Debug*.
 262
 263 **LLVM_ENABLE_EH**:BOOL
 264   Build LLVM with exception-handling support. This is necessary if you wish to
 265   link against LLVM libraries and make use of C++ exceptions in your own code
 266   that need to propagate through LLVM code. Defaults to OFF.
 267
 268 **LLVM_ENABLE_PIC**:BOOL
 269   Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
 270   this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
 271
 272 **LLVM_ENABLE_RTTI**:BOOL
 273   Build LLVM with run-time type information. Defaults to OFF.
 274
 275 **LLVM_ENABLE_WARNINGS**:BOOL
 276   Enable all compiler warnings. Defaults to ON.
 277
 278 **LLVM_ENABLE_PEDANTIC**:BOOL
 279   Enable pedantic mode. This disables compiler-specific extensions, if
 280   possible. Defaults to ON.
 281
 282 **LLVM_ENABLE_WERROR**:BOOL
 283   Stop and fail the build, if a compiler warning is triggered. Defaults to OFF.
 284
 285 **LLVM_ABI_BREAKING_CHECKS**:STRING
 286   Used to decide if LLVM should be built with ABI breaking checks or
 287   not.  Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
 288   `FORCE_OFF`.  `WITH_ASSERTS` turns on ABI breaking checks in an
 289   assertion enabled build.  `FORCE_ON` (`FORCE_OFF`) turns them on
 290   (off) irrespective of whether normal (`NDEBUG`-based) assertions are
 291   enabled or not.  A version of LLVM built with ABI breaking checks
 292   is not ABI compatible with a version built without it.
 293
 294 **LLVM_BUILD_32_BITS**:BOOL
 295   Build 32-bit executables and libraries on 64-bit systems. This option is
 296   available only on some 64-bit Unix systems. Defaults to OFF.
 297
 298 **LLVM_TARGET_ARCH**:STRING
 299   LLVM target to use for native code generation. This is required for JIT
 300   generation. It defaults to "host", meaning that it shall pick the architecture
 301   of the machine where LLVM is being built. If you are cross-compiling, set it
 302   to the target architecture name.
 303
 304 **LLVM_TABLEGEN**:STRING
 305   Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
 306   intended for cross-compiling: if the user sets this variable, no native
 307   TableGen will be created.
 308
 309 **LLVM_LIT_ARGS**:STRING
 310   Arguments given to lit.  ``make check`` and ``make clang-test`` are affected.
 311   By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
 312   others.
 313
 314 **LLVM_LIT_TOOLS_DIR**:PATH
 315   The path to GnuWin32 tools for tests. Valid on Windows host.  Defaults to
 316   the empty string, in which case lit will look for tools needed for tests
 317   (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in your
 318   %PATH%, then you can set this variable to the GnuWin32 directory so that
 319   lit can find tools needed for tests in that directory.
 320
 321 **LLVM_ENABLE_FFI**:BOOL
 322   Indicates whether the LLVM Interpreter will be linked with the Foreign Function
 323   Interface library (libffi) in order to enable calling external functions.
 324   If the library or its headers are installed in a custom
 325   location, you can also set the variables FFI_INCLUDE_DIR and
 326   FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found,
 327   respectively. Defaults to OFF.
 328
 329 **LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
 330   These variables specify the path to the source directory for the external
 331   LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
 332   source directory.  If the in-tree subdirectory for an external project
 333   exists (e.g., llvm/tools/clang for Clang), then the corresponding variable
 334   will not be used.  If the variable for an external project does not point
 335   to a valid path, then that project will not be built.
 336
 337 **LLVM_USE_OPROFILE**:BOOL
 338   Enable building OProfile JIT support. Defaults to OFF.
 339
 340 **LLVM_PROFDATA_FILE**:PATH
 341   Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
 342   can only be specified if you're building with clang.
 343
 344 **LLVM_USE_INTEL_JITEVENTS**:BOOL
 345   Enable building support for Intel JIT Events API. Defaults to OFF.
 346
 347 **LLVM_ENABLE_ZLIB**:BOOL
 348   Enable building with zlib to support compression/uncompression in LLVM tools.
 349   Defaults to ON.
 350
 351 **LLVM_USE_SANITIZER**:STRING
 352   Define the sanitizer used to build LLVM binaries and tests. Possible values
 353   are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
 354   and ``Address;Undefined``. Defaults to empty string.
 355
 356 **LLVM_PARALLEL_COMPILE_JOBS**:STRING
 357   Define the maximum number of concurrent compilation jobs.
 358
 359 **LLVM_PARALLEL_LINK_JOBS**:STRING
 360   Define the maximum number of concurrent link jobs.
 361
 362 **LLVM_BUILD_DOCS**:BOOL
 363   Enables all enabled documentation targets (i.e. Doxgyen and Sphinx targets) to
 364   be built as part of the normal build. If the ``install`` target is run then
 365   this also enables all built documentation targets to be installed. Defaults to
 366   OFF.
 367
 368 **LLVM_ENABLE_DOXYGEN**:BOOL
 369   Enables the generation of browsable HTML documentation using doxygen.
 370   Defaults to OFF.
 371
 372 **LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
 373   Enables the generation of a Qt Compressed Help file. Defaults to OFF.
 374   This affects the make target ``doxygen-llvm``. When enabled, apart from
 375   the normal HTML output generated by doxygen, this will produce a QCH file
 376   named ``org.llvm.qch``. You can then load this file into Qt Creator.
 377   This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
 378   otherwise this has no effect.
 379
 380 **LLVM_DOXYGEN_QCH_FILENAME**:STRING
 381   The filename of the Qt Compressed Help file that will be generated when
 382   ``-DLLVM_ENABLE_DOXYGEN=ON`` and
 383   ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
 384   ``org.llvm.qch``.
 385   This option is only useful in combination with
 386   ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
 387   otherwise it has no effect.
 388
 389 **LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
 390   Namespace under which the intermediate Qt Help Project file lives. See `Qt
 391   Help Project`_
 392   for more information. Defaults to "org.llvm". This option is only useful in
 393   combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
 394   it has no effect.
 395
 396 **LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
 397   See `Qt Help Project`_ for
 398   more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
 399   is a combination of the package name and version string. This filter can then
 400   be used in Qt Creator to select only documentation from LLVM when browsing
 401   through all the help files that you might have loaded. This option is only
 402   useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
 403   otherwise it has no effect.
 404
 405 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
 406
 407 **LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
 408   The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
 409   ``find_program()`` can find. This option is only useful in combination with
 410   ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
 411   effect.
 412
 413 **LLVM_DOXYGEN_SVG**:BOOL
 414   Uses .svg files instead of .png files for graphs in the Doxygen output.
 415   Defaults to OFF.
 416
 417 **LLVM_ENABLE_SPHINX**:BOOL
 418   If enabled CMake will search for the ``sphinx-build`` executable and will make
 419   the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
 420   Defaults to OFF.
 421
 422 **SPHINX_EXECUTABLE**:STRING
 423   The path to the ``sphinx-build`` executable detected by CMake.
 424
 425 **SPHINX_OUTPUT_HTML**:BOOL
 426   If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for
 427   building the documentation as html are added (but not built by default unless
 428   ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the
 429   source tree that uses sphinx (e.g.  ``docs-llvm-html``, ``docs-clang-html``
 430   and ``docs-lld-html``). Defaults to ON.
 431
 432 **SPHINX_OUTPUT_MAN**:BOOL
 433   If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
 434   the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
 435   is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
 436   to ON.
 437
 438 **SPHINX_WARNINGS_AS_ERRORS**:BOOL
 439   If enabled then sphinx documentation warnings will be treated as
 440   errors. Defaults to ON.
 441
 442 **LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL
 443   OS X Only: If enabled CMake will generate a target named
 444   'install-xcode-toolchain'. This target will create a directory at
 445   $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can
 446   be used to override the default system tools.
 447
 448 Executing the test suite
 449 ========================
 450
 451 Testing is performed when the *check-all* target is built. For instance, if you are
 452 using Makefiles, execute this command in the root of your build directory:
 453
 454 .. code-block:: console
 455
 456   $ make check-all
 457
 458 On Visual Studio, you may run tests by building the project "check-all".
 459 For more information about testing, see the :doc:`TestingGuide`.
 460
 461 Cross compiling
 462 ===============
 463
 464 See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for
 465 generic instructions on how to cross-compile with CMake. It goes into detailed
 466 explanations and may seem daunting, but it is not. On the wiki page there are
 467 several examples including toolchain files. Go directly to `this section
 468 <http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_
 469 for a quick solution.
 470
 471 Also see the `LLVM-specific variables`_ section for variables used when
 472 cross-compiling.
 473
 474 Embedding LLVM in your project
 475 ==============================
 476
 477 From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems export
 478 LLVM libraries as importable CMake targets. This means that clients of LLVM can
 479 now reliably use CMake to develop their own LLVM-based projects against an
 480 installed version of LLVM regardless of how it was built.
 481
 482 Here is a simple example of a CMakeLists.txt file that imports the LLVM libraries
 483 and uses them to build a simple application ``simple-tool``.
 484
 485 .. code-block:: cmake
 486
 487   cmake_minimum_required(VERSION 2.8.8)
 488   project(SimpleProject)
 489
 490   find_package(LLVM REQUIRED CONFIG)
 491
 492   message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
 493   message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
 494
 495   # Set your project compile flags.
 496   # E.g. if using the C++ header files
 497   # you will need to enable C++11 support
 498   # for your compiler.
 499
 500   include_directories(${LLVM_INCLUDE_DIRS})
 501   add_definitions(${LLVM_DEFINITIONS})
 502
 503   # Now build our tools
 504   add_executable(simple-tool tool.cpp)
 505
 506   # Find the libraries that correspond to the LLVM components
 507   # that we wish to use
 508   llvm_map_components_to_libnames(llvm_libs support core irreader)
 509
 510   # Link against LLVM libraries
 511   target_link_libraries(simple-tool ${llvm_libs})
 512
 513 The ``find_package(...)`` directive when used in CONFIG mode (as in the above
 514 example) will look for the ``LLVMConfig.cmake`` file in various locations (see
 515 cmake manual for details).  It creates a ``LLVM_DIR`` cache entry to save the
 516 directory where ``LLVMConfig.cmake`` is found or allows the user to specify the
 517 directory (e.g. by passing ``-DLLVM_DIR=/usr/share/llvm/cmake`` to
 518 the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
 519
 520 This file is available in two different locations.
 521
 522 * ``<INSTALL_PREFIX>/share/llvm/cmake/LLVMConfig.cmake`` where
 523   ``<INSTALL_PREFIX>`` is the install prefix of an installed version of LLVM.
 524   On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``.
 525
 526 * ``<LLVM_BUILD_ROOT>/share/llvm/cmake/LLVMConfig.cmake`` where
 527   ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this is only
 528   available when building LLVM with CMake.**
 529
 530 If LLVM is installed in your operating system's normal installation prefix (e.g.
 531 on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
 532 automatically find LLVM if it is installed correctly. If LLVM is not installed
 533 or you wish to build directly against the LLVM build tree you can use
 534 ``LLVM_DIR`` as previously mentioned.
 535
 536 The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
 537 include
 538
 539 ``LLVM_CMAKE_DIR``
 540   The path to the LLVM CMake directory (i.e. the directory containing
 541   LLVMConfig.cmake).
 542
 543 ``LLVM_DEFINITIONS``
 544   A list of preprocessor defines that should be used when building against LLVM.
 545
 546 ``LLVM_ENABLE_ASSERTIONS``
 547   This is set to ON if LLVM was built with assertions, otherwise OFF.
 548
 549 ``LLVM_ENABLE_EH``
 550   This is set to ON if LLVM was built with exception handling (EH) enabled,
 551   otherwise OFF.
 552
 553 ``LLVM_ENABLE_RTTI``
 554   This is set to ON if LLVM was built with run time type information (RTTI),
 555   otherwise OFF.
 556
 557 ``LLVM_INCLUDE_DIRS``
 558   A list of include paths to directories containing LLVM header files.
 559
 560 ``LLVM_PACKAGE_VERSION``
 561   The LLVM version. This string can be used with CMake conditionals, e.g., ``if
 562   (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
 563
 564 ``LLVM_TOOLS_BINARY_DIR``
 565   The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
 566
 567 Notice that in the above example we link ``simple-tool`` against several LLVM
 568 libraries. The list of libraries is determined by using the
 569 ``llvm_map_components_to_libnames()`` CMake function. For a list of available
 570 components look at the output of running ``llvm-config --components``.
 571
 572 Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
 573 used instead of ``llvm_map_components_to_libnames()``. This is now deprecated
 574 and will be removed in a future version of LLVM.
 575
 576 .. _cmake-out-of-source-pass:
 577
 578 Developing LLVM passes out of source
 579 ------------------------------------
 580
 581 It is possible to develop LLVM passes out of LLVM's source tree (i.e. against an
 582 installed or built LLVM). An example of a project layout is provided below.
 583
 584 .. code-block:: none
 585
 586   <project dir>/
 587       |
 588       CMakeLists.txt
 589       <pass name>/
 590           |
 591           CMakeLists.txt
 592           Pass.cpp
 593           ...
 594
 595 Contents of ``<project dir>/CMakeLists.txt``:
 596
 597 .. code-block:: cmake
 598
 599   find_package(LLVM REQUIRED CONFIG)
 600
 601   add_definitions(${LLVM_DEFINITIONS})
 602   include_directories(${LLVM_INCLUDE_DIRS})
 603
 604   add_subdirectory(<pass name>)
 605
 606 Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
 607
 608 .. code-block:: cmake
 609
 610   add_library(LLVMPassname MODULE Pass.cpp)
 611
 612 Note if you intend for this pass to be merged into the LLVM source tree at some
 613 point in the future it might make more sense to use LLVM's internal
 614 ``add_llvm_loadable_module`` function instead by...
 615
 616
 617 Adding the following to ``<project dir>/CMakeLists.txt`` (after
 618 ``find_package(LLVM ...)``)
 619
 620 .. code-block:: cmake
 621
 622   list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
 623   include(AddLLVM)
 624
 625 And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to
 626
 627 .. code-block:: cmake
 628
 629   add_llvm_loadable_module(LLVMPassname
 630     Pass.cpp
 631     )
 632
 633 When you are done developing your pass, you may wish to integrate it
 634 into the LLVM source tree. You can achieve it in two easy steps:
 635
 636 #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
 637
 638 #. Adding ``add_subdirectory(<pass name>)`` line into
 639    ``<LLVM root>/lib/Transform/CMakeLists.txt``.
 640
 641 Compiler/Platform-specific topics
 642 =================================
 643
 644 Notes for specific compilers and/or platforms.
 645
 646 Microsoft Visual C++
 647 --------------------
 648
 649 **LLVM_COMPILER_JOBS**:STRING
 650   Specifies the maximum number of parallel compiler jobs to use per project
 651   when building with msbuild or Visual Studio. Only supported for the Visual
 652   Studio 2010 CMake generator. 0 means use all processors. Default is 0.