[PATCH] Documentation: add minimum clang/llvm version

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

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.

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.

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 [off-list ref]

On Tue, 25 Aug 2020 15:51:31 -0700
Nathan Chancellor [off-list ref] wrote:

quoted

+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

On 8/25/20 17:51, Nathan Chancellor wrote:

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

quoted

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

quoted

 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.

quoted

 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?

quoted

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

Regardless of the nits above:

Reviewed-and-tested-by: Nathan Chancellor [off-list ref]

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

typo: guaranteed

Will

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 <redacted>

-- 
Kees Cook

On Wed, Aug 26, 2020 at 12:26 AM 'Nick Desaulniers' via Clang Built
Linux [off-list ref] 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)?
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.

On Wed, Aug 26, 2020 at 8:53 AM Sedat Dilek [off-list ref] 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