[PATCH] Documentation: add minimum clang/llvm version

[Nick Desaulniers]

Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start
small, supporting just one formal upstream release of LLVM for now.

We can probably widen the support window of supported versions over
time. Also, note that LLVM's release process is different than GCC's.
GCC tends to have 1 major release per year while releasing minor updates
to the past 3 major versions. LLVM tends to support one major release
and one minor release every six months.

Signed-off-by: Nick Desaulniers <ndesau...@google.com>
---
Note to reviewers: working remote, I'm having trouble testing/verifying
that I have the RST links wired up correctly; I would appreciate it if
someone is able to `make htmldocs` and check
Documentation/output/process/changes.html properly links to
Documentation/output/kbuild/llvm.html.

Documentation/kbuild/llvm.rst | 2 ++
Documentation/process/changes.rst | 10 ++++++++++
2 files changed, 12 insertions(+)

diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
index 2aac50b97921..70ec6e9a183b 100644
--- a/Documentation/kbuild/llvm.rst
+++ b/Documentation/kbuild/llvm.rst
@@ -1,3 +1,5 @@
+.. _kbuild_llvm:
+
==============================
Building Linux with Clang/LLVM
==============================
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index ee741763a3fc..6c580ef9f2a3 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -30,6 +30,7 @@ you probably needn't concern yourself with pcmciautils.
Program Minimal version Command to check the version
====================== =============== ========================================
GNU C 4.9 gcc --version
+Clang/LLVM (optional) 10.0.1 clang --version
GNU make 3.81 make --version
binutils 2.23 ld -v
flex 2.5.35 flex --version
@@ -68,6 +69,15 @@ GCC
The gcc version requirements may vary depending on the type of CPU in your
computer.

+Clang/LLVM (optional)
+---------------------
+
+The latest formal release of clang and LLVM utils (according to
+`releases.llvm.org <https://releases.llvm.org>`_) are supported for building
+kernels. Older releases aren't gauranteed to work, and we may drop workarounds
+from the kernel that were used to support older versions. Please see additional
+docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
+
Make
----

--
2.28.0.297.g1956fa8f8d-goog

[Nathan Chancellor]

On Tue, Aug 25, 2020 at 03:25:51PM -0700, Nick Desaulniers wrote:
> Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start
> small, supporting just one formal upstream release of LLVM for now.
>
> We can probably widen the support window of supported versions over
> time. Also, note that LLVM's release process is different than GCC's.
> GCC tends to have 1 major release per year while releasing minor updates
> to the past 3 major versions. LLVM tends to support one major release
> and one minor release every six months.
>
> Signed-off-by: Nick Desaulniers <ndesau...@google.com>
> ---
> Note to reviewers: working remote, I'm having trouble testing/verifying
> that I have the RST links wired up correctly; I would appreciate it if
> someone is able to `make htmldocs` and check
> Documentation/output/process/changes.html properly links to
> Documentation/output/kbuild/llvm.html.

I ran 'make O=out htmldocs' and can confirm that the link works properly
in process/changes.html, pointing to kbuild/llvm.html.

> Documentation/kbuild/llvm.rst | 2 ++
> Documentation/process/changes.rst | 10 ++++++++++
> 2 files changed, 12 insertions(+)
>
> diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
> index 2aac50b97921..70ec6e9a183b 100644
> --- a/Documentation/kbuild/llvm.rst
> +++ b/Documentation/kbuild/llvm.rst
> @@ -1,3 +1,5 @@
> +.. _kbuild_llvm:
> +
> ==============================
> Building Linux with Clang/LLVM
> ==============================
> diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
> index ee741763a3fc..6c580ef9f2a3 100644
> --- a/Documentation/process/changes.rst
> +++ b/Documentation/process/changes.rst
> @@ -30,6 +30,7 @@ you probably needn't concern yourself with pcmciautils.
> Program Minimal version Command to check the version
> ====================== =============== ========================================
> GNU C 4.9 gcc --version
> +Clang/LLVM (optional) 10.0.1 clang --version

Maybe it is worth making the "(optional)" a footnote like Sphinx? Seems
to just kind of stick out to me but I do not have a strong opinion
unless others do.

> GNU make 3.81 make --version
> binutils 2.23 ld -v
> flex 2.5.35 flex --version
> @@ -68,6 +69,15 @@ GCC
> The gcc version requirements may vary depending on the type of CPU in your
> computer.
>
> +Clang/LLVM (optional)
> +---------------------
> +
> +The latest formal release of clang and LLVM utils (according to
> +`releases.llvm.org <https://releases.llvm.org>`_) are supported for building
> +kernels. Older releases aren't gauranteed to work, and we may drop workarounds
> +from the kernel that were used to support older versions. Please see additional
> +docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
> +

Do we maybe want to add a section for LLVM/clang in the "Getting updated
software" section? Maybe just a link to the existing section that we
have in kbuild/llvm.rst?

> Make
> ----
>
> --
> 2.28.0.297.g1956fa8f8d-goog
>

Regardless of the nits above:

Reviewed-and-tested-by: Nathan Chancellor <natecha...@gmail.com>

[Jonathan Corbet]

On Tue, 25 Aug 2020 15:51:31 -0700
Nathan Chancellor <natecha...@gmail.com> wrote:

> > +Clang/LLVM (optional) 10.0.1 clang --version
>
> Maybe it is worth making the "(optional)" a footnote like Sphinx? Seems
> to just kind of stick out to me but I do not have a strong opinion
> unless others do.

Let's not do that; the table needs to be properly readable in plain-text
format. Adding that sort of markup will just serve to obfuscate things.

Thanks,

jon

[Gustavo A. R. Silva]

On 8/25/20 17:51, Nathan Chancellor wrote:
> On Tue, Aug 25, 2020 at 03:25:51PM -0700, Nick Desaulniers wrote:
>> Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start
>> small, supporting just one formal upstream release of LLVM for now.
>>
>> We can probably widen the support window of supported versions over
>> time. Also, note that LLVM's release process is different than GCC's.
>> GCC tends to have 1 major release per year while releasing minor updates
>> to the past 3 major versions. LLVM tends to support one major release
>> and one minor release every six months.
>>
>> Signed-off-by: Nick Desaulniers <ndesau...@google.com>
>> ---
>> Note to reviewers: working remote, I'm having trouble testing/verifying
>> that I have the RST links wired up correctly; I would appreciate it if
>> someone is able to `make htmldocs` and check
>> Documentation/output/process/changes.html properly links to
>> Documentation/output/kbuild/llvm.html.
>
> I ran 'make O=out htmldocs' and can confirm that the link works properly
> in process/changes.html, pointing to kbuild/llvm.html.
>

The same here.

Tested-by: Gustavo A. R. Silva <gusta...@kernel.org>

Thanks
--
Gustavo

[Will Deacon]

On Tue, Aug 25, 2020 at 03:25:51PM -0700, Nick Desaulniers wrote:

typo: guaranteed

Will

[Kees Cook]

On Tue, Aug 25, 2020 at 03:25:51PM -0700, Nick Desaulniers wrote:

> Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start
> small, supporting just one formal upstream release of LLVM for now.
>
> We can probably widen the support window of supported versions over
> time. Also, note that LLVM's release process is different than GCC's.
> GCC tends to have 1 major release per year while releasing minor updates
> to the past 3 major versions. LLVM tends to support one major release
> and one minor release every six months.
>
> Signed-off-by: Nick Desaulniers <ndesau...@google.com>

Yay! :)

With the typo Will found fixed:

Reviewed-by: Kees Cook <kees...@chromium.org>

--
Kees Cook

[Sedat Dilek]

Thanks for the text - a first good step.

Do you plan checks in the source-code - in the future (see [1] where I
played a bit)?
Arch-specific supported LLVM toolchain versions?
Feature-specific support (like KCSAN, Clang-IAS, etc.)?
In the future we should introduce some checks for this to be user-friendly.

If you talk about "Clang/LLVM" does this include the LLD linker?
Personally, I think LLD is worth a separate item like GNU/ld (BFD) linker.

The last few days I was able to build with GCC v10.2 and LLD and even
full LLVM "bin"utils (see [2]) version 11.0.0-rc2 on Debian/unstable
AMD64.

Just some thoughts - for the future.

- Sedat -

[1] https://github.com/ClangBuiltLinux/linux/issues/941
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/kbuild/llvm.rst#n47

> ----
>
> --
> 2.28.0.297.g1956fa8f8d-goog
>
> --
> 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 clang-built-li...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/clang-built-linux/20200825222552.3113760-1-ndesaulniers%40google.com.

[Nick Desaulniers]

On Wed, Aug 26, 2020 at 8:53 AM Sedat Dilek <sedat...@gmail.com> wrote:
>
> Thanks for the text - a first good step.
>
> Do you plan checks in the source-code - in the future (see [1] where I
> played a bit)?

Oh, I forgot! Good idea, will add a check to compiler-clang.h.

> Arch-specific supported LLVM toolchain versions?

No. That's going to be a complicated mess with frequent churn.

> Feature-specific support (like KCSAN, Clang-IAS, etc.)?

Ditto. (no)

> In the future we should introduce some checks for this to be user-friendly.
>
> If you talk about "Clang/LLVM" does this include the LLD linker?
> Personally, I think LLD is worth a separate item like GNU/ld (BFD) linker.

binutils version checks aren't enforced like the compiler version is,
so for now I'll stick to just checking the compiler version. That
dodges the combinatorial explosion with regards to support you're
referring to. Otherwise we're talking about a complicated
multidimensional table that we don't have CI coverage of.

> [1] https://github.com/ClangBuiltLinux/linux/issues/941
> [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/kbuild/llvm.rst#n47
--

Thanks,
~Nick Desaulniers

[Nick Desaulniers]

Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start
small, supporting just one formal upstream release of LLVM for now.

We can probably widen the support window of supported versions over
time. Also, note that LLVM's release process is different than GCC's.
GCC tends to have 1 major release per year while releasing minor updates
to the past 3 major versions. LLVM tends to support one major release
and one minor release every six months.

Reviewed-by: Kees Cook <kees...@chromium.org>
Reviewed-by: Nathan Chancellor <natecha...@gmail.com>

Tested-by: Gustavo A. R. Silva <gusta...@kernel.org>

Tested-by: Nathan Chancellor <natecha...@gmail.com>

Signed-off-by: Nick Desaulniers <ndesau...@google.com>
---

Changes V1 -> V2:
* fix typo, as per Will.
* add link to getting LLVM, as per Nathan.
* collect tags.

Documentation/kbuild/llvm.rst | 4 ++++
Documentation/process/changes.rst | 15 +++++++++++++++
2 files changed, 19 insertions(+)

diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst
index 2aac50b97921..3f10a9c47551 100644

--- a/Documentation/kbuild/llvm.rst
+++ b/Documentation/kbuild/llvm.rst
@@ -1,3 +1,5 @@
+.. _kbuild_llvm:
+
==============================
Building Linux with Clang/LLVM
==============================

@@ -73,6 +75,8 @@ Getting Help
- `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:
+
Getting LLVM
-------------

diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index ee741763a3fc..dac17711dc11 100644

--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -30,6 +30,7 @@ you probably needn't concern yourself with pcmciautils.
Program Minimal version Command to check the version
====================== =============== ========================================
GNU C 4.9 gcc --version
+Clang/LLVM (optional) 10.0.1 clang --version
GNU make 3.81 make --version
binutils 2.23 ld -v
flex 2.5.35 flex --version
@@ -68,6 +69,15 @@ GCC
The gcc version requirements may vary depending on the type of CPU in your
computer.

+Clang/LLVM (optional)
+---------------------
+
+The latest formal release of clang and LLVM utils (according to
+`releases.llvm.org <https://releases.llvm.org>`_) are supported for building

+kernels. Older releases aren't guaranteed to work, and we may drop workarounds

+from the kernel that were used to support older versions. Please see additional
+docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
+
Make

----

@@ -331,6 +341,11 @@ gcc

- <ftp://ftp.gnu.org/gnu/gcc/>

+Clang/LLVM
+----------
+
+- :ref:`Getting LLVM <getting_llvm>`.

[Masahiro Yamada]

Just playing a nitpick:
Supporting Clang makes GCC optional, so now
"GNU C (optional)"

:-)


Reviewed-by: Masahiro Yamada <masa...@kernel.org>


--
Best Regards
Masahiro Yamada

[Will Deacon]

On Wed, Aug 26, 2020 at 12:15:55PM -0700, Nick Desaulniers wrote:
> Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start
> small, supporting just one formal upstream release of LLVM for now.
>
> We can probably widen the support window of supported versions over
> time. Also, note that LLVM's release process is different than GCC's.
> GCC tends to have 1 major release per year while releasing minor updates
> to the past 3 major versions. LLVM tends to support one major release
> and one minor release every six months.
>
> Reviewed-by: Kees Cook <kees...@chromium.org>
> Reviewed-by: Nathan Chancellor <natecha...@gmail.com>
> Tested-by: Gustavo A. R. Silva <gusta...@kernel.org>
> Tested-by: Nathan Chancellor <natecha...@gmail.com>
> Signed-off-by: Nick Desaulniers <ndesau...@google.com>
> ---
> Changes V1 -> V2:
> * fix typo, as per Will.
> * add link to getting LLVM, as per Nathan.
> * collect tags.

Acked-by: Will Deacon <wi...@kernel.org>

Will

[Jonathan Corbet]

On Wed, 26 Aug 2020 12:15:55 -0700
Nick Desaulniers <ndesau...@google.com> wrote:

> Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start
> small, supporting just one formal upstream release of LLVM for now.
>
> We can probably widen the support window of supported versions over
> time. Also, note that LLVM's release process is different than GCC's.
> GCC tends to have 1 major release per year while releasing minor updates
> to the past 3 major versions. LLVM tends to support one major release
> and one minor release every six months.
>
> Reviewed-by: Kees Cook <kees...@chromium.org>
> Reviewed-by: Nathan Chancellor <natecha...@gmail.com>
> Tested-by: Gustavo A. R. Silva <gusta...@kernel.org>
> Tested-by: Nathan Chancellor <natecha...@gmail.com>
> Signed-off-by: Nick Desaulniers <ndesau...@google.com>

Applied, thanks.

jon

[Nick Desaulniers]

Hi Jon,
Thanks for picking up the patch.

Where is your tree? MAINTAINERS lists git://git.lwn.net/linux.git but
https://git.lwn.net/linux.git doesn't connect. Is the web interface
simply disabled? (I try to track which maintainer tree patches get
picked up in, and detect when our patches hit mainline).
--
Thanks,
~Nick Desaulniers

[Jonathan Corbet]

On Mon, 31 Aug 2020 15:56:54 -0700
Nick Desaulniers <ndesau...@google.com> wrote:

> Where is your tree? MAINTAINERS lists git://git.lwn.net/linux.git but
> https://git.lwn.net/linux.git doesn't connect. Is the web interface
> simply disabled? (I try to track which maintainer tree patches get
> picked up in, and detect when our patches hit mainline).

I never set up a web server on that machine, it's never really seemed
worth the effort. You can clone the repo and see your patch there, though
:)

Thanks,

jon