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 Currently, the integrated assembler is disabled by default. You can pass
  64 ``LLVM_IAS=1`` to enable it.
  65
  66 Omitting CROSS_COMPILE
  67 ----------------------
  68
  69 As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
  70
  71 Unless ``LLVM_IAS=1`` is specified, ``CROSS_COMPILE`` is also used to derive
  72 ``--prefix=<path>`` to search for the GNU assembler and linker.
  73
  74 If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
  75 from ``ARCH``.
  76
  77 That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
  78
  79 For example, to cross-compile the arm64 kernel::
  80
  81         make ARCH=arm64 LLVM=1 LLVM_IAS=1
  82
  83 Supported Architectures
  84 -----------------------
  85
  86 LLVM does not target all of the architectures that Linux supports and
  87 just because a target is supported in LLVM does not mean that the kernel
  88 will build or work without any issues. Below is a general summary of
  89 architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
  90 of support corresponds to "S" values in the MAINTAINERS files. If an
  91 architecture is not present, it either means that LLVM does not target
  92 it or there are known issues. Using the latest stable version of LLVM or
  93 even the development tree will generally yield the best results.
  94 An architecture's ``defconfig`` is generally expected to work well,
  95 certain configurations may have problems that have not been uncovered
  96 yet. Bug reports are always welcome at the issue tracker below!
  97
  98 .. list-table::
  99    :widths: 10 10 10
 100    :header-rows: 1
 101
 102    * - Architecture
 103      - Level of support
 104      - ``make`` command
 105    * - arm
 106      - Supported
 107      - ``LLVM=1``
 108    * - arm64
 109      - Supported
 110      - ``LLVM=1``
 111    * - mips
 112      - Maintained
 113      - ``CC=clang``
 114    * - powerpc
 115      - Maintained
 116      - ``CC=clang``
 117    * - riscv
 118      - Maintained
 119      - ``CC=clang``
 120    * - s390
 121      - Maintained
 122      - ``CC=clang``
 123    * - x86
 124      - Supported
 125      - ``LLVM=1``
 126
 127 Getting Help
 128 ------------
 129
 130 - `Website <https://clangbuiltlinux.github.io/>`_
 131 - `Mailing List <https://groups.google.com/forum/#!forum/clang-built-linux>`_: <clang-built-linux@googlegroups.com>
 132 - `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
 133 - IRC: #clangbuiltlinux on chat.freenode.net
 134 - `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux
 135 - `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_
 136 - `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_
 137
 138 .. _getting_llvm:
 139
 140 Getting LLVM
 141 -------------
 142
 143 - https://releases.llvm.org/download.html
 144 - https://github.com/llvm/llvm-project
 145 - https://llvm.org/docs/GettingStarted.html
 146 - https://llvm.org/docs/CMake.html
 147 - https://apt.llvm.org/
 148 - https://www.archlinux.org/packages/extra/x86_64/llvm/
 149 - https://github.com/ClangBuiltLinux/tc-build
 150 - https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source
 151 - https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/