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