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