1======================== 2Building LLVM with CMake 3======================== 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11`CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake 12does not build the project, it generates the files needed by your build tool 13(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 the 17legacy configure/make system. 18 19If you are really anxious about getting a functional LLVM build, go to the 20`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. The 22`Options and variables`_ section is a reference for customizing your build. If 23you 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 for 26information about modifying the LLVM CMake build system you may want to see the 27:doc:`CMakePrimer` page. It has a basic overview of the CMake language. 28 29.. _Quick start: 30 31Quick start 32=========== 33 34We use here the command-line, non-interactive CMake interface. 35 36#. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install 37 CMake. Version 3.20.0 is the minimum required. 38 39#. Open a shell. Your development tools must be reachable from this shell 40 through the PATH environment variable. 41 42#. Create a build directory. Building LLVM in the source 43 directory is not supported. cd to this directory: 44 45 .. code-block:: console 46 47 $ mkdir mybuilddir 48 $ cd mybuilddir 49 50#. Execute this command in the shell replacing `path/to/llvm/source/root` with 51 the path to the root of your LLVM source tree: 52 53 .. code-block:: console 54 55 $ cmake path/to/llvm/source/root 56 57 CMake will detect your development environment, perform a series of tests, and 58 generate the files required for building LLVM. CMake will use default values 59 for all build parameters. See the `Options and variables`_ section for 60 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 the 63 environment is not sane enough. In this case, make sure that the toolset that 64 you intend to use is the only one reachable from the shell, and that the shell 65 itself is the correct one for your development environment. CMake will refuse 66 to build MinGW makefiles if you have a POSIX shell reachable through the PATH 67 environment variable, for instance. You can force CMake to use a given build 68 tool; for instructions, see the `Usage`_ section, below. You may 69 also wish to control which targets LLVM enables, or which LLVM 70 components are built; see the `Frequently Used LLVM-related 71 variables`_ below. 72 73#. After CMake has finished running, proceed to use IDE project files, or start 74 the build from the build directory: 75 76 .. code-block:: console 77 78 $ cmake --build . 79 80 The ``--build`` option tells ``cmake`` to invoke the underlying build 81 tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc.) 82 83 The underlying build tool can be invoked directly, of course, but 84 the ``--build`` option is portable. 85 86#. After LLVM has finished building, install it from the build directory: 87 88 .. code-block:: console 89 90 $ cmake --build . --target install 91 92 The ``--target`` option with ``install`` parameter in addition to 93 the ``--build`` option tells ``cmake`` to build the ``install`` target. 94 95 It is possible to set a different install prefix at installation time 96 by invoking the ``cmake_install.cmake`` script generated in the 97 build directory: 98 99 .. code-block:: console 100 101 $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake 102 103.. _Basic CMake usage: 104.. _Usage: 105 106Basic CMake usage 107================= 108 109This section explains basic aspects of CMake 110which you may need in your day-to-day usage. 111 112CMake comes with extensive documentation, in the form of html files, and as 113online help accessible via the ``cmake`` executable itself. Execute ``cmake 114--help`` for further help options. 115 116CMake allows you to specify a build tool (e.g., GNU make, Visual Studio, 117or Xcode). If not specified on the command line, CMake tries to guess which 118build tool to use, based on your environment. Once it has identified your 119build tool, CMake uses the corresponding *Generator* to create files for your 120build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can 121explicitly specify the generator with the command line option ``-G "Name of the 122generator"``. To see a list of the available generators on your system, execute 123 124.. code-block:: console 125 126 $ cmake --help 127 128This will list the generator names at the end of the help text. 129 130Generators' names are case-sensitive, and may contain spaces. For this reason, 131you should enter them exactly as they are listed in the ``cmake --help`` 132output, in quotes. For example, to generate project files specifically for 133Visual Studio 12, you can execute: 134 135.. code-block:: console 136 137 $ cmake -G "Visual Studio 12" path/to/llvm/source/root 138 139For a given development platform there can be more than one adequate 140generator. If you use Visual Studio, "NMake Makefiles" is a generator you can use 141for building with NMake. By default, CMake chooses the most specific generator 142supported by your development environment. If you want an alternative generator, 143you must tell this to CMake with the ``-G`` option. 144 145.. todo:: 146 147 Explain variables and cache. Move explanation here from #options section. 148 149.. _Options and variables: 150 151Options and variables 152===================== 153 154Variables customize how the build will be generated. Options are boolean 155variables, with possible values ON/OFF. Options and variables are defined on the 156CMake command line like this: 157 158.. code-block:: console 159 160 $ cmake -DVARIABLE=value path/to/llvm/source 161 162You can set a variable after the initial CMake invocation to change its 163value. You can also undefine a variable: 164 165.. code-block:: console 166 167 $ cmake -UVARIABLE path/to/llvm/source 168 169Variables are stored in the CMake cache. This is a file named ``CMakeCache.txt`` 170stored at the root of your build directory that is generated by ``cmake``. 171Editing it yourself is not recommended. 172 173Variables are listed in the CMake cache and later in this document with 174the variable name and type separated by a colon. You can also specify the 175variable and type on the CMake command line: 176 177.. code-block:: console 178 179 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source 180 181.. _cmake_frequently_used_variables: 182 183Frequently-used CMake variables 184------------------------------- 185 186Here are some of the CMake variables that are used often, along with a 187brief explanation. For full documentation, consult the CMake manual, 188or execute ``cmake --help-variable VARIABLE_NAME``. See `Frequently 189Used LLVM-related Variables`_ below for information about commonly 190used variables that control features of LLVM and enabled subprojects. 191 192.. _cmake_build_type: 193 194**CMAKE_BUILD_TYPE**:STRING 195 This configures the optimization level for ``make`` or ``ninja`` builds. 196 197 Possible values: 198 199 =========================== ============= ========== ========== ========================== 200 Build Type Optimizations Debug Info Assertions Best suited for 201 =========================== ============= ========== ========== ========================== 202 **Release** For Speed No No Users of LLVM and Clang 203 **Debug** None Yes Yes Developers of LLVM 204 **RelWithDebInfo** For Speed Yes No Users that also need Debug 205 **MinSizeRel** For Size No No When disk space matters 206 =========================== ============= ========== ========== ========================== 207 208 * Optimizations make LLVM/Clang run faster, but can be an impediment for 209 step-by-step debugging. 210 * Builds with debug information can use a lot of RAM and disk space and is 211 usually slower to run. You can improve RAM usage by using ``lld``, see 212 the :ref:`LLVM_USE_LINKER <llvm_use_linker>` option. 213 * Assertions are internal checks to help you find bugs. They typically slow 214 down LLVM and Clang when enabled, but can be useful during development. 215 You can manually set :ref:`LLVM_ENABLE_ASSERTIONS <llvm_enable_assertions>` 216 to override the default from `CMAKE_BUILD_TYPE`. 217 218 If you are using an IDE such as Visual Studio or Xcode, you should use 219 the IDE settings to set the build type. 220 221 Note: on Windows (building with MSVC or clang-cl), CMake's **RelWithDebInfo** 222 setting does not enable the same optimizations as **Release**. Using the 223 **Release** build type with :ref:`LLVM_ENABLE_PDB <llvm_enable_pdb>` set 224 may be a better option. 225 226**CMAKE_INSTALL_PREFIX**:PATH 227 Path where LLVM will be installed when the "install" target is built. 228 229**CMAKE_{C,CXX}_FLAGS**:STRING 230 Extra flags to use when compiling C and C++ source files respectively. 231 232**CMAKE_{C,CXX}_COMPILER**:STRING 233 Specify the C and C++ compilers to use. If you have multiple 234 compilers installed, CMake might not default to the one you wish to 235 use. 236 237.. _Frequently Used LLVM-related variables: 238 239Frequently Used LLVM-related variables 240-------------------------------------- 241 242The default configuration may not match your requirements. Here are 243LLVM variables that are frequently used to control that. The full 244description is in `LLVM-related variables`_ below. 245 246**LLVM_ENABLE_PROJECTS**:STRING 247 Control which projects are enabled. For example you may want to work on clang 248 or lldb by specifying ``-DLLVM_ENABLE_PROJECTS="clang;lldb"``. 249 250**LLVM_ENABLE_RUNTIMES**:STRING 251 Control which runtimes are enabled. For example you may want to work on 252 libc++ or libc++abi by specifying ``-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``. 253 254**LLVM_LIBDIR_SUFFIX**:STRING 255 Extra suffix to append to the directory where libraries are to be 256 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 257 to install libraries to ``/usr/lib64``. 258 259**LLVM_PARALLEL_{COMPILE,LINK}_JOBS**:STRING 260 Building the llvm toolchain can use a lot of resources, particularly 261 linking. These options, when you use the Ninja generator, allow you 262 to restrict the parallelism. For example, to avoid OOMs or going 263 into swap, permit only one link job per 15GB of RAM available on a 264 32GB machine, specify ``-G Ninja -DLLVM_PARALLEL_LINK_JOBS=2``. 265 266**LLVM_TARGETS_TO_BUILD**:STRING 267 Control which targets are enabled. For example you may only need to enable 268 your native target with, for example, ``-DLLVM_TARGETS_TO_BUILD=X86``. 269 270.. _llvm_use_linker: 271 272**LLVM_USE_LINKER**:STRING 273 Override the system's default linker. For instance use ``lld`` with 274 ``-DLLVM_USE_LINKER=lld``. 275 276Rarely-used CMake variables 277--------------------------- 278 279Here are some of the CMake variables that are rarely used, along with a brief 280explanation and LLVM-related notes. For full documentation, consult the CMake 281manual, or execute ``cmake --help-variable VARIABLE_NAME``. 282 283**CMAKE_CXX_STANDARD**:STRING 284 Sets the C++ standard to conform to when building LLVM. Possible values are 285 17 and 20. LLVM Requires C++17 or higher. This defaults to 17. 286 287**CMAKE_INSTALL_BINDIR**:PATH 288 The path to install executables, relative to the *CMAKE_INSTALL_PREFIX*. 289 Defaults to "bin". 290 291**CMAKE_INSTALL_DOCDIR**:PATH 292 The path to install documentation, relative to the *CMAKE_INSTALL_PREFIX*. 293 Defaults to "share/doc". 294 295**CMAKE_INSTALL_INCLUDEDIR**:PATH 296 The path to install header files, relative to the *CMAKE_INSTALL_PREFIX*. 297 Defaults to "include". 298 299**CMAKE_INSTALL_MANDIR**:PATH 300 The path to install manpage files, relative to the *CMAKE_INSTALL_PREFIX*. 301 Defaults to "share/man". 302 303.. _LLVM-related variables: 304 305LLVM-related variables 306----------------------- 307 308These variables provide fine control over the build of LLVM and 309enabled sub-projects. Nearly all of these variable names begin with 310``LLVM_``. 311 312.. _LLVM-related variables BUILD_SHARED_LIBS: 313 314**BUILD_SHARED_LIBS**:BOOL 315 Flag indicating if each LLVM component (e.g. Support) is built as a shared 316 library (ON) or as a static library (OFF). Its default value is OFF. On 317 Windows, shared libraries may be used when building with MinGW, including 318 mingw-w64, but not when building with the Microsoft toolchain. 319 320 .. note:: BUILD_SHARED_LIBS is only recommended for use by LLVM developers. 321 If you want to build LLVM as a shared library, you should use the 322 ``LLVM_BUILD_LLVM_DYLIB`` option. 323 324**LLVM_ABI_BREAKING_CHECKS**:STRING 325 Used to decide if LLVM should be built with ABI breaking checks or 326 not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and 327 `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an 328 assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on 329 (off) irrespective of whether normal (`NDEBUG`-based) assertions are 330 enabled or not. A version of LLVM built with ABI breaking checks 331 is not ABI compatible with a version built without it. 332 333**LLVM_ADDITIONAL_BUILD_TYPES**:LIST 334 Adding a semicolon separated list of additional build types to this flag 335 allows for them to be specified as values in CMAKE_BUILD_TYPE without 336 encountering a fatal error during the configuration process. 337 338**LLVM_APPEND_VC_REV**:BOOL 339 Embed version control revision info (Git revision id). 340 The version info is provided by the ``LLVM_REVISION`` macro in 341 ``llvm/include/llvm/Support/VCSRevision.h``. Developers using git who don't 342 need revision info can disable this option to avoid re-linking most binaries 343 after a branch switch. Defaults to ON. 344 345**LLVM_FORCE_VC_REPOSITORY**:STRING 346 Set the git repository to include in version info rather than calling git to 347 determine it. 348 349**LLVM_FORCE_VC_REVISION**:STRING 350 Force a specific Git revision id rather than calling to git to determine it. 351 This is useful in environments where git is not available or non-functional 352 but the VC revision is available through other means. 353 354**LLVM_BUILD_32_BITS**:BOOL 355 Build 32-bit executables and libraries on 64-bit systems. This option is 356 available only on some 64-bit Unix systems. Defaults to OFF. 357 358**LLVM_BUILD_BENCHMARKS**:BOOL 359 Adds benchmarks to the list of default targets. Defaults to OFF. 360 361**LLVM_BUILD_DOCS**:BOOL 362 Adds all *enabled* documentation targets (i.e. Doxgyen and Sphinx targets) as 363 dependencies of the default build targets. This results in all of the (enabled) 364 documentation targets being as part of a normal build. If the ``install`` 365 target is run then this also enables all built documentation targets to be 366 installed. Defaults to OFF. To enable a particular documentation target, see 367 LLVM_ENABLE_SPHINX and LLVM_ENABLE_DOXYGEN. 368 369**LLVM_BUILD_EXAMPLES**:BOOL 370 Build LLVM examples. Defaults to OFF. Targets for building each example are 371 generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more 372 details. 373 374**LLVM_BUILD_INSTRUMENTED_COVERAGE**:BOOL 375 If enabled, `source-based code coverage 376 <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_ instrumentation 377 is enabled while building llvm. If CMake can locate the code coverage 378 scripts and the llvm-cov and llvm-profdata tools that pair to your compiler, 379 the build will also generate the `generate-coverage-report` target to generate 380 the code coverage report for LLVM, and the `clear-profile-data` utility target 381 to delete captured profile data. See documentation for 382 *LLVM_CODE_COVERAGE_TARGETS* and *LLVM_COVERAGE_SOURCE_DIRS* for more 383 information on configuring code coverage reports. 384 385**LLVM_BUILD_LLVM_DYLIB**:BOOL 386 If enabled, the target for building the libLLVM shared library is added. 387 This library contains all of LLVM's components in a single shared library. 388 Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS. 389 Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB 390 is also ON. 391 The components in the library can be customised by setting LLVM_DYLIB_COMPONENTS 392 to a list of the desired components. 393 This option is not available on Windows. 394 395**LLVM_BUILD_TESTS**:BOOL 396 Include LLVM unit tests in the 'all' build target. Defaults to OFF. Targets 397 for building each unit test are generated in any case. You can build a 398 specific unit test using the targets defined under *unittests*, such as 399 ADTTests, IRTests, SupportTests, etc. (Search for ``add_llvm_unittest`` in 400 the subdirectories of *unittests* for a complete list of unit tests.) It is 401 possible to build all unit tests with the target *UnitTests*. 402 403**LLVM_BUILD_TOOLS**:BOOL 404 Build LLVM tools. Defaults to ON. Targets for building each tool are generated 405 in any case. You can build a tool separately by invoking its target. For 406 example, you can build *llvm-as* with a Makefile-based system by executing *make 407 llvm-as* at the root of your build directory. 408 409**LLVM_CCACHE_BUILD**:BOOL 410 If enabled and the ``ccache`` program is available, then LLVM will be 411 built using ``ccache`` to speed up rebuilds of LLVM and its components. 412 Defaults to OFF. The size and location of the cache maintained 413 by ``ccache`` can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR 414 options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment 415 variables, respectively. 416 417**LLVM_CODE_COVERAGE_TARGETS**:STRING 418 If set to a semicolon separated list of targets, those targets will be used 419 to drive the code coverage reports. If unset, the target list will be 420 constructed using the LLVM build's CMake export list. 421 422**LLVM_COVERAGE_SOURCE_DIRS**:STRING 423 If set to a semicolon separated list of directories, the coverage reports 424 will limit code coverage summaries to just the listed directories. If unset, 425 coverage reports will include all sources identified by the tooling. 426 427**LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL 428 macOS Only: If enabled CMake will generate a target named 429 'install-xcode-toolchain'. This target will create a directory at 430 $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can 431 be used to override the default system tools. 432 433**LLVM_DEFAULT_TARGET_TRIPLE**:STRING 434 LLVM target to use for code generation when no target is explicitly specified. 435 It defaults to "host", meaning that it shall pick the architecture 436 of the machine where LLVM is being built. If you are building a cross-compiler, 437 set it to the target triple of your desired architecture. 438 439**LLVM_DOXYGEN_QCH_FILENAME**:STRING 440 The filename of the Qt Compressed Help file that will be generated when 441 ``-DLLVM_ENABLE_DOXYGEN=ON`` and 442 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to 443 ``org.llvm.qch``. 444 This option is only useful in combination with 445 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; 446 otherwise it has no effect. 447 448**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING 449 The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's 450 ``find_program()`` can find. This option is only useful in combination with 451 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no 452 effect. 453 454**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING 455 See `Qt Help Project`_ for 456 more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which 457 is a combination of the package name and version string. This filter can then 458 be used in Qt Creator to select only documentation from LLVM when browsing 459 through all the help files that you might have loaded. This option is only 460 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; 461 otherwise it has no effect. 462 463.. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters 464 465**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING 466 Namespace under which the intermediate Qt Help Project file lives. See `Qt 467 Help Project`_ 468 for more information. Defaults to "org.llvm". This option is only useful in 469 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise 470 it has no effect. 471 472**LLVM_DOXYGEN_SVG**:BOOL 473 Uses .svg files instead of .png files for graphs in the Doxygen output. 474 Defaults to OFF. 475 476.. _llvm_enable_assertions: 477 478**LLVM_ENABLE_ASSERTIONS**:BOOL 479 Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE`` 480 is *Debug*. 481 482**LLVM_ENABLE_BINDINGS**:BOOL 483 If disabled, do not try to build the OCaml bindings. 484 485**LLVM_ENABLE_DEBUGLOC_COVERAGE_TRACKING**:STRING 486 Enhances Debugify's ability to detect line number errors by storing extra 487 information inside Instructions, removing false positives from Debugify's 488 results at the cost of performance. Allowed values are `DISABLED` (default) 489 and `COVERAGE`. `COVERAGE` tracks whether and why a line number was 490 intentionally dropped or not generated for an instruction, allowing Debugify 491 to avoid reporting these as errors; this comes with a small performance cost 492 of ~0.1%. `COVERAGE` is an ABI-breaking option. 493 494**LLVM_ENABLE_DIA_SDK**:BOOL 495 Enable building with MSVC DIA SDK for PDB debugging support. Available 496 only with MSVC. Defaults to ON. 497 498**LLVM_ENABLE_DOXYGEN**:BOOL 499 Enables the generation of browsable HTML documentation using doxygen. 500 Defaults to OFF. 501 502**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL 503 Enables the generation of a Qt Compressed Help file. Defaults to OFF. 504 This affects the make target ``doxygen-llvm``. When enabled, apart from 505 the normal HTML output generated by doxygen, this will produce a QCH file 506 named ``org.llvm.qch``. You can then load this file into Qt Creator. 507 This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``; 508 otherwise this has no effect. 509 510**LLVM_ENABLE_EH**:BOOL 511 Build LLVM with exception-handling support. This is necessary if you wish to 512 link against LLVM libraries and make use of C++ exceptions in your own code 513 that need to propagate through LLVM code. Defaults to OFF. 514 515**LLVM_ENABLE_EXPENSIVE_CHECKS**:BOOL 516 Enable additional time/memory expensive checking. Defaults to OFF. 517 518**LLVM_ENABLE_FFI**:BOOL 519 Indicates whether the LLVM Interpreter will be linked with the Foreign Function 520 Interface library (libffi) in order to enable calling external functions. 521 If the library or its headers are installed in a custom 522 location, you can also set the variables FFI_INCLUDE_DIR and 523 FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found, 524 respectively. Defaults to OFF. 525 526**LLVM_ENABLE_HTTPLIB**:BOOL 527 Enables the optional cpp-httplib dependency which is used by llvm-debuginfod 528 to serve debug info over HTTP. `cpp-httplib <https://github.com/yhirose/cpp-httplib>`_ 529 must be installed, or `httplib_ROOT` must be set. Defaults to OFF. 530 531**LLVM_ENABLE_IDE**:BOOL 532 Tell the build system that an IDE is being used. This in turn disables the 533 creation of certain convenience build system targets, such as the various 534 ``install-*`` and ``check-*`` targets, since IDEs don't always deal well with 535 a large number of targets. This is usually autodetected, but it can be 536 configured manually to explicitly control the generation of those targets. 537 538**LLVM_ENABLE_LIBCXX**:BOOL 539 If the host compiler and linker supports the stdlib flag, -stdlib=libc++ is 540 passed to invocations of both so that the project is built using libc++ 541 instead of stdlibc++. Defaults to OFF. 542 543**LLVM_ENABLE_LIBPFM**:BOOL 544 Enable building with libpfm to support hardware counter measurements in LLVM 545 tools. 546 Defaults to ON. 547 548**LLVM_ENABLE_LLD**:BOOL 549 This option is equivalent to `-DLLVM_USE_LINKER=lld`, except during a 2-stage 550 build where a dependency is added from the first stage to the second ensuring 551 that lld is built before stage2 begins. 552 553**LLVM_ENABLE_LLVM_LIBC**: BOOL 554 If the LLVM libc overlay is installed in a location where the host linker 555 can access it, all built executables will be linked against the LLVM libc 556 overlay before linking against the system libc. Defaults to OFF. 557 558**LLVM_ENABLE_LTO**:STRING 559 Add ``-flto`` or ``-flto=`` flags to the compile and link command 560 lines, enabling link-time optimization. Possible values are ``Off``, 561 ``On``, ``Thin`` and ``Full``. Defaults to OFF. 562 563**LLVM_ENABLE_MODULES**:BOOL 564 Compile with `Clang Header Modules 565 <https://clang.llvm.org/docs/Modules.html>`_. 566 567.. _llvm_enable_pdb: 568 569**LLVM_ENABLE_PDB**:BOOL 570 For Windows builds using MSVC or clang-cl, generate PDB files when 571 :ref:`CMAKE_BUILD_TYPE <cmake_build_type>` is set to Release. 572 573**LLVM_ENABLE_PEDANTIC**:BOOL 574 Enable pedantic mode. This disables compiler-specific extensions, if 575 possible. Defaults to ON. 576 577**LLVM_ENABLE_PIC**:BOOL 578 Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports 579 this flag. Some systems, like Windows, do not need this flag. Defaults to ON. 580 581**LLVM_ENABLE_PROJECTS**:STRING 582 Semicolon-separated list of projects to build, or *all* for building all 583 (clang, lldb, lld, polly, etc) projects. This flag assumes that projects 584 are checked out side-by-side and not nested, i.e. clang needs to be in 585 parallel of llvm instead of nested in ``llvm/tools``. This feature allows 586 to have one build for only LLVM and another for clang+llvm using the same 587 source checkout. 588 589 The full list is: 590 591 ``bolt;clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;lld;lldb;mlir;openmp;polly;pstl`` 592 593 .. note:: 594 Some projects listed here can also go in ``LLVM_ENABLE_RUNTIMES``. They 595 should only appear in one of the two lists. If a project is a valid possiblity 596 for both, prefer putting it in ``LLVM_ENABLE_RUNTIMES``. 597 598**LLVM_ENABLE_RTTI**:BOOL 599 Build LLVM with run-time type information. Defaults to OFF. 600 601**LLVM_ENABLE_RUNTIMES**:STRING 602 Build libc++, libc++abi, libunwind or compiler-rt using the just-built compiler. 603 This is the correct way to build runtimes when putting together a toolchain. 604 It will build the builtins separately from the other runtimes to preserve 605 correct dependency ordering. If you want to build the runtimes using a system 606 compiler, see the `libc++ documentation <https://libcxx.llvm.org/VendorDocumentation.html>`_. 607 608 .. note:: 609 The list should not have duplicates with ``LLVM_ENABLE_PROJECTS``. 610 611 The full list is: 612 613 ``libc;libunwind;libcxxabi;pstl;libcxx;compiler-rt;openmp;llvm-libgcc;offload`` 614 615 To enable all of them, use: 616 617 ``LLVM_ENABLE_RUNTIMES=all`` 618 619**LLVM_ENABLE_SPHINX**:BOOL 620 If specified, CMake will search for the ``sphinx-build`` executable and will make 621 the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available. 622 Defaults to OFF. 623 624**LLVM_ENABLE_THREADS**:BOOL 625 Build with threads support, if available. Defaults to ON. 626 627**LLVM_ENABLE_UNWIND_TABLES**:BOOL 628 Enable unwind tables in the binary. Disabling unwind tables can reduce the 629 size of the libraries. Defaults to ON. 630 631**LLVM_ENABLE_WARNINGS**:BOOL 632 Enable all compiler warnings. Defaults to ON. 633 634**LLVM_ENABLE_WERROR**:BOOL 635 Stop and fail the build, if a compiler warning is triggered. Defaults to OFF. 636 637**LLVM_ENABLE_Z3_SOLVER**:BOOL 638 If enabled, the Z3 constraint solver is activated for the Clang static analyzer. 639 A recent version of the z3 library needs to be available on the system. 640 641**LLVM_ENABLE_ZLIB**:STRING 642 Used to decide if LLVM tools should support compression/decompression with 643 zlib. Allowed values are ``OFF``, ``ON`` (default, enable if zlib is found), 644 and ``FORCE_ON`` (error if zlib is not found). 645 646**LLVM_ENABLE_ZSTD**:STRING 647 Used to decide if LLVM tools should support compression/decompression with 648 zstd. Allowed values are ``OFF``, ``ON`` (default, enable if zstd is found), 649 and ``FORCE_ON`` (error if zstd is not found). 650 651**LLVM_EXPERIMENTAL_TARGETS_TO_BUILD**:STRING 652 Semicolon-separated list of experimental targets to build and linked into 653 llvm. This will build the experimental target without needing it to add to the 654 list of all the targets available in the LLVM's main CMakeLists.txt. 655 656**LLVM_EXTERNAL_PROJECTS**:STRING 657 Semicolon-separated list of additional external projects to build as part of 658 llvm. For each project LLVM_EXTERNAL_<NAME>_SOURCE_DIR have to be specified 659 with the path for the source code of the project. Example: 660 ``-DLLVM_EXTERNAL_PROJECTS="Foo;Bar" 661 -DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo 662 -DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``. 663 664**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH 665 These variables specify the path to the source directory for the external 666 LLVM projects Clang, lld, and Polly, respectively, relative to the top-level 667 source directory. If the in-tree subdirectory for an external project 668 exists (e.g., llvm/tools/clang for Clang), then the corresponding variable 669 will not be used. If the variable for an external project does not point 670 to a valid path, then that project will not be built. 671 672**LLVM_EXTERNALIZE_DEBUGINFO**:BOOL 673 Generate dSYM files and strip executables and libraries (Darwin Only). 674 Defaults to OFF. 675 676**LLVM_ENABLE_EXPORTED_SYMBOLS_IN_EXECUTABLES**:BOOL 677 When building executables, preserve symbol exports. Defaults to ON. 678 You can use this option to disable exported symbols from all 679 executables (Darwin Only). 680 681**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL 682 If enabled, the compiler and standard library versions won't be checked. LLVM 683 may not compile at all, or might fail at runtime due to known bugs in these 684 toolchains. 685 686**LLVM_INCLUDE_BENCHMARKS**:BOOL 687 Generate build targets for the LLVM benchmarks. Defaults to ON. 688 689**LLVM_INCLUDE_EXAMPLES**:BOOL 690 Generate build targets for the LLVM examples. Defaults to ON. You can use this 691 option to disable the generation of build targets for the LLVM examples. 692 693**LLVM_INCLUDE_TESTS**:BOOL 694 Generate build targets for the LLVM unit tests. Defaults to ON. You can use 695 this option to disable the generation of build targets for the LLVM unit 696 tests. 697 698**LLVM_INCLUDE_TOOLS**:BOOL 699 Generate build targets for the LLVM tools. Defaults to ON. You can use this 700 option to disable the generation of build targets for the LLVM tools. 701 702**LLVM_INDIVIDUAL_TEST_COVERAGE**:BOOL 703 Enable individual test case coverage. When set to ON, code coverage data for 704 each test case will be generated and stored in a separate directory under the 705 config.test_exec_root path. This feature allows code coverage analysis of each 706 individual test case. Defaults to OFF. 707 708**LLVM_INSTALL_BINUTILS_SYMLINKS**:BOOL 709 Install symlinks from the binutils tool names to the corresponding LLVM tools. 710 For example, ar will be symlinked to llvm-ar. 711 712**LLVM_INSTALL_CCTOOLS_SYMLINKS**:BOOL 713 Install symliks from the cctools tool names to the corresponding LLVM tools. 714 For example, lipo will be symlinked to llvm-lipo. 715 716**LLVM_INSTALL_OCAMLDOC_HTML_DIR**:STRING 717 The path to install OCamldoc-generated HTML documentation to. This path can 718 either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to 719 ``${CMAKE_INSTALL_DOCDIR}/llvm/ocaml-html``. 720 721**LLVM_INSTALL_SPHINX_HTML_DIR**:STRING 722 The path to install Sphinx-generated HTML documentation to. This path can 723 either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to 724 ``${CMAKE_INSTALL_DOCDIR}/llvm/html``. 725 726**LLVM_INSTALL_UTILS**:BOOL 727 If enabled, utility binaries like ``FileCheck`` and ``not`` will be installed 728 to CMAKE_INSTALL_PREFIX. 729 730**LLVM_INSTALL_DOXYGEN_HTML_DIR**:STRING 731 The path to install Doxygen-generated HTML documentation to. This path can 732 either be absolute or relative to the *CMAKE_INSTALL_PREFIX*. Defaults to 733 ``${CMAKE_INSTALL_DOCDIR}/llvm/doxygen-html``. 734 735**LLVM_INTEGRATED_CRT_ALLOC**:PATH 736 On Windows, allows embedding a different C runtime allocator into the LLVM 737 tools and libraries. Using a lock-free allocator such as the ones listed below 738 greatly decreases ThinLTO link time by about an order of magnitude. It also 739 midly improves Clang build times, by about 5-10%. At the moment, rpmalloc, 740 snmalloc and mimalloc are supported. Use the path to `git clone` to select 741 the respective allocator, for example: 742 743 .. code-block:: console 744 745 $ D:\git> git clone https://github.com/mjansson/rpmalloc 746 $ D:\llvm-project> cmake ... -DLLVM_INTEGRATED_CRT_ALLOC=D:\git\rpmalloc 747 748 This option needs to be used along with the static CRT, ie. if building the 749 Release target, add -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded. 750 Note that rpmalloc is also supported natively in-tree, see option below. 751 752**LLVM_ENABLE_RPMALLOC**:BOOL 753 Similar to LLVM_INTEGRATED_CRT_ALLOC, embeds the in-tree rpmalloc into the 754 host toolchain as a C runtime allocator. The version currently used is 755 rpmalloc 1.4.5. This option also implies linking with the static CRT, there's 756 no need to provide CMAKE_MSVC_RUNTIME_LIBRARY. 757 758**LLVM_LINK_LLVM_DYLIB**:BOOL 759 If enabled, tools will be linked with the libLLVM shared library. Defaults 760 to OFF. Setting LLVM_LINK_LLVM_DYLIB to ON also sets LLVM_BUILD_LLVM_DYLIB 761 to ON. 762 This option is not available on Windows. 763 764**LLVM_<target>_LINKER_FLAGS**:STRING 765 Defines the set of linker flags that should be applied to a <target>. 766 767**LLVM_LIT_ARGS**:STRING 768 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 769 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 770 others. 771 772**LLVM_LIT_TOOLS_DIR**:PATH 773 The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to 774 the empty string, in which case lit will look for tools needed for tests 775 (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in your 776 %PATH%, then you can set this variable to the GnuWin32 directory so that 777 lit can find tools needed for tests in that directory. 778 779**LLVM_NATIVE_TOOL_DIR**:STRING 780 Full path to a directory containing executables for the build host 781 (containing binaries such as ``llvm-tblgen`` and ``clang-tblgen``). This is 782 intended for cross-compiling: if the user sets this variable and the 783 directory contains executables with the expected names, no separate 784 native versions of those executables will be built. 785 786**LLVM_NO_INSTALL_NAME_DIR_FOR_BUILD_TREE**:BOOL 787 Defaults to ``OFF``. If set to ``ON``, CMake's default logic for library IDs 788 on Darwin in the build tree will be used. Otherwise the install-time library 789 IDs will be used in the build tree as well. Mainly useful when other CMake 790 library ID control variables (e.g., ``CMAKE_INSTALL_NAME_DIR``) are being 791 set to non-standard values. 792 793**LLVM_OPTIMIZED_TABLEGEN**:BOOL 794 If enabled and building a debug or asserts build the CMake build system will 795 generate a Release build tree to build a fully optimized tablegen for use 796 during the build. Enabling this option can significantly speed up build times 797 especially when building LLVM in Debug configurations. 798 799**LLVM_PARALLEL_{COMPILE,LINK,TABLEGEN}_JOBS**:STRING 800 Limit the maximum number of concurrent compilation, link or 801 tablegen jobs respectively. The default total number of parallel jobs is 802 determined by the number of logical CPUs. 803 804**LLVM_PROFDATA_FILE**:PATH 805 Path to a profdata file to pass into clang's -fprofile-instr-use flag. This 806 can only be specified if you're building with clang. 807 808**LLVM_RAM_PER_{COMPILE,LINK,TABLEGEN}_JOB**:STRING 809 Limit the number of concurrent compile, link or tablegen jobs 810 respectively, depending on available physical memory. The value 811 specified is in MB. The respective 812 ``LLVM_PARALLEL_{COMPILE,LINK,TABLEGEN}_JOBS`` variable is 813 overwritten by computing the memory size divided by the 814 specified value. The largest memory user is linking, but remember 815 that jobs in the other categories might run in parallel to the link 816 jobs, and you need to consider their memory requirements when 817 in a memory-limited environment. Using a 818 ``-DLLVM_RAM_PER_LINK_JOB=10000`` is a good approximation. On ELF 819 platforms debug builds can reduce link-time memory pressure by also 820 using ``LLVM_USE_SPLIT_DWARF``. 821 822**LLVM_REVERSE_ITERATION**:BOOL 823 If enabled, all supported unordered llvm containers would be iterated in 824 reverse order. This is useful for uncovering non-determinism caused by 825 iteration of unordered containers. 826 827**LLVM_STATIC_LINK_CXX_STDLIB**:BOOL 828 Statically link to the C++ standard library if possible. This uses the flag 829 "-static-libstdc++", but a Clang host compiler will statically link to libc++ 830 if used in conjunction with the **LLVM_ENABLE_LIBCXX** flag. Defaults to OFF. 831 832**LLVM_TABLEGEN**:STRING 833 Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is 834 intended for cross-compiling: if the user sets this variable, no native 835 TableGen will be created. 836 837**LLVM_TARGET_ARCH**:STRING 838 LLVM target to use for native code generation. This is required for JIT 839 generation. It defaults to "host", meaning that it shall pick the architecture 840 of the machine where LLVM is being built. If you are cross-compiling, set it 841 to the target architecture name. 842 843**LLVM_TARGETS_TO_BUILD**:STRING 844 Semicolon-separated list of targets to build, or *all* for building all 845 targets. Case-sensitive. Defaults to *all*. Example: 846 ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``. 847 The full list, as of March 2023, is: 848 ``AArch64;AMDGPU;ARM;AVR;BPF;Hexagon;Lanai;LoongArch;Mips;MSP430;NVPTX;PowerPC;RISCV;Sparc;SystemZ;VE;WebAssembly;X86;XCore`` 849 850 You can also specify ``host`` or ``Native`` to automatically detect and 851 include the target corresponding to the host machine's architecture, or 852 use ``all`` to include all available targets. 853 For example, on an x86_64 machine, specifying ``-DLLVM_TARGETS_TO_BUILD=host`` 854 will include the ``X86`` target. 855 856**LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN**:BOOL 857 If enabled, the compiler version check will only warn when using a toolchain 858 which is about to be deprecated, instead of emitting an error. 859 860**LLVM_UBSAN_FLAGS**:STRING 861 Defines the set of compile flags used to enable UBSan. Only used if 862 ``LLVM_USE_SANITIZER`` contains ``Undefined``. This can be used to override 863 the default set of UBSan flags. 864 865**LLVM_UNREACHABLE_OPTIMIZE**:BOOL 866 This flag controls the behavior of `llvm_unreachable()` in release build 867 (when assertions are disabled in general). When ON (default) then 868 `llvm_unreachable()` is considered "undefined behavior" and optimized as 869 such. When OFF it is instead replaced with a guaranteed "trap". 870 871**LLVM_USE_INTEL_JITEVENTS**:BOOL 872 Enable building support for Intel JIT Events API. Defaults to OFF. 873 874**LLVM_USE_LINKER**:STRING 875 Add ``-fuse-ld={name}`` to the link invocation. The possible value depend on 876 your compiler, for clang the value can be an absolute path to your custom 877 linker, otherwise clang will prefix the name with ``ld.`` and apply its usual 878 search. For example to link LLVM with the Gold linker, cmake can be invoked 879 with ``-DLLVM_USE_LINKER=gold``. 880 881**LLVM_USE_OPROFILE**:BOOL 882 Enable building OProfile JIT support. Defaults to OFF. 883 884**LLVM_USE_PERF**:BOOL 885 Enable building support for Perf (linux profiling tool) JIT support. Defaults to OFF. 886 887**LLVM_USE_RELATIVE_PATHS_IN_FILES**:BOOL 888 Rewrite absolute source paths in sources and debug info to relative ones. The 889 source prefix can be adjusted via the LLVM_SOURCE_PREFIX variable. 890 891**LLVM_USE_RELATIVE_PATHS_IN_DEBUG_INFO**:BOOL 892 Rewrite absolute source paths in debug info to relative ones. The source prefix 893 can be adjusted via the LLVM_SOURCE_PREFIX variable. 894 895**LLVM_USE_SANITIZER**:STRING 896 Define the sanitizer used to build LLVM binaries and tests. Possible values 897 are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``, 898 ``DataFlow``, and ``Address;Undefined``. Defaults to empty string. 899 900**LLVM_USE_SPLIT_DWARF**:BOOL 901 If enabled CMake will pass ``-gsplit-dwarf`` to the compiler. This option 902 reduces link-time memory usage by reducing the amount of debug information that 903 the linker needs to resolve. It is recommended for platforms using the ELF object 904 format, like Linux systems when linker memory usage is too high. 905 906**SPHINX_EXECUTABLE**:STRING 907 The path to the ``sphinx-build`` executable detected by CMake. 908 For installation instructions, see 909 https://www.sphinx-doc.org/en/master/usage/installation.html 910 911**SPHINX_OUTPUT_HTML**:BOOL 912 If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for 913 building the documentation as html are added (but not built by default unless 914 ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the 915 source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html`` 916 and ``docs-lld-html``). Defaults to ON. 917 918**SPHINX_OUTPUT_MAN**:BOOL 919 If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building 920 the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS`` 921 is enabled). Currently the only target added is ``docs-llvm-man``. Defaults 922 to ON. 923 924**SPHINX_WARNINGS_AS_ERRORS**:BOOL 925 If enabled then sphinx documentation warnings will be treated as 926 errors. Defaults to ON. 927 928Advanced variables 929~~~~~~~~~~~~~~~~~~ 930 931These are niche, and changing them from their defaults is more likely to cause 932things to go wrong. They are also unstable across LLVM versions. 933 934**LLVM_EXAMPLES_INSTALL_DIR**:STRING 935 The path for examples of using LLVM, relative to the *CMAKE_INSTALL_PREFIX*. 936 Only matters if *LLVM_BUILD_EXAMPLES* is enabled. 937 Defaults to "examples". 938 939**LLVM_TOOLS_INSTALL_DIR**:STRING 940 The path to install the main LLVM tools, relative to the *CMAKE_INSTALL_PREFIX*. 941 Defaults to *CMAKE_INSTALL_BINDIR*. 942 943**LLVM_UTILS_INSTALL_DIR**:STRING 944 The path to install auxiliary LLVM utilities, relative to the *CMAKE_INSTALL_PREFIX*. 945 Only matters if *LLVM_INSTALL_UTILS* is enabled. 946 Defaults to *LLVM_TOOLS_INSTALL_DIR*. 947 948CMake Caches 949============ 950 951Recently LLVM and Clang have been adding some more complicated build system 952features. Utilizing these new features often involves a complicated chain of 953CMake variables passed on the command line. Clang provides a collection of CMake 954cache scripts to make these features more approachable. 955 956CMake cache files are utilized using CMake's -C flag: 957 958.. code-block:: console 959 960 $ cmake -C <path to cache file> <path to sources> 961 962CMake cache scripts are processed in an isolated scope, only cached variables 963remain set when the main configuration runs. CMake cached variables do not reset 964variables that are already set unless the FORCE option is specified. 965 966A few notes about CMake Caches: 967 968- Order of command line arguments is important 969 970 - -D arguments specified before -C are set before the cache is processed and 971 can be read inside the cache file 972 - -D arguments specified after -C are set after the cache is processed and 973 are unset inside the cache file 974 975- All -D arguments will override cache file settings 976- CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command 977 line arguments 978- It is recommended that all -D options should be specified *before* -C 979 980For more information about some of the advanced build configurations supported 981via Cache files see :doc:`AdvancedBuilds`. 982 983Executing the Tests 984=================== 985 986Testing is performed when the *check-all* target is built. For instance, if you are 987using Makefiles, execute this command in the root of your build directory: 988 989.. code-block:: console 990 991 $ make check-all 992 993On Visual Studio, you may run tests by building the project "check-all". 994For more information about testing, see the :doc:`TestingGuide`. 995 996Cross compiling 997=============== 998 999See `this wiki page <https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/CrossCompiling>`_ for 1000generic instructions on how to cross-compile with CMake. It goes into detailed 1001explanations and may seem daunting, but it is not. On the wiki page there are 1002several examples including toolchain files. Go directly to the 1003``Information how to set up various cross compiling toolchains`` section 1004for a quick solution. 1005 1006Also see the `LLVM-related variables`_ section for variables used when 1007cross-compiling. 1008 1009Embedding LLVM in your project 1010============================== 1011 1012From LLVM 3.5 onwards the CMake build system exports LLVM libraries as 1013importable CMake targets. This means that clients of LLVM can now reliably use 1014CMake to develop their own LLVM-based projects against an installed version of 1015LLVM regardless of how it was built. 1016 1017Here is a simple example of a CMakeLists.txt file that imports the LLVM libraries 1018and uses them to build a simple application ``simple-tool``. 1019 1020.. code-block:: cmake 1021 1022 cmake_minimum_required(VERSION 3.20.0) 1023 project(SimpleProject) 1024 1025 find_package(LLVM REQUIRED CONFIG) 1026 1027 message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}") 1028 message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}") 1029 1030 # Set your project compile flags. 1031 # E.g. if using the C++ header files 1032 # you will need to enable C++11 support 1033 # for your compiler. 1034 1035 include_directories(${LLVM_INCLUDE_DIRS}) 1036 separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS}) 1037 add_definitions(${LLVM_DEFINITIONS_LIST}) 1038 1039 # Now build our tools 1040 add_executable(simple-tool tool.cpp) 1041 1042 # Find the libraries that correspond to the LLVM components 1043 # that we wish to use 1044 llvm_map_components_to_libnames(llvm_libs support core irreader) 1045 1046 # Link against LLVM libraries 1047 target_link_libraries(simple-tool ${llvm_libs}) 1048 1049The ``find_package(...)`` directive when used in CONFIG mode (as in the above 1050example) will look for the ``LLVMConfig.cmake`` file in various locations (see 1051cmake manual for details). It creates a ``LLVM_DIR`` cache entry to save the 1052directory where ``LLVMConfig.cmake`` is found or allows the user to specify the 1053directory (e.g. by passing ``-DLLVM_DIR=/usr/lib/cmake/llvm`` to 1054the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``). 1055 1056This file is available in two different locations. 1057 1058* ``<LLVM_INSTALL_PACKAGE_DIR>/LLVMConfig.cmake`` where 1059 ``<LLVM_INSTALL_PACKAGE_DIR>`` is the location where LLVM CMake modules are 1060 installed as part of an installed version of LLVM. This is typically 1061 ``cmake/llvm/`` within the lib directory. On Linux, this is typically 1062 ``/usr/lib/cmake/llvm/LLVMConfig.cmake``. 1063 1064* ``<LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmake`` where 1065 ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this is only 1066 available when building LLVM with CMake.** 1067 1068If LLVM is installed in your operating system's normal installation prefix (e.g. 1069on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will 1070automatically find LLVM if it is installed correctly. If LLVM is not installed 1071or you wish to build directly against the LLVM build tree you can use 1072``LLVM_DIR`` as previously mentioned. 1073 1074The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables 1075include 1076 1077``LLVM_CMAKE_DIR`` 1078 The path to the LLVM CMake directory (i.e. the directory containing 1079 LLVMConfig.cmake). 1080 1081``LLVM_DEFINITIONS`` 1082 A list of preprocessor defines that should be used when building against LLVM. 1083 1084``LLVM_ENABLE_ASSERTIONS`` 1085 This is set to ON if LLVM was built with assertions, otherwise OFF. 1086 1087``LLVM_ENABLE_EH`` 1088 This is set to ON if LLVM was built with exception handling (EH) enabled, 1089 otherwise OFF. 1090 1091``LLVM_ENABLE_RTTI`` 1092 This is set to ON if LLVM was built with run time type information (RTTI), 1093 otherwise OFF. 1094 1095``LLVM_INCLUDE_DIRS`` 1096 A list of include paths to directories containing LLVM header files. 1097 1098``LLVM_PACKAGE_VERSION`` 1099 The LLVM version. This string can be used with CMake conditionals, e.g., ``if 1100 (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``. 1101 1102``LLVM_TOOLS_BINARY_DIR`` 1103 The path to the directory containing the LLVM tools (e.g. ``llvm-as``). 1104 1105Notice that in the above example we link ``simple-tool`` against several LLVM 1106libraries. The list of libraries is determined by using the 1107``llvm_map_components_to_libnames()`` CMake function. For a list of available 1108components look at the output of running ``llvm-config --components``. 1109 1110Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was 1111used instead of ``llvm_map_components_to_libnames()``. This is now deprecated 1112and will be removed in a future version of LLVM. 1113 1114.. _cmake-out-of-source-pass: 1115 1116Developing LLVM passes out of source 1117------------------------------------ 1118 1119It is possible to develop LLVM passes out of LLVM's source tree (i.e. against an 1120installed or built LLVM). An example of a project layout is provided below. 1121 1122.. code-block:: none 1123 1124 <project dir>/ 1125 | 1126 CMakeLists.txt 1127 <pass name>/ 1128 | 1129 CMakeLists.txt 1130 Pass.cpp 1131 ... 1132 1133Contents of ``<project dir>/CMakeLists.txt``: 1134 1135.. code-block:: cmake 1136 1137 find_package(LLVM REQUIRED CONFIG) 1138 1139 separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS}) 1140 add_definitions(${LLVM_DEFINITIONS_LIST}) 1141 include_directories(${LLVM_INCLUDE_DIRS}) 1142 1143 add_subdirectory(<pass name>) 1144 1145Contents of ``<project dir>/<pass name>/CMakeLists.txt``: 1146 1147.. code-block:: cmake 1148 1149 add_library(LLVMPassname MODULE Pass.cpp) 1150 1151Note if you intend for this pass to be merged into the LLVM source tree at some 1152point in the future it might make more sense to use LLVM's internal 1153``add_llvm_library`` function with the MODULE argument instead by... 1154 1155 1156Adding the following to ``<project dir>/CMakeLists.txt`` (after 1157``find_package(LLVM ...)``) 1158 1159.. code-block:: cmake 1160 1161 list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}") 1162 include(AddLLVM) 1163 1164And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to 1165 1166.. code-block:: cmake 1167 1168 add_llvm_library(LLVMPassname MODULE 1169 Pass.cpp 1170 ) 1171 1172When you are done developing your pass, you may wish to integrate it 1173into the LLVM source tree. You can achieve it in two easy steps: 1174 1175#. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transforms`` directory. 1176 1177#. Adding ``add_subdirectory(<pass name>)`` line into 1178 ``<LLVM root>/lib/Transforms/CMakeLists.txt``. 1179 1180Compiler/Platform-specific topics 1181================================= 1182 1183Notes for specific compilers and/or platforms. 1184 1185Windows 1186------- 1187 1188**LLVM_COMPILER_JOBS**:STRING 1189 Specifies the maximum number of parallel compiler jobs to use per project 1190 when building with msbuild or Visual Studio. Only supported for the Visual 1191 Studio 2010 CMake generator. 0 means use all processors. Default is 0. 1192 1193**CMAKE_MT**:STRING 1194 When compiling with clang-cl, recent CMake versions will default to selecting 1195 `llvm-mt` as the Manifest Tool instead of Microsoft's `mt.exe`. This will 1196 often cause errors like: 1197 1198 .. code-block:: console 1199 1200 -- Check for working C compiler: [...]clang-cl.exe - broken 1201 [...] 1202 MT: command [...] failed (exit code 0x1) with the following output: 1203 llvm-mt: error: no libxml2 1204 ninja: build stopped: subcommand failed. 1205 1206 To work around this error, set `CMAKE_MT=mt`. 1207