1.. _kbuild_llvm:
2
3==============================
4Building Linux with Clang/LLVM
5==============================
6
7This document covers how to build the Linux kernel with Clang and LLVM
8utilities.
9
10About
11-----
12
13The Linux kernel has always traditionally been compiled with GNU toolchains
14such as GCC and binutils. Ongoing work has allowed for `Clang
15<https://clang.llvm.org/>`_ and `LLVM <https://llvm.org/>`_ utilities to be
16used 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
20collection 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
22supports C and the GNU C extensions required by the kernel, and is pronounced
23"klang," not "see-lang."
24
25Clang
26-----
27
28The 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
35Cross Compiling
36---------------
37
38A single Clang compiler binary will typically contain all supported backends,
39which 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
45example: ::
46
47	clang --target=aarch64-linux-gnu foo.c
48
49LLVM Utilities
50--------------
51
52LLVM has substitutes for GNU binutils utilities. Kbuild supports ``LLVM=1``
53to enable them. ::
54
55	make LLVM=1
56
57They 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
63The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
64disable it.
65
66Omitting CROSS_COMPILE
67----------------------
68
69As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
70
71If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
72from ``ARCH``.
73
74That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
75
76For example, to cross-compile the arm64 kernel::
77
78	make ARCH=arm64 LLVM=1
79
80If ``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
85Supported Architectures
86-----------------------
87
88LLVM does not target all of the architectures that Linux supports and
89just because a target is supported in LLVM does not mean that the kernel
90will build or work without any issues. Below is a general summary of
91architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
92of support corresponds to "S" values in the MAINTAINERS files. If an
93architecture is not present, it either means that LLVM does not target
94it or there are known issues. Using the latest stable version of LLVM or
95even the development tree will generally yield the best results.
96An architecture's ``defconfig`` is generally expected to work well,
97certain configurations may have problems that have not been uncovered
98yet. 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
129Getting 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
143Getting 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/
155