docs/BuildingADistribution.rst

   1 ===============================
   2 Building a Distribution of LLVM
   3 ===============================
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction
   9 ============
  10
  11 This document is geared toward people who want to build and package LLVM and any
  12 combination of LLVM sub-project tools for distribution. This document covers
  13 useful features of the LLVM build system as well as best practices and general
  14 information about packaging LLVM.
  15
  16 If you are new to CMake you may find the :doc:`CMake` or :doc:`CMakePrimer`
  17 documentation useful. Some of the things covered in this document are the inner
  18 workings of the builds described in the :doc:`AdvancedBuilds` document.
  19
  20 General Distribution Guidance
  21 =============================
  22
  23 When building a distribution of a compiler it is generally advised to perform a
  24 bootstrap build of the compiler. That means building a "stage 1" compiler with
  25 your host toolchain, then building the "stage 2" compiler using the "stage 1"
  26 compiler. This is done so that the compiler you distribute benefits from all the
  27 bug fixes, performance optimizations and general improvements provided by the
  28 new compiler.
  29
  30 In deciding how to build your distribution there are a few trade-offs that you
  31 will need to evaluate. The big two are:
  32
  33 #. Compile time of the distribution against performance of the built compiler
  34
  35 #. Binary size of the distribution against performance of the built compiler
  36
  37 The guidance for maximizing performance of the generated compiler is to use LTO,
  38 PGO, and statically link everything. This will result in an overall larger
  39 distribution, and it will take longer to generate, but it provides the most
  40 opportunity for the compiler to optimize.
  41
  42 The guidance for minimizing distribution size is to dynamically link LLVM and
  43 Clang libraries into the tools to reduce code duplication. This will come at a
  44 substantial performance penalty to the generated binary both because it reduces
  45 optimization opportunity, and because dynamic linking requires resolving symbols
  46 at process launch time, which can be very slow for C++ code.
  47
  48 .. _shared_libs:
  49
  50 .. warning::
  51   One very important note: Distributions should never be built using the
  52   *BUILD_SHARED_LIBS* CMake option. That option exists for optimizing developer
  53   workflow only. Due to design and implementation decisions, LLVM relies on
  54   global data which can end up being duplicated across shared libraries
  55   resulting in bugs. As such this is not a safe way to distribute LLVM or
  56   LLVM-based tools.
  57
  58 The simplest example of building a distribution with reasonable performance is
  59 captured in the DistributionExample CMake cache file located at
  60 clang/cmake/caches/DistributionExample.cmake. The following command will perform
  61 and install the distribution build:
  62
  63 .. code-block:: console
  64
  65   $ cmake -G Ninja -C <path to clang>/cmake/caches/DistributionExample.cmake <path to LLVM source>
  66   $ ninja stage2-distribution
  67   $ ninja stage2-install-distribution
  68
  69 Difference between ``install`` and ``install-distribution``
  70 -----------------------------------------------------------
  71
  72 One subtle but important thing to note is the difference between the ``install``
  73 and ``install-distribution`` targets. The ``install`` target is expected to
  74 install every part of LLVM that your build is configured to generate except the
  75 LLVM testing tools. Alternatively the ``install-distribution`` target, which is
  76 recommended for building distributions, only installs specific parts of LLVM as
  77 specified at configuration time by *LLVM_DISTRIBUTION_COMPONENTS*.
  78
  79 Additionally by default the ``install`` target will install the LLVM testing
  80 tools as the public tools. This can be changed well by setting
  81 *LLVM_INSTALL_TOOLCHAIN_ONLY* to ``On``. The LLVM tools are intended for
  82 development and testing of LLVM, and should only be included in distributions
  83 that support LLVM development.
  84
  85 When building with *LLVM_DISTRIBUTION_COMPONENTS* the build system also
  86 generates a ``distribution`` target which builds all the components specified in
  87 the list. This is a convenience build target to allow building just the
  88 distributed pieces without needing to build all configured targets.
  89
  90 Special Notes for Library-only Distributions
  91 --------------------------------------------
  92
  93 One of the most powerful features of LLVM is its library-first design mentality
  94 and the way you can compose a wide variety of tools using different portions of
  95 LLVM. Even in this situation using *BUILD_SHARED_LIBS* is not supported. If you
  96 want to distribute LLVM as a shared library for use in a tool, the recommended
  97 method is using *LLVM_BUILD_LLVM_DYLIB*, and you can use *LLVM_DYLIB_COMPONENTS*
  98 to configure which LLVM components are part of libLLVM.
  99
 100 Options for Optimizing LLVM
 101 ===========================
 102
 103 There are four main build optimizations that our CMake build system supports.
 104 When performing a bootstrap build it is not beneficial to do anything other than
 105 setting *CMAKE_BUILD_TYPE* to ``Release`` for the stage-1 compiler. This is
 106 because the more intensive optimizations are expensive to perform and the
 107 stage-1 compiler is thrown away. All of the further options described should be
 108 set on the stage-2 compiler either using a CMake cache file, or by prefixing the
 109 option with *BOOTSTRAP_*.
 110
 111 The first and simplest to use is the compiler optimization level by setting the
 112 *CMAKE_BUILD_TYPE* option. The main values of interest are ``Release`` or
 113 ``RelWithDebInfo``. By default the ``Release`` option uses the ``-O3``
 114 optimization level, and ``RelWithDebInfo`` uses ``-O2``. If you want to generate
 115 debug information and use ``-O3`` you can override the
 116 *CMAKE_<LANG>_FLAGS_RELWITHDEBINFO* option for C and CXX.
 117 DistributionExample.cmake does this.
 118
 119 Another easy to use option is Link-Time-Optimization. You can set the
 120 *LLVM_ENABLE_LTO* option on your stage-2 build to ``Thin`` or ``Full`` to enable
 121 building LLVM with LTO. These options will significantly increase link time of
 122 the binaries in the distribution, but it will create much faster binaries. This
 123 option should not be used if your distribution includes static archives, as the
 124 objects inside the archive will be LLVM bitcode, which is not portable.
 125
 126 The :doc:`AdvancedBuilds` documentation describes the built-in tooling for
 127 generating LLVM profiling information to drive Profile-Guided-Optimization. The
 128 in-tree profiling tests are very limited, and generating the profile takes a
 129 significant amount of time, but it can result in a significant improvement in
 130 the performance of the generated binaries.
 131
 132 In addition to PGO profiling we also have limited support in-tree for generating
 133 linker order files. These files provide the linker with a suggested ordering for
 134 functions in the final binary layout. This can measurably speed up clang by
 135 physically grouping functions that are called temporally close to eachother. The
 136 current tooling is only available on Darwin systems with ``dtrace(1)``. It is
 137 worth noting that dtrace is non-deterministic, and so the order file generation
 138 using dtrace is also non-deterministic.
 139
 140 Options for Reducing Size
 141 =========================
 142
 143 .. warning::
 144   Any steps taken to reduce the binary size will come at a cost of runtime
 145   performance in the generated binaries.
 146
 147 The simplest and least significant way to reduce binary size is to set the
 148 *CMAKE_BUILD_TYPE* variable to ``MinSizeRel``, which will set the compiler
 149 optimization level to ``-Os`` which optimizes for binary size. This will have
 150 both the least benefit to size and the least impact on performance.
 151
 152 The most impactful way to reduce binary size is to dynamically link LLVM into
 153 all the tools. This reduces code size by decreasing duplication of common code
 154 between the LLVM-based tools. This can be done by setting the following two
 155 CMake options to ``On``: *LLVM_BUILD_LLVM_DYLIB* and *LLVM_LINK_LLVM_DYLIB*.
 156
 157 .. warning::
 158   Distributions should never be built using the *BUILD_SHARED_LIBS* CMake
 159   option. (:ref:`See the warning above for more explanation <shared_libs>`.).
 160
 161 Relevant CMake Options
 162 ======================
 163
 164 This section provides documentation of the CMake options that are intended to
 165 help construct distributions. This is not an exhaustive list, and many
 166 additional options are documented in the :doc:`CMake` page. Some key options
 167 that are already documented include: *LLVM_TARGETS_TO_BUILD*,
 168 *LLVM_ENABLE_PROJECTS*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.
 169
 170 **LLVM_ENABLE_RUNTIMES**:STRING
 171   When building a distribution that includes LLVM runtime projects (i.e. libcxx,
 172   compiler-rt, libcxxabi, libunwind...), it is important to build those projects
 173   with the just-built compiler.
 174
 175 **LLVM_DISTRIBUTION_COMPONENTS**:STRING
 176   This variable can be set to a semi-colon separated list of LLVM build system
 177   components to install. All LLVM-based tools are components, as well as most
 178   of the libraries and runtimes. Component names match the names of the build
 179   system targets.
 180
 181 **LLVM_RUNTIME_DISTRIBUTION_COMPONENTS**:STRING
 182   This variable can be set to a semi-colon separated list of runtime library
 183   components. This is used in conjunction with *LLVM_ENABLE_RUNTIMES* to specify
 184   components of runtime libraries that you want to include in your distribution.
 185   Just like with *LLVM_DISTRIBUTION_COMPONENTS*, component names match the names
 186   of the build system targets.
 187
 188 **LLVM_DYLIB_COMPONENTS**:STRING
 189   This variable can be set to a semi-colon separated name of LLVM library
 190   components. LLVM library components are either library names with the LLVM
 191   prefix removed (i.e. Support, Demangle...), LLVM target names, or special
 192   purpose component names. The special purpose component names are:
 193
 194   #. ``all`` - All LLVM available component libraries
 195   #. ``Native`` - The LLVM target for the Native system
 196   #. ``AllTargetsAsmPrinters`` - All the included target ASM printers libraries
 197   #. ``AllTargetsAsmParsers`` - All the included target ASM parsers libraries
 198   #. ``AllTargetsDescs`` - All the included target descriptions libraries
 199   #. ``AllTargetsDisassemblers`` - All the included target dissassemblers libraries
 200   #. ``AllTargetsInfos`` - All the included target info libraries
 201
 202 **LLVM_INSTALL_TOOLCHAIN_ONLY**:BOOL
 203   This option defaults to ``Off``: when set to ``On`` it removes many of the
 204   LLVM development and testing tools as well as component libraries from the
 205   default ``install`` target. Including the development tools is not recommended
 206   for distributions as many of the LLVM tools are only intended for development
 207   and testing use.