Loading...
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/
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>`_, and `OpenMandriva
19<https://www.openmandriva.org/>`_ use Clang built kernels. `LLVM is a
20collection of toolchain components implemented in terms of C++ objects
21<https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM that
22supports C and the GNU C extensions required by the kernel, and is pronounced
23"klang," not "see-lang."
24
25Clang
26-----
27
28The compiler used can be swapped out via ``CC=`` command line argument to ``make``.
29``CC=`` should be set when selecting a config and during a build. ::
30
31 make CC=clang defconfig
32
33 make CC=clang
34
35Cross Compiling
36---------------
37
38A single Clang compiler binary will typically contain all supported backends,
39which can help simplify cross compiling. ::
40
41 make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu-
42
43``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead
44``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For
45example: ::
46
47 clang --target=aarch64-linux-gnu foo.c
48
49LLVM Utilities
50--------------
51
52LLVM has substitutes for GNU binutils utilities. They can be enabled individually.
53The full list of supported make variables::
54
55 make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \
56 OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \
57 HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld
58
59To simplify the above command, Kbuild supports the ``LLVM`` variable::
60
61 make LLVM=1
62
63If your LLVM tools are not available in your PATH, you can supply their
64location using the LLVM variable with a trailing slash::
65
66 make LLVM=/path/to/llvm/
67
68which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc.
69
70If your LLVM tools have a version suffix and you want to test with that
71explicit version rather than the unsuffixed executables like ``LLVM=1``, you
72can pass the suffix using the ``LLVM`` variable::
73
74 make LLVM=-14
75
76which will use ``clang-14``, ``ld.lld-14``, etc.
77
78``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like
79``LLVM=1``. If you only wish to use certain LLVM utilities, use their respective
80make variables.
81
82The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
83disable it.
84
85Omitting CROSS_COMPILE
86----------------------
87
88As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
89
90If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
91from ``ARCH``.
92
93That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
94
95For example, to cross-compile the arm64 kernel::
96
97 make ARCH=arm64 LLVM=1
98
99If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive
100``--prefix=<path>`` to search for the GNU assembler and linker. ::
101
102 make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu-
103
104Supported Architectures
105-----------------------
106
107LLVM does not target all of the architectures that Linux supports and
108just because a target is supported in LLVM does not mean that the kernel
109will build or work without any issues. Below is a general summary of
110architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
111of support corresponds to "S" values in the MAINTAINERS files. If an
112architecture is not present, it either means that LLVM does not target
113it or there are known issues. Using the latest stable version of LLVM or
114even the development tree will generally yield the best results.
115An architecture's ``defconfig`` is generally expected to work well,
116certain configurations may have problems that have not been uncovered
117yet. Bug reports are always welcome at the issue tracker below!
118
119.. list-table::
120 :widths: 10 10 10
121 :header-rows: 1
122
123 * - Architecture
124 - Level of support
125 - ``make`` command
126 * - arm
127 - Supported
128 - ``LLVM=1``
129 * - arm64
130 - Supported
131 - ``LLVM=1``
132 * - hexagon
133 - Maintained
134 - ``LLVM=1``
135 * - mips
136 - Maintained
137 - ``LLVM=1``
138 * - powerpc
139 - Maintained
140 - ``CC=clang``
141 * - riscv
142 - Maintained
143 - ``LLVM=1``
144 * - s390
145 - Maintained
146 - ``CC=clang``
147 * - um (User Mode)
148 - Maintained
149 - ``LLVM=1``
150 * - x86
151 - Supported
152 - ``LLVM=1``
153
154Getting Help
155------------
156
157- `Website <https://clangbuiltlinux.github.io/>`_
158- `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev>
159- `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_
160- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
161- IRC: #clangbuiltlinux on irc.libera.chat
162- `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux
163- `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_
164- `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_
165
166.. _getting_llvm:
167
168Getting LLVM
169-------------
170
171- https://releases.llvm.org/download.html
172- https://github.com/llvm/llvm-project
173- https://llvm.org/docs/GettingStarted.html
174- https://llvm.org/docs/CMake.html
175- https://apt.llvm.org/
176- https://www.archlinux.org/packages/extra/x86_64/llvm/
177- https://github.com/ClangBuiltLinux/tc-build
178- https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source
179- https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/