Lines Matching +full:llvm +full:- +full:build
2 Building LLVM with CMake
11 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
12 does not build the project, it generates the files needed by your build tool
13 (GNU make, Visual Studio, etc.) for building LLVM.
19 If you are really anxious about getting a functional LLVM build, go to the
22 `Options and variables`_ section is a reference for customizing your build. If
25 This page is geared towards users of the LLVM CMake build. If you're looking for
26 information about modifying the LLVM CMake build system you may want to see the
34 We use here the command-line, non-interactive CMake interface.
42 #. Create a build directory. Building LLVM in the source
45 .. code-block:: console
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:
53 .. code-block:: console
55 $ cmake path/to/llvm/source/root
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.
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
69 also wish to control which targets LLVM enables, or which LLVM
70 components are built; see the `Frequently Used LLVM-related
74 the build from the build directory:
76 .. code-block:: console
78 $ cmake --build .
80 The ``--build`` option tells ``cmake`` to invoke the underlying build
83 The underlying build tool can be invoked directly, of course, but
84 the ``--build`` option is portable.
86 #. After LLVM has finished building, install it from the build directory:
88 .. code-block:: console
90 $ cmake --build . --target install
92 The ``--target`` option with ``install`` parameter in addition to
93 the ``--build`` option tells ``cmake`` to build the ``install`` target.
97 build directory:
99 .. code-block:: console
101 $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
110 which you may need in your day-to-day usage.
114 --help`` for further help options.
116 CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,
118 build tool to use, based on your environment. Once it has identified your
119 build tool, CMake uses the corresponding *Generator* to create files for your
120 build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can
121 explicitly specify the generator with the command line option ``-G "Name of the
124 .. code-block:: console
126 $ cmake --help
130 Generators' names are case-sensitive, and may contain spaces. For this reason,
131 you should enter them exactly as they are listed in the ``cmake --help``
135 .. code-block:: console
137 $ cmake -G "Visual Studio 12" path/to/llvm/source/root
143 you must tell this to CMake with the ``-G`` option.
154 Variables customize how the build will be generated. Options are boolean
158 .. code-block:: console
160 $ cmake -DVARIABLE=value path/to/llvm/source
165 .. code-block:: console
167 $ cmake -UVARIABLE path/to/llvm/source
170 stored at the root of your build directory that is generated by ``cmake``.
177 .. code-block:: console
179 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
183 Frequently-used CMake variables
184 -------------------------------
188 or execute ``cmake --help-variable VARIABLE_NAME``. See `Frequently
189 Used LLVM-related Variables`_ below for information about commonly
190 used variables that control features of LLVM and enabled subprojects.
200 Build Type Optimizations Debug Info Assertions Best suited for
202 **Release** For Speed No No Users of LLVM and Clang
203 **Debug** None Yes Yes Developers of LLVM
208 * Optimizations make LLVM/Clang run faster, but can be an impediment for
209 step-by-step debugging.
214 down LLVM and Clang when enabled, but can be useful during development.
219 the IDE settings to set the build type.
221 Note: on Windows (building with MSVC or clang-cl), CMake's **RelWithDebInfo**
223 **Release** build type with :ref:`LLVM_ENABLE_PDB <llvm_enable_pdb>` set
227 Path where LLVM will be installed when the "install" target is built.
237 .. _Frequently Used LLVM-related variables:
239 Frequently Used LLVM-related variables
240 --------------------------------------
243 LLVM variables that are frequently used to control that. The full
244 description is in `LLVM-related variables`_ below.
248 or lldb by specifying ``-DLLVM_ENABLE_PROJECTS="clang;lldb"``.
252 libc++ or libc++abi by specifying ``-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
256 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
260 Building the llvm toolchain can use a lot of resources, particularly
264 32GB machine, specify ``-G Ninja -DLLVM_PARALLEL_LINK_JOBS=2``.
268 your native target with, for example, ``-DLLVM_TARGETS_TO_BUILD=X86``.
274 ``-DLLVM_USE_LINKER=lld``.
276 Rarely-used CMake variables
277 ---------------------------
280 explanation and LLVM-related notes. For full documentation, consult the CMake
281 manual, or execute ``cmake --help-variable VARIABLE_NAME``.
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.
303 .. _LLVM-related variables:
305 LLVM-related variables
306 -----------------------
308 These variables provide fine control over the build of LLVM and
309 enabled sub-projects. Nearly all of these variable names begin with
312 .. _LLVM-related variables BUILD_SHARED_LIBS:
315 Flag indicating if each LLVM component (e.g. Support) is built as a shared
318 mingw-w64, but not when building with the Microsoft toolchain.
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
325 Used to decide if LLVM should be built with ABI breaking checks or
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
334 Adding a semicolon separated list of additional build types to this flag
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
351 This is useful in environments where git is not available or non-functional
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.
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``
370 Build LLVM examples. Defaults to OFF. Targets for building each example are
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
387 This library contains all of LLVM's components in a single shared library.
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
401 possible to build all unit tests with the target *UnitTests*.
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.
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.
420 constructed using the LLVM build's CMake export list.
429 'install-xcode-toolchain'. This target will create a directory at
434 LLVM target to use for code generation when no target is explicitly specified.
436 of the machine where LLVM is being built. If you are building a cross-compiler,
441 ``-DLLVM_ENABLE_DOXYGEN=ON`` and
442 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
443 ``org.llvm.qch``.
445 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
451 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
458 be used in Qt Creator to select only documentation from LLVM when browsing
460 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
463 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
468 for more information. Defaults to "org.llvm". This option is only useful in
469 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
483 If disabled, do not try to build the OCaml bindings.
492 of ~0.1%. `COVERAGE` is an ABI-breaking option.
504 This affects the make target ``doxygen-llvm``. When enabled, apart from
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``;
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.
519 Indicates whether the LLVM Interpreter will be linked with the Foreign Function
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>`_
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
539 If the host compiler and linker supports the stdlib flag, -stdlib=libc++ is
544 Enable building with libpfm to support hardware counter measurements in LLVM
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
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
559 Add ``-flto`` or ``-flto=`` flags to the compile and link command
560 lines, enabling link-time optimization. Possible values are ``Off``,
565 <https://clang.llvm.org/docs/Modules.html>`_.
570 For Windows builds using MSVC or clang-cl, generate PDB files when
574 Enable pedantic mode. This disables compiler-specific extensions, if
578 Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
582 Semicolon-separated list of projects to build, or *all* for building all
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
591 ``bolt;clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;lld;lldb;mlir;openmp;polly;pstl``
599 Build LLVM with run-time type information. Defaults to OFF.
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>`_.
613 ``libc;libunwind;libcxxabi;pstl;libcxx;compiler-rt;openmp;llvm-libgcc;offload``
620 If specified, CMake will search for the ``sphinx-build`` executable and will make
625 Build with threads support, if available. Defaults to ON.
635 Stop and fail the build, if a compiler warning is triggered. Defaults to OFF.
642 Used to decide if LLVM tools should support compression/decompression with
647 Used to decide if LLVM tools should support compression/decompression with
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.
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
660 ``-DLLVM_EXTERNAL_PROJECTS="Foo;Bar"
661 -DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo
662 -DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``.
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
682 If enabled, the compiler and standard library versions won't be checked. LLVM
687 Generate build targets for the LLVM benchmarks. Defaults to ON.
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.
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
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.
709 Install symlinks from the binutils tool names to the corresponding LLVM tools.
710 For example, ar will be symlinked to llvm-ar.
713 Install symliks from the cctools tool names to the corresponding LLVM tools.
714 For example, lipo will be symlinked to llvm-lipo.
717 The path to install OCamldoc-generated HTML documentation to. This path can
719 ``${CMAKE_INSTALL_DOCDIR}/llvm/ocaml-html``.
722 The path to install Sphinx-generated HTML documentation to. This path can
724 ``${CMAKE_INSTALL_DOCDIR}/llvm/html``.
731 The path to install Doxygen-generated HTML documentation to. This path can
733 ``${CMAKE_INSTALL_DOCDIR}/llvm/doxygen-html``.
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
739 midly improves Clang build times, by about 5-10%. At the moment, rpmalloc,
743 .. code-block:: console
746 $ D:\llvm-project> cmake ... -DLLVM_INTEGRATED_CRT_ALLOC=D:\git\rpmalloc
749 Release target, add -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded.
750 Note that rpmalloc is also supported natively in-tree, see option below.
753 Similar to LLVM_INTEGRATED_CRT_ALLOC, embeds the in-tree rpmalloc into the
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
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
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
791 set to non-standard values.
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.
805 Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
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
823 If enabled, all supported unordered llvm containers would be iterated in
824 reverse order. This is useful for uncovering non-determinism caused by
829 "-static-libstdc++", but a Clang host compiler will statically link to libc++
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
838 LLVM target to use for native code generation. This is required for JIT
840 of the machine where LLVM is being built. If you are cross-compiling, set it
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"``.
853 For example, on an x86_64 machine, specifying ``-DLLVM_TARGETS_TO_BUILD=host``
866 This flag controls the behavior of `llvm_unreachable()` in release build
875 Add ``-fuse-ld={name}`` to the link invocation. The possible value depend on
878 search. For example to link LLVM with the Gold linker, cmake can be invoked
879 with ``-DLLVM_USE_LINKER=gold``.
896 Define the sanitizer used to build LLVM binaries and tests. Possible values
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
907 The path to the ``sphinx-build`` executable detected by CMake.
909 https://www.sphinx-doc.org/en/master/usage/installation.html
915 source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
916 and ``docs-lld-html``). Defaults to ON.
921 is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
932 things to go wrong. They are also unstable across LLVM versions.
935 The path for examples of using LLVM, relative to the *CMAKE_INSTALL_PREFIX*.
940 The path to install the main LLVM tools, relative to the *CMAKE_INSTALL_PREFIX*.
944 The path to install auxiliary LLVM utilities, relative to the *CMAKE_INSTALL_PREFIX*.
951 Recently LLVM and Clang have been adding some more complicated build system
956 CMake cache files are utilized using CMake's -C flag:
958 .. code-block:: console
960 $ cmake -C <path to cache file> <path to sources>
968 - Order of command line arguments is important
970 - -D arguments specified before -C are set before the cache is processed and
972 - -D arguments specified after -C are set after the cache is processed and
975 - All -D arguments will override cache file settings
976 - CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command
978 - It is recommended that all -D options should be specified *before* -C
980 For more information about some of the advanced build configurations supported
986 Testing is performed when the *check-all* target is built. For instance, if you are
987 using Makefiles, execute this command in the root of your build directory:
989 .. code-block:: console
991 $ make check-all
993 On Visual Studio, you may run tests by building the project "check-all".
1000 generic instructions on how to cross-compile with CMake. It goes into detailed
1006 Also see the `LLVM-related variables`_ section for variables used when
1007 cross-compiling.
1009 Embedding LLVM in your project
1012 From LLVM 3.5 onwards the CMake build system exports LLVM libraries as
1013 importable CMake targets. This means that clients of LLVM can now reliably use
1014 CMake to develop their own LLVM-based projects against an installed version of
1015 LLVM regardless of how it was built.
1017 Here is a simple example of a CMakeLists.txt file that imports the LLVM libraries
1018 and uses them to build a simple application ``simple-tool``.
1020 .. code-block:: cmake
1025 find_package(LLVM REQUIRED CONFIG)
1027 message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
1039 # Now build our tools
1040 add_executable(simple-tool tool.cpp)
1042 # Find the libraries that correspond to the LLVM components
1046 # Link against LLVM libraries
1047 target_link_libraries(simple-tool ${llvm_libs})
1053 directory (e.g. by passing ``-DLLVM_DIR=/usr/lib/cmake/llvm`` to
1054 the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
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``.
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.**
1068 If LLVM is installed in your operating system's normal installation prefix (e.g.
1069 on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
1070 automatically find LLVM if it is installed correctly. If LLVM is not installed
1071 or you wish to build directly against the LLVM build tree you can use
1078 The path to the LLVM CMake directory (i.e. the directory containing
1082 A list of preprocessor defines that should be used when building against LLVM.
1085 This is set to ON if LLVM was built with assertions, otherwise OFF.
1088 This is set to ON if LLVM was built with exception handling (EH) enabled,
1092 This is set to ON if LLVM was built with run time type information (RTTI),
1096 A list of include paths to directories containing LLVM header files.
1099 The LLVM version. This string can be used with CMake conditionals, e.g., ``if
1103 The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
1105 Notice that in the above example we link ``simple-tool`` against several LLVM
1108 components look at the output of running ``llvm-config --components``.
1110 Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
1112 and will be removed in a future version of LLVM.
1114 .. _cmake-out-of-source-pass:
1116 Developing LLVM passes out of source
1117 ------------------------------------
1119 It is possible to develop LLVM passes out of LLVM's source tree (i.e. against an
1120 installed or built LLVM). An example of a project layout is provided below.
1122 .. code-block:: none
1135 .. code-block:: cmake
1137 find_package(LLVM REQUIRED CONFIG)
1147 .. code-block:: cmake
1151 Note if you intend for this pass to be merged into the LLVM source tree at some
1152 point in the future it might make more sense to use LLVM's internal
1157 ``find_package(LLVM ...)``)
1159 .. code-block:: cmake
1166 .. code-block:: cmake
1173 into the LLVM source tree. You can achieve it in two easy steps:
1175 #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transforms`` directory.
1178 ``<LLVM root>/lib/Transforms/CMakeLists.txt``.
1180 Compiler/Platform-specific topics
1186 -------
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
1198 .. code-block:: console
1200 -- Check for working C compiler: [...]clang-cl.exe - broken
1203 llvm-mt: error: no libxml2
1204 ninja: build stopped: subcommand failed.