Refresh the docs for 2022: * add link to Chimera Linux. * add Quick Start section pointing out that LLVM=1 is the simple recommended method. * Re-order the sections on Clang and Cross Compiling to come after the section on LLVM utilities. I think the documentation flows better this way. * Add note about LLVM=1 to Omitting CROSS_COMPILE section. * Change note in Supported Architectures from discussing CC=clang vs. LLVM=1 to discussion LLVM=1 vs. LLVM_IAS=0. * Update make command column of support architecture table; we now support LLVM=1 everywhere; just some more work to get ARCH=s390 assembling with clang. * Word wrap a few columns over 80 lines. Signed-off-by: Nick Desaulniers <ndesaulniers@xxxxxxxxxx> --- Documentation/kbuild/llvm.rst | 82 +++++++++++++++++++++-------------- 1 file changed, 50 insertions(+), 32 deletions(-) diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index d32616891dcf..7f52cde70bc7 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -15,36 +15,27 @@ 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 +<https://www.chromium.org/chromium-os>`_, `OpenMandriva +<https://www.openmandriva.org/>`_, and `Chimera Linux +<https://chimera-linux.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 ------ +Quick Start +----------- +:: -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 LLVM=1 - make CC=clang defconfig +for native builds or - make CC=clang +or :: -Cross Compiling ---------------- + ARCH=arm64 make LLVM=1 -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 +for cross compiling. LLVM Utilities -------------- @@ -63,6 +54,32 @@ They can be enabled individually. The full list of the parameters: :: The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to disable it. +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. +``CC=clang`` is implied by ``LLVM=1``, but if it's desired to simply use clang +as the compiler for the target, then ``CC=`` is a quick substitute. :: + + 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 + Omitting CROSS_COMPILE ---------------------- @@ -71,7 +88,8 @@ 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. +That means if you use only LLVM tools via ``LLVM=1``, ``CROSS_COMPILE`` becomes +unnecessary. For example, to cross-compile the arm64 kernel:: @@ -88,13 +106,13 @@ 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 +architectures that currently work with ``LLVM=1`` but may need the integrated +assembler disabled via ``LLVM_IAS=0``. 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:: @@ -112,16 +130,16 @@ yet. Bug reports are always welcome at the issue tracker below! - ``LLVM=1`` * - mips - Maintained - - ``CC=clang`` + - ``LLVM=1`` * - powerpc - Maintained - - ``CC=clang`` + - ``LLVM=1`` * - riscv - Maintained - - ``CC=clang`` + - ``LLVM=1`` * - s390 - Maintained - - ``CC=clang`` + - ``LLVM=1 LLVM_IAS=0`` * - x86 - Supported - ``LLVM=1`` base-commit: c5d9ae265b105d9a67575fb67bd4650a6fc08e25 -- 2.35.1.265.g69c8d7142f-goog
