Advanced Build Configurations - LLVM
Hide navigation sidebar Hide table of contents sidebar Back to top Edit this page Toggle table of contents sidebar Advanced Build Configurations # 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 or Building LLVM with CMake pages.
This page is intended for users doing more complex builds. Many of the examples below are written assuming specific CMake Generators. Unless explicitly stated otherwise, these commands should work with any CMake generator. Many of the build configurations mentioned on this documentation page can be utilized by using a CMake cache. A CMake cache is essentially a configuration file that sets the necessary flags for a specific build configuration.
The caches for Clang are located in /clang/cmake/caches within the monorepo. They can be passed to CMake using the -C flag as demonstrated in the examples below along with additional configuration flags. The caches for Flang are located in /flang/cmake/caches within the monorepo. They can be passed to CMake using the -C flag as demonstrated in the examples below along with additional configuration flags. Due to the Flang’s heavy reliance on Clang, these caches ensure equal handling of Flang and Clang, resulting in both being built within the same arrangement.
Bootstrap Builds # The Clang CMake build system supports bootstrap (aka multi-stage) builds. At a high level, a multi-stage build is a chain of builds that pass data from one stage into the next. The most common and simple version of this is a traditional bootstrap build. In a simple two-stage bootstrap build, we build clang using the system compiler, then use that just-built clang to build clang again. In CMake this simplest form of a bootstrap build can be configured with a single option, CLANG_ENABLE_BOOTSTRAP . $ cmake -G Ninja -DCMAKE_BUILD_TYPE = Release \ -DCLANG_ENABLE_BOOTSTRAP = On \ -DLLVM_ENABLE_PROJECTS = "clang" \ <path to source>/llvm $ ninja stage2 This command itself isn’t terribly useful because it assumes default configurations for each stage.
The next series of examples utilize CMake cache scripts to provide more complex options. By default, only a few CMake options will be passed between stages. The list, called _BOOTSTRAP_DEFAULT_PASSTHROUGH, is defined in clang/CMakeLists.txt . To force the passing of the variables between stages, use the -DCLANG_BOOTSTRAP_PASSTHROUGH CMake option, each variable separated by a “;”. For example: $ cmake -G Ninja -DCMAKE_BUILD_TYPE = Release \ -DCLANG_ENABLE_BOOTSTRAP = On \ -DCLANG_BOOTSTRAP_PASSTHROUGH = "CMAKE_INSTALL_PREFIX;CMAKE_VERBOSE_MAKEFILE" \ -DLLVM_ENABLE_PROJECTS = "clang" \ <path to source>/llvm $ ninja stage2 CMake options starting with BOOTSTRAP_ will be passed only to the stage2 build.
This gives the opportunity to use Clang-specific build flags. For example, the following CMake call will enable -fno-addrsig only during the stage2 build for C and C++. $ cmake [ .. ] -DBOOTSTRAP_CMAKE_CXX_FLAGS = '-fno-addrsig' -DBOOTSTRAP_CMAKE_C_FLAGS = '-fno-addrsig' [ .. ] The clang build system refers to builds as stages. A stage1 build is a standard build using the compiler installed on the host, and a stage2 build is built using the stage1 compiler.
This nomenclature holds up to more stages too. In general, a stage*n* build is built using the output from stage*n-1*. Apple Clang Builds (A More Complex Bootstrap) # Apple’s Clang builds are a slightly more complicated example of the simple bootstrapping scenario. Apple Clang is built using a 2-stage build. The stage1 compiler is a host-only compiler with some options set. The stage1 compiler is a balance of optimization vs build time because it is a throwaway.
The stage2 compiler is the fully optimized compiler intended to ship to users. Setting up these compilers requires a lot of options. To simplify the configuration, the Apple Clang build settings are contained in CMake Cache files. You can build an Apple Clang compiler using the following commands: $ cmake -G Ninja -C <path to source>/clang/cmake/caches/Apple-stage1.cmake <path to source>/llvm $ ninja stage2-distribution This CMake invocation configures the stage1 host compiler, and sets CLANG_BOOTSTRAP_CMAKE_ARGS to pass the Apple-stage2.cmake cache script to the stage2 configuration step.
When you build the stage2-distribution target it builds the minimal stage1 compiler and required tools, then configures and builds the stage2 compiler based on the settings in Apple-stage2.cmake. This pattern of using cache scripts to set complex settings, and specifically to make later stage builds include cache scripts is common in our more advanced build configurations. Multi-stage PGO # Profile-Guided Optimization (PGO) is a really great way to optimize the code clang generates.
Our multi-stage PGO builds are a workflow for generating PGO profiles that can be used to optimize clang. At a high level, the way PGO works is that you build an instrumented compiler, then you run the instrumented compiler against sample source files. While the instrumented compiler runs it will output a bunch of files containing performance counters ( .profraw files). After generating all the profraw files you use llvm-profdata to merge the files into a single profdata file that you can feed into the LLVM_PROFDATA_FILE option.
Our PGO.cmake cache automates that whole process. You can use it for configuration with CMake with the following command: $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \ <path to source>/llvm Similarly, to build optimized Flang (along with Clang), you can use the following command: $ cmake -G Ninja -C <path to source>/flang/cmake/caches/PGO.cmake \ <path to source>/llvm There are several additional options that the cache file also accepts to modify the build, particularly the PGO_INSTRUMENT_LTO option.
Setting this option to Thin or Full will enable ThinLTO or full LTO respectively, further enhancing the performance gains from a PGO build by enabling interprocedural optimizations. For example, to run a CMake configuration for a PGO build that also enables ThinLTO, use the following command: $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \ -DPGO_INSTRUMENT_LTO = Thin \ <path to source>/llvm By default, the compiler will generate profile data by compiling a simple hello world program.
You can also configure the use of an external project for generating profile data that may be a better fit for your use case. The project you specify must either be a lit test suite (use the CLANG_PGO_TRAINING_DATA option) or a CMake project (use the CLANG_PERF_TRAINING_DATA_SOURCE_DIR option). For example, if you wanted to use the LLVM Test Suite to generate profile data you would use the following command: $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \ -DBOOTSTRAP_CLANG_PGO_TRAINING_DATA_SOURCE_DIR = <path to llvm-test-suite> \ -DBOOTSTRAP_CLANG_PGO_TRAINING_DEPS = runtimes Similarly, to build optimized Flang (along with Clang), you can use the following command: $ cmake -G Ninja -C <path to source>/flang/cmake/caches/PGO.cmake \ -DBOOTSTRAP_CLANG_PGO_TRAINING_DATA_SOURCE_DIR = <path to llvm-test-suite> \ -DBOOTSTRAP_CLANG_PGO_TRAINING_DEPS = runtimes \ -DBOOTSTRAP_FLANG_PGO_TRAINING_DATA_SOURCE_DIR = <path to llvm-test-suite> \ -DBOOTSTRAP_FLANG_PGO_TRAINING_DATA_SOURCE_CMAKE_ARGS = "-DTEST_SUITE_SUBDIRS=Fortran" \ -DBOOTSTRAP_FLANG_PGO_TRAINING_DEPS = runtimes The BOOTSTRAP_ prefix tells CMake to pass the variables on to the instrumented stage two build.
And the CLANG_PGO_TRAINING_DEPS option lets you specify additional build targets to build before building the external project. The LLVM Test Suite requires compiler-rt to build, so we need to add the runtimes target as a dependency. After c
The rest of this page is on the live site.