| Message ID | 20220215204947.1719516-1-ndesaulniers@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation/llvm: refresh docs for LLVM=1 | expand |
On Tue, Feb 15, 2022 at 12:49:47PM -0800, Nick Desaulniers wrote: > 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. This patch is doing a lot, it might make sense to split it up. Reviewing documentation changes is not the easiest as it is. Comments inline, thanks for the patch! > Signed-off-by: Nick Desaulniers <ndesaulniers@google.com> > --- > 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 make ARCH=arm64 LLVM=1 is used throughout the rest of the document and I think it is more consistent to keep all the variables on the right side of make. Compare: $ rg "make .*=" Documentation vs. $ rg "=.* make" Documentation > > -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 ... via the ``CC=``... ? > +``make``. ``CC=`` should be set when selecting a config and during a build. I think ``CC=`` should be set when generating a config and building a kernel. might read a little bit better? > +``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`` Are we ready for this yet? https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22%5BARCH%5D+powerpc%22+label%3A%22%5BTOOL%5D+integrated-as%22 I think we could potentially say LLVM=1 LLVM_IAS=0 but pseries_defconfig does not build with ld.lld: https://github.com/ClangBuiltLinux/linux/issues/602 Maybe it is worth breaking up powerpc into powerpc32, powerpc64, and powerpc64le? > * - riscv > - Maintained > - - ``CC=clang`` > + - ``LLVM=1`` > * - s390 > - Maintained > - - ``CC=clang`` > + - ``LLVM=1 LLVM_IAS=0`` I don't think s390 is ready for this claim. ld.lld and llvm-objcopy do not support s390, which are both used in a defconfig build, as far as I am aware. https://github.com/ClangBuiltLinux/linux/issues/1524 https://github.com/ClangBuiltLinux/linux/issues/1530 > * - x86 > - Supported > - ``LLVM=1`` > > base-commit: c5d9ae265b105d9a67575fb67bd4650a6fc08e25 > -- > 2.35.1.265.g69c8d7142f-goog > The rest of the changes look good to me. Cheers, Nathan
Hi Nick, Thanks for sending this so quickly, no warnings from a quick test: Tested-by: Miguel Ojeda <ojeda@kernel.org> A couple of nits below in case you do a v2. On Tue, Feb 15, 2022 at 9:49 PM Nick Desaulniers <ndesaulniers@google.com> wrote: > > * Word wrap a few columns over 80 lines. Top to bottom writing? :P > +For example: :: This may be simplified to: For example:: Similar applies elsewhere where a colon + :: marker is wanted. Not sure what the preferred style is, since the file uses both. Cheers, Miguel
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``
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@google.com> --- Documentation/kbuild/llvm.rst | 82 +++++++++++++++++++++-------------- 1 file changed, 50 insertions(+), 32 deletions(-) base-commit: c5d9ae265b105d9a67575fb67bd4650a6fc08e25