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