Building LLVM with CMake

1.Introduction

CMAKE is a cross-platform build generator tool. cmake will not build the project, it will generate the files needed by the build tools (gnu make, Visual Studio, etc.) needed to build llvm.

If you are a new participant, please start from the "LLVM System Getting Started" page. This page is for existing participants who moved from the old configuration / generation system.

If you are really worried about getting a functional LLVM build, go to the quick start section. If you are new to CMAKE, start with basic CMAKE usage and then return to the quick start section after you know what you are doing. The options and variables section is a reference for custom builds. If you already have experience with cmake, this is the recommended starting point.

This page is for users built by llvm cmake. If you are 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 cmake language.

2.Quick start

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

• Download and install cmake. The minimum requirement is version 3.4.3.
• Open a shell. Your development tools must be accessible from this shell through the path environment variable.
• Create a build directory. llvm does not support compilation in the source directory. cd to this directory:

$ mkdir mybuilddir
$ cd mybuilddir

• Run this command in the shell and replace path / to / llvm / source / root with the root path of the llvm source tree:

$ cmake path/to/llvm/source/root

CMake will detect your development environment, perform a series of tests, and generate the files needed to build LLVM. CMake will use default values ​​for all build parameters. For a list of modifiable generation parameters, see the "Options and Variables" section.

If CMake cannot detect your toolset, or it thinks the environment is not sound enough, this operation may fail. In this example, make sure that the tool set you plan to use is the only tool set that can be accessed from the shell, and that the shell itself is the right tool set for your development environment. For example, if you have a POSIX shell that can be accessed through the PATH environment variable, CMake will refuse to build the MinGW makefile. You can force CMake to use a given build tool; for instructions, see the usage section below.

• After CMake finishes running, continue to use IDE project files, or start building from the build directory:

$ cmake --build .

The --build option tells cmake to call the underlying build tools (make, ninja, xcodebuild, msbuild, etc.).

Of course, the underlying build tools can be called directly, but the --build option is portable.

• After LLVM finishes building, install from the build directory:

$ cmake --build . --target install

In addition to the --build option, the --target option also carries an install parameter, which tells cmake to build an installation target.

You can set a different installation prefix during installation by calling cmake_install. The cmake script generated in the build directory:

$ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake

3.Basic CMake usage

This section explains the basic aspects of CMake, which you may need in your daily use.

CMake comes with a large number of documents, which are provided in the form of html files, and provide online help through the CMake executable file itself. Run cmake --help for more help options.

CMake allows you to specify a build tool (for example, GNU make, Visual Studio, or Xcode). If not specified on the command line, CMake will try to guess which build tool to use based on your environment. Once the build tool is determined, CMake uses the corresponding generator to create a file for the build tool (for example, makefile or Visual Studio or Xcode project file). You can use the command line option -G "Name of the generator" to specify the generator explicitly. To view the list of generators available on the system, execute

$ cmake --help

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

The name of the generator is case sensitive and may contain spaces. For this reason, you should enter them in quotation marks as listed in the cmake -help output. For example, to generate a specific project file 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 multiple sufficient generators. If you use Visual Studio, "NMake makefile" is a generator that can be built with NMake. By default, CMake selects the most specific generator supported by your development environment. If you want an alternative generator, you must tell CMake to use the -G option.

4.Options and variables

Variables customize how they are built. The options are Boolean variables and the possible values ​​are ON / OFF. Options and variables are defined on the CMake command line as follows:

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

You can set a variable to change its value after the initial CMake call. 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 in the root directory of the build directory generated by cmake. It is not recommended that you edit it yourself.

Variables are listed in the CMake cache. Later in this document, variable names and types are separated by colons. You can also specify variables and types on the CMake command line:

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

5.Frequently-used CMake variables

Here are some frequently used CMake variables, along with simple explanations and llvm-specific notes. For complete documentation, please refer to the CMake manual, or execute CMake --help-variable VARIABLE_NAME.

CMAKE_BUILD_TYPE: string

Set the generation type for token-based generators. Possible values ​​are Release, Debug, RelWithDebInfo, and MinSizeRel. If you are using an IDE such as Visual Studio, you should use IDE settings to set the build type. Note that Release and RelWithDebInfo use different levels of optimization on most platforms.

CMAKE_INSTALL_PREFIX: path

The path to which LLVM will be installed when calling "make install" or building an "install" target.

LLVM_LIBDIR_SUFFIX: string

Attach an additional suffix to the directory where the library is to be installed. On 64-bit architecture, you can use -DLLVM_LIBDIR_SUFFIX = 64 to install the library to / usr / lib64.

CMAKE_C_FLAGS: string

Extra flags to use when compiling C source files.

CMAKE_CXX_FLAGS: string

Extra flags to use when compiling c ++ source files.

6. LLVM-specific variables

LLVM_TARGETS_TO_BUILD:字符串

A list of targets to be built separated by semicolons, or all used to build all targets. Case sensitive. The default is all. For example: -DLLVM_TARGETS_TO_BUILD = "X86; PowerPC".

LLVM_BUILD_TOOLS: BOOL

Build LLVM tool. The default is ON. In any case, the goal of building each tool is generated. You can build tools individually by calling the target of the tool. For example, you can use the makefile-based system to build llvm-as by executing make llvm-as in the root directory of the build directory.

LLVM_INCLUDE_TOOLS: BOOL

Generate targets for LLVM tools. The default is ON. You can use this option to disable generation of build targets for LLVM tools.

LLVM_INSTALL_BINUTILS_SYMLINKS: BOOL

Install a symbolic link from the name of the binutils tool to the corresponding LLVM tool. For example, ar links the symbol to llvm-ar.

LLVM_BUILD_EXAMPLES: BOOL

Example of building LLVM. The default value is OFF. In any case, a goal to build each example will be generated. For more details, see the LLVM_BUILD_TOOLS document above.

LLVM_INCLUDE_EXAMPLES: BOOL

Generate build targets for LLVM examples. The default is ON. You can use this option to disable the build target that generates LLVM examples.

LLVM_BUILD_TESTS: BOOL

Build LLVM unit test. In any case, the goal of building each unit test is generated. You can use the goals defined under unit tests to build a specific unit test, such as ADTTests, IRTests, SupportTests, etc. (search for add_llvm_unittest in the unit test subdirectory to get a complete list of unit tests) You can use target unit tests to build all unit tests.

LLVM_INCLUDE_TESTS: BOOL

Generate targets for LLVM unit test generation. The default is ON. You can use this option to disable generation of build targets for LLVM unit tests.

LLVM_BUILD_BENCHMARKS: BOOL

Add the benchmark to the default target list. The default is OFF.

LLVM_INCLUDE_BENCHMARKS: BOOL

Generate build targets for LLVM benchmarks. The default is ON.

LLVM_APPEND_VC_REV: BOOL

Embedded version control revision information (svn revision number or Git revision id)). The version information is provided by the LLVM_REVISION macro in llvm / include / llvm / Support / vcsupdate.h. Git developers who do not need revision information can disable this option to avoid relinking most binaries after branch switching. The default is ON.