2020-08-26 19:15:55 +00:00
|
|
|
.. _kbuild_llvm:
|
|
|
|
|
2020-02-26 23:23:36 +00:00
|
|
|
==============================
|
|
|
|
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>`_, and `OpenMandriva
|
|
|
|
<https://www.openmandriva.org/>`_ use Clang built kernels. `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
|
|
|
|
-----
|
|
|
|
|
2020-08-25 23:14:38 +00:00
|
|
|
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. ::
|
2020-02-26 23:23:36 +00:00
|
|
|
|
|
|
|
make CC=clang defconfig
|
|
|
|
|
|
|
|
make CC=clang
|
|
|
|
|
|
|
|
Cross Compiling
|
|
|
|
---------------
|
|
|
|
|
|
|
|
A single Clang compiler binary will typically contain all supported backends,
|
2020-08-25 23:14:38 +00:00
|
|
|
which can help simplify cross compiling. ::
|
2020-02-26 23:23:36 +00:00
|
|
|
|
2021-08-02 18:39:10 +00:00
|
|
|
make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu-
|
2020-02-26 23:23:36 +00:00
|
|
|
|
2020-08-25 23:14:38 +00:00
|
|
|
``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead
|
2020-09-25 15:21:14 +00:00
|
|
|
``CROSS_COMPILE`` is used to set a command line flag: ``--target=<triple>``. For
|
2020-08-25 23:14:38 +00:00
|
|
|
example: ::
|
2020-02-26 23:23:36 +00:00
|
|
|
|
2020-09-25 15:21:14 +00:00
|
|
|
clang --target=aarch64-linux-gnu foo.c
|
2020-02-26 23:23:36 +00:00
|
|
|
|
|
|
|
LLVM Utilities
|
|
|
|
--------------
|
|
|
|
|
kbuild: Make $(LLVM) more flexible
The LLVM make variable allows a developer to quickly switch between the
GNU and LLVM tools. However, it does not handle versioned binaries, such
as the ones shipped by Debian, as LLVM=1 just defines the tool variables
with the unversioned binaries.
There was some discussion during the review of the patch that introduces
LLVM=1 around versioned binaries, ultimately coming to the conclusion
that developers can just add the folder that contains the unversioned
binaries to their PATH, as Debian's versioned suffixed binaries are
really just symlinks to the unversioned binaries in /usr/lib/llvm-#/bin:
$ realpath /usr/bin/clang-14
/usr/lib/llvm-14/bin/clang
$ PATH=/usr/lib/llvm-14/bin:$PATH make ... LLVM=1
However, that can be cumbersome to developers who are constantly testing
series with different toolchains and versions. It is simple enough to
support these versioned binaries directly in the Kbuild system by
allowing the developer to specify the version suffix with LLVM=, which
is shorter than the above suggestion:
$ make ... LLVM=-14
It does not change the meaning of LLVM=1 (which will continue to use
unversioned binaries) and it does not add too much additional complexity
to the existing $(LLVM) code, while allowing developers to quickly test
their series with different versions of the whole LLVM suite of tools.
Some developers may build LLVM from source but not add the binaries to
their PATH, as they may not want to use that toolchain systemwide.
Support those developers by allowing them to supply the directory that
the LLVM tools are available in, as it is no more complex to support
than the version suffix change above.
$ make ... LLVM=/path/to/llvm/
Update and reorder the documentation to reflect these new additions.
At the same time, notate that LLVM=0 is not the same as just omitting it
altogether, which has confused people in the past.
Link: https://lore.kernel.org/r/20200317215515.226917-1-ndesaulniers@google.com/
Link: https://lore.kernel.org/r/20220224151322.072632223@infradead.org/
Suggested-by: Masahiro Yamada <masahiroy@kernel.org>
Suggested-by: Peter Zijlstra <peterz@infradead.org>
Signed-off-by: Nathan Chancellor <nathan@kernel.org>
Reviewed-by: Kees Cook <keescook@chromium.org>
Reviewed-by: Nick Desaulniers <ndesaulniers@google.com>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
2022-03-04 17:08:14 +00:00
|
|
|
LLVM has substitutes for GNU binutils utilities. They can be enabled individually.
|
|
|
|
The full list of supported make variables::
|
2020-02-26 23:23:36 +00:00
|
|
|
|
2020-08-25 23:14:38 +00:00
|
|
|
make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \
|
2020-10-23 11:57:32 +00:00
|
|
|
OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \
|
|
|
|
HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld
|
2020-02-26 23:23:36 +00:00
|
|
|
|
kbuild: Make $(LLVM) more flexible
The LLVM make variable allows a developer to quickly switch between the
GNU and LLVM tools. However, it does not handle versioned binaries, such
as the ones shipped by Debian, as LLVM=1 just defines the tool variables
with the unversioned binaries.
There was some discussion during the review of the patch that introduces
LLVM=1 around versioned binaries, ultimately coming to the conclusion
that developers can just add the folder that contains the unversioned
binaries to their PATH, as Debian's versioned suffixed binaries are
really just symlinks to the unversioned binaries in /usr/lib/llvm-#/bin:
$ realpath /usr/bin/clang-14
/usr/lib/llvm-14/bin/clang
$ PATH=/usr/lib/llvm-14/bin:$PATH make ... LLVM=1
However, that can be cumbersome to developers who are constantly testing
series with different toolchains and versions. It is simple enough to
support these versioned binaries directly in the Kbuild system by
allowing the developer to specify the version suffix with LLVM=, which
is shorter than the above suggestion:
$ make ... LLVM=-14
It does not change the meaning of LLVM=1 (which will continue to use
unversioned binaries) and it does not add too much additional complexity
to the existing $(LLVM) code, while allowing developers to quickly test
their series with different versions of the whole LLVM suite of tools.
Some developers may build LLVM from source but not add the binaries to
their PATH, as they may not want to use that toolchain systemwide.
Support those developers by allowing them to supply the directory that
the LLVM tools are available in, as it is no more complex to support
than the version suffix change above.
$ make ... LLVM=/path/to/llvm/
Update and reorder the documentation to reflect these new additions.
At the same time, notate that LLVM=0 is not the same as just omitting it
altogether, which has confused people in the past.
Link: https://lore.kernel.org/r/20200317215515.226917-1-ndesaulniers@google.com/
Link: https://lore.kernel.org/r/20220224151322.072632223@infradead.org/
Suggested-by: Masahiro Yamada <masahiroy@kernel.org>
Suggested-by: Peter Zijlstra <peterz@infradead.org>
Signed-off-by: Nathan Chancellor <nathan@kernel.org>
Reviewed-by: Kees Cook <keescook@chromium.org>
Reviewed-by: Nick Desaulniers <ndesaulniers@google.com>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
2022-03-04 17:08:14 +00:00
|
|
|
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.
|
|
|
|
|
2021-08-06 17:27:01 +00:00
|
|
|
The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to
|
|
|
|
disable it.
|
2020-04-08 01:36:22 +00:00
|
|
|
|
2021-08-02 18:39:10 +00:00
|
|
|
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::
|
|
|
|
|
2021-08-06 17:27:01 +00:00
|
|
|
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-
|
2021-08-02 18:39:10 +00:00
|
|
|
|
2021-01-14 00:34:47 +00:00
|
|
|
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``
|
|
|
|
* - mips
|
|
|
|
- Maintained
|
|
|
|
- ``CC=clang``
|
|
|
|
* - powerpc
|
|
|
|
- Maintained
|
|
|
|
- ``CC=clang``
|
|
|
|
* - riscv
|
|
|
|
- Maintained
|
|
|
|
- ``CC=clang``
|
|
|
|
* - s390
|
|
|
|
- Maintained
|
|
|
|
- ``CC=clang``
|
|
|
|
* - x86
|
|
|
|
- Supported
|
|
|
|
- ``LLVM=1``
|
|
|
|
|
2020-02-26 23:23:36 +00:00
|
|
|
Getting Help
|
|
|
|
------------
|
|
|
|
|
|
|
|
- `Website <https://clangbuiltlinux.github.io/>`_
|
2021-09-08 02:58:27 +00:00
|
|
|
- `Mailing List <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev>
|
|
|
|
- `Old Mailing List Archives <https://groups.google.com/g/clang-built-linux>`_
|
2020-02-26 23:23:36 +00:00
|
|
|
- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
|
2021-09-08 02:58:30 +00:00
|
|
|
- IRC: #clangbuiltlinux on irc.libera.chat
|
2020-02-26 23:23:36 +00:00
|
|
|
- `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>`_
|
|
|
|
|
2020-08-26 19:15:55 +00:00
|
|
|
.. _getting_llvm:
|
|
|
|
|
2020-02-26 23:23:36 +00:00
|
|
|
Getting LLVM
|
|
|
|
-------------
|
|
|
|
|
2020-07-19 19:46:02 +00:00
|
|
|
- https://releases.llvm.org/download.html
|
2020-02-26 23:23:36 +00:00
|
|
|
- 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/
|