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 | ||
91a9d502 NC |
52 | LLVM has substitutes for GNU binutils utilities. Kbuild supports ``LLVM=1`` |
53 | to enable them. :: | |
a0d1c951 MY |
54 | |
55 | make LLVM=1 | |
56 | ||
91a9d502 | 57 | They can be enabled individually. The full list of the parameters: :: |
fcf1b6a3 | 58 | |
91a9d502 | 59 | make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ |
d9b5665f VG |
60 | OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ |
61 | HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld | |
fcf1b6a3 | 62 | |
f12b034a ND |
63 | The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to |
64 | disable it. | |
7e20e47c | 65 | |
e08831ba ND |
66 | Omitting CROSS_COMPILE |
67 | ---------------------- | |
68 | ||
69 | As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``. | |
70 | ||
e08831ba ND |
71 | If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred |
72 | from ``ARCH``. | |
73 | ||
74 | That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary. | |
75 | ||
76 | For example, to cross-compile the arm64 kernel:: | |
77 | ||
f12b034a ND |
78 | make ARCH=arm64 LLVM=1 |
79 | ||
80 | If ``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- | |
e08831ba | 84 | |
ed4e9e61 NC |
85 | Supported Architectures |
86 | ----------------------- | |
87 | ||
88 | LLVM does not target all of the architectures that Linux supports and | |
89 | just because a target is supported in LLVM does not mean that the kernel | |
90 | will build or work without any issues. Below is a general summary of | |
91 | architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level | |
92 | of support corresponds to "S" values in the MAINTAINERS files. If an | |
93 | architecture is not present, it either means that LLVM does not target | |
94 | it or there are known issues. Using the latest stable version of LLVM or | |
95 | even the development tree will generally yield the best results. | |
96 | An architecture's ``defconfig`` is generally expected to work well, | |
97 | certain configurations may have problems that have not been uncovered | |
98 | yet. 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 | ||
fcf1b6a3 ND |
129 | Getting Help |
130 | ------------ | |
131 | ||
132 | - `Website <https://clangbuiltlinux.github.io/>`_ | |
28f8fc19 NC |
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>`_ | |
fcf1b6a3 | 135 | - `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_ |
1c3493bb | 136 | - IRC: #clangbuiltlinux on irc.libera.chat |
fcf1b6a3 ND |
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 | ||
3519c4d6 ND |
141 | .. _getting_llvm: |
142 | ||
fcf1b6a3 ND |
143 | Getting LLVM |
144 | ------------- | |
145 | ||
16a122c7 | 146 | - https://releases.llvm.org/download.html |
fcf1b6a3 ND |
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/ |