git: 9df88b0b78 - main - committers-guide: Add section on range of compilers

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=9df88b0b78a78a642d26d83e14dbd77af908e3b2

commit 9df88b0b78a78a642d26d83e14dbd77af908e3b2
Author:     Warner Losh <imp@FreeBSD.org>
AuthorDate: 2023-02-28 00:34:33 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2023-02-28 00:34:33 +0000

    committers-guide: Add section on range of compilers
    
    Document the range of compilers the project uses for building, CI and
    external toolchain support, and try to assign the proper level of effort
    developers should go to for each of them.
    
    Sponsored by:           Netflix
    Differential Revision:  https://reviews.freebsd.org/D38709
---
 .../en/articles/committers-guide/_index.adoc       | 62 +++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 4508b23a11..e4e7a3821b 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -3084,11 +3084,11 @@ If you have not done it before, chances are good that you do not actually know t
 There is no shame in asking "how in the heck do I do this?" We already know you are an intelligent person; otherwise, you would not be a committer.
 . Test your changes before committing them.
 +
-This may sound obvious, but if it really were so obvious then we probably would not see so many cases of people clearly not doing this.
 If your changes are to the kernel, make sure you can still compile both GENERIC and LINT.
 If your changes are anywhere else, make sure you can still make world.
 If your changes are to a branch, make sure your testing occurs with a machine which is running that code.
 If you have a change which also may break another architecture, be sure and test on all supported architectures.
+Please ensure your change works for <<compilers,supported toolchains>>.
 Please refer to the https://www.FreeBSD.org/internal/[FreeBSD Internal Page] for a list of available resources.
 As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available.
 . Do not commit to contributed software without _explicit_ approval from the respective maintainers.
@@ -3120,6 +3120,66 @@ Developers should also be aware of our Tier Policy for the long term support of
 The rules here are intended to provide guidance during the development process, and are distinct from the requirements for features and architectures listed in that section.
 The Tier rules for feature support on architectures at release-time are more strict than the rules for changes during the development process.
 
+[[compilers]]
+=== Policy on Multiple Compilers
+
+FreeBSD build 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.
+Clang and GCC support similar dialects of C and C++, necessitating a relatively small amount of conditional code.
+The project gains increased code coverage and improves the code quality by using features from both compilers.
+The project is able to build in more user environments and leverage more CI environments by supporting this range, increasing convenience for users and giving them more tools to test with.
+By carefully constraining the range of versions supported to modern versions of these compilers, the project avoids unduely increasing the testing matrix.
+Older and obscure compilers, as well as older dialects of the langauges, have extemely limited support that allow user programs to build with them, but without constraining the base system to being built with them.
+The exact balance continues to evolve to ensure the benefits of extra work remain greater than the burdens it imposes.
+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 compiler Clang compiler.
+Due to being in the tree, this compiler is the most supported compiler.
+All changes must to compile with it, prior to commit.
+Complete testing, as appropriate for the change, should be done with this compiler.
+
+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 package, such as package:aarch64-gcc[] or package:riscv64-gcc[].
+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=arm64-gcc12` or `CROSS_TOOLCHAIN=llvm15` where necessary.
+
+The FreeBSD 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.
+
+The FreeBSD project is also upgrading compilers.
+Both Clang and GCC are fast moving targets.
+Some work to change things in the tree, for example removing the old-style K&R function declarations and definitions, will land in the tree prior to the compiler landing.
+Committers should try to be mindful about this and be receptive to looking into problems with their code or changes with these new compilers.
+Also, just after a new compiler version hits the tree, people may need to compile things with the old version if there was an undetected regression suspected.
+
+In addition to the compiler, LLVM's LLD and GNU's binutils are used indirectly by the compiler.
+Committers should be mindful of variations in assembler syntax and features of the linkers and ensure both variants work.
+These components will be tested as part of FreeBSD's CI jobs for Clang or GCC.
+
+The FreeBSD project provides headers and libraries that allow other compilers to be used to build software not in the base system.
+These headers have support for making the environment as strict as the standard, supporting prior dialects of ANSI-C back to C89, and other edge cases our large ports collection has uncovered.
+This support constrains retirement of older standards in places like header files, but does not constrain updating the base system to newer dialects.
+Nor does it require the base system to compile with these older standards as a whole.
+Breaking this support will cause packages in the ports collection to fail, and should be avoided where possible, and prompty fixed when it is easy to do so.
+
+The FreeBSD build system currently accomodates these different environments.
+As new warnings are added to compilers, the project tries to fix them.
+However, sometimes these warnings require extensive rework, so are suppressed in some way by using make variables that evaluate to the proper thing depending on the compiler version.
+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.
+
 === Other Suggestions
 
 When committing documentation changes, use a spell checker before committing.