Documentation/kbuild/llvm.rst

   1 .. _kbuild_llvm:
   2
   3 ==============================
   4 Building Linux with Clang/LLVM
   5 ==============================
   6
   7 This document covers how to build the Linux kernel with Clang and LLVM
   8 utilities.
   9
  10 About
  11 -----
  12
  13 The Linux kernel has always traditionally been compiled with GNU toolchains
  14 such as GCC and binutils. Ongoing work has allowed for `Clang
  15 <https://clang.llvm.org/>`_ and `LLVM <https://llvm.org/>`_ utilities to be
  16 used 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
  21 datacenter fleets also run kernels built with Clang.
  22
  23 `LLVM is a collection of toolchain components implemented in terms of C++
  24 objects <https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM
  25 that supports C and the GNU C extensions required by the kernel, and is
  26 pronounced "klang," not "see-lang."
  27
  28 Building with LLVM
  29 ------------------
  30
  31 Invoke ``make`` via::
  32
  33         make LLVM=1
  34
  35 to compile for the host target. For cross compiling::
  36
  37         make LLVM=1 ARCH=arm64
  38
  39 The LLVM= argument
  40 ------------------
  41
  42 LLVM has substitutes for GNU binutils utilities. They can be enabled
  43 individually. 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
  51 If your LLVM tools are not available in your PATH, you can supply their
  52 location using the LLVM variable with a trailing slash::
  53
  54         make LLVM=/path/to/llvm/
  55
  56 which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. The
  57 following may also be used::
  58
  59         PATH=/path/to/llvm:$PATH make LLVM=1
  60
  61 If your LLVM tools have a version suffix and you want to test with that
  62 explicit version rather than the unsuffixed executables like ``LLVM=1``, you
  63 can pass the suffix using the ``LLVM`` variable::
  64
  65         make LLVM=-14
  66
  67 which will use ``clang-14``, ``ld.lld-14``, etc.
  68
  69 To support combinations of out of tree paths with version suffixes, we
  70 recommend::
  71
  72         PATH=/path/to/llvm/:$PATH make LLVM=-14
  73
  74 ``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like
  75 ``LLVM=1``. If you only wish to use certain LLVM utilities, use their
  76 respective make variables.
  77
  78 The same value used for ``LLVM=`` should be set for each invocation of ``make``
  79 if configuring and building via distinct commands. ``LLVM=`` should also be set
  80 as an environment variable when running scripts that will eventually run
  81 ``make``.
  82
  83 Cross Compiling
  84 ---------------
  85
  86 A single Clang compiler binary (and corresponding LLVM utilities) will
  87 typically contain all supported back ends, which can help simplify cross
  88 compiling 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=arm64
  92
  93 As an example of mixing LLVM and GNU utilities, for a target like ``ARCH=s390``
  94 which does not yet have ``ld.lld`` or ``llvm-objcopy`` support, you could
  95 invoke ``make`` via::
  96
  97         make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \
  98           OBJCOPY=s390x-linux-gnu-objcopy
  99
 100 This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and
 101 ``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 (or
 104 corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM=1``
 105 is not set.
 106
 107 The LLVM_IAS= argument
 108 ----------------------
 109
 110 Clang can assemble assembler code. You can pass ``LLVM_IAS=0`` to disable this
 111 behavior and have Clang invoke the corresponding non-integrated assembler
 112 instead. Example::
 113
 114         make LLVM=1 LLVM_IAS=0
 115
 116 ``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=0``
 117 is used in order to set ``--prefix=`` for the compiler to find the
 118 corresponding non-integrated assembler (typically, you don't want to use the
 119 system assembler when targeting another architecture). Example::
 120
 121         make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi-
 122
 123
 124 Ccache
 125 ------
 126
 127 ``ccache`` can be used with ``clang`` to improve subsequent builds, (though
 128 KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds
 129 in 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-timestamp
 134 .. _Reproducible_builds: reproducible-builds.html#timestamps
 135
 136 Supported Architectures
 137 -----------------------
 138
 139 LLVM does not target all of the architectures that Linux supports and
 140 just because a target is supported in LLVM does not mean that the kernel
 141 will build or work without any issues. Below is a general summary of
 142 architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
 143 of support corresponds to "S" values in the MAINTAINERS files. If an
 144 architecture is not present, it either means that LLVM does not target
 145 it or there are known issues. Using the latest stable version of LLVM or
 146 even the development tree will generally yield the best results.
 147 An architecture's ``defconfig`` is generally expected to work well,
 148 certain configurations may have problems that have not been uncovered
 149 yet. Bug reports are always welcome at the issue tracker below!
 150
 151 .. list-table::
 152    :widths: 10 10 10
 153    :header-rows: 1
 154
 155    * - Architecture
 156      - Level of support
 157      - ``make`` command
 158    * - arm
 159      - Supported
 160      - ``LLVM=1``
 161    * - arm64
 162      - Supported
 163      - ``LLVM=1``
 164    * - hexagon
 165      - Maintained
 166      - ``LLVM=1``
 167    * - loongarch
 168      - Maintained
 169      - ``LLVM=1``
 170    * - mips
 171      - Maintained
 172      - ``LLVM=1``
 173    * - powerpc
 174      - Maintained
 175      - ``LLVM=1``
 176    * - riscv
 177      - Supported
 178      - ``LLVM=1``
 179    * - s390
 180      - Maintained
 181      - ``CC=clang``
 182    * - um (User Mode)
 183      - Maintained
 184      - ``LLVM=1``
 185    * - x86
 186      - Supported
 187      - ``LLVM=1``
 188
 189 Getting Help
 190 ------------
 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.chat
 197 - `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux
 198 - `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
 203 Getting LLVM
 204 -------------
 205
 206 We provide prebuilt stable versions of LLVM on `kernel.org
 207 <https://kernel.org/pub/tools/llvm/>`_. These have been optimized with profile
 208 data for building Linux kernels, which should improve kernel build times
 209 relative to other distributions of LLVM.
 210
 211 Below are links that may be useful for building LLVM from source or procuring
 212 it through a distribution's package manager.
 213
 214 - https://releases.llvm.org/download.html
 215 - https://github.com/llvm/llvm-project
 216 - https://llvm.org/docs/GettingStarted.html
 217 - https://llvm.org/docs/CMake.html
 218 - https://apt.llvm.org/
 219 - https://www.archlinux.org/packages/extra/x86_64/llvm/
 220 - https://github.com/ClangBuiltLinux/tc-build
 221 - https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source
 222 - https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/