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