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