Documentation/llvm: add documentation on building w/ Clang/LLVM

Commit Message

Nick Desaulniers Feb. 24, 2020, 5:41 p.m. UTC

Added to kbuild documentation. Provides more official info on building
kernels with Clang and LLVM than our wiki.

Suggested-by: Kees Cook <[e-mail]>
Reviewed-by: Nathan Chancellor <[e-mail]>
Signed-off-by: Nick Desaulniers <[e-mail]>
---
 Documentation/kbuild/index.rst |  1 +
 Documentation/kbuild/llvm.rst  | 80 ++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 Documentation/kbuild/llvm.rst

Comments

Randy Dunlap Feb. 24, 2020, 9:20 p.m. UTC | #1

On 2/24/20 9:41 AM, Nick Desaulniers wrote:
> Added to kbuild documentation. Provides more official info on building
> kernels with Clang and LLVM than our wiki.
> 
> Suggested-by: Kees Cook <[e-mail]>
> Reviewed-by: Nathan Chancellor <[e-mail]>
> Signed-off-by: Nick Desaulniers <[e-mail]>
> ---
>  Documentation/kbuild/index.rst |  1 +
>  Documentation/kbuild/llvm.rst  | 80 ++++++++++++++++++++++++++++++++++
>  2 files changed, 81 insertions(+)
>  create mode 100644 Documentation/kbuild/llvm.rst
> 
> diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
> index 0f144fad99a6..3882bd5f7728 100644
> --- a/Documentation/kbuild/index.rst
> +++ b/Documentation/kbuild/index.rst
> @@ -19,6 +19,7 @@ Kernel Build System
>  
>      issues
>      reproducible-builds
> +    llvm
>  
>  .. only::  subproject and html
>  
> diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
> new file mode 100644
> index 000000000000..68ae022aebc0
> --- /dev/null
> +++ b/Documentation/kbuild/llvm.rst
> @@ -0,0 +1,80 @@
> +==============================
> +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. On going work has allowed for `Clang

                             Ongoing

> +<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."


Thanks for the info.

Masahiro Yamada Feb. 25, 2020, 12:33 a.m. UTC | #2

On Tue, Feb 25, 2020 at 2:41 AM Nick Desaulniers
<[e-mail]> wrote:
>
> Added to kbuild documentation. Provides more official info on building
> kernels with Clang and LLVM than our wiki.
>
> Suggested-by: Kees Cook <[e-mail]>
> Reviewed-by: Nathan Chancellor <[e-mail]>
> Signed-off-by: Nick Desaulniers <[e-mail]>
> ---


Perhaps, is it better to explicitly add it to MAINTAINERS?

--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4118,6 +4118,7 @@ W:        https://clangbuiltlinux.github.io/
 B:     https://github.com/ClangBuiltLinux/linux/issues
 C:     irc://chat.freenode.net/clangbuiltlinux
 S:     Supported
+F:     Documentation/kbuild/llvm.rst
 K:     \b(?i:clang|llvm)\b

 CLEANCACHE API



Thanks.

Kees Cook Feb. 25, 2020, 4:08 a.m. UTC | #3

On Mon, Feb 24, 2020 at 09:41:28AM -0800, Nick Desaulniers wrote:
> Added to kbuild documentation. Provides more official info on building
> kernels with Clang and LLVM than our wiki.
> 
> Suggested-by: Kees Cook <[e-mail]>
> Reviewed-by: Nathan Chancellor <[e-mail]>
> Signed-off-by: Nick Desaulniers <[e-mail]>
> ---
>  Documentation/kbuild/index.rst |  1 +
>  Documentation/kbuild/llvm.rst  | 80 ++++++++++++++++++++++++++++++++++
>  2 files changed, 81 insertions(+)
>  create mode 100644 Documentation/kbuild/llvm.rst
> 
> diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
> index 0f144fad99a6..3882bd5f7728 100644
> --- a/Documentation/kbuild/index.rst
> +++ b/Documentation/kbuild/index.rst
> @@ -19,6 +19,7 @@ Kernel Build System
>  
>      issues
>      reproducible-builds
> +    llvm
>  
>  .. only::  subproject and html
>  
> diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
> new file mode 100644
> index 000000000000..68ae022aebc0
> --- /dev/null
> +++ b/Documentation/kbuild/llvm.rst
> @@ -0,0 +1,80 @@
> +==============================
> +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. On going 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
> +-----
> +
> +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.
> +
> +	ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make CC=clang
> +
> +`CROSS_COMPILE` is not used to suffix the Clang compiler binary, instead

s/suffix/prefix/

> +`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. These can be invoked as
> +additional parameters to `make`.
> +
> +	make CC=clang AS=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \\
> +	  OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump OBJSIZE=llvm-objsize \\
> +	  READELF=llvm-readelf HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar \\
> +	  HOSTLD=ld.lld
> +
> +Getting Help
> +------------
> +
> +- `Website <https://clangbuiltlinux.github.io/>`_
> +- `Mailing List <https://groups.google.com/forum/#!forum/clang-built-linux>`_: <[e-mail]>
> +- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
> +- IRC: #clangbuiltlinux on chat.freenode.net
> +- `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
> +-------------
> +
> +- http://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/

Should this also include an update to Documentation/process/changes.rst
with the minimum version required? (I would expect this to be "9" for Clang,
and "11" for ld.lld.)

Otherwise, yes, with Randy and Masahiro's suggestions, please consider it:

Reviewed-by: Kees Cook <[e-mail]>

Nathan Chancellor Feb. 25, 2020, 4:16 a.m. UTC | #4

On Mon, Feb 24, 2020 at 08:08:26PM -0800, Kees Cook wrote:
> On Mon, Feb 24, 2020 at 09:41:28AM -0800, Nick Desaulniers wrote:
> > Added to kbuild documentation. Provides more official info on building
> > kernels with Clang and LLVM than our wiki.
> > 
> > Suggested-by: Kees Cook <[e-mail]>
> > Reviewed-by: Nathan Chancellor <[e-mail]>
> > Signed-off-by: Nick Desaulniers <[e-mail]>
> > ---
> >  Documentation/kbuild/index.rst |  1 +
> >  Documentation/kbuild/llvm.rst  | 80 ++++++++++++++++++++++++++++++++++
> >  2 files changed, 81 insertions(+)
> >  create mode 100644 Documentation/kbuild/llvm.rst
> > 
> > diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
> > index 0f144fad99a6..3882bd5f7728 100644
> > --- a/Documentation/kbuild/index.rst
> > +++ b/Documentation/kbuild/index.rst
> > @@ -19,6 +19,7 @@ Kernel Build System
> >  
> >      issues
> >      reproducible-builds
> > +    llvm
> >  
> >  .. only::  subproject and html
> >  
> > diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
> > new file mode 100644
> > index 000000000000..68ae022aebc0
> > --- /dev/null
> > +++ b/Documentation/kbuild/llvm.rst
> > @@ -0,0 +1,80 @@
> > +==============================
> > +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. On going 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
> > +-----
> > +
> > +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.
> > +
> > +	ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make CC=clang
> > +
> > +`CROSS_COMPILE` is not used to suffix the Clang compiler binary, instead
> 
> s/suffix/prefix/
> 
> > +`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. These can be invoked as
> > +additional parameters to `make`.
> > +
> > +	make CC=clang AS=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \\
> > +	  OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump OBJSIZE=llvm-objsize \\
> > +	  READELF=llvm-readelf HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar \\
> > +	  HOSTLD=ld.lld
> > +
> > +Getting Help
> > +------------
> > +
> > +- `Website <https://clangbuiltlinux.github.io/>`_
> > +- `Mailing List <https://groups.google.com/forum/#!forum/clang-built-linux>`_: <[e-mail]>
> > +- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
> > +- IRC: #clangbuiltlinux on chat.freenode.net
> > +- `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
> > +-------------
> > +
> > +- http://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/
> 
> Should this also include an update to Documentation/process/changes.rst
> with the minimum version required? (I would expect this to be "9" for Clang,
> and "11" for ld.lld.)

I think the clang one should be added in a separate patch that
solidifies that in include/linux/compiler-clang.h with a CLANG_VERSION
macro and version check, like in include/linux/compiler-gcc.h.

ld.lld's minimum version should also be 9, what is the blocking issue
that makes it 11?

> Otherwise, yes, with Randy and Masahiro's suggestions, please consider it:
> 
> Reviewed-by: Kees Cook <[e-mail]>
> 
> -- 
> Kees Cook

Cheers,
Nathan

Kees Cook Feb. 25, 2020, 4:25 a.m. UTC | #5

On Mon, Feb 24, 2020 at 09:16:43PM -0700, Nathan Chancellor wrote:
> I think the clang one should be added in a separate patch that
> solidifies that in include/linux/compiler-clang.h with a CLANG_VERSION
> macro and version check, like in include/linux/compiler-gcc.h.

Sounds good.

> ld.lld's minimum version should also be 9, what is the blocking issue
> that makes it 11?

I think I've mostly got future patches on my mind. lld before 11 will
blow up on this:
https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git/log/?h=build/link-time
(but I haven't sent this patch yet since I didn't want to break lld
until it was fixed, which it is now, but I got distracted by other
stuff).

Additionally there will be LTO, but LTO will be version-checked. Then I
was thinking about the orphan section handling, and there is very
clearly more work to be done there too... (i.e. the synthesized sections
get reported by the orphan warning before they're actually processed by
DISCARD is some cases -- I still need to isolate the behavior and open a
bug.)

Sedat Dilek Feb. 25, 2020, 6:33 a.m. UTC | #6

On Tue, Feb 25, 2020 at 5:08 AM Kees Cook <[e-mail]> wrote:
>
> On Mon, Feb 24, 2020 at 09:41:28AM -0800, Nick Desaulniers wrote:
> > Added to kbuild documentation. Provides more official info on building
> > kernels with Clang and LLVM than our wiki.
> >
> > Suggested-by: Kees Cook <[e-mail]>
> > Reviewed-by: Nathan Chancellor <[e-mail]>
> > Signed-off-by: Nick Desaulniers <[e-mail]>
> > ---
> >  Documentation/kbuild/index.rst |  1 +
> >  Documentation/kbuild/llvm.rst  | 80 ++++++++++++++++++++++++++++++++++
> >  2 files changed, 81 insertions(+)
> >  create mode 100644 Documentation/kbuild/llvm.rst
> >
> > diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
> > index 0f144fad99a6..3882bd5f7728 100644
> > --- a/Documentation/kbuild/index.rst
> > +++ b/Documentation/kbuild/index.rst
> > @@ -19,6 +19,7 @@ Kernel Build System
> >
> >      issues
> >      reproducible-builds
> > +    llvm
> >
> >  .. only::  subproject and html
> >
> > diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
> > new file mode 100644
> > index 000000000000..68ae022aebc0
> > --- /dev/null
> > +++ b/Documentation/kbuild/llvm.rst
> > @@ -0,0 +1,80 @@
> > +==============================
> > +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. On going 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
> > +-----
> > +
> > +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.
> > +
> > +     ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make CC=clang
> > +
> > +`CROSS_COMPILE` is not used to suffix the Clang compiler binary, instead
>
> s/suffix/prefix/
>
> > +`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. These can be invoked as
> > +additional parameters to `make`.
> > +
> > +     make CC=clang AS=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \\
> > +       OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump OBJSIZE=llvm-objsize \\
> > +       READELF=llvm-readelf HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar \\
> > +       HOSTLD=ld.lld
> > +
> > +Getting Help
> > +------------
> > +
> > +- `Website <https://clangbuiltlinux.github.io/>`_
> > +- `Mailing List <https://groups.google.com/forum/#!forum/clang-built-linux>`_: <[e-mail]>
> > +- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
> > +- IRC: #clangbuiltlinux on chat.freenode.net
> > +- `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
> > +-------------
> > +
> > +- http://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/
>
> Should this also include an update to Documentation/process/changes.rst
> with the minimum version required? (I would expect this to be "9" for Clang,
> and "11" for ld.lld.)
>
> Otherwise, yes, with Randy and Masahiro's suggestions, please consider it:
>
> Reviewed-by: Kees Cook <[e-mail]>
>

Hi,

that update for documentation purposes was overdue.

My last experiments were with Linux v5.3 and llvm-toolchain 9.0 means
Clang compiler v9.0 and LLD linker v9.0 on x86-64.
With Debian's kernel-config I was able to build OOTB (out-of-the-box)
with no extra patches.
I cannot speak for higher Linux and/or llvm-toolchain versions/combinations.

I would prefer such an information also for the *supported* Linux
versions, so people have a good orientation.

So for the above scenario, you can add:

Reviewed-by: Sedat Dilek <[e-mail]>.(Clang and LLD v9.0,
Linux v5.3, x86-64)

Regards,
- Sedat -




> --
> Kees Cook
>
> --
> You received this message because you are subscribed to the Google Groups "Clang Built Linux" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to [e-mail].
> To view this discussion on the web visit https://groups.google.com/d/msgid/clang-built-linux/202002242003.870E5F80%40keescook.

Nick Desaulniers Feb. 25, 2020, 8:52 p.m. UTC | #7

On Mon, Feb 24, 2020 at 4:34 PM Masahiro Yamada <[e-mail]> wrote:
>
> On Tue, Feb 25, 2020 at 2:41 AM Nick Desaulniers
> <[e-mail]> wrote:
> >
> > Added to kbuild documentation. Provides more official info on building
> > kernels with Clang and LLVM than our wiki.
> >
> > Suggested-by: Kees Cook <[e-mail]>
> > Reviewed-by: Nathan Chancellor <[e-mail]>
> > Signed-off-by: Nick Desaulniers <[e-mail]>
> > ---
>
>
> Perhaps, is it better to explicitly add it to MAINTAINERS?
>
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -4118,6 +4118,7 @@ W:        https://clangbuiltlinux.github.io/
>  B:     https://github.com/ClangBuiltLinux/linux/issues
>  C:     irc://chat.freenode.net/clangbuiltlinux
>  S:     Supported
> +F:     Documentation/kbuild/llvm.rst
>  K:     \b(?i:clang|llvm)\b

I'm happy to leave it to the maintainers of Documentation/.  Otherwise
we have a file for which there is no MAINTAINER, which seems
ambiguous.

Nick Desaulniers Feb. 25, 2020, 8:59 p.m. UTC | #8

On Mon, Feb 24, 2020 at 8:16 PM Nathan Chancellor
<[e-mail]> wrote:
> > Should this also include an update to Documentation/process/changes.rst
> > with the minimum version required? (I would expect this to be "9" for Clang,
> > and "11" for ld.lld.)
>
> I think the clang one should be added in a separate patch that
> solidifies that in include/linux/compiler-clang.h with a CLANG_VERSION
> macro and version check, like in include/linux/compiler-gcc.h.
>
> ld.lld's minimum version should also be 9, what is the blocking issue
> that makes it 11?

I'm super hesitant to put a minimally required version of Clang, since
it really depends on the configs you're using.  Sure, clang-9 will
probably work better than clang-4 for some configs, but I would say
ToT clang built from source would be even better, as unrealistic as
that is for most people.  The question of "what's our support model"
hasn't realistically come up yet, so I don't really want to make a
decision on that right now and potentially pigeonhole us into some
support scheme that's theoretical or hypothetical.  We need to expand
out the CI more, and get more people to even care about Clang, before
we start to concern ourselves with providing an answer to the question
"what versions of clang are supported?"  But it's just a strong
opinion of mine, held loosely.

Either way, it can be done (or not) in a follow up patch.  I would
like to land some Documentation/ even if it's not perfect, we can go
from there.

Kees Cook Feb. 25, 2020, 9:56 p.m. UTC | #9

On Tue, Feb 25, 2020 at 12:59:25PM -0800, Nick Desaulniers wrote:
> On Mon, Feb 24, 2020 at 8:16 PM Nathan Chancellor
> <[e-mail]> wrote:
> > > Should this also include an update to Documentation/process/changes.rst
> > > with the minimum version required? (I would expect this to be "9" for Clang,
> > > and "11" for ld.lld.)
> >
> > I think the clang one should be added in a separate patch that
> > solidifies that in include/linux/compiler-clang.h with a CLANG_VERSION
> > macro and version check, like in include/linux/compiler-gcc.h.
> >
> > ld.lld's minimum version should also be 9, what is the blocking issue
> > that makes it 11?
> 
> I'm super hesitant to put a minimally required version of Clang, since
> it really depends on the configs you're using.  Sure, clang-9 will
> probably work better than clang-4 for some configs, but I would say

I think it's not unreasonable to say clang-9 due to x86 not building
prior to clang-9. (Yes, other archs can build with earlier clang, but
that's true for earlier gccs too.)

> ToT clang built from source would be even better, as unrealistic as
> that is for most people.  The question of "what's our support model"
> hasn't realistically come up yet, so I don't really want to make a
> decision on that right now and potentially pigeonhole us into some
> support scheme that's theoretical or hypothetical.  We need to expand
> out the CI more, and get more people to even care about Clang, before
> we start to concern ourselves with providing an answer to the question
> "what versions of clang are supported?"  But it's just a strong
> opinion of mine, held loosely.

"Supported" is hand-wavey anyway. I would say, "this version is
_expected_ to build the kernel", etc.

> Either way, it can be done (or not) in a follow up patch.  I would
> like to land some Documentation/ even if it's not perfect, we can go
> from there.

Sounds fine, but I think we should take a specific version stand as the
"minimum" version. Being able to build x86 defconfig is a good minimum
IMO.

Joe Perches Feb. 25, 2020, 10:20 p.m. UTC | #10

On Tue, 2020-02-25 at 13:56 -0800, Kees Cook wrote:
> I think we should take a specific version stand as the
> "minimum" version. Being able to build x86 defconfig is a good minimum
> IMO.

Agree.

It's odd to say that clang 4 is fine for arm when it's
not fine for x86.  It's also reasonable to expect arm
users to upgrade their compiler to a more recent version
when the only cost is a very small bit of time.

Masahiro Yamada Feb. 26, 2020, noon UTC | #11

On Wed, Feb 26, 2020 at 5:52 AM Nick Desaulniers
<[e-mail]> wrote:
>
> On Mon, Feb 24, 2020 at 4:34 PM Masahiro Yamada <[e-mail]> wrote:
> >
> > On Tue, Feb 25, 2020 at 2:41 AM Nick Desaulniers
> > <[e-mail]> wrote:
> > >
> > > Added to kbuild documentation. Provides more official info on building
> > > kernels with Clang and LLVM than our wiki.
> > >
> > > Suggested-by: Kees Cook <[e-mail]>
> > > Reviewed-by: Nathan Chancellor <[e-mail]>
> > > Signed-off-by: Nick Desaulniers <[e-mail]>
> > > ---
> >
> >
> > Perhaps, is it better to explicitly add it to MAINTAINERS?
> >
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -4118,6 +4118,7 @@ W:        https://clangbuiltlinux.github.io/
> >  B:     https://github.com/ClangBuiltLinux/linux/issues
> >  C:     irc://chat.freenode.net/clangbuiltlinux
> >  S:     Supported
> > +F:     Documentation/kbuild/llvm.rst
> >  K:     \b(?i:clang|llvm)\b
>
> I'm happy to leave it to the maintainers of Documentation/.  Otherwise
> we have a file for which there is no MAINTAINER, which seems
> ambiguous.

It is common that MAINTAINERS lists per-file (per-driver) maintainers.
It does not necessarily mean a person who picks up patches.

scripts/get_maintainer.pl lists maintainers that
match any F:, N:, K: patterns.
So, both Doc and Kbuild maintainers/ML will still be listed.

Having said that, it is up to you. Either is fine with me.
Another pattern 'K: \b(?i:clang|llvm)\b'  covers this file anyway.


(BTW, I am also happy to see your name as the maintainer of this entry.)


Thanks.

--
Best Regards
Masahiro Yamada

Sedat Dilek Feb. 26, 2020, 12:33 p.m. UTC | #12

On Wed, Feb 26, 2020 at 1:01 PM Masahiro Yamada <[e-mail]> wrote:
>
> On Wed, Feb 26, 2020 at 5:52 AM Nick Desaulniers
> <[e-mail]> wrote:
> >
> > On Mon, Feb 24, 2020 at 4:34 PM Masahiro Yamada <[e-mail]> wrote:
> > >
> > > On Tue, Feb 25, 2020 at 2:41 AM Nick Desaulniers
> > > <[e-mail]> wrote:
> > > >
> > > > Added to kbuild documentation. Provides more official info on building
> > > > kernels with Clang and LLVM than our wiki.
> > > >
> > > > Suggested-by: Kees Cook <[e-mail]>
> > > > Reviewed-by: Nathan Chancellor <[e-mail]>
> > > > Signed-off-by: Nick Desaulniers <[e-mail]>
> > > > ---
> > >
> > >
> > > Perhaps, is it better to explicitly add it to MAINTAINERS?
> > >
> > > --- a/MAINTAINERS
> > > +++ b/MAINTAINERS
> > > @@ -4118,6 +4118,7 @@ W:        https://clangbuiltlinux.github.io/
> > >  B:     https://github.com/ClangBuiltLinux/linux/issues
> > >  C:     irc://chat.freenode.net/clangbuiltlinux
> > >  S:     Supported
> > > +F:     Documentation/kbuild/llvm.rst
> > >  K:     \b(?i:clang|llvm)\b
> >
> > I'm happy to leave it to the maintainers of Documentation/.  Otherwise
> > we have a file for which there is no MAINTAINER, which seems
> > ambiguous.
>
> It is common that MAINTAINERS lists per-file (per-driver) maintainers.
> It does not necessarily mean a person who picks up patches.
>
> scripts/get_maintainer.pl lists maintainers that
> match any F:, N:, K: patterns.
> So, both Doc and Kbuild maintainers/ML will still be listed.
>
> Having said that, it is up to you. Either is fine with me.
> Another pattern 'K: \b(?i:clang|llvm)\b'  covers this file anyway.
>
>
> (BTW, I am also happy to see your name as the maintainer of this entry.)
>

+1 (Please drop the BTW - This was suggested in the brainstorming
session on the ClangBuiltLinux Meetup in Zurich).

I suggest to add Nathan and Kees if they are willing to be responsible
for the maintainer job.

- Sedat -

Nick Desaulniers Feb. 26, 2020, 11:18 p.m. UTC | #13

On Tue, Feb 25, 2020 at 2:21 PM Joe Perches <[e-mail]> wrote:
>
> On Tue, 2020-02-25 at 13:56 -0800, Kees Cook wrote:
> > I think we should take a specific version stand as the
> > "minimum" version. Being able to build x86 defconfig is a good minimum
> > IMO.
>
> Agree.
>
> It's odd to say that clang 4 is fine for arm when it's
> not fine for x86.  It's also reasonable to expect arm
> users to upgrade their compiler to a more recent version
> when the only cost is a very small bit of time.

That's a very x86 centric point of view.

Joe Perches Feb. 26, 2020, 11:23 p.m. UTC | #14

On Wed, 2020-02-26 at 15:18 -0800, Nick Desaulniers wrote:
> On Tue, Feb 25, 2020 at 2:21 PM Joe Perches <[e-mail]> wrote:
> > On Tue, 2020-02-25 at 13:56 -0800, Kees Cook wrote:
> > > I think we should take a specific version stand as the
> > > "minimum" version. Being able to build x86 defconfig is a good minimum
> > > IMO.
> > 
> > Agree.
> > 
> > It's odd to say that clang 4 is fine for arm when it's
> > not fine for x86.  It's also reasonable to expect arm
> > users to upgrade their compiler to a more recent version
> > when the only cost is a very small bit of time.
> 
> That's a very x86 centric point of view.

Really?

How many code generation improvements and possible defects
have been corrected between clang 4 and clang 10 for arm?

I presume more than a few.

Nathan Chancellor Feb. 27, 2020, 4:38 a.m. UTC | #15

On Wed, Feb 26, 2020 at 01:33:13PM +0100, Sedat Dilek wrote:
> On Wed, Feb 26, 2020 at 1:01 PM Masahiro Yamada <[e-mail]> wrote:
> >
> > On Wed, Feb 26, 2020 at 5:52 AM Nick Desaulniers
> > <[e-mail]> wrote:
> > >
> > > On Mon, Feb 24, 2020 at 4:34 PM Masahiro Yamada <[e-mail]> wrote:
> > > >
> > > > On Tue, Feb 25, 2020 at 2:41 AM Nick Desaulniers
> > > > <[e-mail]> wrote:
> > > > >
> > > > > Added to kbuild documentation. Provides more official info on building
> > > > > kernels with Clang and LLVM than our wiki.
> > > > >
> > > > > Suggested-by: Kees Cook <[e-mail]>
> > > > > Reviewed-by: Nathan Chancellor <[e-mail]>
> > > > > Signed-off-by: Nick Desaulniers <[e-mail]>
> > > > > ---
> > > >
> > > >
> > > > Perhaps, is it better to explicitly add it to MAINTAINERS?
> > > >
> > > > --- a/MAINTAINERS
> > > > +++ b/MAINTAINERS
> > > > @@ -4118,6 +4118,7 @@ W:        https://clangbuiltlinux.github.io/
> > > >  B:     https://github.com/ClangBuiltLinux/linux/issues
> > > >  C:     irc://chat.freenode.net/clangbuiltlinux
> > > >  S:     Supported
> > > > +F:     Documentation/kbuild/llvm.rst
> > > >  K:     \b(?i:clang|llvm)\b
> > >
> > > I'm happy to leave it to the maintainers of Documentation/.  Otherwise
> > > we have a file for which there is no MAINTAINER, which seems
> > > ambiguous.
> >
> > It is common that MAINTAINERS lists per-file (per-driver) maintainers.
> > It does not necessarily mean a person who picks up patches.
> >
> > scripts/get_maintainer.pl lists maintainers that
> > match any F:, N:, K: patterns.
> > So, both Doc and Kbuild maintainers/ML will still be listed.
> >
> > Having said that, it is up to you. Either is fine with me.
> > Another pattern 'K: \b(?i:clang|llvm)\b'  covers this file anyway.
> >
> >
> > (BTW, I am also happy to see your name as the maintainer of this entry.)
> >
> 
> +1 (Please drop the BTW - This was suggested in the brainstorming
> session on the ClangBuiltLinux Meetup in Zurich).
> 
> I suggest to add Nathan and Kees if they are willing to be responsible
> for the maintainer job.
> 
> - Sedat -

I would not mind having my name added under this MAINTAINERS entry but I
definitely think that is a conversation for a different thread.

Cheers,
Nathan

Nathan Chancellor Feb. 27, 2020, 4:44 a.m. UTC | #16

On Tue, Feb 25, 2020 at 12:59:25PM -0800, Nick Desaulniers wrote:
> On Mon, Feb 24, 2020 at 8:16 PM Nathan Chancellor
> <[e-mail]> wrote:
> > > Should this also include an update to Documentation/process/changes.rst
> > > with the minimum version required? (I would expect this to be "9" for Clang,
> > > and "11" for ld.lld.)
> >
> > I think the clang one should be added in a separate patch that
> > solidifies that in include/linux/compiler-clang.h with a CLANG_VERSION
> > macro and version check, like in include/linux/compiler-gcc.h.
> >
> > ld.lld's minimum version should also be 9, what is the blocking issue
> > that makes it 11?
> 
> I'm super hesitant to put a minimally required version of Clang, since
> it really depends on the configs you're using.  Sure, clang-9 will
> probably work better than clang-4 for some configs, but I would say
> ToT clang built from source would be even better, as unrealistic as
> that is for most people.  The question of "what's our support model"
> hasn't realistically come up yet, so I don't really want to make a
> decision on that right now and potentially pigeonhole us into some
> support scheme that's theoretical or hypothetical.  We need to expand
> out the CI more, and get more people to even care about Clang, before
> we start to concern ourselves with providing an answer to the question
> "what versions of clang are supported?"  But it's just a strong
> opinion of mine, held loosely.
> 
> Either way, it can be done (or not) in a follow up patch.  I would
> like to land some Documentation/ even if it's not perfect, we can go
> from there.
> -- 
> Thanks,
> ~Nick Desaulniers

I think the question of support model is something that we are going to
have to sit down and figure out sooner rather than later, especially if
we are adding this file to the Documentation; we are saying that this IS
supported in some fashion, we need to be able to answer how we are going
to resolve issues and what versions can be adequately expect to work
with the kernel.

I think that being able to tell people to update is not unreasonable,
given how efficient we are getting fixing into clang. However, clang's
release model is definitely different from gcc's and that can make
getting fixes into the hands of regular users harder, aside from asking
them to build their own version, which again, is not that difficult and
hard to do with something like tc-build.

I agree this should happen in a follow up patch. I think starting with
clang-9 and saying if anything older works, cool, otherwise update is
probably a decent initial model.

Cheers,
Nathan

Patch

diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
index 0f144fad99a6..3882bd5f7728 100644
--- a/Documentation/kbuild/index.rst
+++ b/Documentation/kbuild/index.rst
@@ -19,6 +19,7 @@  Kernel Build System
 
     issues
     reproducible-builds
+    llvm
 
 .. only::  subproject and html
 
diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
new file mode 100644
index 000000000000..68ae022aebc0
--- /dev/null
+++ b/Documentation/kbuild/llvm.rst
@@ -0,0 +1,80 @@ 
+==============================
+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. On going 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
+-----
+
+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.
+
+	ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make CC=clang
+
+`CROSS_COMPILE` is not used to suffix 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. These can be invoked as
+additional parameters to `make`.
+
+	make CC=clang AS=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \\
+	  OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump OBJSIZE=llvm-objsize \\
+	  READELF=llvm-readelf HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar \\
+	  HOSTLD=ld.lld
+
+Getting Help
+------------
+
+- `Website <https://clangbuiltlinux.github.io/>`_
+- `Mailing List <https://groups.google.com/forum/#!forum/clang-built-linux>`_: <[e-mail]>
+- `Issue Tracker <https://github.com/ClangBuiltLinux/linux/issues>`_
+- IRC: #clangbuiltlinux on chat.freenode.net
+- `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
+-------------
+
+- http://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/