From 7762186d3e032f4d55568b36ce08563c6f7c3619 Mon Sep 17 00:00:00 2001
From: John Baldwin <jhb@FreeBSD.org>
Date: Fri, 30 May 2025 19:26:05 -0400
Subject: committers-guide: Update current compiler verisons

- Restructure some of the text to avoid hardcoding compiler versions when
  possible.

- Explicitly note the naming pattern for llvm toolchain packages.

Reviewed by:	emaste
Differential Revision:	https://reviews.freebsd.org/D50618
---
 .../en/articles/committers-guide/_index.adoc       | 35 ++++++++++++++--------
 1 file changed, 22 insertions(+), 13 deletions(-)

(limited to 'documentation/content/en/articles/committers-guide/_index.adoc')

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index f8a617ace1..34106482fe 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -3206,7 +3206,7 @@ The Tier rules for feature support on architectures at release-time are more str
 [[compilers]]
 === Policy on Multiple Compilers
 
-FreeBSD builds with both Clang and GCC.
+The FreeBSD base system builds with both Clang and GCC.
 The project does this in a careful and controlled way to maximize benefits from this extra work, while keeping the extra work to a minimum.
 Supporting both Clang and GCC improves the flexibility our users have.
 These compilers have different strengths and weaknesses, and supporting both allows users to pick the best one for their needs.
@@ -3219,22 +3219,29 @@ The exact balance continues to evolve to ensure the benefits of extra work remai
 The project used to support really old Intel compilers or old GCC versions, but we traded supporting those obsolete compilers for a carefully selected range of modern compilers.
 This section documents where we use different compilers, and the expectations around that.
 
-The FreeBSD project provides an in-tree Clang compiler.
+The FreeBSD base system includes an in-tree Clang compiler.
 Due to being in the tree, this compiler is the most supported compiler.
 All changes must compile with it, prior to commit.
 Complete testing, as appropriate for the change, should be done with this compiler.
 
-At any moment in time, the FreeBSD project also supports one or more out-of-tree compilers.
-At present, this is GCC 12.x.
-Ideally, committers should test compile with this compiler, especially for large or risky changes.
-This compiler is available as the `${TARGET_ARCH}-gcc${VERSION}` package, such as package:devel/freebsd-gcc12@aarch64[aarch64-gcc12] or package:devel/freebsd-gcc12@riscv64[riscv64-gcc12].
+The FreeBSD base system also supports various versions of Clang and GCC as out-of-tree compilers.
+For large or risky changes, committers should do a test build with a
+supported version of GCC.
+Out of tree compilers are available as packages.
+GCC compilers are available as `${TARGET_ARCH}-gcc${VERSION}` packages, such as package:devel/freebsd-gcc14@aarch64[aarch64-gcc14].
+Clang compilers are available as `llvm${VERSION}` packages, such as
+package:devel/llvm18[llvm18].
 The project runs automated CI jobs to build everything with these compilers.
 Committers are expected to fix the jobs they break with their changes.
-Committers may test build with, for example `CROSS_TOOLCHAIN=aarch64-gcc12` or `CROSS_TOOLCHAIN=llvm15` where necessary.
+Committers may test builds of userspace or individual kernels by setting `CROSS_TOOLCHAIN` to the package name, for example `CROSS_TOOLCHAIN=aarch64-gcc14` or `CROSS_TOOLCHAIN=llvm18`.
+For universe or tinderbox builds, `USE_GCC_TOOLCHAINS=gcc${VERSION}` builds all architectures using the appropriate GCC compiler packages.
+For universe or tinderbox builds using an out-of-tree Clang, pass `CROSS_TOOLCHAIN=llvm${VERSION}`.
+Note that while all architectures in the base system can be compiled by Clang,
+only a few architectures can be fully built by GCC.
 
 The FreeBSD project also has some CI pipelines on github.
-For pull requests on github and some branches pushed to the github forks, a number of cross compilation jobs run.
-These test FreeBSD building using a version of Clang that sometimes lags the in-tree compiler by a major version for a time.
+For pull requests on github and some branches pushed to github forks, a number of cross compilation jobs run.
+These test FreeBSD building using versions of Clang that lag the in-tree compiler by one or more major versions.
 
 The FreeBSD project is also upgrading compilers.
 Both Clang and GCC are fast moving targets.
@@ -3258,10 +3265,12 @@ However, sometimes these warnings require extensive rework, so are suppressed in
 Developers should be mindful of this, and ensure any compiler specific flags are properly conditionalized.
 
 ==== Current Compiler Versions
-The in-tree compiler is currently Clang 15.x.
-Currently, GCC 12 and Clang 12, 13, 14 and 15 are tested in the github and project's CI jenkins jobs.
-Work is underway to get the tree ready for Clang 16.
-The oldest project supported branch has Clang 12, so the bootstrap portions of the build must work for Clang major versions 12 to 15.
+The versions of supported compilers for a given branch such as `main` or `stable/X` varies over time.
+The authoritative source for supported compiler versions are automated CI jobs tested in GitHub's cross-build actions and Jenkins.
+
+For `main`, the in-tree compiler is currently Clang 19.
+Currently, GCC 12, 13, and 14 are tested for amd64 via CI jobs in Jenkins.
+Clang 14 and 18 are tested for aarch64 and arm64 in GitHub's cross-build actions.
 
 === Other Suggestions
 
-- 
cgit v1.2.3

