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,59 @@ 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. +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 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.