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