Commit | Line | Data |
---|---|---|
3519c4d6 ND |
1 | .. _kbuild_llvm: |
2 | ||
fcf1b6a3 ND |
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 | |
0aee6bec ND |
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 | |
21 | datacenter fleets also run kernels built with Clang. | |
22 | ||
23 | `LLVM is a collection of toolchain components implemented in terms of C++ | |
24 | objects <https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM | |
25 | that supports C and the GNU C extensions required by the kernel, and is | |
26 | pronounced "klang," not "see-lang." | |
fcf1b6a3 ND |
27 | |
28 | Clang | |
29 | ----- | |
30 | ||
91a9d502 NC |
31 | The 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. :: | |
fcf1b6a3 ND |
33 | |
34 | make CC=clang defconfig | |
35 | ||
36 | make CC=clang | |
37 | ||
38 | Cross Compiling | |
39 | --------------- | |
40 | ||
41 | A single Clang compiler binary will typically contain all supported backends, | |
91a9d502 | 42 | which can help simplify cross compiling. :: |
fcf1b6a3 | 43 | |
e08831ba | 44 | make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu- |
fcf1b6a3 | 45 | |
91a9d502 | 46 | ``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead |
e30d694c | 47 | ``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For |
91a9d502 | 48 | example: :: |
fcf1b6a3 | 49 | |
e30d694c | 50 | clang --target=aarch64-linux-gnu foo.c |
fcf1b6a3 ND |
51 | |
52 | LLVM Utilities | |
53 | -------------- | |
54 | ||
e9c28192 NC |
55 | LLVM has substitutes for GNU binutils utilities. They can be enabled individually. |
56 | The full list of supported make variables:: | |
fcf1b6a3 | 57 | |
91a9d502 | 58 | make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ |
d9b5665f VG |
59 | OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ |
60 | HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld | |
fcf1b6a3 | 61 | |
e9c28192 NC |
62 | To simplify the above command, Kbuild supports the ``LLVM`` variable:: |
63 | ||
64 | make LLVM=1 | |
65 | ||
66 | If your LLVM tools are not available in your PATH, you can supply their | |
67 | location using the LLVM variable with a trailing slash:: | |
68 | ||
69 | make LLVM=/path/to/llvm/ | |
70 | ||
71 | which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. | |
72 | ||
73 | If your LLVM tools have a version suffix and you want to test with that | |
74 | explicit version rather than the unsuffixed executables like ``LLVM=1``, you | |
75 | can pass the suffix using the ``LLVM`` variable:: | |
76 | ||
77 | make LLVM=-14 | |
78 | ||
79 | which 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 | |
83 | make variables. | |
84 | ||
f12b034a ND |
85 | The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to |
86 | disable it. | |
7e20e47c | 87 | |
e08831ba ND |
88 | Omitting CROSS_COMPILE |
89 | ---------------------- | |
90 | ||
91 | As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``. | |
92 | ||
e08831ba ND |
93 | If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred |
94 | from ``ARCH``. | |
95 | ||
96 | That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary. | |
97 | ||
98 | For example, to cross-compile the arm64 kernel:: | |
99 | ||
f12b034a ND |
100 | make ARCH=arm64 LLVM=1 |
101 | ||
102 | If ``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- | |
e08831ba | 106 | |
ed4e9e61 NC |
107 | Supported Architectures |
108 | ----------------------- | |
109 | ||
110 | LLVM does not target all of the architectures that Linux supports and | |
111 | just because a target is supported in LLVM does not mean that the kernel | |
112 | will build or work without any issues. Below is a general summary of | |
113 | architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level | |
114 | of support corresponds to "S" values in the MAINTAINERS files. If an | |
115 | architecture is not present, it either means that LLVM does not target | |
116 | it or there are known issues. Using the latest stable version of LLVM or | |
117 | even the development tree will generally yield the best results. | |
118 | An architecture's ``defconfig`` is generally expected to work well, | |
119 | certain configurations may have problems that have not been uncovered | |
120 | yet. 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`` | |
291810be ND |
135 | * - hexagon |
136 | - Maintained | |
137 | - ``LLVM=1`` | |
ed4e9e61 NC |
138 | * - mips |
139 | - Maintained | |
291810be | 140 | - ``LLVM=1`` |
ed4e9e61 NC |
141 | * - powerpc |
142 | - Maintained | |
143 | - ``CC=clang`` | |
144 | * - riscv | |
145 | - Maintained | |
291810be | 146 | - ``LLVM=1`` |
ed4e9e61 NC |
147 | * - s390 |
148 | - Maintained | |
149 | - ``CC=clang`` | |
291810be ND |
150 | * - um (User Mode) |
151 | - Maintained | |
152 | - ``LLVM=1`` | |
ed4e9e61 NC |
153 | * - x86 |
154 | - Supported | |
155 | - ``LLVM=1`` | |
156 | ||
fcf1b6a3 ND |
157 | Getting Help |
158 | ------------ | |
159 | ||
160 | - `Website <https://clangbuiltlinux.github.io/>`_ | |
28f8fc19 NC |
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>`_ | |
fcf1b6a3 | 163 | - `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_ |
1c3493bb | 164 | - IRC: #clangbuiltlinux on irc.libera.chat |
fcf1b6a3 ND |
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 | ||
3519c4d6 ND |
169 | .. _getting_llvm: |
170 | ||
fcf1b6a3 ND |
171 | Getting LLVM |
172 | ------------- | |
173 | ||
dcc11ac9 NC |
174 | We provide prebuilt stable versions of LLVM on `kernel.org <https://kernel.org/pub/tools/llvm/>`_. |
175 | Below are links that may be useful for building LLVM from source or procuring | |
176 | it through a distribution's package manager. | |
177 | ||
16a122c7 | 178 | - https://releases.llvm.org/download.html |
fcf1b6a3 ND |
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/ |