1============================= 2Advanced Build Configurations 3============================= 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11`CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake 12does not build the project, it generates the files needed by your build tool 13(GNU make, Visual Studio, etc.) for building LLVM. 14 15If **you are a new contributor**, please start with the :doc:`GettingStarted` or 16:doc:`CMake` pages. This page is intended for users doing more complex builds. 17 18Many of the examples below are written assuming specific CMake Generators. 19Unless otherwise explicitly called out these commands should work with any CMake 20generator. 21 22Bootstrap Builds 23================ 24 25The Clang CMake build system supports bootstrap (aka multi-stage) builds. At a 26high level a multi-stage build is a chain of builds that pass data from one 27stage into the next. The most common and simple version of this is a traditional 28bootstrap build. 29 30In a simple two-stage bootstrap build, we build clang using the system compiler, 31then use that just-built clang to build clang again. In CMake this simplest form 32of a bootstrap build can be configured with a single option, 33CLANG_ENABLE_BOOTSTRAP. 34 35.. code-block:: console 36 37 $ cmake -G Ninja -DCLANG_ENABLE_BOOTSTRAP=On <path to source> 38 $ ninja stage2 39 40This command itself isn't terribly useful because it assumes default 41configurations for each stage. The next series of examples utilize CMake cache 42scripts to provide more complex options. 43 44By default, only a few CMake options will be passed between stages. 45The list, called _BOOTSTRAP_DEFAULT_PASSTHROUGH, is defined in clang/CMakeLists.txt. 46To force the passing of the variables between stages, use the -DCLANG_BOOTSTRAP_PASSTHROUGH 47CMake option, each variable separated by a ";". As example: 48 49.. code-block:: console 50 51 $ cmake -G Ninja -DCLANG_ENABLE_BOOTSTRAP=On -DCLANG_BOOTSTRAP_PASSTHROUGH="CMAKE_INSTALL_PREFIX;CMAKE_VERBOSE_MAKEFILE" <path to source> 52 $ ninja stage2 53 54The clang build system refers to builds as stages. A stage1 build is a standard 55build using the compiler installed on the host, and a stage2 build is built 56using the stage1 compiler. This nomenclature holds up to more stages too. In 57general a stage*n* build is built using the output from stage*n-1*. 58 59Apple Clang Builds (A More Complex Bootstrap) 60============================================= 61 62Apple's Clang builds are a slightly more complicated example of the simple 63bootstrapping scenario. Apple Clang is built using a 2-stage build. 64 65The stage1 compiler is a host-only compiler with some options set. The stage1 66compiler is a balance of optimization vs build time because it is a throwaway. 67The stage2 compiler is the fully optimized compiler intended to ship to users. 68 69Setting up these compilers requires a lot of options. To simplify the 70configuration the Apple Clang build settings are contained in CMake Cache files. 71You can build an Apple Clang compiler using the following commands: 72 73.. code-block:: console 74 75 $ cmake -G Ninja -C <path to clang>/cmake/caches/Apple-stage1.cmake <path to source> 76 $ ninja stage2-distribution 77 78This CMake invocation configures the stage1 host compiler, and sets 79CLANG_BOOTSTRAP_CMAKE_ARGS to pass the Apple-stage2.cmake cache script to the 80stage2 configuration step. 81 82When you build the stage2-distribution target it builds the minimal stage1 83compiler and required tools, then configures and builds the stage2 compiler 84based on the settings in Apple-stage2.cmake. 85 86This pattern of using cache scripts to set complex settings, and specifically to 87make later stage builds include cache scripts is common in our more advanced 88build configurations. 89 90Multi-stage PGO 91=============== 92 93Profile-Guided Optimizations (PGO) is a really great way to optimize the code 94clang generates. Our multi-stage PGO builds are a workflow for generating PGO 95profiles that can be used to optimize clang. 96 97At a high level, the way PGO works is that you build an instrumented compiler, 98then you run the instrumented compiler against sample source files. While the 99instrumented compiler runs it will output a bunch of files containing 100performance counters (.profraw files). After generating all the profraw files 101you use llvm-profdata to merge the files into a single profdata file that you 102can feed into the LLVM_PROFDATA_FILE option. 103 104Our PGO.cmake cache script automates that whole process. You can use it by 105running: 106 107.. code-block:: console 108 109 $ cmake -G Ninja -C <path_to_clang>/cmake/caches/PGO.cmake <source dir> 110 $ ninja stage2-instrumented-generate-profdata 111 112If you let that run for a few hours or so, it will place a profdata file in your 113build directory. This takes a really long time because it builds clang twice, 114and you *must* have compiler-rt in your build tree. 115 116This process uses any source files under the perf-training directory as training 117data as long as the source files are marked up with LIT-style RUN lines. 118 119After it finishes you can use “find . -name clang.profdata” to find it, but it 120should be at a path something like: 121 122.. code-block:: console 123 124 <build dir>/tools/clang/stage2-instrumented-bins/utils/perf-training/clang.profdata 125 126You can feed that file into the LLVM_PROFDATA_FILE option when you build your 127optimized compiler. 128 129The PGO came cache has a slightly different stage naming scheme than other 130multi-stage builds. It generates three stages; stage1, stage2-instrumented, and 131stage2. Both of the stage2 builds are built using the stage1 compiler. 132 133The PGO came cache generates the following additional targets: 134 135**stage2-instrumented** 136 Builds a stage1 x86 compiler, runtime, and required tools (llvm-config, 137 llvm-profdata) then uses that compiler to build an instrumented stage2 compiler. 138 139**stage2-instrumented-generate-profdata** 140 Depends on "stage2-instrumented" and will use the instrumented compiler to 141 generate profdata based on the training files in <clang>/utils/perf-training 142 143**stage2** 144 Depends of "stage2-instrumented-generate-profdata" and will use the stage1 145 compiler with the stage2 profdata to build a PGO-optimized compiler. 146 147**stage2-check-llvm** 148 Depends on stage2 and runs check-llvm using the stage2 compiler. 149 150**stage2-check-clang** 151 Depends on stage2 and runs check-clang using the stage2 compiler. 152 153**stage2-check-all** 154 Depends on stage2 and runs check-all using the stage2 compiler. 155 156**stage2-test-suite** 157 Depends on stage2 and runs the test-suite using the stage3 compiler (requires 158 in-tree test-suite). 159 1603-Stage Non-Determinism 161======================= 162 163In the ancient lore of compilers non-determinism is like the multi-headed hydra. 164Whenever its head pops up, terror and chaos ensue. 165 166Historically one of the tests to verify that a compiler was deterministic would 167be a three stage build. The idea of a three stage build is you take your sources 168and build a compiler (stage1), then use that compiler to rebuild the sources 169(stage2), then you use that compiler to rebuild the sources a third time 170(stage3) with an identical configuration to the stage2 build. At the end of 171this, you have a stage2 and stage3 compiler that should be bit-for-bit 172identical. 173 174You can perform one of these 3-stage builds with LLVM & clang using the 175following commands: 176 177.. code-block:: console 178 179 $ cmake -G Ninja -C <path_to_clang>/cmake/caches/3-stage.cmake <source dir> 180 $ ninja stage3 181 182After the build you can compare the stage2 & stage3 compilers. We have a bot 183setup `here <http://lab.llvm.org:8011/builders/clang-3stage-ubuntu>`_ that runs 184this build and compare configuration. 185