[PATCH] Documentation: add minimum clang/llvm version

[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 <ndesaulniers@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

Re: [PATCH] Documentation: add minimum clang/llvm version

[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 <ndesaulniers@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 <natechancellor@gmail.com>

Re: [PATCH] Documentation: add minimum clang/llvm version

[Jonathan Corbet]

On Tue, 25 Aug 2020 15:51:31 -0700
Nathan Chancellor <natechancellor@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

Re: [PATCH] Documentation: add minimum clang/llvm version

[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 <ndesaulniers@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 <gustavoars@kernel.org>

Thanks
--
Gustavo

>>  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 <natechancellor@gmail.com>
> 

Re: [PATCH] Documentation: add minimum clang/llvm version

[Will Deacon]

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 <ndesaulniers@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

typo: guaranteed

Will

Re: [PATCH] Documentation: add minimum clang/llvm version

[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 <ndesaulniers@google.com>

Yay! :)

With the typo Will found fixed:

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

-- 
Kees Cook

Re: [PATCH] Documentation: add minimum clang/llvm version

[Sedat Dilek]

On Wed, Aug 26, 2020 at 12:26 AM 'Nick Desaulniers' via Clang Built
Linux <clang-built-linux@googlegroups.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.
>
> Signed-off-by: Nick Desaulniers <ndesaulniers@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

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-linux+unsubscribe@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.

Re: [PATCH] Documentation: add minimum clang/llvm version

[Nick Desaulniers]

On Wed, Aug 26, 2020 at 8:53 AM Sedat Dilek <sedat.dilek@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