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.

  1. Download and install CMake. Version 3.13.4 is the minimum required.

  2. Open a shell. Your development tools must be reachable from this shell through the PATH environment variable.

  3. Create a build directory. Building LLVM in the source directory is not supported. cd to this directory:

    $ mkdir mybuilddir
$ cd mybuilddir

  4. 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.

  5. 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.

  6. 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

This configures the optimization level for make or ninja builds. The default CMAKE_BUILD_TYPE is set to Debug but you should carefully read the list below to figure out what configuration matches your use case the best.

Possible values:

Build Type

Optimizations

Debug Info

Assertions

Best suited for

Release

For Speed

No

No

Users of LLVM and Clang

Debug

None

Yes

Yes

Developers of LLVM

RelWithDebInfo

For Speed

Yes

No

Users that also need Debug

MinSizeRel

For Size

No

No

When disk space matters

  • Optimizations make LLVM/Clang run faster, but can be an impediment for step-by-step debugging.

  • Builds with debug information can use a lot of RAM and disk space and is usually slower to run. You can improve RAM usage by using lld, see the LLVM_USE_LINKER option.

  • Assertions are internal checks to help you find bugs. They typically slow down LLVM and Clang when enabled, but can be useful during development. You can manually set LLVM_ENABLE_ASSERTIONS to override the default from CMAKE_BUILD_TYPE.

If you are using an IDE such as Visual Studio or Xcode, you should use the IDE settings to set the build type.

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”.

CMake Caches

Recently LLVM and Clang have been adding some more complicated build system features. Utilizing these new features often involves a complicated chain of CMake variables passed on the command line. Clang provides a collection of CMake cache scripts to make these features more approachable.

CMake cache files are utilized using CMake’s -C flag:

$ cmake -C <path to cache file> <path to sources>

CMake cache scripts are processed in an isolated scope, only cached variables remain set when the main configuration runs. CMake cached variables do not reset variables that are already set unless the FORCE option is specified.

A few notes about CMake Caches:

  • Order of command line arguments is important

    • -D arguments specified before -C are set before the cache is processed and can be read inside the cache file

    • -D arguments specified after -C are set after the cache is processed and are unset inside the cache file

  • All -D arguments will override cache file settings

  • CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command line arguments

  • It is recommended that all -D options should be specified before -C

For more information about some of the advanced build configurations supported via Cache files see Advanced Build Configurations.

Executing the Tests

Testing is performed when the check-all target is built. For instance, if you are using Makefiles, execute this command in the root of your build directory:

$ make check-all

On Visual Studio, you may run tests by building the project “check-all”. For more information about testing, see the LLVM Testing Infrastructure Guide.

Cross compiling

See this wiki page for generic instructions on how to cross-compile with CMake. It goes into detailed explanations and may seem daunting, but it is not. On the wiki page there are several examples including toolchain files. Go directly to the Information how to set up various cross compiling toolchains section for a quick solution.

Also see the LLVM-related variables section for variables used when cross-compiling.

Embedding LLVM in your project

From LLVM 3.5 onwards the CMake build system exports LLVM libraries as importable CMake targets. This means that clients of LLVM can now reliably use CMake to develop their own LLVM-based projects against an installed version of LLVM regardless of how it was built.

Here is a simple example of a CMakeLists.txt file that imports the LLVM libraries and uses them to build a simple application simple-tool.

cmake_minimum_required(VERSION 3.13.4)
project(SimpleProject)

find_package(LLVM REQUIRED CONFIG)

message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")

# Set your project compile flags.
# E.g. if using the C++ header files
# you will need to enable C++11 support
# for your compiler.

include_directories(${LLVM_INCLUDE_DIRS})
separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
add_definitions(${LLVM_DEFINITIONS_LIST})

# Now build our tools
add_executable(simple-tool tool.cpp)

# Find the libraries that correspond to the LLVM components
# that we wish to use
llvm_map_components_to_libnames(llvm_libs support core irreader)

# Link against LLVM libraries
target_link_libraries(simple-tool ${llvm_libs})

The find_package(...) directive when used in CONFIG mode (as in the above example) will look for the LLVMConfig.cmake file in various locations (see cmake manual for details). It creates a LLVM_DIR cache entry to save the directory where LLVMConfig.cmake is found or allows the user to specify the directory (e.g. by passing -DLLVM_DIR=/usr/lib/cmake/llvm to the cmake command or by setting it directly in ccmake or cmake-gui).

This file is available in two different locations.

  • <LLVM_INSTALL_PACKAGE_DIR>/LLVMConfig.cmake where <LLVM_INSTALL_PACKAGE_DIR> is the location where LLVM CMake modules are installed as part of an installed version of LLVM. This is typically cmake/llvm/ within the lib directory. On Linux, this is typically /usr/lib/cmake/llvm/LLVMConfig.cmake.

  • <LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmake where <LLVM_BUILD_ROOT> is the root of the LLVM build tree. Note: this is only available when building LLVM with CMake.

If LLVM is installed in your operating system’s normal installation prefix (e.g. on Linux this is usually /usr/) find_package(LLVM ...) will automatically find LLVM if it is installed correctly. If LLVM is not installed or you wish to build directly against the LLVM build tree you can use LLVM_DIR as previously mentioned.

The LLVMConfig.cmake file sets various useful variables. Notable variables include

LLVM_CMAKE_DIR

The path to the LLVM CMake directory (i.e. the directory containing LLVMConfig.cmake).

LLVM_DEFINITIONS

A list of preprocessor defines that should be used when building against LLVM.

LLVM_ENABLE_ASSERTIONS

This is set to ON if LLVM was built with assertions, otherwise OFF.

LLVM_ENABLE_EH

This is set to ON if LLVM was built with exception handling (EH) enabled, otherwise OFF.

LLVM_ENABLE_RTTI

This is set to ON if LLVM was built with run time type information (RTTI), otherwise OFF.

LLVM_INCLUDE_DIRS

A list of include paths to directories containing LLVM header files.

LLVM_PACKAGE_VERSION

The LLVM version. This string can be used with CMake conditionals, e.g., if (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5").

LLVM_TOOLS_BINARY_DIR

The path to the directory containing the LLVM tools (e.g. llvm-as).

Notice that in the above example we link simple-tool against several LLVM libraries. The list of libraries is determined by using the llvm_map_components_to_libnames() CMake function. For a list of available components look at the output of running llvm-config --components.

Note that for LLVM < 3.5 llvm_map_components_to_libraries() was used instead of llvm_map_components_to_libnames(). This is now deprecated and will be removed in a future version of LLVM.

Developing LLVM passes out of source

It is possible to develop LLVM passes out of LLVM’s source tree (i.e. against an installed or built LLVM). An example of a project layout is provided below.

<project dir>/
    |
    CMakeLists.txt
    <pass name>/
        |
        CMakeLists.txt
        Pass.cpp
        ...

Contents of <project dir>/CMakeLists.txt:

find_package(LLVM REQUIRED CONFIG)

separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS})
add_definitions(${LLVM_DEFINITIONS_LIST})
include_directories(${LLVM_INCLUDE_DIRS})

add_subdirectory(<pass name>)

Contents of <project dir>/<pass name>/CMakeLists.txt:

add_library(LLVMPassname MODULE Pass.cpp)

Note if you intend for this pass to be merged into the LLVM source tree at some point in the future it might make more sense to use LLVM’s internal add_llvm_library function with the MODULE argument instead by…

Adding the following to <project dir>/CMakeLists.txt (after find_package(LLVM ...))

list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
include(AddLLVM)

And then changing <project dir>/<pass name>/CMakeLists.txt to

add_llvm_library(LLVMPassname MODULE
  Pass.cpp
  )

When you are done developing your pass, you may wish to integrate it into the LLVM source tree. You can achieve it in two easy steps:

  1. Copying <pass name> folder into <LLVM root>/lib/Transform directory.

  2. Adding add_subdirectory(<pass name>) line into <LLVM root>/lib/Transform/CMakeLists.txt.

Compiler/Platform-specific topics

Notes for specific compilers and/or platforms.

Windows

LLVM_COMPILER_JOBS:STRING

Specifies the maximum number of parallel compiler jobs to use per project when building with msbuild or Visual Studio. Only supported for the Visual Studio 2010 CMake generator. 0 means use all processors. Default is 0.

CMAKE_MT:STRING

When compiling with clang-cl, recent CMake versions will default to selecting llvm-mt as the Manifest Tool instead of Microsoft’s mt.exe. This will often cause errors like:

-- Check for working C compiler: [...]clang-cl.exe - broken
[...]
    MT: command [...] failed (exit code 0x1) with the following output:
    llvm-mt: error: no libxml2
    ninja: build stopped: subcommand failed.

To work around this error, set CMAKE_MT=mt.