1 .. _kbuild_llvm: 2 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 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." 27 28 Building with LLVM 29 ------------------ 30 31 Invoke ``make`` via:: 32 33 make LLVM=1 34 35 to compile for the host target. For cross compiling:: 36 37 make LLVM=1 ARCH=arm64 38 39 The LLVM= argument 40 ------------------ 41 42 LLVM has substitutes for GNU binutils utilities. They can be enabled 43 individually. 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 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 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 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 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 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 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``. 82 83 Cross Compiling 84 --------------- 85 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 108 ---------------------- 109 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:: 120 121 make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi- 122 123 124 Ccache 125 ------ 126 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 129 in 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 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`` 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 * - um (User Mode) 183 - Maintained 184 - ``LLVM=1`` 185 * - x86 186 - Supported 187 - ``LLVM=1`` 188 189 Getting Help 190 ------------ 191 192 - `Website <https://clangbuiltlinux.github.io/>`_ 193 - `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.google.com/g/clang-built-linux>`_ 195 - `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_ 196 - IRC: #clangbuiltlinux on irc.libera.chat 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 201 .. _getting_llvm: 202 203 Getting LLVM 204 ------------- 205 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 211 Below are links that may be useful for building LLVM from source or procuring 212 it through a distribution's package manager. 213 214 - https://releases.llvm.org/download.html 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/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.