xref: /linux/Documentation/kbuild/llvm.rst (revision 84b9b44b) 
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>`_, `OpenMandriva
19<https://www.openmandriva.org/>`_, and `Chimera Linux
20<https://chimera-linux.org/>`_ use Clang built kernels. Google's and Meta's
21datacenter fleets also run kernels built with Clang.
22
23`LLVM is a collection of toolchain components implemented in terms of C++
24objects <https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM
25that supports C and the GNU C extensions required by the kernel, and is
26pronounced "klang," not "see-lang."
27
28Clang
29-----
30
31The compiler used can be swapped out via ``CC=`` command line argument to ``make``.
32``CC=`` should be set when selecting a config and during a build. ::
33
34	make CC=clang defconfig
35
36	make CC=clang
37
38Cross Compiling
39---------------
40
41A single Clang compiler binary will typically contain all supported backends,
42which can help simplify cross compiling. ::
43
44	make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu-
45
46``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead
47``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For
48example: ::
49
50	clang --target=aarch64-linux-gnu foo.c
51
52LLVM Utilities
53--------------
54
55LLVM has substitutes for GNU binutils utilities. They can be enabled individually.
56The full list of supported make variables::
57
58	make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \
59	  OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \
60	  HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld
61
62To simplify the above command, Kbuild supports the ``LLVM`` variable::
63
64	make LLVM=1
65
66If your LLVM tools are not available in your PATH, you can supply their
67location using the LLVM variable with a trailing slash::
68
69	make LLVM=/path/to/llvm/
70
71which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc.
72
73If your LLVM tools have a version suffix and you want to test with that
74explicit version rather than the unsuffixed executables like ``LLVM=1``, you
75can pass the suffix using the ``LLVM`` variable::
76
77	make LLVM=-14
78
79which will use ``clang-14``, ``ld.lld-14``, etc.
80
81``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like
82``LLVM=1``. If you only wish to use certain LLVM utilities, use their respective
83make variables.
84
85The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
86disable it.
87
88Omitting CROSS_COMPILE
89----------------------
90
91As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
92
93If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
94from ``ARCH``.
95
96That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
97
98For example, to cross-compile the arm64 kernel::
99
100	make ARCH=arm64 LLVM=1
101
102If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive
103``--prefix=<path>`` to search for the GNU assembler and linker. ::
104
105	make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu-
106
107Supported Architectures
108-----------------------
109
110LLVM does not target all of the architectures that Linux supports and
111just because a target is supported in LLVM does not mean that the kernel
112will build or work without any issues. Below is a general summary of
113architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
114of support corresponds to "S" values in the MAINTAINERS files. If an
115architecture is not present, it either means that LLVM does not target
116it or there are known issues. Using the latest stable version of LLVM or
117even the development tree will generally yield the best results.
118An architecture's ``defconfig`` is generally expected to work well,
119certain configurations may have problems that have not been uncovered
120yet. Bug reports are always welcome at the issue tracker below!
121
122.. list-table::
123   :widths: 10 10 10
124   :header-rows: 1
125
126   * - Architecture
127     - Level of support
128     - ``make`` command
129   * - arm
130     - Supported
131     - ``LLVM=1``
132   * - arm64
133     - Supported
134     - ``LLVM=1``
135   * - hexagon
136     - Maintained
137     - ``LLVM=1``
138   * - mips
139     - Maintained
140     - ``LLVM=1``
141   * - powerpc
142     - Maintained
143     - ``CC=clang``
144   * - riscv
145     - Maintained
146     - ``LLVM=1``
147   * - s390
148     - Maintained
149     - ``CC=clang``
150   * - um (User Mode)
151     - Maintained
152     - ``LLVM=1``
153   * - x86
154     - Supported
155     - ``LLVM=1``
156
157Getting Help
158------------
159
160- `Website <https://clangbuiltlinux.github.io/>`_
161- `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev>
162- `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_
163- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
164- IRC: #clangbuiltlinux on irc.libera.chat
165- `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux
166- `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_
167- `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_
168
169.. _getting_llvm:
170
171Getting LLVM
172-------------
173
174We provide prebuilt stable versions of LLVM on `kernel.org <https://kernel.org/pub/tools/llvm/>`_.
175Below are links that may be useful for building LLVM from source or procuring
176it through a distribution's package manager.
177
178- https://releases.llvm.org/download.html
179- https://github.com/llvm/llvm-project
180- https://llvm.org/docs/GettingStarted.html
181- https://llvm.org/docs/CMake.html
182- https://apt.llvm.org/
183- https://www.archlinux.org/packages/extra/x86_64/llvm/
184- https://github.com/ClangBuiltLinux/tc-build
185- https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source
186- https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/
187