1 .. _kbuild_llvm: 1 .. _kbuild_llvm:
2 2
3 ============================== 3 ==============================
4 Building Linux with Clang/LLVM 4 Building Linux with Clang/LLVM
5 ============================== 5 ==============================
6 6
7 This document covers how to build the Linux ke 7 This document covers how to build the Linux kernel with Clang and LLVM
8 utilities. 8 utilities.
9 9
10 About 10 About
11 ----- 11 -----
12 12
13 The Linux kernel has always traditionally been 13 The Linux kernel has always traditionally been compiled with GNU toolchains
14 such as GCC and binutils. Ongoing work has all 14 such as GCC and binutils. Ongoing work has allowed for `Clang
15 <https://clang.llvm.org/>`_ and `LLVM <https:/ 15 <https://clang.llvm.org/>`_ and `LLVM <https://llvm.org/>`_ utilities to be
16 used as viable substitutes. Distributions such 16 used as viable substitutes. Distributions such as `Android
17 <https://www.android.com/>`_, `ChromeOS 17 <https://www.android.com/>`_, `ChromeOS
18 <https://www.chromium.org/chromium-os>`_, `Ope 18 <https://www.chromium.org/chromium-os>`_, `OpenMandriva
19 <https://www.openmandriva.org/>`_, and `Chimer 19 <https://www.openmandriva.org/>`_, and `Chimera Linux
20 <https://chimera-linux.org/>`_ use Clang built 20 <https://chimera-linux.org/>`_ use Clang built kernels. Google's and Meta's
21 datacenter fleets also run kernels built with 21 datacenter fleets also run kernels built with Clang.
22 22
23 `LLVM is a collection of toolchain components 23 `LLVM is a collection of toolchain components implemented in terms of C++
24 objects <https://www.aosabook.org/en/llvm.html 24 objects <https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM
25 that supports C and the GNU C extensions requi 25 that supports C and the GNU C extensions required by the kernel, and is
26 pronounced "klang," not "see-lang." 26 pronounced "klang," not "see-lang."
27 27
28 Building with LLVM 28 Building with LLVM
29 ------------------ 29 ------------------
30 30
31 Invoke ``make`` via:: 31 Invoke ``make`` via::
32 32
33 make LLVM=1 33 make LLVM=1
34 34
35 to compile for the host target. For cross comp 35 to compile for the host target. For cross compiling::
36 36
37 make LLVM=1 ARCH=arm64 37 make LLVM=1 ARCH=arm64
38 38
39 The LLVM= argument 39 The LLVM= argument
40 ------------------ 40 ------------------
41 41
42 LLVM has substitutes for GNU binutils utilitie 42 LLVM has substitutes for GNU binutils utilities. They can be enabled
43 individually. The full list of supported make 43 individually. The full list of supported make variables::
44 44
45 make CC=clang LD=ld.lld AR=llvm-ar NM= 45 make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \
46 OBJCOPY=llvm-objcopy OBJDUMP=llvm-ob 46 OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \
47 HOSTCC=clang HOSTCXX=clang++ HOSTAR= 47 HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld
48 48
49 ``LLVM=1`` expands to the above. 49 ``LLVM=1`` expands to the above.
50 50
51 If your LLVM tools are not available in your P 51 If your LLVM tools are not available in your PATH, you can supply their
52 location using the LLVM variable with a traili 52 location using the LLVM variable with a trailing slash::
53 53
54 make LLVM=/path/to/llvm/ 54 make LLVM=/path/to/llvm/
55 55
56 which will use ``/path/to/llvm/clang``, ``/pat 56 which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. The
57 following may also be used:: 57 following may also be used::
58 58
59 PATH=/path/to/llvm:$PATH make LLVM=1 59 PATH=/path/to/llvm:$PATH make LLVM=1
60 60
61 If your LLVM tools have a version suffix and y 61 If your LLVM tools have a version suffix and you want to test with that
62 explicit version rather than the unsuffixed ex 62 explicit version rather than the unsuffixed executables like ``LLVM=1``, you
63 can pass the suffix using the ``LLVM`` variabl 63 can pass the suffix using the ``LLVM`` variable::
64 64
65 make LLVM=-14 65 make LLVM=-14
66 66
67 which will use ``clang-14``, ``ld.lld-14``, et 67 which will use ``clang-14``, ``ld.lld-14``, etc.
68 68
69 To support combinations of out of tree paths w 69 To support combinations of out of tree paths with version suffixes, we
70 recommend:: 70 recommend::
71 71
72 PATH=/path/to/llvm/:$PATH make LLVM=-1 72 PATH=/path/to/llvm/:$PATH make LLVM=-14
73 73
74 ``LLVM=0`` is not the same as omitting ``LLVM` 74 ``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like
75 ``LLVM=1``. If you only wish to use certain LL 75 ``LLVM=1``. If you only wish to use certain LLVM utilities, use their
76 respective make variables. 76 respective make variables.
77 77
78 The same value used for ``LLVM=`` should be se 78 The same value used for ``LLVM=`` should be set for each invocation of ``make``
79 if configuring and building via distinct comma 79 if configuring and building via distinct commands. ``LLVM=`` should also be set
80 as an environment variable when running script 80 as an environment variable when running scripts that will eventually run
81 ``make``. 81 ``make``.
82 82
83 Cross Compiling 83 Cross Compiling
84 --------------- 84 ---------------
85 85
86 A single Clang compiler binary (and correspond 86 A single Clang compiler binary (and corresponding LLVM utilities) will
87 typically contain all supported back ends, whi 87 typically contain all supported back ends, which can help simplify cross
88 compiling especially when ``LLVM=1`` is used. 88 compiling especially when ``LLVM=1`` is used. If you use only LLVM tools,
89 ``CROSS_COMPILE`` or target-triple-prefixes be 89 ``CROSS_COMPILE`` or target-triple-prefixes become unnecessary. Example::
90 90
91 make LLVM=1 ARCH=arm64 91 make LLVM=1 ARCH=arm64
92 92
93 As an example of mixing LLVM and GNU utilities 93 As an example of mixing LLVM and GNU utilities, for a target like ``ARCH=s390``
94 which does not yet have ``ld.lld`` or ``llvm-o 94 which does not yet have ``ld.lld`` or ``llvm-objcopy`` support, you could
95 invoke ``make`` via:: 95 invoke ``make`` via::
96 96
97 make LLVM=1 ARCH=s390 LD=s390x-linux-g 97 make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \
98 OBJCOPY=s390x-linux-gnu-objcopy 98 OBJCOPY=s390x-linux-gnu-objcopy
99 99
100 This example will invoke ``s390x-linux-gnu-ld. 100 This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and
101 ``s390x-linux-gnu-objcopy``, so ensure those a 101 ``s390x-linux-gnu-objcopy``, so ensure those are reachable in your ``$PATH``.
102 102
103 ``CROSS_COMPILE`` is not used to prefix the Cl 103 ``CROSS_COMPILE`` is not used to prefix the Clang compiler binary (or
104 corresponding LLVM utilities) as is the case f 104 corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM=1``
105 is not set. 105 is not set.
106 106
107 The LLVM_IAS= argument 107 The LLVM_IAS= argument
108 ---------------------- 108 ----------------------
109 109
110 Clang can assemble assembler code. You can pas 110 Clang can assemble assembler code. You can pass ``LLVM_IAS=0`` to disable this
111 behavior and have Clang invoke the correspondi 111 behavior and have Clang invoke the corresponding non-integrated assembler
112 instead. Example:: 112 instead. Example::
113 113
114 make LLVM=1 LLVM_IAS=0 114 make LLVM=1 LLVM_IAS=0
115 115
116 ``CROSS_COMPILE`` is necessary when cross comp 116 ``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=0``
117 is used in order to set ``--prefix=`` for the 117 is used in order to set ``--prefix=`` for the compiler to find the
118 corresponding non-integrated assembler (typica 118 corresponding non-integrated assembler (typically, you don't want to use the
119 system assembler when targeting another archit 119 system assembler when targeting another architecture). Example::
120 120
121 make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_ 121 make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi-
122 122
123 123
124 Ccache 124 Ccache
125 ------ 125 ------
126 126
127 ``ccache`` can be used with ``clang`` to impro 127 ``ccache`` can be used with ``clang`` to improve subsequent builds, (though
128 KBUILD_BUILD_TIMESTAMP_ should be set to a det 128 KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds
129 in order to avoid 100% cache misses, see Repro 129 in order to avoid 100% cache misses, see Reproducible_builds_ for more info)::
130 130
131 KBUILD_BUILD_TIMESTAMP='' make LLVM=1 131 KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang"
132 132
133 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild 133 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
134 .. _Reproducible_builds: reproducible-builds.h 134 .. _Reproducible_builds: reproducible-builds.html#timestamps
135 135
136 Supported Architectures 136 Supported Architectures
137 ----------------------- 137 -----------------------
138 138
139 LLVM does not target all of the architectures 139 LLVM does not target all of the architectures that Linux supports and
140 just because a target is supported in LLVM doe 140 just because a target is supported in LLVM does not mean that the kernel
141 will build or work without any issues. Below i 141 will build or work without any issues. Below is a general summary of
142 architectures that currently work with ``CC=cl 142 architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
143 of support corresponds to "S" values in the MA 143 of support corresponds to "S" values in the MAINTAINERS files. If an
144 architecture is not present, it either means t 144 architecture is not present, it either means that LLVM does not target
145 it or there are known issues. Using the latest 145 it or there are known issues. Using the latest stable version of LLVM or
146 even the development tree will generally yield 146 even the development tree will generally yield the best results.
147 An architecture's ``defconfig`` is generally e 147 An architecture's ``defconfig`` is generally expected to work well,
148 certain configurations may have problems that 148 certain configurations may have problems that have not been uncovered
149 yet. Bug reports are always welcome at the iss 149 yet. Bug reports are always welcome at the issue tracker below!
150 150
151 .. list-table:: 151 .. list-table::
152 :widths: 10 10 10 152 :widths: 10 10 10
153 :header-rows: 1 153 :header-rows: 1
154 154
155 * - Architecture 155 * - Architecture
156 - Level of support 156 - Level of support
157 - ``make`` command 157 - ``make`` command
158 * - arm 158 * - arm
159 - Supported 159 - Supported
160 - ``LLVM=1`` 160 - ``LLVM=1``
161 * - arm64 161 * - arm64
162 - Supported 162 - Supported
163 - ``LLVM=1`` 163 - ``LLVM=1``
164 * - hexagon 164 * - hexagon
165 - Maintained 165 - Maintained
166 - ``LLVM=1`` 166 - ``LLVM=1``
167 * - loongarch 167 * - loongarch
168 - Maintained 168 - Maintained
169 - ``LLVM=1`` 169 - ``LLVM=1``
170 * - mips 170 * - mips
171 - Maintained 171 - Maintained
172 - ``LLVM=1`` 172 - ``LLVM=1``
173 * - powerpc 173 * - powerpc
174 - Maintained 174 - Maintained
175 - ``LLVM=1`` 175 - ``LLVM=1``
176 * - riscv 176 * - riscv
177 - Supported 177 - Supported
178 - ``LLVM=1`` 178 - ``LLVM=1``
179 * - s390 179 * - s390
180 - Maintained 180 - Maintained
181 - ``LLVM=1`` (LLVM >= 18.1.0), ``CC=clang 181 - ``LLVM=1`` (LLVM >= 18.1.0), ``CC=clang`` (LLVM < 18.1.0)
182 * - um (User Mode) 182 * - um (User Mode)
183 - Maintained 183 - Maintained
184 - ``LLVM=1`` 184 - ``LLVM=1``
185 * - x86 185 * - x86
186 - Supported 186 - Supported
187 - ``LLVM=1`` 187 - ``LLVM=1``
188 188
189 Getting Help 189 Getting Help
190 ------------ 190 ------------
191 191
192 - `Website <https://clangbuiltlinux.github.io/ 192 - `Website <https://clangbuiltlinux.github.io/>`_
193 - `Mailing List <https://lore.kernel.org/llvm/> 193 - `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev">https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev>
194 - `Old Mailing List Archives <https://groups.g 194 - `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_
195 - `Issue Tracker <https://github.com/ClangBuil 195 - `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
196 - IRC: #clangbuiltlinux on irc.libera.chat 196 - IRC: #clangbuiltlinux on irc.libera.chat
197 - `Telegram <https://t.me/ClangBuiltLinux>`_: 197 - `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux
198 - `Wiki <https://github.com/ClangBuiltLinux/li 198 - `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_
199 - `Beginner Bugs <https://github.com/ClangBuil 199 - `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_
200 200
201 .. _getting_llvm: 201 .. _getting_llvm:
202 202
203 Getting LLVM 203 Getting LLVM
204 ------------- 204 -------------
205 205
206 We provide prebuilt stable versions of LLVM on 206 We provide prebuilt stable versions of LLVM on `kernel.org
207 <https://kernel.org/pub/tools/llvm/>`_. These 207 <https://kernel.org/pub/tools/llvm/>`_. These have been optimized with profile
208 data for building Linux kernels, which should 208 data for building Linux kernels, which should improve kernel build times
209 relative to other distributions of LLVM. 209 relative to other distributions of LLVM.
210 210
211 Below are links that may be useful for buildin 211 Below are links that may be useful for building LLVM from source or procuring
212 it through a distribution's package manager. 212 it through a distribution's package manager.
213 213
214 - https://releases.llvm.org/download.html 214 - https://releases.llvm.org/download.html
215 - https://github.com/llvm/llvm-project 215 - https://github.com/llvm/llvm-project
216 - https://llvm.org/docs/GettingStarted.html 216 - https://llvm.org/docs/GettingStarted.html
217 - https://llvm.org/docs/CMake.html 217 - https://llvm.org/docs/CMake.html
218 - https://apt.llvm.org/ 218 - https://apt.llvm.org/
219 - https://www.archlinux.org/packages/extra/x86 219 - https://www.archlinux.org/packages/extra/x86_64/llvm/
220 - https://github.com/ClangBuiltLinux/tc-build 220 - https://github.com/ClangBuiltLinux/tc-build
221 - https://github.com/ClangBuiltLinux/linux/wik 221 - https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source
222 - https://android.googlesource.com/platform/pr 222 - https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.