1214 lines · plain
1========================2Building LLVM with CMake3========================4 5.. contents::6 :local:7 8Introduction9============10 11`CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake12does not build the project; it generates the files needed by your build tool13(GNU make, Visual Studio, etc.) for building LLVM.14 15If **you are a new contributor**, please start with the :doc:`GettingStarted`16page. This page is geared for existing contributors moving from the17legacy configure/make system.18 19If you are really anxious about getting a functional LLVM build, go to the20`Quick start`_ section. If you are a CMake novice, start with `Basic CMake usage`_21and then go back to the `Quick start`_ section once you know what you are doing. The22`Options and variables`_ section is a reference for customizing your build. If23you already have experience with CMake, this is the recommended starting point.24 25This page is geared towards users of the LLVM CMake build. If you're looking for26information about modifying the LLVM CMake build system, you may want to see the27:doc:`CMakePrimer` page. It has a basic overview of the CMake language.28 29.. _Quick start:30 31Quick start32===========33 34We use here the command-line, non-interactive CMake interface.35 36#. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install37 CMake. Version 3.20.0 is the minimum required.38 39#. Open a shell. Your development tools must be reachable from this shell40 through the ``PATH`` environment variable.41 42#. Create a build directory. Building LLVM in the source43 directory is not supported. ``cd`` to this directory:44 45 .. code-block:: console46 47 $ mkdir mybuilddir48 $ cd mybuilddir49 50#. Execute this command in the shell replacing `path/to/llvm/source/root` with51 the path to the root of your LLVM source tree:52 53 .. code-block:: console54 55 $ cmake path/to/llvm/source/root56 57 CMake will detect your development environment, perform a series of tests, and58 generate the files required for building LLVM. CMake will use default values59 for all build parameters. See the `Options and variables`_ section for60 a list of build parameters that you can modify.61 62 This can fail if CMake can't detect your toolset, or if it thinks that the63 environment is not sane enough. In this case, make sure that the toolset that64 you intend to use is the only one reachable from the shell, and that the shell65 itself is the correct one for your development environment. CMake will refuse66 to build MinGW makefiles if you have a POSIX shell reachable through the PATH67 environment variable, for instance. You can force CMake to use a given build68 tool; for instructions, see the `Usage`_ section, below. You may69 also wish to control which targets LLVM enables, or which LLVM70 components are built; see the `Frequently Used LLVM-related71 variables`_ below.72 73#. After CMake has finished running, use IDE project files, or start74 the build from the build directory:75 76 .. code-block:: console77 78 $ cmake --build .79 80 The ``--build`` option tells ``cmake`` to invoke the underlying build81 tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc.)82 83 The underlying build tool can be invoked directly, of course, but84 the ``--build`` option is portable.85 86#. After LLVM has finished building, install it from the build directory:87 88 .. code-block:: console89 90 $ cmake --build . --target install91 92 The ``--target`` option with ``install`` parameter in addition to93 the ``--build`` option tells ``cmake`` to build the ``install`` target.94 95 It is possible to set a different install prefix at installation time96 by invoking the ``cmake_install.cmake`` script generated in the97 build directory:98 99 .. code-block:: console100 101 $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake102 103.. _Basic CMake usage:104.. _Usage:105 106Basic CMake usage107=================108 109This section explains basic aspects of CMake for daily use.110 111CMake comes with extensive documentation, in the form of HTML files, and as112online help accessible via the ``cmake`` executable itself. Execute ``cmake113--help`` for further help options.114 115CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,116or Xcode). If not specified on the command line, CMake tries to guess which117build tool to use based on your environment. Once it has identified your118build tool, CMake uses the corresponding *Generator* to create files for your119build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can120explicitly specify the generator with the command line option ``-G "Name of the121generator"``. To see a list of the available generators on your system, execute:122 123.. code-block:: console124 125 $ cmake --help126 127This will list the generator names at the end of the help text.128 129Generators' names are case-sensitive and may contain spaces. For this reason,130you should enter them exactly as they are listed in the ``cmake --help``131output, in quotes. For example, to generate project files specifically for132Visual Studio 12, you can execute:133 134.. code-block:: console135 136 $ cmake -G "Visual Studio 12" path/to/llvm/source/root137 138A given development platform can have more than one adequate139generator. If you use Visual Studio, "NMake Makefiles" is a generator you can use140for building with NMake. By default, CMake chooses the most specific generator141supported by your development environment. If you want an alternative generator,142you must specify this to CMake with the ``-G`` option.143 144.. todo::145 146 Explain variables and cache. Move explanation here from #options section.147 148.. _Options and variables:149 150Options and variables151=====================152 153Variables customize how the build will be generated. Options are boolean154variables, with possible values ON/OFF. Options and variables are defined on the155CMake command line like this:156 157.. code-block:: console158 159 $ cmake -DVARIABLE=value path/to/llvm/source160 161You can set a variable after the initial CMake invocation to change its162value. You can also undefine a variable:163 164.. code-block:: console165 166 $ cmake -UVARIABLE path/to/llvm/source167 168Variables are stored in the CMake cache. This is a file named ``CMakeCache.txt``169stored at the root of your build directory that is generated by ``cmake``.170Editing it yourself is not recommended.171 172Variables are listed in the CMake cache and later in this document with173the variable name and type separated by a colon. You can also specify the174variable and type on the CMake command line:175 176.. code-block:: console177 178 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source179 180.. _cmake_frequently_used_variables:181 182Frequently-used CMake variables183-------------------------------184 185Here are some of the CMake variables that are used often, along with a186brief explanation. For full documentation, consult the CMake manual,187or execute ``cmake --help-variable VARIABLE_NAME``. See `Frequently188Used LLVM-related Variables`_ below for information about commonly189used variables that control features of LLVM and enabled subprojects.190 191.. _cmake_build_type:192 193**CMAKE_BUILD_TYPE**:STRING194 This configures the optimization level for ``make`` or ``ninja`` builds.195 196 Possible values:197 198 =========================== ============= ========== ========== ==========================199 Build Type Optimizations Debug Info Assertions Best suited for200 =========================== ============= ========== ========== ==========================201 **Release** For Speed No No Users of LLVM and Clang202 **Debug** None Yes Yes Developers of LLVM203 **RelWithDebInfo** For Speed Yes No Users that also need Debug204 **MinSizeRel** For Size No No When disk space matters205 =========================== ============= ========== ========== ==========================206 207 * Optimizations make LLVM/Clang run faster but can be an impediment for208 step-by-step debugging.209 * Builds with debug information can use a lot of RAM and disk space and are210 usually slower to run. You can improve RAM usage by using ``lld``, see211 the :ref:`LLVM_USE_LINKER <llvm_use_linker>` option.212 * Assertions are internal checks to help you find bugs. They typically slow213 down LLVM and Clang when enabled but can be useful during development.214 You can manually set :ref:`LLVM_ENABLE_ASSERTIONS <llvm_enable_assertions>`215 to override the default from `CMAKE_BUILD_TYPE`.216 217 If you are using an IDE such as Visual Studio or Xcode, use218 the IDE settings to set the build type.219 220 Note: on Windows (building with MSVC or clang-cl), CMake's **RelWithDebInfo**221 setting does not enable the same optimizations as **Release**. Using the222 **Release** build type with :ref:`LLVM_ENABLE_PDB <llvm_enable_pdb>` set223 may be a better option.224 225**CMAKE_INSTALL_PREFIX**:PATH226 Path where LLVM will be installed when the "install" target is built.227 228**CMAKE_{C,CXX}_FLAGS**:STRING229 Extra flags to use when compiling C and C++ source files respectively.230 231**CMAKE_{C,CXX}_COMPILER**:STRING232 Specify the C and C++ compilers to use. If you have multiple233 compilers installed, CMake might not default to the one you wish to234 use.235 236.. _Frequently Used LLVM-related variables:237 238Frequently Used LLVM-related variables239--------------------------------------240 241The default configuration may not match your requirements. Here are242LLVM variables that are frequently used to control that. The full243description is in `LLVM-related variables`_ below.244 245**LLVM_ENABLE_PROJECTS**:STRING246 Control which projects are enabled. For example, you may want to work on clang247 or lldb by specifying ``-DLLVM_ENABLE_PROJECTS="clang;lldb"``.248 249**LLVM_ENABLE_RUNTIMES**:STRING250 Control which runtimes are enabled. For example, you may want to work on251 libc++ or libc++abi by specifying ``-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.252 253**LLVM_LIBDIR_SUFFIX**:STRING254 Extra suffix to append to the directory where libraries are to be255 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``256 to install libraries to ``/usr/lib64``.257 258**LLVM_PARALLEL_{COMPILE,LINK}_JOBS**:STRING259 Building the llvm toolchain can use a lot of resources, particularly260 during linking. These options, when you use the Ninja generator, allow you261 to restrict the parallelism. For example, to avoid OOMs or going262 into swap, permit only one link job per 15 GB of RAM available on a263 32 GB machine, specify ``-G Ninja -DLLVM_PARALLEL_LINK_JOBS=2``.264 265**LLVM_TARGETS_TO_BUILD**:STRING266 Control which targets are enabled. For example, you may only need to enable267 your native target with, for example, ``-DLLVM_TARGETS_TO_BUILD=X86``.268 269.. _llvm_use_linker:270 271**LLVM_USE_LINKER**:STRING272 Override the system's default linker. For instance, use ``lld`` with273 ``-DLLVM_USE_LINKER=lld``.274 275Rarely-used CMake variables276---------------------------277 278Here are some of the CMake variables that are rarely used, along with a brief279explanation and LLVM-related notes. For full documentation, consult the CMake280manual, or execute ``cmake --help-variable VARIABLE_NAME``.281 282**CMAKE_CXX_STANDARD**:STRING283 Sets the C++ standard to conform to when building LLVM.284 LLVM requires C++17 or higher. This defaults to 17.285 286**CMAKE_INSTALL_BINDIR**:PATH287 The path to install executables, relative to the *CMAKE_INSTALL_PREFIX*.288 Defaults to "bin".289 290**CMAKE_INSTALL_DOCDIR**:PATH291 The path to install documentation, relative to the *CMAKE_INSTALL_PREFIX*.292 Defaults to "share/doc".293 294**CMAKE_INSTALL_INCLUDEDIR**:PATH295 The path to install header files, relative to the *CMAKE_INSTALL_PREFIX*.296 Defaults to "include".297 298**CMAKE_INSTALL_MANDIR**:PATH299 The path to install manpage files, relative to the *CMAKE_INSTALL_PREFIX*.300 Defaults to "share/man".301 302.. _LLVM-related variables:303 304LLVM-related variables305-----------------------306 307These variables provide fine control over the build of LLVM and308its enabled sub-projects. Nearly all of these variable names begin with309``LLVM_``.310 311.. _LLVM-related variables BUILD_SHARED_LIBS:312 313**BUILD_SHARED_LIBS**:BOOL314 Flag indicating if each LLVM component (e.g. Support) is built as a shared315 library (ON) or as a static library (OFF). Its default value is OFF. On316 Windows, shared libraries may be used when building with MinGW, including317 mingw-w64, but not when building with the Microsoft toolchain.318 319 .. note:: ``BUILD_SHARED_LIBS`` is only recommended for use by LLVM developers.320 If you want to build LLVM as a shared library, you should use the321 ``LLVM_BUILD_LLVM_DYLIB`` option.322 323**LLVM_ABI_BREAKING_CHECKS**:STRING324 Used to decide if LLVM should be built with ABI breaking checks or325 not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and326 `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an327 assertion-enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on328 (off) irrespective of whether normal (`NDEBUG`-based) assertions are329 enabled or not. A version of LLVM built with ABI breaking checks330 is not ABI compatible with a version built without it.331 332**LLVM_ADDITIONAL_BUILD_TYPES**:LIST333 Adding a semicolon-separated list of additional build types to this flag334 allows for them to be specified as values in ``CMAKE_BUILD_TYPE`` without335 encountering a fatal error during the configuration process.336 337**LLVM_APPEND_VC_REV**:BOOL338 Embed version control revision info (Git revision id).339 The version info is provided by the ``LLVM_REVISION`` macro in340 ``llvm/include/llvm/Support/VCSRevision.h``. Developers using git who don't341 need revision info can disable this option to avoid re-linking most binaries342 after a branch switch. Defaults to ON.343 344**LLVM_FORCE_VC_REPOSITORY**:STRING345 Set the git repository to include in version info rather than calling git to346 determine it.347 348**LLVM_FORCE_VC_REVISION**:STRING349 Force a specific Git revision id rather than calling git to determine it.350 This is useful in environments where git is not available or non-functional351 but the VC revision is available through other means.352 353**LLVM_BUILD_32_BITS**:BOOL354 Build 32-bit executables and libraries on 64-bit systems. This option is355 available only on some 64-bit Unix systems. Defaults to OFF.356 357**LLVM_BUILD_BENCHMARKS**:BOOL358 Adds benchmarks to the list of default targets. Defaults to OFF.359 360**LLVM_BUILD_DOCS**:BOOL361 Adds all *enabled* documentation targets (i.e., Doxygen and Sphinx targets) as362 dependencies of the default build targets. This results in all of the (enabled)363 documentation targets being built as part of a normal build. If the ``install``364 target is run, then this also enables all built documentation targets to be365 installed. Defaults to OFF. To enable a particular documentation target, see366 ``LLVM_ENABLE_SPHINX`` and ``LLVM_ENABLE_DOXYGEN``.367 368**LLVM_BUILD_EXAMPLES**:BOOL369 Build LLVM examples. Defaults to OFF. Targets for building each example are370 generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more371 details.372 373**LLVM_BUILD_INSTRUMENTED_COVERAGE**:BOOL374 If enabled, `source-based code coverage375 <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_ instrumentation376 is enabled while building llvm. If CMake can locate the code coverage377 scripts and the llvm-cov and llvm-profdata tools that pair with your compiler,378 the build will also generate the `generate-coverage-report` target to generate379 the code coverage report for LLVM, and the `clear-profile-data` utility target380 to delete captured profile data. See documentation for381 *LLVM_CODE_COVERAGE_TARGETS* and *LLVM_COVERAGE_SOURCE_DIRS* for more382 information on configuring code coverage reports.383 384**LLVM_BUILD_LLVM_DYLIB**:BOOL385 If enabled, the target for building the libLLVM shared library is added.386 This library contains all of LLVM's components in a single shared library.387 Defaults to OFF. This cannot be used in conjunction with ``BUILD_SHARED_LIBS``.388 Tools will only be linked to the libLLVM shared library if ``LLVM_LINK_LLVM_DYLIB``389 is also ON.390 The components in the library can be customised by setting ``LLVM_DYLIB_COMPONENTS``391 to a list of the desired components.392 This option is not available on Windows.393 394**LLVM_BUILD_TESTS**:BOOL395 Include LLVM unit tests in the 'all' build target. Defaults to OFF. Targets396 for building each unit test are generated in any case. You can build a397 specific unit test using the targets defined under *unittests*, such as398 ADTTests, IRTests, SupportTests, etc. (Search for ``add_llvm_unittest`` in399 the subdirectories of *unittests* for a complete list of unit tests.) It is400 possible to build all unit tests with the target *UnitTests*.401 402**LLVM_BUILD_TOOLS**:BOOL403 Build LLVM tools. Defaults to ON. Targets for building each tool are generated404 in any case. You can build a tool separately by invoking its target. For405 example, you can build *llvm-as* with a Makefile-based system by executing *make406 llvm-as* at the root of your build directory.407 408**LLVM_CCACHE_BUILD**:BOOL409 If enabled and the ``ccache`` program is available, then LLVM will be410 built using ``ccache`` to speed up rebuilds of LLVM and its components.411 Defaults to OFF. The size and location of the cache maintained412 by ``ccache`` can be adjusted via the ``LLVM_CCACHE_MAXSIZE`` and ``LLVM_CCACHE_DIR``413 options, which are passed to the ``CCACHE_MAXSIZE`` and ``CCACHE_DIR`` environment414 variables, respectively.415 416**LLVM_CODE_COVERAGE_TARGETS**:STRING417 If set to a semicolon-separated list of targets, those targets will be used418 to drive the code coverage reports. If unset, the target list will be419 constructed using the LLVM build's CMake export list.420 421**LLVM_COVERAGE_SOURCE_DIRS**:STRING422 If set to a semicolon-separated list of directories, the coverage reports423 will limit code coverage summaries to just the listed directories. If unset,424 coverage reports will include all sources identified by the tooling.425 426**LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL427 macOS only: If enabled, CMake will generate a target named428 'install-xcode-toolchain'. This target will create a directory at429 ``$CMAKE_INSTALL_PREFIX/Toolchains`` containing an xctoolchain directory which can430 be used to override the default system tools.431 432**LLVM_DEFAULT_TARGET_TRIPLE**:STRING433 LLVM target to use for code generation when no target is explicitly specified.434 It defaults to "host", meaning that it shall pick the architecture435 of the machine where LLVM is being built. If you are building a cross-compiler,436 set it to the target triple of your desired architecture.437 438**LLVM_DOXYGEN_QCH_FILENAME**:STRING439 The filename of the Qt Compressed Help file that will be generated when440 ``-DLLVM_ENABLE_DOXYGEN=ON`` and441 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to442 ``org.llvm.qch``.443 This option is only useful in combination with444 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;445 otherwise it has no effect.446 447**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING448 The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's449 ``find_program()`` can find. This option is only useful in combination with450 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no451 effect.452 453**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING454 See `Qt Help Project`_ for455 more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which456 is a combination of the package name and version string. This filter can then457 be used in Qt Creator to select only documentation from LLVM when browsing458 through all the help files that you might have loaded. This option is only459 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;460 otherwise it has no effect.461 462.. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters463 464**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING465 Namespace under which the intermediate Qt Help Project file lives. See `Qt466 Help Project`_467 for more information. Defaults to "org.llvm". This option is only useful in468 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise469 it has no effect.470 471 472.. _llvm_enable_assertions:473 474**LLVM_ENABLE_ASSERTIONS**:BOOL475 Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``476 is *Debug*.477 478**LLVM_ENABLE_BINDINGS**:BOOL479 If disabled, do not try to build the OCaml bindings.480 481**LLVM_ENABLE_DEBUGLOC_COVERAGE_TRACKING**:STRING482 Enhances Debugify's ability to detect line number errors by storing extra483 information inside Instructions, removing false positives from Debugify's484 results at the cost of performance. Allowed values are `DISABLED` (default),485 `COVERAGE`, and `COVERAGE_AND_ORIGIN`. `COVERAGE` tracks whether and why a486 line number was intentionally dropped or not generated for an instruction,487 allowing Debugify to avoid reporting these as errors; this comes with a small488 performance cost of ~0.1%. `COVERAGE_AND_ORIGIN` additionally stores a489 stacktrace of the point where each DebugLoc is unintentionally dropped,490 allowing for much easier bug triaging at the cost of a ~10x performance491 slowdown. `COVERAGE` and `COVERAGE_AND_ORIGIN` are ABI-breaking options.492 493**LLVM_ENABLE_DIA_SDK**:BOOL494 Enable building with MSVC DIA SDK for PDB debugging support. Available495 only with MSVC. Defaults to ON.496 497**LLVM_ENABLE_DOXYGEN**:BOOL498 Enables the generation of browsable HTML documentation using doxygen.499 Defaults to OFF.500 501**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL502 Enables the generation of a Qt Compressed Help file. Defaults to OFF.503 This affects the make target ``doxygen-llvm``. When enabled, apart from504 the normal HTML output generated by doxygen, this will produce a QCH file505 named ``org.llvm.qch``. You can then load this file into Qt Creator.506 This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;507 otherwise this has no effect.508 509**LLVM_ENABLE_EH**:BOOL510 Build LLVM with exception-handling support. This is necessary if you wish to511 link against LLVM libraries and make use of C++ exceptions in your own code512 that need to propagate through LLVM code. Defaults to OFF.513 514**LLVM_ENABLE_EXPENSIVE_CHECKS**:BOOL515 Enable additional time/memory expensive checking. Defaults to OFF.516 517**LLVM_ENABLE_FFI**:BOOL518 Indicates whether the LLVM Interpreter will be linked with the Foreign Function519 Interface library (libffi) in order to enable calling external functions.520 If the library or its headers are installed in a custom521 location, you can also set the variables ``FFI_INCLUDE_DIR`` and522 ``FFI_LIBRARY_DIR`` to the directories where ``ffi.h`` and ``libffi.so`` can be found,523 respectively. Defaults to OFF.524 525**LLVM_ENABLE_HTTPLIB**:BOOL526 Enables the optional cpp-httplib dependency which is used by llvm-debuginfod527 to serve debug info over HTTP. `cpp-httplib <https://github.com/yhirose/cpp-httplib>`_528 must be installed, or `httplib_ROOT` must be set. Defaults to OFF.529 530**LLVM_ENABLE_IDE**:BOOL531 Tell the build system that an IDE is being used. This in turn disables the532 creation of certain convenience build system targets, such as the various533 ``install-*`` and ``check-*`` targets, since IDEs don't always deal well with534 a large number of targets. This is usually autodetected, but it can be535 configured manually to explicitly control the generation of those targets.536 537**LLVM_ENABLE_LIBCXX**:BOOL538 If the host compiler and linker support the stdlib flag, ``-stdlib=libc++`` is539 passed to invocations of both so that the project is built using libc++540 instead of stdlibc++. Defaults to OFF.541 542**LLVM_ENABLE_LIBEDIT**:BOOL543 Controls whether to enable libedit support for command-line editing and history544 in LLVM tools. When ``ON``, forces libedit support to be enabled and will cause a545 CMake configuration error if libedit cannot be found. When ``OFF``, disables546 libedit support entirely. If not specified, LLVM will auto-detect libedit547 availability. Defaults to auto-detection.548 549**LLVM_ENABLE_LIBPFM**:BOOL550 Enable building with libpfm to support hardware counter measurements in LLVM551 tools.552 Defaults to ON.553 554**LLVM_ENABLE_LLD**:BOOL555 This option is equivalent to `-DLLVM_USE_LINKER=lld`, except during a 2-stage556 build where a dependency is added from the first stage to the second ensuring557 that lld is built before stage2 begins.558 559**LLVM_ENABLE_LLVM_LIBC**: BOOL560 If the LLVM libc overlay is installed in a location where the host linker561 can access it, all built executables will be linked against the LLVM libc562 overlay before linking against the system libc. Defaults to OFF.563 564**LLVM_ENABLE_LTO**:STRING565 Add ``-flto`` or ``-flto=`` flags to the compile and link command566 lines, enabling link-time optimization. Possible values are ``Off``,567 ``On``, ``Thin`` and ``Full``. Defaults to OFF.568 569**LLVM_ENABLE_MODULES**:BOOL570 Compile with `Clang Header Modules571 <https://clang.llvm.org/docs/Modules.html>`_.572 573.. _llvm_enable_pdb:574 575**LLVM_ENABLE_PDB**:BOOL576 For Windows builds using MSVC or clang-cl, generate PDB files when577 :ref:`CMAKE_BUILD_TYPE <cmake_build_type>` is set to Release.578 579**LLVM_ENABLE_PEDANTIC**:BOOL580 Enable pedantic mode. This disables compiler-specific extensions, if581 possible. Defaults to ON.582 583**LLVM_ENABLE_PIC**:BOOL584 Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports585 this flag. Some systems, like Windows, do not need this flag. Defaults to ON.586 587**LLVM_ENABLE_PROJECTS**:STRING588 Semicolon-separated list of projects to build, or *all* for building all589 (clang, lldb, lld, polly, etc) projects. This flag assumes that projects590 are checked out side-by-side and not nested, i.e. clang needs to be in591 parallel to llvm instead of nested in ``llvm/tools``. This feature allows592 having one build for only LLVM and another for clang+llvm using the same593 source checkout.594 595 The full list is:596 597 ``bolt;clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;lld;lldb;mlir;openmp;polly``598 599 .. note::600 Some projects listed here can also go in ``LLVM_ENABLE_RUNTIMES``. They601 should only appear in one of the two lists. If a project is a valid possibility602 for both, prefer putting it in ``LLVM_ENABLE_RUNTIMES``.603 604**LLVM_ENABLE_RTTI**:BOOL605 Build LLVM with run-time type information. Defaults to OFF.606 607**LLVM_ENABLE_RUNTIMES**:STRING608 Build libc++, libc++abi, libunwind or compiler-rt using the just-built compiler.609 This is the correct way to build runtimes when putting together a toolchain.610 It will build the builtins separately from the other runtimes to preserve611 correct dependency ordering. If you want to build the runtimes using a system612 compiler, see the `libc++ documentation <https://libcxx.llvm.org/VendorDocumentation.html>`_.613 614 .. note::615 The list should not have duplicates with ``LLVM_ENABLE_PROJECTS``.616 617 To list all possible runtimes, include an invalid name. For example618 ``-DLLVM_ENABLE_RUNTIMES=notaruntime``. The resulting CMake error will list619 the possible runtime names.620 621 To enable all of the runtimes, use:622 623 ``LLVM_ENABLE_RUNTIMES=all``624 625**LLVM_ENABLE_SPHINX**:BOOL626 If specified, CMake will search for the ``sphinx-build`` executable and will make627 the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.628 Defaults to OFF.629 630**LLVM_ENABLE_THREADS**:BOOL631 Build with threads support, if available. Defaults to ON.632 633**LLVM_ENABLE_UNWIND_TABLES**:BOOL634 Enable unwind tables in the binary. Disabling unwind tables can reduce the635 size of the libraries. Defaults to ON.636 637**LLVM_ENABLE_WARNINGS**:BOOL638 Enable all compiler warnings. Defaults to ON.639 640**LLVM_ENABLE_WERROR**:BOOL641 Stop and fail the build, if a compiler warning is triggered. Defaults to OFF.642 643**LLVM_ENABLE_Z3_SOLVER**:BOOL644 If enabled, the Z3 constraint solver is activated for the Clang static analyzer.645 A recent version of the z3 library must be available on the system.646 647**LLVM_ENABLE_ZLIB**:STRING648 Used to decide if LLVM tools should support compression/decompression with649 zlib. Allowed values are ``OFF``, ``ON`` (default, enable if zlib is found),650 and ``FORCE_ON`` (error if zlib is not found).651 652**LLVM_ENABLE_ZSTD**:STRING653 Used to decide if LLVM tools should support compression/decompression with654 zstd. Allowed values are ``OFF``, ``ON`` (default, enable if zstd is found),655 and ``FORCE_ON`` (error if zstd is not found).656 657**LLVM_EXPERIMENTAL_TARGETS_TO_BUILD**:STRING658 Semicolon-separated list of experimental targets to build and linked into659 llvm. This will build the experimental target without needing it to add to the660 list of all the targets available in the LLVM's main ``CMakeLists.txt``.661 662**LLVM_EXTERNAL_PROJECTS**:STRING663 Semicolon-separated list of additional external projects to build as part of664 llvm. For each project, ``LLVM_EXTERNAL_<NAME>_SOURCE_DIR`` has to be specified665 with the path for the source code of the project. Example:666 ``-DLLVM_EXTERNAL_PROJECTS="Foo;Bar"667 -DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo668 -DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``.669 670**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH671 These variables specify the path to the source directory for the external672 LLVM projects Clang, lld, and Polly, respectively, relative to the top-level673 source directory. If the in-tree subdirectory for an external project674 exists (e.g., ``llvm/tools/clang`` for Clang), then the corresponding variable675 will not be used. If the variable for an external project does not point676 to a valid path, then that project will not be built.677 678**LLVM_EXTERNALIZE_DEBUGINFO**:BOOL679 Generate dSYM files and strip executables and libraries (Darwin only).680 Defaults to OFF.681 682**LLVM_ENABLE_EXPORTED_SYMBOLS_IN_EXECUTABLES**:BOOL683 When building executables, preserve symbol exports. Defaults to ON.684 You can use this option to disable exported symbols from all685 executables (Darwin Only).686 687**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL688 If enabled, the compiler and standard library versions won't be checked. LLVM689 may not compile at all, or might fail at runtime due to known bugs in these690 toolchains.691 692**LLVM_INCLUDE_BENCHMARKS**:BOOL693 Generate build targets for the LLVM benchmarks. Defaults to ON.694 695**LLVM_INCLUDE_EXAMPLES**:BOOL696 Generate build targets for the LLVM examples. Defaults to ON. You can use this697 option to disable the generation of build targets for the LLVM examples.698 699**LLVM_INCLUDE_TESTS**:BOOL700 Generate build targets for the LLVM unit tests. Defaults to ON. You can use701 this option to disable the generation of build targets for the LLVM unit702 tests.703 704**LLVM_INCLUDE_TOOLS**:BOOL705 Generate build targets for the LLVM tools. Defaults to ON. You can use this706 option to disable the generation of build targets for the LLVM tools.707 708**LLVM_INDIVIDUAL_TEST_COVERAGE**:BOOL709 Enable individual test case coverage. When set to ON, code coverage data for710 each test case will be generated and stored in a separate directory under the711 config.test_exec_root path. This feature allows code coverage analysis of each712 individual test case. Defaults to OFF.713 714**LLVM_INSTALL_BINUTILS_SYMLINKS**:BOOL715 Install symlinks from the binutils tool names to the corresponding LLVM tools.716 For example, ar will be symlinked to llvm-ar.717 718**LLVM_INSTALL_CCTOOLS_SYMLINKS**:BOOL719 Install symlinks from the cctools tool names to the corresponding LLVM tools.720 For example, lipo will be symlinked to llvm-lipo.721 722**LLVM_INSTALL_OCAMLDOC_HTML_DIR**:STRING723 The path to install OCamldoc-generated HTML documentation to. This path can724 either be absolute or relative to the ``CMAKE_INSTALL_PREFIX``. Defaults to725 ``${CMAKE_INSTALL_DOCDIR}/llvm/ocaml-html``.726 727**LLVM_INSTALL_SPHINX_HTML_DIR**:STRING728 The path to install Sphinx-generated HTML documentation to. This path can729 either be absolute or relative to the ``CMAKE_INSTALL_PREFIX``. Defaults to730 ``${CMAKE_INSTALL_DOCDIR}/llvm/html``.731 732**LLVM_INSTALL_UTILS**:BOOL733 If enabled, utility binaries like ``FileCheck`` and ``not`` will be installed734 to ``CMAKE_INSTALL_PREFIX``.735 736**LLVM_INSTALL_DOXYGEN_HTML_DIR**:STRING737 The path to install Doxygen-generated HTML documentation to. This path can738 either be absolute or relative to the *CMAKE_INSTALL_PREFIX*. Defaults to739 ``${CMAKE_INSTALL_DOCDIR}/llvm/doxygen-html``.740 741**LLVM_INTEGRATED_CRT_ALLOC**:PATH742 On Windows, allows embedding a different C runtime allocator into the LLVM743 tools and libraries. Using a lock-free allocator such as the ones listed below744 greatly decreases ThinLTO link time by about an order of magnitude. It also745 mildly improves Clang build times, by about 5-10%. At the moment, rpmalloc,746 snmalloc and mimalloc are supported. Use the path to `git clone` to select747 the respective allocator, for example:748 749 .. code-block:: console750 751 $ D:\git> git clone https://github.com/mjansson/rpmalloc752 $ D:\llvm-project> cmake ... -DLLVM_INTEGRATED_CRT_ALLOC=D:\git\rpmalloc753 754 This option needs to be used along with the static CRT, i.e., if building the755 Release target, add ``-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded``.756 Note that rpmalloc is also supported natively in-tree, see option below.757 758**LLVM_ENABLE_RPMALLOC**:BOOL759 Similar to LLVM_INTEGRATED_CRT_ALLOC, embeds the in-tree rpmalloc into the760 host toolchain as a C runtime allocator. The version currently used is761 rpmalloc 1.4.5. This option also implies linking with the static CRT, there's762 no need to provide CMAKE_MSVC_RUNTIME_LIBRARY.763 764**LLVM_LINK_LLVM_DYLIB**:BOOL765 If enabled, tools will be linked with the libLLVM shared library. Defaults766 to OFF. Setting ``LLVM_LINK_LLVM_DYLIB`` to ON also sets ``LLVM_BUILD_LLVM_DYLIB``767 to ON.768 This option is not available on Windows.769 770**LLVM_<target>_LINKER_FLAGS**:STRING771 Defines the set of linker flags that should be applied to a <target>.772 773**LLVM_LIT_ARGS**:STRING774 Arguments given to lit. ``make check`` and ``make clang-test`` are affected.775 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on776 others.777 778**LLVM_LIT_TOOLS_DIR**:PATH779 The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to780 the empty string, in which case lit will look for tools needed for tests781 (e.g., ``grep``, ``sort``, etc.) in your ``%PATH%``. If GnuWin32 is not in your782 ``%PATH%``, then you can set this variable to the GnuWin32 directory so that783 lit can find tools needed for tests in that directory.784 785**LLVM_NATIVE_TOOL_DIR**:STRING786 Full path to a directory containing executables for the build host787 (containing binaries such as ``llvm-tblgen`` and ``clang-tblgen``). This is788 intended for cross-compiling: if the user sets this variable and the789 directory contains executables with the expected names, no separate790 native versions of those executables will be built.791 792**LLVM_NO_INSTALL_NAME_DIR_FOR_BUILD_TREE**:BOOL793 Defaults to ``OFF``. If set to ``ON``, CMake's default logic for library IDs794 on Darwin in the build tree will be used. Otherwise the install-time library795 IDs will be used in the build tree as well. Mainly useful when other CMake796 library ID control variables (e.g., ``CMAKE_INSTALL_NAME_DIR``) are being797 set to non-standard values.798 799**LLVM_OPTIMIZED_TABLEGEN**:BOOL800 If enabled and building a debug or assert build, the CMake build system will801 generate a Release build tree to build a fully optimized tablegen for use802 during the build. Enabling this option can significantly speed up build times,803 especially when building LLVM in Debug configurations.804 805**LLVM_PARALLEL_{COMPILE,LINK,TABLEGEN}_JOBS**:STRING806 Limit the maximum number of concurrent compilation, link or807 tablegen jobs respectively. The default total number of parallel jobs is808 determined by the number of logical CPUs.809 810**LLVM_PROFDATA_FILE**:PATH811 Path to a profdata file to pass into clang's ``-fprofile-instr-use`` flag. This812 can only be specified if you're building with clang.813 814**LLVM_RAM_PER_{COMPILE,LINK,TABLEGEN}_JOB**:STRING815 Limit the number of concurrent compile, link or tablegen jobs816 respectively, depending on available physical memory. The value817 specified is in MB. The respective818 ``LLVM_PARALLEL_{COMPILE,LINK,TABLEGEN}_JOBS`` variable is819 overwritten by computing the memory size divided by the820 specified value. The largest memory user is linking, but remember821 that jobs in the other categories might run in parallel with the link822 jobs, and you need to consider their memory requirements when823 in a memory-limited environment. Using a824 ``-DLLVM_RAM_PER_LINK_JOB=10000`` is a good approximation. On ELF825 platforms debug builds can reduce link-time memory pressure by also826 using ``LLVM_USE_SPLIT_DWARF``.827 828**LLVM_REVERSE_ITERATION**:BOOL829 If enabled, all supported unordered llvm containers would be iterated in830 reverse order. This is useful for uncovering non-determinism caused by831 iteration of unordered containers.832 833**LLVM_STATIC_LINK_CXX_STDLIB**:BOOL834 Statically link to the C++ standard library if possible. This uses the flag835 ``-static-libstdc++``, but a Clang host compiler will statically link to libc++836 if used in conjunction with the **LLVM_ENABLE_LIBCXX** flag. Defaults to OFF.837 838**LLVM_TABLEGEN**:STRING839 Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is840 intended for cross-compiling: if the user sets this variable, no native841 TableGen will be created.842 843**LLVM_TARGET_ARCH**:STRING844 LLVM target to use for native code generation. This is required for JIT845 generation. It defaults to "host", meaning that it shall pick the architecture846 of the machine where LLVM is being built. If you are cross-compiling, set it847 to the target architecture name.848 849**LLVM_TARGETS_TO_BUILD**:STRING850 Semicolon-separated list of targets to build, or *all* for building all851 targets. Case-sensitive. Defaults to *all*. Example:852 ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.853 The full list, as of August 2025, is:854 ``AArch64;AMDGPU;ARM;AVR;BPF;Hexagon;Lanai;LoongArch;Mips;MSP430;NVPTX;PowerPC;RISCV;Sparc;SPIRV;SystemZ;VE;WebAssembly;X86;XCore``855 856 You can also specify ``host`` or ``Native`` to automatically detect and857 include the target corresponding to the host machine's architecture, or858 use ``all`` to include all available targets.859 For example, on an x86_64 machine, specifying ``-DLLVM_TARGETS_TO_BUILD=host``860 will include the ``X86`` target.861 862**LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN**:BOOL863 If enabled, the compiler version check will only warn when using a toolchain864 which is about to be deprecated, instead of emitting an error.865 866**LLVM_UBSAN_FLAGS**:STRING867 Defines the set of compile flags used to enable UBSan. Only used if868 ``LLVM_USE_SANITIZER`` contains ``Undefined``. This can be used to override869 the default set of UBSan flags.870 871**LLVM_UNREACHABLE_OPTIMIZE**:BOOL872 This flag controls the behavior of ``llvm_unreachable()`` in a release build873 (when assertions are disabled in general). When ON (default) then874 ``llvm_unreachable()`` is considered "undefined behavior" and optimized as875 such. When OFF it is instead replaced with a guaranteed "trap".876 877**LLVM_USE_INTEL_JITEVENTS**:BOOL878 Enable building support for Intel JIT Events API. Defaults to OFF.879 880**LLVM_USE_LINKER**:STRING881 Add ``-fuse-ld={name}`` to the link invocation. The possible values depend on882 your compiler. For clang, the value can be an absolute path to your custom883 linker, otherwise clang will prefix the name with ``ld.`` and apply its usual884 search. For example, to link LLVM with the Gold linker, cmake can be invoked885 with ``-DLLVM_USE_LINKER=gold``.886 887**LLVM_USE_OPROFILE**:BOOL888 Enable building OProfile JIT support. Defaults to OFF.889 890**LLVM_USE_PERF**:BOOL891 Enable building support for Perf (linux profiling tool) JIT support. Defaults to OFF.892 893**LLVM_USE_RELATIVE_PATHS_IN_FILES**:BOOL894 Rewrite absolute source paths in sources and debug info to relative ones. The895 source prefix can be adjusted via the ``LLVM_SOURCE_PREFIX`` variable.896 897**LLVM_USE_RELATIVE_PATHS_IN_DEBUG_INFO**:BOOL898 Rewrite absolute source paths in debug info to relative ones. The source prefix899 can be adjusted via the ``LLVM_SOURCE_PREFIX`` variable.900 901**LLVM_USE_SANITIZER**:STRING902 Define the sanitizer used to build LLVM binaries and tests. Possible values903 are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,904 ``DataFlow``, and ``Address;Undefined``. Defaults to empty string.905 906**LLVM_USE_SPLIT_DWARF**:BOOL907 If enabled CMake will pass ``-gsplit-dwarf`` to the compiler. This option908 reduces link-time memory usage by reducing the amount of debug information that909 the linker needs to resolve. It is recommended for platforms using the ELF object910 format, like Linux systems when linker memory usage is too high.911 912**SPHINX_EXECUTABLE**:STRING913 The path to the ``sphinx-build`` executable detected by CMake.914 For installation instructions, see915 https://www.sphinx-doc.org/en/master/usage/installation.html916 917**SPHINX_OUTPUT_HTML**:BOOL918 If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for919 building the documentation as HTML are added (but not built by default unless920 ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the921 source tree that uses sphinx (e.g., ``docs-llvm-html``, ``docs-clang-html``922 and ``docs-lld-html``). Defaults to ON.923 924**SPHINX_OUTPUT_MAN**:BOOL925 If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building926 the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``927 is enabled). Currently the only target added is ``docs-llvm-man``. Defaults928 to ON.929 930**SPHINX_WARNINGS_AS_ERRORS**:BOOL931 If enabled, then sphinx documentation warnings will be treated as932 errors. Defaults to ON.933 934Advanced variables935~~~~~~~~~~~~~~~~~~936 937These are niche, and changing them from their defaults is more likely to cause938things to go wrong. They are also unstable across LLVM versions.939 940**LLVM_EXAMPLES_INSTALL_DIR**:STRING941 The path for examples of using LLVM, relative to the *CMAKE_INSTALL_PREFIX*.942 Only matters if *LLVM_BUILD_EXAMPLES* is enabled.943 Defaults to "examples".944 945**LLVM_TOOLS_INSTALL_DIR**:STRING946 The path to install the main LLVM tools, relative to the *CMAKE_INSTALL_PREFIX*.947 Defaults to *CMAKE_INSTALL_BINDIR*.948 949**LLVM_UTILS_INSTALL_DIR**:STRING950 The path to install auxiliary LLVM utilities, relative to the *CMAKE_INSTALL_PREFIX*.951 Only matters if *LLVM_INSTALL_UTILS* is enabled.952 Defaults to *LLVM_TOOLS_INSTALL_DIR*.953 954CMake Caches955============956 957Recently, LLVM and Clang have been adding some more complicated build system958features. Utilizing these new features often involves a complicated chain of959CMake variables passed on the command line. Clang provides a collection of CMake960cache scripts to make these features more approachable.961 962CMake cache files are utilized using CMake's ``-C`` flag:963 964.. code-block:: console965 966 $ cmake -C <path to cache file> <path to sources>967 968CMake cache scripts are processed in an isolated scope, only cached variables969remain set when the main configuration runs. CMake cached variables do not reset970variables that are already set unless the FORCE option is specified.971 972A few notes about CMake Caches:973 974- Order of command line arguments is important975 976 - ``-D`` arguments specified before ``-C`` are set before the cache is processed and977 can be read inside the cache file978 - ``-D`` arguments specified after ``-C`` are set after the cache is processed and979 are unset inside the cache file980 981- All ``-D`` arguments will override cache file settings982- CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command983 line arguments984- It is recommended that all ``-D`` options be specified *before* ``-C``985 986For more information about some of the advanced build configurations supported987via Cache files see :doc:`AdvancedBuilds`.988 989Executing the Tests990===================991 992Testing is performed when the *check-all* target is built. For instance, if you are993using Makefiles, execute this command in the root of your build directory:994 995.. code-block:: console996 997 $ make check-all998 999On Visual Studio, you may run tests by building the project "check-all".1000For more information about testing, see the :doc:`TestingGuide`.1001 1002Cross compiling1003===============1004 1005See `this wiki page <https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling>`_ for1006generic instructions on how to cross-compile with CMake. It goes into detailed1007explanations and may seem daunting, but it is not. The wiki page has1008several examples including toolchain files. Go directly to the1009``Information how to set up various cross compiling toolchains`` section1010for a quick solution.1011 1012Also see the `LLVM-related variables`_ section for variables used when1013cross-compiling.1014 1015Embedding LLVM in your project1016==============================1017 1018From LLVM 3.5 onward, the CMake build system exports LLVM libraries as1019importable CMake targets. This means that clients of LLVM can now reliably use1020CMake to develop their own LLVM-based projects against an installed version of1021LLVM regardless of how it was built.1022 1023Here is a simple example of a ``CMakeLists.txt`` file that imports the LLVM libraries1024and uses them to build a simple application ``simple-tool``.1025 1026.. code-block:: cmake1027 1028 cmake_minimum_required(VERSION 3.20.0)1029 project(SimpleProject)1030 1031 find_package(LLVM REQUIRED CONFIG)1032 1033 message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")1034 message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")1035 1036 # Set your project compile flags.1037 # E.g. if using the C++ header files1038 # you will need to enable C++11 support1039 # for your compiler.1040 1041 include_directories(${LLVM_INCLUDE_DIRS})1042 separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})1043 add_definitions(${LLVM_DEFINITIONS_LIST})1044 1045 # Now build our tools1046 add_executable(simple-tool tool.cpp)1047 1048 # Find the libraries that correspond to the LLVM components1049 # that we wish to use1050 llvm_map_components_to_libnames(llvm_libs support core irreader)1051 1052 # Link against LLVM libraries1053 target_link_libraries(simple-tool ${llvm_libs})1054 1055The ``find_package(...)`` directive when used in CONFIG mode (as in the above1056example) will look for the ``LLVMConfig.cmake`` file in various locations (see1057CMake manual for details). It creates an ``LLVM_DIR`` cache entry to save the1058directory where ``LLVMConfig.cmake`` is found or allows the user to specify the1059directory (e.g., by passing ``-DLLVM_DIR=/usr/lib/cmake/llvm`` to1060the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).1061 1062This file is available in two different locations.1063 1064* ``<LLVM_INSTALL_PACKAGE_DIR>/LLVMConfig.cmake`` where1065 ``<LLVM_INSTALL_PACKAGE_DIR>`` is the location where LLVM CMake modules are1066 installed as part of an installed version of LLVM. This is typically1067 ``cmake/llvm/`` within the lib directory. On Linux, this is typically1068 ``/usr/lib/cmake/llvm/LLVMConfig.cmake``.1069 1070* ``<LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmake`` where1071 ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this is only1072 available when building LLVM with CMake.**1073 1074If LLVM is installed in your operating system's normal installation prefix (e.g.1075on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will1076automatically find LLVM if it is installed correctly. If LLVM is not installed1077or you wish to build directly against the LLVM build tree you can use1078``LLVM_DIR`` as previously mentioned.1079 1080The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables1081include:1082 1083``LLVM_CMAKE_DIR``1084 The path to the LLVM CMake directory (i.e., the directory containing1085 ``LLVMConfig.cmake``).1086 1087``LLVM_DEFINITIONS``1088 A list of preprocessor defines that should be used when building against LLVM.1089 1090``LLVM_ENABLE_ASSERTIONS``1091 This is set to ON if LLVM was built with assertions, otherwise OFF.1092 1093``LLVM_ENABLE_EH``1094 This is set to ON if LLVM was built with exception handling (EH) enabled,1095 otherwise OFF.1096 1097``LLVM_ENABLE_RTTI``1098 This is set to ON if LLVM was built with run time type information (RTTI),1099 otherwise OFF.1100 1101``LLVM_INCLUDE_DIRS``1102 A list of include paths to directories containing LLVM header files.1103 1104``LLVM_PACKAGE_VERSION``1105 The LLVM version. This string can be used with CMake conditionals, e.g., ``if1106 (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.1107 1108``LLVM_TOOLS_BINARY_DIR``1109 The path to the directory containing the LLVM tools (e.g., ``llvm-as``).1110 1111Notice that in the above example we link ``simple-tool`` against several LLVM1112libraries. The list of libraries is determined by using the1113``llvm_map_components_to_libnames()`` CMake function. For a list of available1114components look at the output of running ``llvm-config --components``.1115 1116Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was1117used instead of ``llvm_map_components_to_libnames()``. This is now deprecated1118and will be removed in a future version of LLVM.1119 1120.. _cmake-out-of-source-pass:1121 1122Developing LLVM passes out of source1123------------------------------------1124 1125You can develop LLVM passes out of LLVM's source tree (i.e., against an1126installed or built LLVM). An example of a project layout is provided below.1127 1128.. code-block:: none1129 1130 <project dir>/1131 |1132 CMakeLists.txt1133 <pass name>/1134 |1135 CMakeLists.txt1136 Pass.cpp1137 ...1138 1139Contents of ``<project dir>/CMakeLists.txt``:1140 1141.. code-block:: cmake1142 1143 find_package(LLVM REQUIRED CONFIG)1144 1145 separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})1146 add_definitions(${LLVM_DEFINITIONS_LIST})1147 include_directories(${LLVM_INCLUDE_DIRS})1148 1149 add_subdirectory(<pass name>)1150 1151Contents of ``<project dir>/<pass name>/CMakeLists.txt``:1152 1153.. code-block:: cmake1154 1155 add_library(LLVMPassname MODULE Pass.cpp)1156 1157Note if you intend for this pass to be merged into the LLVM source tree at some1158point in the future it might make more sense to use LLVM's internal1159``add_llvm_library`` function with the MODULE argument instead by...1160 1161 1162Adding the following to ``<project dir>/CMakeLists.txt`` (after1163``find_package(LLVM ...)``)1164 1165.. code-block:: cmake1166 1167 list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")1168 include(AddLLVM)1169 1170And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to1171 1172.. code-block:: cmake1173 1174 add_llvm_library(LLVMPassname MODULE1175 Pass.cpp1176 )1177 1178When you are done developing your pass, you may wish to integrate it1179into the LLVM source tree. You can achieve it in two easy steps:1180 1181#. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transforms`` directory.1182 1183#. Adding ``add_subdirectory(<pass name>)`` line into1184 ``<LLVM root>/lib/Transforms/CMakeLists.txt``.1185 1186Compiler/Platform-specific topics1187=================================1188 1189Notes for specific compilers and/or platforms.1190 1191Windows1192-------1193 1194**LLVM_COMPILER_JOBS**:STRING1195 Specifies the maximum number of parallel compiler jobs to use per project1196 when building with msbuild or Visual Studio. Only supported for the Visual1197 Studio 2010 CMake generator. 0 means use all processors. Default is 0.1198 1199**CMAKE_MT**:STRING1200 When compiling with clang-cl, CMake may use ``llvm-mt`` as the Manifest Tool1201 when available. ```llvm-mt``` is only present when libxml2 is found at build-time.1202 To ensure using Microsoft's Manifest Tool set `CMAKE_MT=mt`.1203 1204Apple/OSX1205---------1206 1207**CMAKE_OSX_SYSROOT**:STRING1208 When compiling for OSX, in order for the test suite to find libSystem to link1209 dylib tests you'll need to run CMake with ```xcrun --show-sdk-path``` as the1210 string to pass in so that the testsuite can find your os libraries.1211 1212 This will show up as ```ld: library not found for -lSystem``` when running1213 tests.1214