clang/cmake/caches/README.txt

   1 CMake Caches
   2 ============
   3
   4 This directory contains CMake cache scripts that pre-populate the CMakeCache in
   5 a build directory with commonly used settings.
   6
   7 You can use the caches files with the following CMake invocation:
   8
   9 cmake -G <build system>
  10   -C <path to cache file>
  11   [additional CMake options (i.e. -DCMAKE_INSTALL_PREFIX=<install path>)]
  12   <path to llvm>
  13
  14 Options specified on the command line will override options in the cache files.
  15
  16 The following cache files exist.
  17
  18 Apple-stage1
  19 ------------
  20
  21 The Apple stage1 cache configures a two stage build similar to how Apple builds
  22 the clang shipped with Xcode. The build files generated from this invocation has
  23 a target named "stage2" which performs an LTO build of clang.
  24
  25 The Apple-stage2 cache can be used directly to match the build settings Apple
  26 uses in shipping builds without doing a full bootstrap build.
  27
  28 PGO
  29 ---
  30
  31 The PGO CMake cache can be used to generate a multi-stage instrumented compiler.
  32 You can configure your build directory with the following invocation of CMake:
  33
  34 cmake -G <generator> -C <path_to_clang>/cmake/caches/PGO.cmake <source dir>
  35
  36 After configuration the following additional targets will be generated:
  37
  38 stage2-instrumented:
  39 Builds a stage1 x86 compiler, runtime, and required tools (llvm-config,
  40 llvm-profdata) then uses that compiler to build an instrumented stage2 compiler.
  41
  42 stage2-instrumented-generate-profdata:
  43 Depends on "stage2-instrumented" and will use the instrumented compiler to
  44 generate profdata based on the training files in <clang>/utils/perf-training
  45
  46 stage2:
  47 Depends on "stage2-instrumented-generate-profdata" and will use the stage1
  48 compiler with the stage2 profdata to build a PGO-optimized compiler.
  49
  50 stage2-check-llvm:
  51 Depends on stage2 and runs check-llvm using the stage3 compiler.
  52
  53 stage2-check-clang:
  54 Depends on stage2 and runs check-clang using the stage3 compiler.
  55
  56 stage2-check-all:
  57 Depends on stage2 and runs check-all using the stage3 compiler.
  58
  59 stage2-test-suite:
  60 Depends on stage2 and runs the test-suite using the stage3 compiler (requires
  61 in-tree test-suite).
  62
  63 3-stage
  64 -------
  65
  66 This cache file can be used to generate a 3-stage clang build. You can configure
  67 using the following CMake command:
  68
  69 cmake -C <path to clang>/cmake/caches/3-stage.cmake -G Ninja <path to llvm>
  70
  71 You can then run "ninja stage3-clang" to build stage1, stage2 and stage3 clangs.
  72
  73 This is useful for finding non-determinism the compiler by verifying that stage2
  74 and stage3 are identical.