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/ 180