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 74The same value used for ``LLVM=`` should be set for each invocation of ``make`` 75if configuring and building via distinct commands. ``LLVM=`` should also be set 76as an environment variable when running scripts that will eventually run 77``make``. 78 79Cross Compiling 80--------------- 81 82A single Clang compiler binary (and corresponding LLVM utilities) will 83typically contain all supported back ends, which can help simplify cross 84compiling especially when ``LLVM=1`` is used. If you use only LLVM tools, 85``CROSS_COMPILE`` or target-triple-prefixes become unnecessary. Example:: 86 87 make LLVM=1 ARCH=arm64 88 89As an example of mixing LLVM and GNU utilities, for a target like ``ARCH=s390`` 90which does not yet have ``ld.lld`` or ``llvm-objcopy`` support, you could 91invoke ``make`` via:: 92 93 make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \ 94 OBJCOPY=s390x-linux-gnu-objcopy 95 96This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and 97``s390x-linux-gnu-objcopy``, so ensure those are reachable in your ``$PATH``. 98 99``CROSS_COMPILE`` is not used to prefix the Clang compiler binary (or 100corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM=1`` 101is not set. 102 103The LLVM_IAS= argument 104---------------------- 105 106Clang can assemble assembler code. You can pass ``LLVM_IAS=0`` to disable this 107behavior and have Clang invoke the corresponding non-integrated assembler 108instead. Example:: 109 110 make LLVM=1 LLVM_IAS=0 111 112``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=0`` 113is used in order to set ``--prefix=`` for the compiler to find the 114corresponding non-integrated assembler (typically, you don't want to use the 115system assembler when targeting another architecture). Example:: 116 117 make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi- 118 119 120Ccache 121------ 122 123``ccache`` can be used with ``clang`` to improve subsequent builds, (though 124KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds 125in order to avoid 100% cache misses, see Reproducible_builds_ for more info):: 126 127 KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang" 128 129.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp 130.. _Reproducible_builds: reproducible-builds.html#timestamps 131 132Supported Architectures 133----------------------- 134 135LLVM does not target all of the architectures that Linux supports and 136just because a target is supported in LLVM does not mean that the kernel 137will build or work without any issues. Below is a general summary of 138architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level 139of support corresponds to "S" values in the MAINTAINERS files. If an 140architecture is not present, it either means that LLVM does not target 141it or there are known issues. Using the latest stable version of LLVM or 142even the development tree will generally yield the best results. 143An architecture's ``defconfig`` is generally expected to work well, 144certain configurations may have problems that have not been uncovered 145yet. Bug reports are always welcome at the issue tracker below! 146 147.. list-table:: 148 :widths: 10 10 10 149 :header-rows: 1 150 151 * - Architecture 152 - Level of support 153 - ``make`` command 154 * - arm 155 - Supported 156 - ``LLVM=1`` 157 * - arm64 158 - Supported 159 - ``LLVM=1`` 160 * - hexagon 161 - Maintained 162 - ``LLVM=1`` 163 * - loongarch 164 - Maintained 165 - ``LLVM=1`` 166 * - mips 167 - Maintained 168 - ``LLVM=1`` 169 * - powerpc 170 - Maintained 171 - ``LLVM=1`` 172 * - riscv 173 - Supported 174 - ``LLVM=1`` 175 * - s390 176 - Maintained 177 - ``LLVM=1`` (LLVM >= 18.1.0), ``CC=clang`` (LLVM < 18.1.0) 178 * - sparc (sparc64 only) 179 - Maintained 180 - ``CC=clang LLVM_IAS=0`` (LLVM >= 20) 181 * - um (User Mode) 182 - Maintained 183 - ``LLVM=1`` 184 * - x86 185 - Supported 186 - ``LLVM=1`` 187 188Getting Help 189------------ 190 191- `Website <https://clangbuiltlinux.github.io/>`_ 192- `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev> 193- `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_ 194- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_ 195- IRC: #clangbuiltlinux on irc.libera.chat 196- `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux 197- `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_ 198- `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_ 199 200.. _getting_llvm: 201 202Getting LLVM 203------------- 204 205We provide prebuilt stable versions of LLVM on `kernel.org 206<https://kernel.org/pub/tools/llvm/>`_. These have been optimized with profile 207data for building Linux kernels, which should improve kernel build times 208relative to other distributions of LLVM. 209 210Below are links that may be useful for building LLVM from source or procuring 211it through a distribution's package manager. 212 213- https://releases.llvm.org/download.html 214- https://github.com/llvm/llvm-project 215- https://llvm.org/docs/GettingStarted.html 216- https://llvm.org/docs/CMake.html 217- https://apt.llvm.org/ 218- https://www.archlinux.org/packages/extra/x86_64/llvm/ 219- https://github.com/ClangBuiltLinux/tc-build 220- https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source 221- https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/ 222