runtime/cgo: document the state of clang support and minimum required version

[mauri870]

We consistently encounter issues exclusive to Clang in the bug tracker, such as:

• cmd/cgo/internal/testsanitizers: TestMSAN/msan8 fails with clang16.0.6 #64616
• runtime/cgo: build fails with GOARCH=arm GOARM=5 CC=clang #65290
• cmd/cgo: building with clang 13 errors out with unknown warning group '-Wunaligned-access' #64943
• cmd/go: TestScript/cgo_stale_precompiled fails with Clang 14.0.6 #64423
• cmd/link: coverage analysis fail when using CGO & LLVM/clang 12 #58848
• cmd/cgo/internal/testtls: signal arrived during external code execution on Windows with clang 14.0.6 #64400
• cmd/cgo: Wrong types in compiler errors with clang 14 #53013

Since resolving certain issues may involve implementing workarounds such as adjusting CFLAGS or incorporating specific compiler options like -Wno-something, it would be beneficial to determine the minimum compiler versions we target. This information is crucial in understanding whether these changes might adversely impact cgo programs, especially those relying on versions dating back to the minimum required version. This consideration is heightened by the fact that cgo directives must not only be compatible with clang but also with gcc.

Additionally, there are requests for expanded OS support for clang, specifically regarding Windows support. There is #64563 that covers adding a Linux LUCI builder with a recent Clang toolchain.

Upon reviewing the cgo wiki and MinimumRequirements#cgo, there is no mention of Clang support or a specified minimum required version.

If we are actively pursuing Clang support in a consistent manner perhaps it would be beneficial to start documenting the support in some way.

In the decision made for #43605, it was agreed to document the minimum GCC version as 4.6. We may consider specifying a corresponding clang version, such as 3.0, based on a similar timeframe (~2011).

cc @golang/runtime

[mxmauro]

CLang support on Windows, sucks. Mostly related to unsupported linker flags (lld-link) and using double dash instead of single dashes or slashes.

[aclements]

@golang/release, how difficult is it to test against multiple Clang versions? Do we actually have test coverage back to GCC 4.6?

[mknyszek]

If it's possible to package clang in such a way that we could just download and extract it, then point at the bin directory with some environment variables to get our builds to use it, then this is potentially very straightforward on LUCI.

[mauri870]

I recall the llvm website has an script to automatically install the toolchain for a specific version, that might help https://apt.llvm.org/#llvmsh

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 17 # <version number>

[mknyszek]

I think we want to avoid running a shell script from the wider web as part of our build process. 😅 That being said, it turns out that it was relatively easy to just set up a clang release in CIPD. I have a builder already set up so we'll see if it works. (See https://go.dev/cl/559255.) The process of uploading a new clang version is manual but fairly simple. It consists of only a few commands and a very straightforward configuration CL.

[mknyszek]

We discussed this briefly as a team and I think, barring any particular reason to exclude specific clang versions (like we do for gcc, because of certain pragmas generated by cgo (#43605)), I think our policy will probably just be best-effort across versions but generally supported. Additionally, we'll try to stay up-to-date with new versions of clang on the builders. The new LUCI clang builder is based on clang 15 and there are some issues with moving up further in time (too old glibc on our builder images) but they're fixable.

So I guess in terms of a concrete policy, I propose text along the lines of:

"clang is generally supported for use with cgo. However, the Go project does not test against most or all versions of clang, and instead focuses on testing against a recent version of clang only. Please file an issue if you experience an issue with using clang and cgo. Patches to fix Go builds against old versions of clang are generally welcome, provided they do not introduce a significant long-term maintenance burden. The Go project reserves the right to set a minimum required version of clang in the future."

EDIT: FWIW, we could also apply this text to gcc, because it's also true that we don't test against each and every version of gcc. The only difference is that we did set a minimum required version.