223 lines · plain
1.. _kbuild_llvm:2 3==============================4Building Linux with Clang/LLVM5==============================6 7This document covers how to build the Linux kernel with Clang and LLVM8utilities.9 10About11-----12 13The Linux kernel has always traditionally been compiled with GNU toolchains14such as GCC and binutils. Ongoing work has allowed for `Clang15<https://clang.llvm.org/>`_ and `LLVM <https://llvm.org/>`_ utilities to be16used as viable substitutes. Distributions such as `Android17<https://www.android.com/>`_, `ChromeOS18<https://www.chromium.org/chromium-os>`_, `OpenMandriva19<https://www.openmandriva.org/>`_, and `Chimera Linux20<https://chimera-linux.org/>`_ use Clang built kernels. Google's and Meta's21datacenter 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 LLVM25that supports C and the GNU C extensions required by the kernel, and is26pronounced "klang," not "see-lang."27 28Building with LLVM29------------------30 31Invoke ``make`` via::32 33 make LLVM=134 35to compile for the host target. For cross compiling::36 37 make LLVM=1 ARCH=arm6438 39The LLVM= argument40------------------41 42LLVM has substitutes for GNU binutils utilities. They can be enabled43individually. 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.lld48 49``LLVM=1`` expands to the above.50 51If your LLVM tools are not available in your PATH, you can supply their52location 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. The57following may also be used::58 59 PATH=/path/to/llvm:$PATH make LLVM=160 61If your LLVM tools have a version suffix and you want to test with that62explicit version rather than the unsuffixed executables like ``LLVM=1``, you63can pass the suffix using the ``LLVM`` variable::64 65 make LLVM=-1466 67which will use ``clang-14``, ``ld.lld-14``, etc.68 69To support combinations of out of tree paths with version suffixes, we70recommend::71 72 PATH=/path/to/llvm/:$PATH make LLVM=-1473 74``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like75``LLVM=1``. If you only wish to use certain LLVM utilities, use their76respective 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 set80as an environment variable when running scripts that will eventually run81``make``.82 83Cross Compiling84---------------85 86A single Clang compiler binary (and corresponding LLVM utilities) will87typically contain all supported back ends, which can help simplify cross88compiling 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=arm6492 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 could95invoke ``make`` via::96 97 make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \98 OBJCOPY=s390x-linux-gnu-objcopy99 100This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and101``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 (or104corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM=1``105is not set.106 107The LLVM_IAS= argument108----------------------109 110Clang can assemble assembler code. You can pass ``LLVM_IAS=0`` to disable this111behavior and have Clang invoke the corresponding non-integrated assembler112instead. Example::113 114 make LLVM=1 LLVM_IAS=0115 116``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=0``117is used in order to set ``--prefix=`` for the compiler to find the118corresponding non-integrated assembler (typically, you don't want to use the119system assembler when targeting another architecture). Example::120 121 make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi-122 123 124Ccache125------126 127``ccache`` can be used with ``clang`` to improve subsequent builds, (though128KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds129in 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-timestamp134.. _Reproducible_builds: reproducible-builds.html#timestamps135 136Supported Architectures137-----------------------138 139LLVM does not target all of the architectures that Linux supports and140just because a target is supported in LLVM does not mean that the kernel141will build or work without any issues. Below is a general summary of142architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level143of support corresponds to "S" values in the MAINTAINERS files. If an144architecture is not present, it either means that LLVM does not target145it or there are known issues. Using the latest stable version of LLVM or146even 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 uncovered149yet. Bug reports are always welcome at the issue tracker below!150 151.. list-table::152 :widths: 10 10 10153 :header-rows: 1154 155 * - Architecture156 - Level of support157 - ``make`` command158 * - arm159 - Supported160 - ``LLVM=1``161 * - arm64162 - Supported163 - ``LLVM=1``164 * - hexagon165 - Maintained166 - ``LLVM=1``167 * - loongarch168 - Maintained169 - ``LLVM=1``170 * - mips171 - Maintained172 - ``LLVM=1``173 * - powerpc174 - Maintained175 - ``LLVM=1``176 * - riscv177 - Supported178 - ``LLVM=1``179 * - s390180 - Maintained181 - ``LLVM=1`` (LLVM >= 18.1.0), ``CC=clang`` (LLVM < 18.1.0)182 * - um (User Mode)183 - Maintained184 - ``LLVM=1``185 * - x86186 - Supported187 - ``LLVM=1``188 189Getting Help190------------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.chat197- `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux198- `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 LLVM204-------------205 206We provide prebuilt stable versions of LLVM on `kernel.org207<https://kernel.org/pub/tools/llvm/>`_. These have been optimized with profile208data for building Linux kernels, which should improve kernel build times209relative to other distributions of LLVM.210 211Below are links that may be useful for building LLVM from source or procuring212it through a distribution's package manager.213 214- https://releases.llvm.org/download.html215- https://github.com/llvm/llvm-project216- https://llvm.org/docs/GettingStarted.html217- https://llvm.org/docs/CMake.html218- https://apt.llvm.org/219- https://www.archlinux.org/packages/extra/x86_64/llvm/220- https://github.com/ClangBuiltLinux/tc-build221- https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source222- https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/223