258 lines · plain
1===============================2Building a Distribution of LLVM3===============================4 5.. contents::6 :local:7 8Introduction9============10 11This document is geared toward people who want to build and package LLVM and any12combination of its sub-project tools for distribution. This document covers13useful features of the LLVM build system as well as best practices and general14information about packaging LLVM.15 16If you are new to CMake, you may find the :doc:`CMake` or :doc:`CMakePrimer`17documentation useful. This document covers some of the inner18workings of the builds described in the :doc:`AdvancedBuilds` document.19 20General Distribution Guidance21=============================22 23When building a distribution of a compiler, it is generally advised to perform a24bootstrap build of the compiler. That means building a "stage 1" compiler with25your 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 the27bug fixes, performance optimizations and general improvements provided by the28new compiler.29 30In deciding how to build your distribution, there are a few trade-offs that you31will need to evaluate. The big two are:32 33#. Compile time of the distribution against performance of the built compiler34 35#. Binary size of the distribution against performance of the built compiler36 37The guidance for maximizing performance of the generated compiler is to use LTO,38PGO, and statically link everything. This will result in an overall larger39distribution, and it will take longer to generate, but it provides the most40opportunity for the compiler to optimize.41 42The guidance for minimizing distribution size is to dynamically link LLVM and43Clang libraries into the tools to reduce code duplication. This will come at a44substantial performance penalty to the generated binary, both because it reduces45optimization opportunities and because dynamic linking requires resolving symbols46at 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 the52 *BUILD_SHARED_LIBS* CMake option. That option exists for optimizing developer53 workflow only. Due to design and implementation decisions, LLVM relies on54 global data which can end up being duplicated across shared libraries55 resulting in bugs. As such this is not a safe way to distribute LLVM or56 LLVM-based tools.57 58The simplest example of building a distribution with reasonable performance is59captured in the DistributionExample CMake cache file located at60``clang/cmake/caches/DistributionExample.cmake``. The following commands will perform61and install the distribution build:62 63.. code-block:: console64 65 $ cmake -G Ninja -C <path to clang>/cmake/caches/DistributionExample.cmake <path to LLVM source>66 $ ninja stage2-distribution67 $ ninja stage2-install-distribution68 69Difference between ``install`` and ``install-distribution``70-----------------------------------------------------------71 72One subtle but important difference to note is between the ``install``73and ``install-distribution`` targets. The ``install`` target is expected to74install every part of LLVM that your build is configured to generate except the75LLVM testing tools. Alternatively the ``install-distribution`` target, which is76recommended for building distributions, only installs specific parts of LLVM as77specified at configuration time by *LLVM_DISTRIBUTION_COMPONENTS*.78 79Additionally, by default, the ``install`` target will install the LLVM testing80tools as the public tools. This can be changed well by setting81*LLVM_INSTALL_TOOLCHAIN_ONLY* to ``On``. The LLVM tools are intended for82development and testing of LLVM, and should only be included in distributions83that support LLVM development.84 85When building with *LLVM_DISTRIBUTION_COMPONENTS* the build system also86generates a ``distribution`` target which builds all the components specified in87the list. This is a convenience build target to allow building just the88distributed pieces without needing to build all configured targets.89 90.. _Multi-distribution configurations:91 92Multi-distribution configurations93---------------------------------94 95The ``install-distribution`` target described above is for building a single96distribution. LLVM's build system also supports building multiple distributions,97which can be used to e.g. have one distribution containing just tools and98another for libraries (to enable development). These are configured by setting99the *LLVM_DISTRIBUTIONS* variable to hold a list of all distribution names100(which conventionally start with an uppercase letter, e.g. "Development"), and101then setting the *LLVM_<distribution>_DISTRIBUTION_COMPONENTS* variable to the102list of targets for that distribution. For each distribution, the build system103generates an ``install-${distribution}-distribution`` target, where104``${distribution}`` is the name of the distribution in lowercase, to install105that distribution.106 107Each distribution creates its own set of CMake exports, and the target to108install the CMake exports for a particular distribution for a project is named109``${project}-${distribution}-cmake-exports``, where ``${project}`` is the name110of the project in lowercase and ``${distribution}`` is the name of the111distribution in lowercase, unless the project is LLVM, in which case the target112is just named ``${distribution}-cmake-exports``. These targets need to be113explicitly included in the *LLVM_<distribution>_DISTRIBUTION_COMPONENTS*114variable in order to be included as part of the distribution.115 116Unlike with the single distribution setup, when building multiple distributions,117any components specified in *LLVM_RUNTIME_DISTRIBUTION_COMPONENTS* are not118automatically added to any distribution. Instead, you must include the targets119explicitly in some *LLVM_<distribution>_DISTRIBUTION_COMPONENTS* list.120 121By default, each target can appear in multiple distributions; a target will be122installed as part of all distributions it appears in, and it'll be exported by123the last distribution it appears in (the order of distributions is the order124they appear in *LLVM_DISTRIBUTIONS*). We also define some umbrella targets (e.g.125``llvm-libraries`` to install all LLVM libraries); a target can appear in a126different distribution than its umbrella, in which case the target will be127exported by the distribution it appears in (and not the distribution its128umbrella appears in). Set *LLVM_STRICT_DISTRIBUTIONS* to ``On`` if you want to129enforce a target appearing in only one distribution and umbrella distributions130being consistent with target distributions.131 132We strongly encourage looking at ``clang/cmake/caches/MultiDistributionExample.cmake``133as an example of configuring multiple distributions.134 135Special Notes for Library-only Distributions136--------------------------------------------137 138One of the most powerful features of LLVM is its library-first design mentality139and the way you can compose a wide variety of tools using different portions of140LLVM. Even in this situation, using *BUILD_SHARED_LIBS* is not supported. If you141want to distribute LLVM as a shared library for use in a tool, the recommended142method is using *LLVM_BUILD_LLVM_DYLIB*, and you can use *LLVM_DYLIB_COMPONENTS*143to configure which LLVM components are part of libLLVM.144Note: *LLVM_BUILD_LLVM_DYLIB* is not available on Windows.145 146Options for Optimizing LLVM147===========================148 149There are four main build optimizations that our CMake build system supports.150When performing a bootstrap build, it is not beneficial to do anything other than151setting *CMAKE_BUILD_TYPE* to ``Release`` for the stage-1 compiler. This is152because the more intensive optimizations are expensive to perform and the153stage-1 compiler is thrown away. All of the further options described should be154set on the stage-2 compiler either using a CMake cache file, or by prefixing the155option with *BOOTSTRAP_*.156 157The first and simplest to use is the compiler optimization level by setting the158*CMAKE_BUILD_TYPE* option. The main values of interest are ``Release`` or159``RelWithDebInfo``. By default the ``Release`` option uses the ``-O3``160optimization level, and ``RelWithDebInfo`` uses ``-O2``. If you want to generate161debug information and use ``-O3`` you can override the162*CMAKE_<LANG>_FLAGS_RELWITHDEBINFO* option for C and CXX.163DistributionExample.cmake does this.164 165Another easy-to-use option is Link-Time-Optimization. You can set the166*LLVM_ENABLE_LTO* option on your stage-2 build to ``Thin`` or ``Full`` to enable167building LLVM with LTO. These options will significantly increase link time of168the binaries in the distribution, but it will create much faster binaries. This169option should not be used if your distribution includes static archives, as the170objects inside the archive will be LLVM bitcode, which is not portable.171 172The :doc:`AdvancedBuilds` documentation describes the built-in tooling for173generating LLVM profiling information to drive Profile-Guided-Optimization. The174in-tree profiling tests are very limited, and generating the profile takes a175significant amount of time, but it can result in a significant improvement in176the performance of the generated binaries.177 178In addition to PGO profiling, we also have limited in-tree support for generating179linker order files. These files provide the linker with a suggested ordering for180functions in the final binary layout. This can measurably speed up clang by181physically grouping functions that are called temporally close to each other.182The current tooling is only available on Darwin systems with ``dtrace(1)``. It183is worth noting that dtrace is non-deterministic, and so the order file184generation using dtrace is also non-deterministic.185 186Options for Reducing Size187=========================188 189.. warning::190 Any steps taken to reduce binary size will come at the cost of runtime191 performance in the generated binaries.192 193The simplest and least significant way to reduce binary size is to set the194*CMAKE_BUILD_TYPE* variable to ``MinSizeRel``, which will set the compiler195optimization level to ``-Os`` which optimizes for binary size. This will have196both the least benefit to size and the least impact on performance.197 198The most impactful way to reduce binary size is to dynamically link LLVM into199all the tools. This reduces code size by decreasing duplication of common code200among the LLVM-based tools. This can be done by setting the following two201CMake options to ``On``: *LLVM_BUILD_LLVM_DYLIB* and *LLVM_LINK_LLVM_DYLIB*.202 203.. warning::204 Distributions should never be built using the *BUILD_SHARED_LIBS* CMake205 option. (:ref:`See the warning above for more explanation <shared_libs>`.).206 207Relevant CMake Options208======================209 210This section provides documentation of the CMake options that are intended to211help construct distributions. This is not an exhaustive list, and many212additional options are documented in the :doc:`CMake` page. Some key options213that are already documented include: *LLVM_TARGETS_TO_BUILD*, *LLVM_ENABLE_PROJECTS*,214*LLVM_ENABLE_RUNTIMES*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.215 216**LLVM_ENABLE_RUNTIMES**:STRING217 When building a distribution that includes LLVM runtime projects (i.e., libcxx,218 compiler-rt, libcxxabi, libunwind...), it is important to build those projects219 with the just-built compiler.220 221**LLVM_DISTRIBUTION_COMPONENTS**:STRING222 This variable can be set to a semicolon-separated list of LLVM build system223 components to install. All LLVM-based tools are components, as well as most224 of the libraries and runtimes. Component names match the names of the build225 system targets.226 227**LLVM_DISTRIBUTIONS**:STRING228 This variable can be set to a semicolon-separated list of distributions. See229 the :ref:`Multi-distribution configurations` section above for details on this230 and other CMake variables to configure multiple distributions.231 232**LLVM_RUNTIME_DISTRIBUTION_COMPONENTS**:STRING233 This variable can be set to a semicolon-separated list of runtime library234 components. This is used in conjunction with *LLVM_ENABLE_RUNTIMES* to specify235 components of runtime libraries that you want to include in your distribution.236 Just like with *LLVM_DISTRIBUTION_COMPONENTS*, component names match the names237 of the build system targets.238 239**LLVM_DYLIB_COMPONENTS**:STRING240 This variable can be set to a semicolon-separated name of LLVM library241 components. LLVM library components are either library names with the LLVM242 prefix removed (i.e., Support, Demangle...), LLVM target names, or special243 purpose component names. The special purpose component names are:244 245 #. ``all`` - All available LLVM component libraries246 #. ``Native`` - The LLVM target for the Native system247 #. ``AllTargetsAsmParsers`` - All the included target ASM parsers libraries248 #. ``AllTargetsDescs`` - All the included target descriptions libraries249 #. ``AllTargetsDisassemblers`` - All the included target dissassemblers libraries250 #. ``AllTargetsInfos`` - All the included target info libraries251 252**LLVM_INSTALL_TOOLCHAIN_ONLY**:BOOL253 This option defaults to ``Off``: when set to ``On`` it removes many of the254 LLVM development and testing tools as well as component libraries from the255 default ``install`` target. Including the development tools is not recommended256 for distributions as many of the LLVM tools are only intended for development257 and testing use.258