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 * - um (User Mode) 183 - Maintained 184 - ``LLVM=1`` 185 * - x86 186 - Supported 187 - ``LLVM=1`` 188 189Getting Help 190------------ 191 192- `Website <https://clangbuiltlinux.github.io/>`_ 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>`_ 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 203Getting LLVM 204------------- 205 206We provide prebuilt stable versions of LLVM on `kernel.org 207<https://kernel.org/pub/tools/llvm/>`_. These have been optimized with profile 208data for building Linux kernels, which should improve kernel build times 209relative to other distributions of LLVM. 210 211Below are links that may be useful for building LLVM from source or procuring 212it 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/ 223