187 lines
6.0 KiB
ReStructuredText
187 lines
6.0 KiB
ReStructuredText
.. _kbuild_llvm:
|
|
|
|
==============================
|
|
Building Linux with Clang/LLVM
|
|
==============================
|
|
|
|
This document covers how to build the Linux kernel with Clang and LLVM
|
|
utilities.
|
|
|
|
About
|
|
-----
|
|
|
|
The Linux kernel has always traditionally been compiled with GNU toolchains
|
|
such as GCC and binutils. Ongoing work has allowed for `Clang
|
|
<https://clang.llvm.org/>`_ and `LLVM <https://llvm.org/>`_ utilities to be
|
|
used as viable substitutes. Distributions such as `Android
|
|
<https://www.android.com/>`_, `ChromeOS
|
|
<https://www.chromium.org/chromium-os>`_, `OpenMandriva
|
|
<https://www.openmandriva.org/>`_, and `Chimera Linux
|
|
<https://chimera-linux.org/>`_ use Clang built kernels. Google's and Meta's
|
|
datacenter fleets also run kernels built with Clang.
|
|
|
|
`LLVM is a collection of toolchain components implemented in terms of C++
|
|
objects <https://www.aosabook.org/en/llvm.html>`_. Clang is a front-end to LLVM
|
|
that supports C and the GNU C extensions required by the kernel, and is
|
|
pronounced "klang," not "see-lang."
|
|
|
|
Clang
|
|
-----
|
|
|
|
The compiler used can be swapped out via ``CC=`` command line argument to ``make``.
|
|
``CC=`` should be set when selecting a config and during a build. ::
|
|
|
|
make CC=clang defconfig
|
|
|
|
make CC=clang
|
|
|
|
Cross Compiling
|
|
---------------
|
|
|
|
A single Clang compiler binary will typically contain all supported backends,
|
|
which can help simplify cross compiling. ::
|
|
|
|
make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu-
|
|
|
|
``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead
|
|
``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For
|
|
example: ::
|
|
|
|
clang --target=aarch64-linux-gnu foo.c
|
|
|
|
LLVM Utilities
|
|
--------------
|
|
|
|
LLVM has substitutes for GNU binutils utilities. They can be enabled individually.
|
|
The full list of supported make variables::
|
|
|
|
make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \
|
|
OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \
|
|
HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld
|
|
|
|
To simplify the above command, Kbuild supports the ``LLVM`` variable::
|
|
|
|
make LLVM=1
|
|
|
|
If your LLVM tools are not available in your PATH, you can supply their
|
|
location using the LLVM variable with a trailing slash::
|
|
|
|
make LLVM=/path/to/llvm/
|
|
|
|
which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc.
|
|
|
|
If your LLVM tools have a version suffix and you want to test with that
|
|
explicit version rather than the unsuffixed executables like ``LLVM=1``, you
|
|
can pass the suffix using the ``LLVM`` variable::
|
|
|
|
make LLVM=-14
|
|
|
|
which will use ``clang-14``, ``ld.lld-14``, etc.
|
|
|
|
``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like
|
|
``LLVM=1``. If you only wish to use certain LLVM utilities, use their respective
|
|
make variables.
|
|
|
|
The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
|
|
disable it.
|
|
|
|
Omitting CROSS_COMPILE
|
|
----------------------
|
|
|
|
As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
|
|
|
|
If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
|
|
from ``ARCH``.
|
|
|
|
That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
|
|
|
|
For example, to cross-compile the arm64 kernel::
|
|
|
|
make ARCH=arm64 LLVM=1
|
|
|
|
If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive
|
|
``--prefix=<path>`` to search for the GNU assembler and linker. ::
|
|
|
|
make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu-
|
|
|
|
Supported Architectures
|
|
-----------------------
|
|
|
|
LLVM does not target all of the architectures that Linux supports and
|
|
just because a target is supported in LLVM does not mean that the kernel
|
|
will build or work without any issues. Below is a general summary of
|
|
architectures that currently work with ``CC=clang`` or ``LLVM=1``. Level
|
|
of support corresponds to "S" values in the MAINTAINERS files. If an
|
|
architecture is not present, it either means that LLVM does not target
|
|
it or there are known issues. Using the latest stable version of LLVM or
|
|
even the development tree will generally yield the best results.
|
|
An architecture's ``defconfig`` is generally expected to work well,
|
|
certain configurations may have problems that have not been uncovered
|
|
yet. Bug reports are always welcome at the issue tracker below!
|
|
|
|
.. list-table::
|
|
:widths: 10 10 10
|
|
:header-rows: 1
|
|
|
|
* - Architecture
|
|
- Level of support
|
|
- ``make`` command
|
|
* - arm
|
|
- Supported
|
|
- ``LLVM=1``
|
|
* - arm64
|
|
- Supported
|
|
- ``LLVM=1``
|
|
* - hexagon
|
|
- Maintained
|
|
- ``LLVM=1``
|
|
* - mips
|
|
- Maintained
|
|
- ``LLVM=1``
|
|
* - powerpc
|
|
- Maintained
|
|
- ``CC=clang``
|
|
* - riscv
|
|
- Maintained
|
|
- ``LLVM=1``
|
|
* - s390
|
|
- Maintained
|
|
- ``CC=clang``
|
|
* - um (User Mode)
|
|
- Maintained
|
|
- ``LLVM=1``
|
|
* - x86
|
|
- Supported
|
|
- ``LLVM=1``
|
|
|
|
Getting Help
|
|
------------
|
|
|
|
- `Website <https://clangbuiltlinux.github.io/>`_
|
|
- `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev>
|
|
- `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_
|
|
- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
|
|
- IRC: #clangbuiltlinux on irc.libera.chat
|
|
- `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux
|
|
- `Wiki <https://github.com/ClangBuiltLinux/linux/wiki>`_
|
|
- `Beginner Bugs <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_
|
|
|
|
.. _getting_llvm:
|
|
|
|
Getting LLVM
|
|
-------------
|
|
|
|
We provide prebuilt stable versions of LLVM on `kernel.org <https://kernel.org/pub/tools/llvm/>`_.
|
|
Below are links that may be useful for building LLVM from source or procuring
|
|
it through a distribution's package manager.
|
|
|
|
- https://releases.llvm.org/download.html
|
|
- https://github.com/llvm/llvm-project
|
|
- https://llvm.org/docs/GettingStarted.html
|
|
- https://llvm.org/docs/CMake.html
|
|
- https://apt.llvm.org/
|
|
- https://www.archlinux.org/packages/extra/x86_64/llvm/
|
|
- https://github.com/ClangBuiltLinux/tc-build
|
|
- https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source
|
|
- https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/
|