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 Clang
  29 -----
  30
  31 The 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
  38 Cross Compiling
  39 ---------------
  40
  41 A single Clang compiler binary will typically contain all supported backends,
  42 which 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
  48 example: ::
  49
  50         clang --target=aarch64-linux-gnu foo.c
  51
  52 LLVM Utilities
  53 --------------
  54
  55 LLVM has substitutes for GNU binutils utilities. They can be enabled individually.
  56 The 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
  62 To simplify the above command, Kbuild supports the ``LLVM`` variable::
  63
  64         make LLVM=1
  65
  66 If your LLVM tools are not available in your PATH, you can supply their
  67 location using the LLVM variable with a trailing slash::
  68
  69         make LLVM=/path/to/llvm/
  70
  71 which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc.
  72
  73 If your LLVM tools have a version suffix and you want to test with that
  74 explicit version rather than the unsuffixed executables like ``LLVM=1``, you
  75 can pass the suffix using the ``LLVM`` variable::
  76
  77         make LLVM=-14
  78
  79 which 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
  83 make variables.
  84
  85 The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
  86 disable it.
  87
  88 Omitting CROSS_COMPILE
  89 ----------------------
  90
  91 As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
  92
  93 If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
  94 from ``ARCH``.
  95
  96 That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
  97
  98 For example, to cross-compile the arm64 kernel::
  99
 100         make ARCH=arm64 LLVM=1
 101
 102 If ``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
 107 Supported Architectures
 108 -----------------------
 109
 110 LLVM does not target all of the architectures that Linux supports and
 111 just because a target is supported in LLVM does not mean that the kernel
 112 will build or work without any issues. Below is a general summary of
 113 architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
 114 of support corresponds to "S" values in the MAINTAINERS files. If an
 115 architecture is not present, it either means that LLVM does not target
 116 it or there are known issues. Using the latest stable version of LLVM or
 117 even the development tree will generally yield the best results.
 118 An architecture's ``defconfig`` is generally expected to work well,
 119 certain configurations may have problems that have not been uncovered
 120 yet. 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
 157 Getting 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
 171 Getting LLVM
 172 -------------
 173
 174 We provide prebuilt stable versions of LLVM on `kernel.org <https://kernel.org/pub/tools/llvm/>`_.
 175 Below are links that may be useful for building LLVM from source or procuring
 176 it 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/