From efacc64305b9449c63b3aa26a2399b505a33bb62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Desbiens?= Date: Thu, 10 Sep 2026 07:28:55 -0400 Subject: [PATCH 1/2] Stated the compiler and coverage requirements instead of citing a file no contributor can open Seven comments across five files cited a maintainer-local document as the source for two project requirements: that GCC 14 on Linux is the default compiler, and that the coverage target is 100%. That document is not part of this repository and is not published anywhere, so the citation gave a reader nothing to follow -- it named a source they cannot open, in place of simply stating the requirement. Both requirements are real and both stay. Only the pointer goes: each comment now states the requirement on its own terms, which is what the surrounding prose was already doing everywhere else. cmake/cortex_r52.cmake the pinned reference toolchain scripts/check_gcc.sh why the script exists .github/workflows/gcc_check.yml why the workflow exists, and the GCC_VERSION pin .github/workflows/r52_fvp.yml the GCC_VERSION pin .github/workflows/regression_template.yml the coverage floor, twice Comments only; no behaviour changes. Two paragraphs are rewrapped where the shorter text left a ragged line. Verified that scripts/check_gcc.sh still parses and prints its help from the header range it slices, and that cmake/cortex_r52.cmake still configures the Cortex-R52 build. Assisted-by: Claude Code (Opus 5) --- .github/workflows/gcc_check.yml | 14 +++++++------- .github/workflows/r52_fvp.yml | 2 +- .github/workflows/regression_template.yml | 8 ++++---- cmake/cortex_r52.cmake | 2 +- scripts/check_gcc.sh | 13 ++++++------- 5 files changed, 19 insertions(+), 20 deletions(-) diff --git a/.github/workflows/gcc_check.yml b/.github/workflows/gcc_check.yml index f26cf5704..3eda52fa2 100644 --- a/.github/workflows/gcc_check.yml +++ b/.github/workflows/gcc_check.yml @@ -7,11 +7,11 @@ name: gcc_check # link the example builds, both the script-driven ones and those driven by # CMake. # -# Why this exists: GCC is the project's declared default compiler (AGENTS.md, -# "The default compiler for the project is GCC 14 on Linux") and until this -# workflow landed, nothing in CI compiled a line of any port with it. The only -# cross-compilation check that ran was clang_check, so the LLVM path was better -# guarded than the GNU one, on ports whose directory is literally named gnu. +# Why this exists: GCC 14 on Linux is the project's default compiler, it is +# what the gnu ports exist for, and until this workflow landed, nothing in CI +# compiled a line of any port with it. The only cross-compilation check that +# ran was clang_check, so the LLVM path was better guarded than the GNU one, +# on ports whose directory is literally named gnu. # # What it covers: 840 assembly sources across 40 port families, 469 of them # again behind feature macros, common/src for nine cores, 302 module manager C @@ -94,8 +94,8 @@ jobs: env: # Pinned deliberately, as the runner image is: a toolchain upgrade should # be a reviewable commit rather than something that changes underneath the - # ports. 14.3.rel1 matches AGENTS.md's GCC 14 default and the version - # cortex_m already pins. + # ports. 14.3.rel1 is the GCC 14 the project builds against, and the + # version cortex_m already pins. # Releases: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads GCC_VERSION: 14.3.rel1 diff --git a/.github/workflows/r52_fvp.yml b/.github/workflows/r52_fvp.yml index 8adc1c2be..60861d49b 100644 --- a/.github/workflows/r52_fvp.yml +++ b/.github/workflows/r52_fvp.yml @@ -75,7 +75,7 @@ jobs: # Pinned deliberately. Matches gcc_check.yml and ci_cortex_m.yml so all # three share one cache entry rather than each holding its own copy of # the same archive; change them together or the sharing silently stops. - # 14.3.rel1 is AGENTS.md's declared GCC 14 default. + # 14.3.rel1 is the project's GCC 14 default. GCC_VERSION: 14.3.rel1 # Where the Armv8-R AEM FVP comes from. diff --git a/.github/workflows/regression_template.yml b/.github/workflows/regression_template.yml index ad2d42aa7..267b1b585 100644 --- a/.github/workflows/regression_template.yml +++ b/.github/workflows/regression_template.yml @@ -54,7 +54,7 @@ on: # rate, and not the lower of the two. Probed on the same run: the # ThreadX report at 100.00% lines and 77.67% branches passes a floor of # 99. Worth knowing, because branch coverage is around 78% in both - # suites while AGENTS.md asks for 100%, and a floor set from the + # suites while the project asks for 100%, and a floor set from the # headline line figure says nothing about it. # # Each suite sets its own in regression_test.yml, because they do not @@ -157,9 +157,9 @@ jobs: # ! opens a YAML tag, and the expression will not parse without it. # # fail_below_min turns the summary into a gate. Until now coverage could - # fall from any figure to any other and no check went red, against an - # AGENTS.md that asks for 100% -- a stated requirement measured with a - # gauge that could not fail. + # fall from any figure to any other and no check went red, against a + # project target of 100% -- a stated requirement measured with a gauge + # that could not fail. # # One thing the floor does not defend, and it is the likeliest way for # coverage to break: an empty report reads as 100%. gcovr writes diff --git a/cmake/cortex_r52.cmake b/cmake/cortex_r52.cmake index ea599c682..3e67dea16 100644 --- a/cmake/cortex_r52.cmake +++ b/cmake/cortex_r52.cmake @@ -30,7 +30,7 @@ set(SPEC_FLAGS "--specs=nosys.specs") include(${CMAKE_CURRENT_LIST_DIR}/arm-none-eabi.cmake) -# Pin the reference cross toolchain (see AGENTS.md, "Compiler"). Absolute paths +# Pin the project's reference cross toolchain, GCC 14 for Arm. Absolute paths # are used deliberately so the build does not depend on PATH ordering. Override # with -DARM_TOOLCHAIN_PATH= to build with a # different compiler -- for example the advisory newest-compiler lane. diff --git a/scripts/check_gcc.sh b/scripts/check_gcc.sh index 190d50f8b..e714a5c13 100755 --- a/scripts/check_gcc.sh +++ b/scripts/check_gcc.sh @@ -37,13 +37,12 @@ # # Exit status is 0 when everything builds and 1 otherwise. # -# Why this exists: GCC is the project's declared default compiler (AGENTS.md, -# "The default compiler for the project is GCC 14 on Linux"), it is what the -# gnu ports exist for, and it is what nearly every downstream user builds with -# -- and until this script landed, nothing in CI compiled a line of any port -# with it. The only cross-compilation check that ran was the LLVM one, so the -# ATfE path was better guarded than the GNU one, on ports whose directory is -# literally named gnu. +# Why this exists: GCC 14 on Linux is the project's default compiler, it is +# what the gnu ports exist for, and it is what nearly every downstream user +# builds with -- and until this script landed, nothing in CI compiled a line +# of any port with it. The only cross-compilation check that ran was the LLVM +# one, so the ATfE path was better guarded than the GNU one, on ports whose +# directory is literally named gnu. # # This is the companion to scripts/check_clang.sh and deliberately mirrors it # stage for stage. They are two scripts rather than one with a --toolchain flag From c68fb752a6093b2d6888749e8985d60db9dc7fdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Desbiens?= Date: Thu, 10 Sep 2026 07:37:08 -0400 Subject: [PATCH 2/2] Said who the pinned toolchain default in the CMake toolchain files serves Both cmake/cortex_r52.cmake and cmake/cortex_m52.cmake default ARM_TOOLCHAIN_PATH to a toolchains directory under the user's home, guarded by an EXISTS check. Nothing said whether CI relies on that, and the natural reading is that it does. It does not. The three workflows that install a toolchain unpack it into the workspace and cache it there, and r52_fvp.yml puts that directory on PATH before configuring; scripts/check_gcc.sh passes -DARM_TOOLCHAIN_PATH at each of its three CMake call sites. On a runner the guarded directory is absent, the EXISTS check falls through, and the compiler comes from PATH. The default only ever fires on a developer machine, where it is what makes a no-flag build work. Both comments now say that, so the default is not mistaken for a CI dependency and not removed as dead code. cortex_r52.cmake carries the explanation and cortex_m52.cmake refers to it, matching the cross-reference already there. The r52 comment also claimed absolute paths mean "the build does not depend on PATH ordering", which is only true where the pinned directory exists -- in CI the build depends on PATH and nothing else. Qualified accordingly. Comments only; no behaviour changes. Verified that both toolchain files still configure, and that the fall-through is real: with HOME pointed at a directory holding no toolchains, cortex_r52.cmake configures against the arm-none-eabi-gcc found on PATH. Assisted-by: Claude Code (Opus 5) --- cmake/cortex_m52.cmake | 4 ++++ cmake/cortex_r52.cmake | 18 ++++++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/cmake/cortex_m52.cmake b/cmake/cortex_m52.cmake index be25f62dd..4ba987d6d 100644 --- a/cmake/cortex_m52.cmake +++ b/cmake/cortex_m52.cmake @@ -29,6 +29,10 @@ include(${CMAKE_CURRENT_LIST_DIR}/arm-none-eabi.cmake) # reject the port outright. Override with -DARM_TOOLCHAIN_PATH= to build with a different compiler. The check leaves PATH # alone when the pinned directory is absent. +# +# As in cortex_r52.cmake, the default below serves local builds and nothing +# else -- no CI job has that directory, so on a runner the EXISTS check falls +# through and the compiler comes from PATH. See the longer note there. if(NOT DEFINED ARM_TOOLCHAIN_PATH) set(ARM_TOOLCHAIN_PATH "$ENV{HOME}/toolchains/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-eabi/bin") diff --git a/cmake/cortex_r52.cmake b/cmake/cortex_r52.cmake index 3e67dea16..a9e7aee61 100644 --- a/cmake/cortex_r52.cmake +++ b/cmake/cortex_r52.cmake @@ -30,10 +30,20 @@ set(SPEC_FLAGS "--specs=nosys.specs") include(${CMAKE_CURRENT_LIST_DIR}/arm-none-eabi.cmake) -# Pin the project's reference cross toolchain, GCC 14 for Arm. Absolute paths -# are used deliberately so the build does not depend on PATH ordering. Override -# with -DARM_TOOLCHAIN_PATH= to build with a -# different compiler -- for example the advisory newest-compiler lane. +# Pin the project's reference cross toolchain, GCC 14 for Arm. An absolute +# path is used deliberately, so that a build on a machine which has it does not +# depend on PATH ordering. Override with -DARM_TOOLCHAIN_PATH= to build with a different compiler -- for example the +# advisory newest-compiler lane. +# +# The default below serves local builds and nothing else. It fires only on a +# machine that already has that directory, and no CI job does: the workflows +# unpack the toolchain into the workspace and put it on PATH, and +# scripts/check_gcc.sh passes -DARM_TOOLCHAIN_PATH at every CMake call site. +# On a runner the EXISTS check therefore falls through and the compiler comes +# from PATH. Do not read the default as something CI depends on -- and do not +# remove it as dead code either, because it is what makes a no-flag build work +# on a developer machine. if(NOT DEFINED ARM_TOOLCHAIN_PATH) set(ARM_TOOLCHAIN_PATH "$ENV{HOME}/toolchains/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-eabi/bin")