0001 .. _kbuild_llvm:
0002
0003 ==============================
0004 Building Linux with Clang/LLVM
0005 ==============================
0006
0007 This document covers how to build the Linux kernel with Clang and LLVM
0008 utilities.
0009
0010 About
0011 -----
0012
0013 The Linux kernel has always traditionally been compiled with GNU toolchains
0014 such as GCC and binutils. Ongoing work has allowed for `Clang
0015 <https://clang.llvm.org/>`_ and `LLVM <https://llvm.org/>`_ utilities to be
0016 used as viable substitutes. Distributions such as `Android
0017 <https://www.android.com/>`_, `ChromeOS
0018 <https://www.chromium.org/chromium-os>`_, and `OpenMandriva
0019 <https://www.openmandriva.org/>`_ use Clang built kernels. `LLVM is a
0020 collection of toolchain components implemented in terms of C++ objects
0021 <https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM that
0022 supports C and the GNU C extensions required by the kernel, and is pronounced
0023 "klang," not "see-lang."
0024
0025 Clang
0026 -----
0027
0028 The compiler used can be swapped out via ``CC=`` command line argument to ``make``.
0029 ``CC=`` should be set when selecting a config and during a build. ::
0030
0031 make CC=clang defconfig
0032
0033 make CC=clang
0034
0035 Cross Compiling
0036 ---------------
0037
0038 A single Clang compiler binary will typically contain all supported backends,
0039 which can help simplify cross compiling. ::
0040
0041 make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu-
0042
0043 ``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead
0044 ``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For
0045 example: ::
0046
0047 clang --target=aarch64-linux-gnu foo.c
0048
0049 LLVM Utilities
0050 --------------
0051
0052 LLVM has substitutes for GNU binutils utilities. They can be enabled individually.
0053 The full list of supported make variables::
0054
0055 make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \
0056 OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \
0057 HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld
0058
0059 To simplify the above command, Kbuild supports the ``LLVM`` variable::
0060
0061 make LLVM=1
0062
0063 If your LLVM tools are not available in your PATH, you can supply their
0064 location using the LLVM variable with a trailing slash::
0065
0066 make LLVM=/path/to/llvm/
0067
0068 which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc.
0069
0070 If your LLVM tools have a version suffix and you want to test with that
0071 explicit version rather than the unsuffixed executables like ``LLVM=1``, you
0072 can pass the suffix using the ``LLVM`` variable::
0073
0074 make LLVM=-14
0075
0076 which will use ``clang-14``, ``ld.lld-14``, etc.
0077
0078 ``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like
0079 ``LLVM=1``. If you only wish to use certain LLVM utilities, use their respective
0080 make variables.
0081
0082 The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
0083 disable it.
0084
0085 Omitting CROSS_COMPILE
0086 ----------------------
0087
0088 As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
0089
0090 If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
0091 from ``ARCH``.
0092
0093 That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
0094
0095 For example, to cross-compile the arm64 kernel::
0096
0097 make ARCH=arm64 LLVM=1
0098
0099 If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive
0100 ``--prefix=<path>`` to search for the GNU assembler and linker. ::
0101
0102 make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu-
0103
0104 Supported Architectures
0105 -----------------------
0106
0107 LLVM does not target all of the architectures that Linux supports and
0108 just because a target is supported in LLVM does not mean that the kernel
0109 will build or work without any issues. Below is a general summary of
0110 architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
0111 of support corresponds to "S" values in the MAINTAINERS files. If an
0112 architecture is not present, it either means that LLVM does not target
0113 it or there are known issues. Using the latest stable version of LLVM or
0114 even the development tree will generally yield the best results.
0115 An architecture's ``defconfig`` is generally expected to work well,
0116 certain configurations may have problems that have not been uncovered
0117 yet. Bug reports are always welcome at the issue tracker below!
0118
0119 .. list-table::
0120 :widths: 10 10 10
0121 :header-rows: 1
0122
0123 * - Architecture
0124 - Level of support
0125 - ``make`` command
0126 * - arm
0127 - Supported
0128 - ``LLVM=1``
0129 * - arm64
0130 - Supported
0131 - ``LLVM=1``
0132 * - hexagon
0133 - Maintained
0134 - ``LLVM=1``
0135 * - mips
0136 - Maintained
0137 - ``LLVM=1``
0138 * - powerpc
0139 - Maintained
0140 - ``CC=clang``
0141 * - riscv
0142 - Maintained
0143 - ``LLVM=1``
0144 * - s390
0145 - Maintained
0146 - ``CC=clang``
0147 * - um (User Mode)
0148 - Maintained
0149 - ``LLVM=1``
0150 * - x86
0151 - Supported
0152 - ``LLVM=1``
0153
0154 Getting Help
0155 ------------
0156
0157 - `Website <https://clangbuiltlinux.github.io/>`_
0158 - `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev>
0159 - `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_
0160 - `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
0161 - IRC: #clangbuiltlinux on irc.libera.chat
0162 - `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux
0163 - `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_
0164 - `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_
0165
0166 .. _getting_llvm:
0167
0168 Getting LLVM
0169 -------------
0170
0171 - https://releases.llvm.org/download.html
0172 - https://github.com/llvm/llvm-project
0173 - https://llvm.org/docs/GettingStarted.html
0174 - https://llvm.org/docs/CMake.html
0175 - https://apt.llvm.org/
0176 - https://www.archlinux.org/packages/extra/x86_64/llvm/
0177 - https://github.com/ClangBuiltLinux/tc-build
0178 - https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source
0179 - https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/
