diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -3089,6 +3089,7 @@ 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. +If you change the build system or use compiler specific features, make sure it works in all <>. 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 +3121,49 @@ 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 has built with both Clang and GCC for some time. +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 support out-of-tree compilers. +At present, this is GCC 12.x. +Ideally, committers should test compile with this compiler, especially large change. +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. + +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 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.