Building LLVM with CMake¶

Introduction ¶

CMake is a cross-platform build-generator tool. CMake does not build the project, it generates the files needed by your build tool (GNU make, Visual Studio, etc.) for building LLVM.

If you are a new contributor, please start with the Getting Started with the LLVM System page. This page is geared for existing contributors moving from the legacy configure/make system.

If you are really anxious about getting a functional LLVM build, go to the Quick start section. If you are a CMake novice, start with Basic CMake usage and then go back to the Quick start section once you know what you are doing. The Options and variables section is a reference for customizing your build. If you already have experience with CMake, this is the recommended starting point.

This page is geared towards users of the LLVM CMake build. If you’re looking for information about modifying the LLVM CMake build system you may want to see the CMake Primer page. It has a basic overview of the CMake language.

Quick start ¶

We use here the command-line, non-interactive CMake interface.

Download and install CMake. Version 3.13.4 is the minimum required.
Open a shell. Your development tools must be reachable from this shell through the PATH environment variable.
Create a build directory. Building LLVM in the source directory is not supported. cd to this directory:
```
$ mkdir mybuilddir
$ cd mybuilddir
```
Execute this command in the shell replacing path/to/llvm/source/root with the path to the root of your LLVM source tree:
```
$ cmake path/to/llvm/source/root
```
CMake will detect your development environment, perform a series of tests, and generate the files required for building LLVM. CMake will use default values for all build parameters. See the Options and variables section for a list of build parameters that you can modify.

This can fail if CMake can’t detect your toolset, or if it thinks that the environment is not sane enough. In this case, make sure that the toolset that you intend to use is the only one reachable from the shell, and that the shell itself is the correct one for your development environment. CMake will refuse to build MinGW makefiles if you have a POSIX shell reachable through the PATH environment variable, for instance. You can force CMake to use a given build tool; for instructions, see the Usage section, below. You may also wish to control which targets LLVM enables, or which LLVM components are built; see the Frequently Used LLVM-related variables below.
After CMake has finished running, proceed to use IDE project files, or start the build from the build directory:
```
$ cmake --build .
```
The --build option tells cmake to invoke the underlying build tool (make, ninja, xcodebuild, msbuild, etc.)

The underlying build tool can be invoked directly, of course, but the --build option is portable.
After LLVM has finished building, install it from the build directory:
```
$ cmake --build . --target install
```
The --target option with install parameter in addition to the --build option tells cmake to build the install target.

It is possible to set a different install prefix at installation time by invoking the cmake_install.cmake script generated in the build directory:
```
$ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
```

Basic CMake usage ¶

This section explains basic aspects of CMake which you may need in your day-to-day usage.

CMake comes with extensive documentation, in the form of html files, and as online help accessible via the cmake executable itself. Execute cmake --help for further help options.

CMake allows you to specify a build tool (e.g., GNU make, Visual Studio, or Xcode). If not specified on the command line, CMake tries to guess which build tool to use, based on your environment. Once it has identified your build tool, CMake uses the corresponding Generator to create files for your build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can explicitly specify the generator with the command line option -G "Name of the generator". To see a list of the available generators on your system, execute

$ cmake --help

This will list the generator names at the end of the help text.

Generators’ names are case-sensitive, and may contain spaces. For this reason, you should enter them exactly as they are listed in the cmake --help output, in quotes. For example, to generate project files specifically for Visual Studio 12, you can execute:

$ cmake -G "Visual Studio 12" path/to/llvm/source/root

For a given development platform there can be more than one adequate generator. If you use Visual Studio, “NMake Makefiles” is a generator you can use for building with NMake. By default, CMake chooses the most specific generator supported by your development environment. If you want an alternative generator, you must tell this to CMake with the -G option.

Options and variables ¶

Variables customize how the build will be generated. Options are boolean variables, with possible values ON/OFF. Options and variables are defined on the CMake command line like this:

$ cmake -DVARIABLE=value path/to/llvm/source

You can set a variable after the initial CMake invocation to change its value. You can also undefine a variable:

$ cmake -UVARIABLE path/to/llvm/source

Variables are stored in the CMake cache. This is a file named CMakeCache.txt stored at the root of your build directory that is generated by cmake. Editing it yourself is not recommended.

Variables are listed in the CMake cache and later in this document with the variable name and type separated by a colon. You can also specify the variable and type on the CMake command line:

$ cmake -DVARIABLE:TYPE=value path/to/llvm/source

Frequently-used CMake variables ¶

Here are some of the CMake variables that are used often, along with a brief explanation. For full documentation, consult the CMake manual, or execute cmake --help-variable VARIABLE_NAME. See Frequently Used LLVM-related Variables below for information about commonly used variables that control features of LLVM and enabled subprojects.

CMAKE_BUILD_TYPE:STRING: Sets the build type for make-based generators. Possible values are Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE such as Visual Studio, you should use the IDE settings to set the build type. Be aware that Release and RelWithDebInfo use different optimization levels on most platforms. Be aware that Release and RelWithDebInfo use different optimization levels on most platforms, and that the default value of LLVM_ENABLE_ASSERTIONS is affected.
CMAKE_INSTALL_PREFIX:PATH: Path where LLVM will be installed when the “install” target is built.
CMAKE_{C,CXX}_FLAGS:STRING: Extra flags to use when compiling C and C++ source files respectively.
CMAKE_{C,CXX}_COMPILER:STRING: Specify the C and C++ compilers to use. If you have multiple compilers installed, CMake might not default to the one you wish to use.

Rarely-used CMake variables ¶

Here are some of the CMake variables that are rarely used, along with a brief explanation and LLVM-related notes. For full documentation, consult the CMake manual, or execute cmake --help-variable VARIABLE_NAME.

CMAKE_CXX_STANDARD:STRING: Sets the C++ standard to conform to when building LLVM. Possible values are 14, 17, 20. LLVM Requires C++ 14 or higher. This defaults to 14.
CMAKE_INSTALL_BINDIR:PATH: The path to install executables, relative to the CMAKE_INSTALL_PREFIX. Defaults to “bin”.
CMAKE_INSTALL_INCLUDEDIR:PATH: The path to install header files, relative to the CMAKE_INSTALL_PREFIX. Defaults to “include”.
CMAKE_INSTALL_DOCDIR:PATH: The path to install documentation, relative to the CMAKE_INSTALL_PREFIX. Defaults to “share/doc”.
CMAKE_INSTALL_MANDIR:PATH: The path to install manpage files, relative to the CMAKE_INSTALL_PREFIX. Defaults to “share/man”.

LLVM-related variables ¶

These variables provide fine control over the build of LLVM and enabled sub-projects. Nearly all of these variable names begin with LLVM_.

BUILD_SHARED_LIBS:BOOL: Flag indicating if each LLVM component (e.g. Support) is built as a shared library (ON) or as a static library (OFF). Its default value is OFF. On Windows, shared libraries may be used when building with MinGW, including mingw-w64, but not when building with the Microsoft toolchain.

Note

BUILD_SHARED_LIBS is only recommended for use by LLVM developers. If you want to build LLVM as a shared library, you should use the LLVM_BUILD_LLVM_DYLIB option.
LLVM_ABI_BREAKING_CHECKS:STRING: Used to decide if LLVM should be built with ABI breaking checks or not. Allowed values are WITH_ASSERTS (default), FORCE_ON and FORCE_OFF. WITH_ASSERTS turns on ABI breaking checks in an assertion enabled build. FORCE_ON (FORCE_OFF) turns them on (off) irrespective of whether normal (NDEBUG-based) assertions are enabled or not. A version of LLVM built with ABI breaking checks is not ABI compatible with a version built without it.
LLVM_APPEND_VC_REV:BOOL: Embed version control revision info (Git revision id). The version info is provided by the LLVM_REVISION macro in llvm/include/llvm/Support/VCSRevision.h. Developers using git who don’t need revision info can disable this option to avoid re-linking most binaries after a branch switch. Defaults to ON.
LLVM_BUILD_32_BITS:BOOL: Build 32-bit executables and libraries on 64-bit systems. This option is available only on some 64-bit Unix systems. Defaults to OFF.
LLVM_BUILD_BENCHMARKS:BOOL: Adds benchmarks to the list of default targets. Defaults to OFF.
LLVM_BUILD_DOCS:BOOL: Adds all enabled documentation targets (i.e. Doxgyen and Sphinx targets) as dependencies of the default build targets. This results in all of the (enabled) documentation targets being as part of a normal build. If the install target is run then this also enables all built documentation targets to be installed. Defaults to OFF. To enable a particular documentation target, see see LLVM_ENABLE_SPHINX and LLVM_ENABLE_DOXYGEN.
LLVM_BUILD_EXAMPLES:BOOL: Build LLVM examples. Defaults to OFF. Targets for building each example are generated in any case. See documentation for LLVM_BUILD_TOOLS above for more details.
LLVM_BUILD_INSTRUMENTED_COVERAGE:BOOL: If enabled, source-based code coverage instrumentation is enabled while building llvm. If CMake can locate the code coverage scripts and the llvm-cov and llvm-profdata tools that pair to your compiler, the build will also generate the generate-coverage-report target to generate the code coverage report for LLVM, and the clear-profile-data utility target to delete captured profile data. See documentation for LLVM_CODE_COVERAGE_TARGETS and LLVM_COVERAGE_SOURCE_DIRS for more information on configuring code coverage reports.
LLVM_CODE_COVERAGE_TARGETS:STRING: If set to a semicolon separated list of targets, those targets will be used to drive the code coverage reports. If unset, the target list will be constructed using the LLVM build’s CMake export list.
LLVM_COVERAGE_SOURCE_DIRS:STRING: If set to a semicolon separated list of directories, the coverage reports will limit code coverage summaries to just the listed directories. If unset, coverage reports will include all sources identified by the tooling.
LLVM_BUILD_LLVM_DYLIB:BOOL: If enabled, the target for building the libLLVM shared library is added. This library contains all of LLVM’s components in a single shared library. Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS. Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB is also ON. The components in the library can be customised by setting LLVM_DYLIB_COMPONENTS to a list of the desired components. This option is not available on Windows.
LLVM_BUILD_TESTS:BOOL: Include LLVM unit tests in the ‘all’ build target. Defaults to OFF. Targets for building each unit test are generated in any case. You can build a specific unit test using the targets defined under unittests, such as ADTTests, IRTests, SupportTests, etc. (Search for add_llvm_unittest in the subdirectories of unittests for a complete list of unit tests.) It is possible to build all unit tests with the target UnitTests.
LLVM_BUILD_TOOLS:BOOL: Build LLVM tools. Defaults to ON. Targets for building each tool are generated in any case. You can build a tool separately by invoking its target. For example, you can build llvm-as with a Makefile-based system by executing make llvm-as at the root of your build directory.
LLVM_CCACHE_BUILD:BOOL: If enabled and the ccache program is available, then LLVM will be built using ccache to speed up rebuilds of LLVM and its components. Defaults to OFF. The size and location of the cache maintained by ccache can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment variables, respectively.
LLVM_CREATE_XCODE_TOOLCHAIN:BOOL: macOS Only: If enabled CMake will generate a target named ‘install-xcode-toolchain’. This target will create a directory at $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can be used to override the default system tools.
LLVM_DEFAULT_TARGET_TRIPLE:STRING: LLVM target to use for code generation when no target is explicitly specified. It defaults to “host”, meaning that it shall pick the architecture of the machine where LLVM is being built. If you are building a cross-compiler, set it to the target triple of your desired architecture.
LLVM_DOXYGEN_QCH_FILENAME:STRING: The filename of the Qt Compressed Help file that will be generated when -DLLVM_ENABLE_DOXYGEN=ON and -DLLVM_ENABLE_DOXYGEN_QT_HELP=ON are given. Defaults to org.llvm.qch. This option is only useful in combination with -DLLVM_ENABLE_DOXYGEN_QT_HELP=ON; otherwise it has no effect.
LLVM_DOXYGEN_QHELPGENERATOR_PATH:STRING: The path to the qhelpgenerator executable. Defaults to whatever CMake’s find_program() can find. This option is only useful in combination with -DLLVM_ENABLE_DOXYGEN_QT_HELP=ON; otherwise it has no effect.
LLVM_DOXYGEN_QHP_CUST_FILTER_NAME:STRING: See Qt Help Project for more information. Defaults to the CMake variable ${PACKAGE_STRING} which is a combination of the package name and version string. This filter can then be used in Qt Creator to select only documentation from LLVM when browsing through all the help files that you might have loaded. This option is only useful in combination with -DLLVM_ENABLE_DOXYGEN_QT_HELP=ON; otherwise it has no effect.

LLVM_DOXYGEN_QHP_NAMESPACE:STRING: Namespace under which the intermediate Qt Help Project file lives. See Qt Help Project for more information. Defaults to “org.llvm”. This option is only useful in combination with -DLLVM_ENABLE_DOXYGEN_QT_HELP=ON; otherwise it has no effect.
LLVM_DOXYGEN_SVG:BOOL: Uses .svg files instead of .png files for graphs in the Doxygen output. Defaults to OFF.
LLVM_ENABLE_ASSERTIONS:BOOL: Enables code assertions. Defaults to ON if and only if CMAKE_BUILD_TYPE is Debug.
LLVM_ENABLE_BINDINGS:BOOL: If disabled, do not try to build the OCaml and go bindings.
LLVM_ENABLE_DIA_SDK:BOOL: Enable building with MSVC DIA SDK for PDB debugging support. Available only with MSVC. Defaults to ON.
LLVM_ENABLE_DOXYGEN:BOOL: Enables the generation of browsable HTML documentation using doxygen. Defaults to OFF.
LLVM_ENABLE_DOXYGEN_QT_HELP:BOOL: Enables the generation of a Qt Compressed Help file. Defaults to OFF. This affects the make target doxygen-llvm. When enabled, apart from the normal HTML output generated by doxygen, this will produce a QCH file named org.llvm.qch. You can then load this file into Qt Creator. This option is only useful in combination with -DLLVM_ENABLE_DOXYGEN=ON; otherwise this has no effect.
LLVM_ENABLE_EH:BOOL: Build LLVM with exception-handling support. This is necessary if you wish to link against LLVM libraries and make use of C++ exceptions in your own code that need to propagate through LLVM code. Defaults to OFF.
LLVM_ENABLE_EXPENSIVE_CHECKS:BOOL: Enable additional time/memory expensive checking. Defaults to OFF.
LLVM_ENABLE_FFI:BOOL: Indicates whether the LLVM Interpreter will be linked with the Foreign Function Interface library (libffi) in order to enable calling external functions. If the library or its headers are installed in a custom location, you can also set the variables FFI_INCLUDE_DIR and FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found, respectively. Defaults to OFF.
LLVM_ENABLE_IDE:BOOL: Tell the build system that an IDE is being used. This in turn disables the creation of certain convenience build system targets, such as the various install-* and check-* targets, since IDEs

Documentation

Getting Involved

Additional Links

This Page