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. Kbuild supports ``LLVM=1`` 53to enable them. :: 54 55 make LLVM=1 56 57They can be enabled individually. The full list of the parameters: :: 58 59 make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ 60 OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ 61 HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld 62 63The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to 64disable it. 65 66Omitting CROSS_COMPILE 67---------------------- 68 69As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``. 70 71If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred 72from ``ARCH``. 73 74That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary. 75 76For example, to cross-compile the arm64 kernel:: 77 78 make ARCH=arm64 LLVM=1 79 80If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive 81``--prefix=<path>`` to search for the GNU assembler and linker. :: 82 83 make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu- 84 85Supported Architectures 86----------------------- 87 88LLVM does not target all of the architectures that Linux supports and 89just because a target is supported in LLVM does not mean that the kernel 90will build or work without any issues. Below is a general summary of 91architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level 92of support corresponds to "S" values in the MAINTAINERS files. If an 93architecture is not present, it either means that LLVM does not target 94it or there are known issues. Using the latest stable version of LLVM or 95even the development tree will generally yield the best results. 96An architecture's ``defconfig`` is generally expected to work well, 97certain configurations may have problems that have not been uncovered 98yet. Bug reports are always welcome at the issue tracker below! 99 100.. list-table:: 101 :widths: 10 10 10 102 :header-rows: 1 103 104 * - Architecture 105 - Level of support 106 - ``make`` command 107 * - arm 108 - Supported 109 - ``LLVM=1`` 110 * - arm64 111 - Supported 112 - ``LLVM=1`` 113 * - mips 114 - Maintained 115 - ``CC=clang`` 116 * - powerpc 117 - Maintained 118 - ``CC=clang`` 119 * - riscv 120 - Maintained 121 - ``CC=clang`` 122 * - s390 123 - Maintained 124 - ``CC=clang`` 125 * - x86 126 - Supported 127 - ``LLVM=1`` 128 129Getting Help 130------------ 131 132- `Website <https://clangbuiltlinux.github.io/>`_ 133- `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev> 134- `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_ 135- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_ 136- IRC: #clangbuiltlinux on irc.libera.chat 137- `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux 138- `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_ 139- `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_ 140 141.. _getting_llvm: 142 143Getting LLVM 144------------- 145 146- https://releases.llvm.org/download.html 147- https://github.com/llvm/llvm-project 148- https://llvm.org/docs/GettingStarted.html 149- https://llvm.org/docs/CMake.html 150- https://apt.llvm.org/ 151- https://www.archlinux.org/packages/extra/x86_64/llvm/ 152- https://github.com/ClangBuiltLinux/tc-build 153- https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source 154- https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/ 155