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>`_, and `OpenMandriva
  19 <https://www.openmandriva.org/>`_ use Clang built kernels.  `LLVM is a
  20 collection 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
  22 supports C and the GNU C extensions required by the kernel, and is pronounced
  23 "klang," not "see-lang."
  24
  25 Clang
  26 -----
  27
  28 The 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
  35 Cross Compiling
  36 ---------------
  37
  38 A single Clang compiler binary will typically contain all supported backends,
  39 which 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
  45 example: ::
  46
  47         clang --target=aarch64-linux-gnu foo.c
  48
  49 LLVM Utilities
  50 --------------
  51
  52 LLVM has substitutes for GNU binutils utilities. They can be enabled individually.
  53 The 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
  59 To simplify the above command, Kbuild supports the ``LLVM`` variable::
  60
  61         make LLVM=1
  62
  63 If your LLVM tools are not available in your PATH, you can supply their
  64 location using the LLVM variable with a trailing slash::
  65
  66         make LLVM=/path/to/llvm/
  67
  68 which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc.
  69
  70 If your LLVM tools have a version suffix and you want to test with that
  71 explicit version rather than the unsuffixed executables like ``LLVM=1``, you
  72 can pass the suffix using the ``LLVM`` variable::
  73
  74         make LLVM=-14
  75
  76 which 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
  80 make variables.
  81
  82 The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
  83 disable it.
  84
  85 Omitting CROSS_COMPILE
  86 ----------------------
  87
  88 As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
  89
  90 If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
  91 from ``ARCH``.
  92
  93 That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
  94
  95 For example, to cross-compile the arm64 kernel::
  96
  97         make ARCH=arm64 LLVM=1
  98
  99 If ``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
 104 Supported Architectures
 105 -----------------------
 106
 107 LLVM does not target all of the architectures that Linux supports and
 108 just because a target is supported in LLVM does not mean that the kernel
 109 will build or work without any issues. Below is a general summary of
 110 architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
 111 of support corresponds to "S" values in the MAINTAINERS files. If an
 112 architecture is not present, it either means that LLVM does not target
 113 it or there are known issues. Using the latest stable version of LLVM or
 114 even the development tree will generally yield the best results.
 115 An architecture's ``defconfig`` is generally expected to work well,
 116 certain configurations may have problems that have not been uncovered
 117 yet. 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
 154 Getting 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
 168 Getting 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/