Add documentation for configuration modules

[thomas-bc]

Related Issue(s)
Has Unit Tests (y/n)
Documentation Included (y/n)
Generative AI was used in this contribution (y/n)

---

Change Description

Documents configuration modules, long standing request

Fixes #4514

AI Usage

Authored by AI

[github-actions]

Coverage report — base devel

Overall (line): 84.85% → 84.86% (+0.01)
Regression threshold: 0.50% (line).

Regressions

(none over threshold)

Modules changed

Module	Line	Δ	Function	Δ	Branch	Δ
Os/Generic	90.14	-0.10	89.13	+0.00	74.90	-0.20
Fw/DataStructures	97.42	+0.09	97.14	+0.00	81.75	+0.18
Os/Posix	71.03	+0.39	87.50	+0.00	50.89	+0.22

New modules

Module	Line	Function	Branch
Fw/Prm	0.00	0.00	0.00

Modules without UTs

CFDP/Checksum/GTest, Drv/LinuxGpioDriver, Drv/LinuxI2cDriver, Drv/LinuxSpiDriver, Drv/Ports/DataTypes, Drv/PosixUartDriver, FppTestProject/FppTest/topology/async, FppTestProject/FppTest/topology/components/Comp, FppTestProject/FppTest/topology/components/Framework, FppTestProject/FppTest/topology/components/Receiver, FppTestProject/FppTest/topology/components/Sender, FppTestProject/FppTest/topology/guarded, FppTestProject/FppTest/topology/sync, FppTestProject/FppTest/topology/top_ports, FppTestProject/FppTest/topology/types, Fw/Com, Fw/Comp, Fw/FilePacket/GTest, Fw/Fpy, Fw/Obj, Fw/Port, Fw/Sm, Fw/Test, Fw/Types/GTest, Os/Models, Svc/Ccsds/Types, Svc/Ccsds/Utils, Svc/FatalHandler, Svc/Subtopologies/CdhCore, Svc/Subtopologies/ComCcsds, Svc/Subtopologies/ComCcsdsSdls, Svc/Subtopologies/ComFprime, Svc/Subtopologies/ComLoggerTee, Svc/Subtopologies/DataProducts, Svc/Subtopologies/DpCompression, Svc/Subtopologies/FileHandling, Svc/Subtopologies/FileHandlingCfdp, Svc/Subtopologies/FileHandlingCfdp/FileHandlingCfdpConfig, TestDeploymentsProject/Ref/DpDemo, TestDeploymentsProject/Ref/PingReceiver, TestDeploymentsProject/Ref/RecvBuffApp, TestDeploymentsProject/Ref/SendBuffApp, TestDeploymentsProject/Ref/Top, TestDeploymentsProject/Ref/TypeDemo, cmake/test/data/TestConfigDeployment, cmake/test/data/TestDeployment/TestBuildAutocoder, cmake/test/data/TestDeployment/TestDuplicateDirective, cmake/test/data/TestDeployment/TestHeaderAutocoder, cmake/test/data/TestDeployment/TestLinkDepends, cmake/test/data/TestDeployment/TestRelative, cmake/test/data/test-fprime-library/TestLibrary/TestComponent, cmake/test/data/test-fprime-library2/TestLibrary2/TestComponent

[saitanallensantiago26-beep]

Related Issue(s)
Has Unit Tests (y/n)
Documentation Included (y/n)
Generative AI was used in this contribution (y/n)

---

Change Description

Documents configuration modules, long standing request

Fixes #4514

AI Usage

Authored by AI

[lestarch-autobot]

[Maintainability] suggestion maint-misleading-comment: 12-line STEP 5 comment restates the user manual inline.

Every other STEP in this template is a 1-2 line instruction; this one explains include-root rules, module marking and the unix default in prose that already lives in configuration.md / cmake-platforms.md (both linked from this file). Two copies of the same explanation drift independently, and the wall of text hides the one actionable instruction (remove the directive when the list is empty).

Suggested change

	# STEP 5: Register the platform configuration. A platform supplies "PlatformTypes.fpp" and
	# "PlatformTypes.h" from a configuration module and chooses an implementation for every Os
	# package. Each module is marked GLOBAL_IMPLICIT_DEPENDENCY so that every module in the build
	# receives the platform types and, for the module below, the OS type compile definition.
	# Note: Typically, the unix platform directory is a good default, as it grabs standard
	# types from <cstdint> and chooses the POSIX implementations. Additional platform-specific
	# choices and definitions are then registered in a second, INTERFACE-only configuration
	# module as done below (see Linux.cmake). Otherwise, write a directory equivalent to
	# cmake/platform/unix/Platform/ for the platform. The configuration directory must not sit
	# directly under an include root (project, framework, or library root). Remove the
	# CHOOSES_IMPLEMENTATIONS directive below if this platform adds no choices beyond
	# unix/Platform: a directive with an empty list is a generate-time error.
	# STEP 5: Register the platform configuration module(s). unix/Platform supplies PlatformTypes.{fpp,h}
	# and the POSIX choices; the INTERFACE module below adds platform-specific choices and the OS
	# type definition (see Linux.cmake). Drop CHOOSES_IMPLEMENTATIONS if there is nothing to add: an
	# empty directive is a generate-time error. Details: docs/user-manual/build-system/configuration.md

[lestarch-autobot]

[Maintainability] could fix maint-inconsistent-local-convention: OS-type definition set in STEP 2, consumed 40 lines later via PLATFORM_OS_TYPE_DEFINITION.

Linux.cmake and Darwin.cmake (the reference files this template points to) pass the literal directly to target_compile_definitions. The extra variable exists only to keep a "STEP 2" slot; if a copier deletes or renames either half, the unquoted ${PLATFORM_OS_TYPE_DEFINITION} expands to nothing and the definition silently disappears. Inline the literal here and reduce STEP 2 to a note (or drop it).

Suggested change

	target_compile_definitions(Platform<PLATFORM-NAME> INTERFACE ${PLATFORM_OS_TYPE_DEFINITION})
	target_compile_definitions(Platform<PLATFORM-NAME> INTERFACE -DTGT_OS_TYPE_<PLATFORM-NAME>)

[lestarch-autobot]

[Documentation] could fix stale-user-manual: this section still frames the setting as living in "the Os/ subdirectory of the configuration directory" (line 384), and the header is included as config/RawTimeSource.hpp. Under the model this PR documents in configuration.md (overrides match by file name, the directory name is the include prefix, subdirectories are not preserved) a reader may expect to reproduce the Os/ path in their override module. Worth stating that the override is matched by file name only.

Suggested change

	To switch an entire deployment to a different clock, override this header in the project's configuration module and
	To switch an entire deployment to a different clock, override this header in the project's configuration module (matched by file name, `RawTimeSource.hpp`; the `Os/` sub-directory of `default/config` is not part of the include path or the override match) and

[lestarch-autobot]

[Design] could fix — design-scope-creep: this is the one non-documentation design change in a PR described as "Documents configuration modules". Replacing add_definitions(-DTGT_OS_TYPE_...) with an INTERFACE definition on the GLOBAL_IMPLICIT_DEPENDENCY module matches Linux.cmake/Darwin.cmake and is the right pattern, but it narrows reach: the define now only lands on targets that link the F´ global interface, not on plain add_library/add_executable targets a project builds alongside F´. Worth a line in the PR description (and STEP 2 comment) so new-platform authors migrating from the old template know the scope changed.

[lestarch-autobot]

[Operational] suggestion ops-doc-reality: an override is a whole-file replacement, and the page never says that the copy freezes every other setting in that file at the framework version it was copied from. Scenario: project overrides FpConfig.h (23 FW_* defines) to change one value, later upgrades F´ to a release adding FW_NEW_FEATURE; the copied file lacks it, and each of the ~170 #if FW_... guards in Fw/, Svc/, Os/ evaluates an undefined macro as 0 with no diagnostic (the framework's flag set has no -Wundef), so the feature is silently off in the flight build while default/config/FpConfig.h says it is on. Smallest remedy: state the consequence and the upgrade action next to the copy step.

Suggested change

	3. **Edit the copy.**
	3. **Edit the copy.** The copy replaces the whole file, so every other setting in it is frozen at the framework
	version it was copied from. After upgrading F´, diff each overridden file against its new default and carry
	over added settings: a `FW_*` macro missing from an overridden header is not an error, `#if FW_...` guards
	treat it as 0.

[lestarch-autobot]

Automated review summary (run 1)

Per-agent results

Agent	must fix	suggestion	could fix	future work	outstanding	Verdict
Security Vulnerabilities	0	0	0	0	0	Go
Supply Chain / Runner Safety	0	0	0	0	0	Go
F Prime C/C++ Design	0	0	0	0	0	Go
Documentation Currency	0	0	1	0	0	Go
Design	0	0	1	0	1	Go
Architecture	0	0	0	0	0	Go
Test Quality	0	0	0	0	0	Go
Correctness	0	0	0	0	0	Go
Operational	0	1	0	0	1	Go
Maintainability	0	1	1	0	2	Go
CI safety	—	—	—	—	—	Go
Totals	0	2	3	0	4	Go

Supply-chain surfaces

Surface	Outstanding
Dependencies	clean
Vendored / submodule	clean
Build / test infrastructure	clean
Workflows / actions / scripts	clean
Generator output	clean
Prompt-injection	clean
Review-system integrity	clean

Merge readiness

Merge readiness: Go — all ten reviewers completed with zero outstanding must-fix findings; 5 non-blocking inline threads remain for author discretion.

---

Docs are the star charts of a framework — thanks for updating these; clear skies for the next platform port.