Lines Matching +full:ninja +full:- +full:build
2 Advanced Build Configurations
11 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
12 does not build the project, it generates the files needed by your build tool
22 Many of the build configurations mentioned on this documentation page can be
24 file that sets the necessary flags for a specific build configuration. The caches
26 can be passed to CMake using the :code:`-C` flag as demonstrated in the examples
32 The Clang CMake build system supports bootstrap (aka multi-stage) builds. At a
33 high level a multi-stage build is a chain of builds that pass data from one
35 bootstrap build.
37 In a simple two-stage bootstrap build, we build clang using the system compiler,
38 then use that just-built clang to build clang again. In CMake this simplest form
39 of a bootstrap build can be configured with a single option,
42 .. code-block:: console
44 $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
45 -DCLANG_ENABLE_BOOTSTRAP=On \
46 -DLLVM_ENABLE_PROJECTS="clang" \
48 $ ninja stage2
56 To force the passing of the variables between stages, use the -DCLANG_BOOTSTRAP_PASSTHROUGH
59 .. code-block:: console
61 $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release \
62 -DCLANG_ENABLE_BOOTSTRAP=On \
63 -DCLANG_BOOTSTRAP_PASSTHROUGH="CMAKE_INSTALL_PREFIX;CMAKE_VERBOSE_MAKEFILE" \
64 -DLLVM_ENABLE_PROJECTS="clang" \
66 $ ninja stage2
68 CMake options starting by ``BOOTSTRAP_`` will be passed only to the stage2 build.
69 This gives the opportunity to use Clang specific build flags.
70 For example, the following CMake call will enabled '-fno-addrsig' only during
71 the stage2 build for C and C++.
73 .. code-block:: console
75 …$ cmake [..] -DBOOTSTRAP_CMAKE_CXX_FLAGS='-fno-addrsig' -DBOOTSTRAP_CMAKE_C_FLAGS='-fno-addrsig' …
77 The clang build system refers to builds as stages. A stage1 build is a standard
78 build using the compiler installed on the host, and a stage2 build is built
80 general a stage*n* build is built using the output from stage*n-1*.
86 bootstrapping scenario. Apple Clang is built using a 2-stage build.
88 The stage1 compiler is a host-only compiler with some options set. The stage1
89 compiler is a balance of optimization vs build time because it is a throwaway.
93 configuration the Apple Clang build settings are contained in CMake Cache files.
94 You can build an Apple Clang compiler using the following commands:
96 .. code-block:: console
98 $ cmake -G Ninja -C <path to source>/clang/cmake/caches/Apple-stage1.cmake <path to source>/llvm
99 $ ninja stage2-distribution
102 CLANG_BOOTSTRAP_CMAKE_ARGS to pass the Apple-stage2.cmake cache script to the
105 When you build the stage2-distribution target it builds the minimal stage1
107 based on the settings in Apple-stage2.cmake.
111 build configurations.
113 Multi-stage PGO
116 Profile-Guided Optimizations (PGO) is a really great way to optimize the code
117 clang generates. Our multi-stage PGO builds are a workflow for generating PGO
120 At a high level, the way PGO works is that you build an instrumented compiler,
124 you use llvm-profdata to merge the files into a single profdata file that you
130 .. code-block:: console
132 $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \
136 the build, particularly the PGO_INSTRUMENT_LTO option. Setting this option to
138 the performance gains from a PGO build by enabling interprocedural
139 optimizations. For example, to run a CMake configuration for a PGO build
142 .. code-block:: console
144 $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \
145 -DPGO_INSTRUMENT_LTO=Thin \
156 `LLVM Test Suite <https://github.com/llvm/llvm-test-suite/>`_ to generate
159 .. code-block:: console
161 $ cmake -G Ninja -C <path to source>/clang/cmake/caches/PGO.cmake \
162 -DBOOTSTRAP_CLANG_PGO_TRAINING_DATA_SOURCE_DIR=<path to llvm-test-suite> \
163 -DBOOTSTRAP_CLANG_PGO_TRAINING_DEPS=runtimes
166 stage two build. And the CLANG_PGO_TRAINING_DEPS option let's you specify
167 additional build targets to build before building the external project. The
168 LLVM Test Suite requires compiler-rt to build, so we need to add the
171 After configuration, building the stage2-instrumented-generate-profdata target
172 will automatically build the stage1 compiler, build the instrumented compiler
176 .. code-block:: console
178 $ ninja stage2-instrumented-generate-profdata
181 build directory. This takes a really long time because it builds clang twice,
182 and you *must* have compiler-rt in your build tree.
184 This process uses any source files under the perf-training directory as training
185 data as long as the source files are marked up with LIT-style RUN lines.
187 After it finishes you can use :code:`find . -name clang.profdata` to find it, but it
190 .. code-block:: console
192 <build dir>/tools/clang/stage2-instrumented-bins/utils/perf-training/clang.profdata
194 You can feed that file into the LLVM_PROFDATA_FILE option when you build your
197 It may be necessary to build additional targets before running perf training, such as
201 .. code-block:: cmake
206 multi-stage builds. It generates three stages: stage1, stage2-instrumented, and
211 **stage2-instrumented**
212 Builds a stage1 compiler, runtime, and required tools (llvm-config,
213 llvm-profdata) then uses that compiler to build an instrumented stage2 compiler.
215 **stage2-instrumented-generate-profdata**
216 Depends on stage2-instrumented and will use the instrumented compiler to
217 generate profdata based on the training files in clang/utils/perf-training
220 Depends on stage2-instrumented-generate-profdata and will use the stage1
221 compiler with the stage2 profdata to build a PGO-optimized compiler.
223 **stage2-check-llvm**
224 Depends on stage2 and runs check-llvm using the stage2 compiler.
226 **stage2-check-clang**
227 Depends on stage2 and runs check-clang using the stage2 compiler.
229 **stage2-check-all**
230 Depends on stage2 and runs check-all using the stage2 compiler.
232 **stage2-test-suite**
233 Depends on stage2 and runs the test-suite using the stage2 compiler (requires
234 in-tree test-suite).
239 `BOLT <https://github.com/llvm/llvm-project/blob/main/bolt/README.md>`_
241 post-link by profiling them at runtime and then using that information to
243 at the binary level. There are also CMake caches available to build
246 To configure a single-stage build that builds LLVM/Clang and then optimizes
249 .. code-block:: console
251 $ cmake <path to source>/llvm -C <path to source>/clang/cmake/caches/BOLT.cmake
253 Then, build the BOLT-optimized binary by running the following ninja command:
255 .. code-block:: console
257 $ ninja clang-bolt
259 If you're seeing errors in the build process, try building with a recent
264 significant runtime speedup. To configure a three stage PGO build with ThinLTO
268 .. code-block:: console
270 $ cmake -G Ninja <path to source>/llvm \
271 -C <path to source>/clang/cmake/caches/BOLT-PGO.cmake \
272 -DBOOTSTRAP_LLVM_ENABLE_LLD=ON \
273 -DBOOTSTRAP_BOOTSTRAP_LLVM_ENABLE_LLD=ON \
274 -DPGO_INSTRUMENT_LTO=Thin
276 Then, to build the final optimized binary, build the stage2-clang-bolt target:
278 .. code-block:: console
280 $ ninja stage2-clang-bolt
282 3-Stage Non-Determinism
285 In the ancient lore of compilers non-determinism is like the multi-headed hydra.
289 be a three stage build. The idea of a three stage build is you take your sources
290 and build a compiler (stage1), then use that compiler to rebuild the sources
292 (stage3) with an identical configuration to the stage2 build. At the end of
293 this, you have a stage2 and stage3 compiler that should be bit-for-bit
296 You can perform one of these 3-stage builds with LLVM and clang using the
299 .. code-block:: console
301 $ cmake -G Ninja -C <path to source>/clang/cmake/caches/3-stage.cmake <path to source>/llvm
302 $ ninja stage3
304 After the build you can compare the stage2 and stage3 compilers.