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