Documentation/llvm: refresh docs
Recent fixes for an embargoed hardware security vulnerability failed to link with ld.lld (LLVM's linker). [0] To be fair, our documentation mentions ``CC=clang`` foremost with ``LLVM=1`` being buried "below the fold." We want to encourage the use of ``LLVM=1`` rather than just ``CC=clang``. Make that suggestion "above the fold" and "front and center" in our docs. While here, the following additional changes were made: - remove the bit about CROSS_COMPILE setting --target=, that's no longer true. - Add ARCH=loongarch to the list of maintained targets (though we're still working on getting defconfig building cleanly at the moment; we're pretty close). - Bump ARCH=powerpc from CC=clang to LLVM=1 status. - Promote ARCH=riscv from being Maintained to being Supported. Android is working towards supporting RISC-V, and we have excellent support from multiple companies in this regard. - Note that the toolchain distribution on kernel.org has been built with profile data from kernel builds. - Note how to use ccache with clang. Link: https://github.com/ClangBuiltLinux/linux/issues/1907 [0] Reviewed-by: Nathan Chancellor <nathan@kernel.org> Signed-off-by: Nick Desaulniers <ndesaulniers@google.com> Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
This commit is contained in:
Nick Desaulniers
Masahiro Yamada
parent
1ef061a4e2
commit
a3c6bfba44
|
|
@ -25,50 +25,38 @@ 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
|
||||
-----
|
||||
Building with LLVM
|
||||
------------------
|
||||
|
||||
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. ::
|
||||
Invoke ``make`` via::
|
||||
|
||||
make CC=clang defconfig
|
||||
make LLVM=1
|
||||
|
||||
make CC=clang
|
||||
to compile for the host target. For cross compiling::
|
||||
|
||||
Cross Compiling
|
||||
---------------
|
||||
make LLVM=1 ARCH=arm64
|
||||
|
||||
A single Clang compiler binary will typically contain all supported backends,
|
||||
which can help simplify cross compiling. ::
|
||||
The LLVM= argument
|
||||
------------------
|
||||
|
||||
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::
|
||||
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
|
||||
``LLVM=1`` expands to the above.
|
||||
|
||||
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.
|
||||
which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. The
|
||||
following may also be used::
|
||||
|
||||
PATH=/path/to/llvm:$PATH make LLVM=1
|
||||
|
||||
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
|
||||
|
|
@ -78,31 +66,72 @@ can pass the suffix using the ``LLVM`` variable::
|
|||
|
||||
which will use ``clang-14``, ``ld.lld-14``, etc.
|
||||
|
||||
To support combinations of out of tree paths with version suffixes, we
|
||||
recommend::
|
||||
|
||||
PATH=/path/to/llvm/:$PATH make LLVM=-14
|
||||
|
||||
``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.
|
||||
``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.
|
||||
The same value used for ``LLVM=`` should be set for each invocation of ``make``
|
||||
if configuring and building via distinct commands. ``LLVM=`` should also be set
|
||||
as an environment variable when running scripts that will eventually run
|
||||
``make``.
|
||||
|
||||
Omitting CROSS_COMPILE
|
||||
Cross Compiling
|
||||
---------------
|
||||
|
||||
A single Clang compiler binary (and corresponding LLVM utilities) will
|
||||
typically contain all supported back ends, which can help simplify cross
|
||||
compiling especially when ``LLVM=1`` is used. If you use only LLVM tools,
|
||||
``CROSS_COMPILE`` or target-triple-prefixes become unnecessary. Example::
|
||||
|
||||
make LLVM=1 ARCH=arm64
|
||||
|
||||
As an example of mixing LLVM and GNU utilities, for a target like ``ARCH=s390``
|
||||
which does not yet have ``ld.lld`` or ``llvm-objcopy`` support, you could
|
||||
invoke ``make`` via::
|
||||
|
||||
make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \
|
||||
OBJCOPY=s390x-linux-gnu-objcopy
|
||||
|
||||
This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and
|
||||
``s390x-linux-gnu-objcopy``, so ensure those are reachable in your ``$PATH``.
|
||||
|
||||
``CROSS_COMPILE`` is not used to prefix the Clang compiler binary (or
|
||||
corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM=1``
|
||||
is not set.
|
||||
|
||||
The LLVM_IAS= argument
|
||||
----------------------
|
||||
|
||||
As explained above, ``CROSS_COMPILE`` is used to set ``--target=<triple>``.
|
||||
Clang can assemble assembler code. You can pass ``LLVM_IAS=0`` to disable this
|
||||
behavior and have Clang invoke the corresponding non-integrated assembler
|
||||
instead. Example::
|
||||
|
||||
If ``CROSS_COMPILE`` is not specified, the ``--target=<triple>`` is inferred
|
||||
from ``ARCH``.
|
||||
make LLVM=1 LLVM_IAS=0
|
||||
|
||||
That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary.
|
||||
``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=0``
|
||||
is used in order to set ``--prefix=`` for the compiler to find the
|
||||
corresponding non-integrated assembler (typically, you don't want to use the
|
||||
system assembler when targeting another architecture). Example::
|
||||
|
||||
For example, to cross-compile the arm64 kernel::
|
||||
make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi-
|
||||
|
||||
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. ::
|
||||
Ccache
|
||||
------
|
||||
|
||||
make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu-
|
||||
``ccache`` can be used with ``clang`` to improve subsequent builds, (though
|
||||
KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds
|
||||
in order to avoid 100% cache misses, see Reproducible_builds_ for more info):
|
||||
|
||||
KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang"
|
||||
|
||||
.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
|
||||
.. _Reproducible_builds: reproducible-builds.html#timestamps
|
||||
|
||||
Supported Architectures
|
||||
-----------------------
|
||||
|
|
@ -135,14 +164,17 @@ yet. Bug reports are always welcome at the issue tracker below!
|
|||
* - hexagon
|
||||
- Maintained
|
||||
- ``LLVM=1``
|
||||
* - loongarch
|
||||
- Maintained
|
||||
- ``LLVM=1``
|
||||
* - mips
|
||||
- Maintained
|
||||
- ``LLVM=1``
|
||||
* - powerpc
|
||||
- Maintained
|
||||
- ``CC=clang``
|
||||
- ``LLVM=1``
|
||||
* - riscv
|
||||
- Maintained
|
||||
- Supported
|
||||
- ``LLVM=1``
|
||||
* - s390
|
||||
- Maintained
|
||||
|
|
@ -171,7 +203,11 @@ Getting Help
|
|||
Getting LLVM
|
||||
-------------
|
||||
|
||||
We provide prebuilt stable versions of LLVM on `kernel.org <https://kernel.org/pub/tools/llvm/>`_.
|
||||
We provide prebuilt stable versions of LLVM on `kernel.org
|
||||
<https://kernel.org/pub/tools/llvm/>`_. These have been optimized with profile
|
||||
data for building Linux kernels, which should improve kernel build times
|
||||
relative to other distributions of LLVM.
|
||||
|
||||
Below are links that may be useful for building LLVM from source or procuring
|
||||
it through a distribution's package manager.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue