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