|
150
|
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 Note: *LLVM_BUILD_LLVM_DYLIB* is not available on Windows.
|
|
|
100
|
|
|
101 Options for Optimizing LLVM
|
|
|
102 ===========================
|
|
|
103
|
|
|
104 There are four main build optimizations that our CMake build system supports.
|
|
|
105 When performing a bootstrap build it is not beneficial to do anything other than
|
|
|
106 setting *CMAKE_BUILD_TYPE* to ``Release`` for the stage-1 compiler. This is
|
|
|
107 because the more intensive optimizations are expensive to perform and the
|
|
|
108 stage-1 compiler is thrown away. All of the further options described should be
|
|
|
109 set on the stage-2 compiler either using a CMake cache file, or by prefixing the
|
|
|
110 option with *BOOTSTRAP_*.
|
|
|
111
|
|
|
112 The 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``
|
|
|
115 optimization level, and ``RelWithDebInfo`` uses ``-O2``. If you want to generate
|
|
|
116 debug information and use ``-O3`` you can override the
|
|
|
117 *CMAKE_<LANG>_FLAGS_RELWITHDEBINFO* option for C and CXX.
|
|
|
118 DistributionExample.cmake does this.
|
|
|
119
|
|
|
120 Another 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
|
|
|
122 building LLVM with LTO. These options will significantly increase link time of
|
|
|
123 the binaries in the distribution, but it will create much faster binaries. This
|
|
|
124 option should not be used if your distribution includes static archives, as the
|
|
|
125 objects inside the archive will be LLVM bitcode, which is not portable.
|
|
|
126
|
|
|
127 The :doc:`AdvancedBuilds` documentation describes the built-in tooling for
|
|
|
128 generating LLVM profiling information to drive Profile-Guided-Optimization. The
|
|
|
129 in-tree profiling tests are very limited, and generating the profile takes a
|
|
|
130 significant amount of time, but it can result in a significant improvement in
|
|
|
131 the performance of the generated binaries.
|
|
|
132
|
|
|
133 In addition to PGO profiling we also have limited support in-tree for generating
|
|
|
134 linker order files. These files provide the linker with a suggested ordering for
|
|
|
135 functions in the final binary layout. This can measurably speed up clang by
|
|
|
136 physically grouping functions that are called temporally close to each other.
|
|
|
137 The current tooling is only available on Darwin systems with ``dtrace(1)``. It
|
|
|
138 is worth noting that dtrace is non-deterministic, and so the order file
|
|
|
139 generation using dtrace is also non-deterministic.
|
|
|
140
|
|
|
141 Options 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
|
|
|
148 The 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
|
|
|
150 optimization level to ``-Os`` which optimizes for binary size. This will have
|
|
|
151 both the least benefit to size and the least impact on performance.
|
|
|
152
|
|
|
153 The most impactful way to reduce binary size is to dynamically link LLVM into
|
|
|
154 all the tools. This reduces code size by decreasing duplication of common code
|
|
|
155 between the LLVM-based tools. This can be done by setting the following two
|
|
|
156 CMake 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
|
|
|
162 Relevant CMake Options
|
|
|
163 ======================
|
|
|
164
|
|
|
165 This section provides documentation of the CMake options that are intended to
|
|
|
166 help construct distributions. This is not an exhaustive list, and many
|
|
|
167 additional options are documented in the :doc:`CMake` page. Some key options
|
|
|
168 that 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.
|
