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. Kbuild supports ``LLVM=1``
  53 to enable them. ::
  54
  55         make LLVM=1
  56
  57 They 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
  63 The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
  64 disable it.
  65
  66 Omitting CROSS_COMPILE
  67 ----------------------
  68
  69 As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
  70
  71 If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
  72 from ``ARCH``.
  73
  74 That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
  75
  76 For example, to cross-compile the arm64 kernel::
  77
  78         make ARCH=arm64 LLVM=1
  79
  80 If ``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
  85 Supported Architectures
  86 -----------------------
  87
  88 LLVM does not target all of the architectures that Linux supports and
  89 just because a target is supported in LLVM does not mean that the kernel
  90 will build or work without any issues. Below is a general summary of
  91 architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
  92 of support corresponds to "S" values in the MAINTAINERS files. If an
  93 architecture is not present, it either means that LLVM does not target
  94 it or there are known issues. Using the latest stable version of LLVM or
  95 even the development tree will generally yield the best results.
  96 An architecture's ``defconfig`` is generally expected to work well,
  97 certain configurations may have problems that have not been uncovered
  98 yet. 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
 129 Getting 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
 143 Getting 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/