| |
| fxdemo:05-part:06-prerequisites-and-tooling:06-6-troubleshooting-tool-issues:start [2026/08/09 17:16] – created owen | fxdemo:05-part:06-prerequisites-and-tooling:06-6-troubleshooting-tool-issues:start [2026/08/09 17:16] (current) – owen |
|---|
| ====== 6.5 Prerequisite Validation ====== | ====== 6.6 Troubleshooting Tool Issues ====== |
| |
| [[fxdemo:05-part:start | Go To Top ]] | [[fxdemo:05-part:start | Go To Top ]] |
| [[fxdemo:05-part:06-prerequisites-and-tooling:start | Return to Prerequisites and Tooling ]] | [[fxdemo:05-part:06-prerequisites-and-tooling:start | Return to Prerequisites and Tooling ]] |
| |
| The ''checkPrerequisites.sh'' script should validate the required tools before the developer generates [[dido:99_annexes:annex-b-terms-and-definitions:a:artifact|Artifacts]], builds containers, runs [[dido:99_annexes:annex-b-terms-and-definitions:n:node|Nodes]], or collects acceptance [[dido:99_annexes:annex-b-terms-and-definitions:e:evidence|Evidence]]. | The handbook should help developers resolve common tooling problems without turning every setup issue into an architecture discussion. |
| |
| The script should check: | Troubleshooting guidance should cover predictable failures such as: |
| |
| - Required commands are available on the path. | - Git cannot access the [[dido:99_annexes:annex-b-terms-and-definitions:r:repository|Repository]]. |
| - Required versions meet the [[dido:99_annexes:annex-b-terms-and-definitions:b:baseline|Baseline]] expectations. | - The shell cannot execute a script. |
| - Required environment variables exist and point to valid locations. | - A script has incorrect line endings or permissions. |
| - Required [[dido:99_annexes:annex-b-terms-and-definitions:d:dds|DDS]] tooling can run. | - Python points to the wrong interpreter. |
| - Required container tooling can run. | - The virtual environment does not exist or contains missing packages. |
| - Required Python support exists, if Python utilities form part of the Baseline. | - [[dido:99_annexes:annex-b-terms-and-definitions:d:dds|DDS]] environment variables are missing. |
| - Required runtime language tools exist, if Phase 0 Nodes or generated bindings need them. | - The [[dido:99_annexes:annex-b-terms-and-definitions:i:idl|IDL]] compiler cannot find an input file. |
| - Required [[dido:99_annexes:annex-b-terms-and-definitions:r:repository|Repository]] directories and [[dido:99_annexes:annex-b-terms-and-definitions:c:configuration|Configuration]] templates exist. | - Generated types appear in the wrong location. |
| | - The container runtime cannot build or run an image. |
| | - A required port, volume, network, or runtime path conflicts with a local setting. |
| | - VS Code cannot find recommended extensions or workspace tasks. |
| |
| The script should produce clear, actionable output. When a check passes, the script should report the result briefly. When a check fails, the script should explain what failed, why it matters, and what the developer should inspect or install next. | Troubleshooting guidance should direct developers back to the controlled [[dido:99_annexes:annex-b-terms-and-definitions:b:baseline|Baseline]]. Developers should fix the environment or update the documented Baseline through review. They should not solve prerequisite problems by adding undocumented local workarounds that only work on one machine. |
| |
| The script should return a non-zero exit code when a required prerequisite fails. It may return warnings for missing optional tools, but those warnings should not block Baseline execution unless the developer requested a workflow that depends on the optional tool. | When a tool issue reveals a real gap in the handbook, scripts, Repository layout, or Baseline assumptions, the team should update the relevant material. A repeated troubleshooting problem usually signals that the Baseline needs clearer instructions, stronger validation, or a simpler toolchain. |
| |
| ---- | ---- |